labkit list <node_type> shows the stored nodes of one type; get and list embed two hops by default

[danbarua]

labkit get <handle> and labkit list <node_type> show the record as stored, for an agent that wants the raw nodes rather than an answer. Both take --json and --depth <n>, and --depth now defaults to 2 for both.

What changed

• list <node_type> reads public.labkit_get_collection_as_hal(p_tenant_id, p_label, p_offset, p_limit, p_depth). It goes through a new collection read on ReadSurface, with collectionQuery in packages/core-domain/queries.ts and TenantGraph.collectionAsHal in packages/core-db/graph.ts, the same route get takes through resource/entityAsHal. app-cli imports nothing from core-db for it.
  • Paging options mirror the procedure's arguments: --offset (default 0) and --limit (default 25, at most 200), plus the global --depth.
  • An unknown type is refused before the record opens. The message names every type, taken from NODE_LABELS through the schema's enum. The <node_type> help lists them from the same place.
  • Plain output renders each node the way get does, under a Claim 1-2 heading, and ends with More: --offset N when the procedure returns a next link. --json emits the procedure's HAL document unchanged.
• get now defaults to depth 2. Before, the default was 1.
• One --depth, still global. It defaults to 2, is refused unless it is a whole number from 0 to 6, and its help names both commands. DEFAULT_DEPTH, MAX_DEPTH, DEFAULT_PAGE and MAX_PAGE are each defined once in queries.ts, and the help text reads them.
• Help group "The record as stored", added to READ_GROUPS after "What was done". get moved there from "Finding a handle", and list joined it. Each description says it shows the record with no interpretation, and get's says that why answers the question while get shows what the answer was drawn from.
• Plain rendering of deeper hops. At depth 2, get's plain output used to show only the first hop. Each farther hop is now indented beneath the neighbour it is reached from. This also changes get's plain output.

Choices to overrule

• The default --limit is 25, the same as the HTTP collection handler's default. The procedure has no default of its own.
• get moved out of "Finding a handle".

How the procedure compares with the brief

• The signature is as the brief gives it.
• It caps limit at 200 and depth at 6. The CLI validates both before the record opens.
• It checks the label against the tenant graph's own vertex-label tables, not against the domain's list. In practice the result is the same, because provisioning creates every label in NODE_LABELS. The CLI refuses an unknown type before the procedure is called.
• Its _links are relative HTTP paths (/collections/..., /graph/...). --json emits them as they are.

Not done: an out-of-range --limit or --depth gets zod's generic message, for example Too big: expected number to be <=200, which does not name the flag.

Tests

• tests/persistence/collection-as-hal.test.ts (2 tests, at the TenantGraph level where entityAsHal is tested): limit and offset page through three claims, with the right next/prev links. Each item equals entityAsHal for the same handle at depth 0 and at depth 2.
• tests/cli/record-as-stored.test.ts (3 tests, run through buildProgram):
  • get embeds two hops by default, --depth 1 narrows it to one, and the plain output shows the second hop.
  • list Claim --limit 1 returns the item get returns, and its plain output says More: --offset 1.
  • list Clam is refused before anything runs, and the message names every entry of NODE_LABELS.
• bun test tests/persistence/collection-as-hal.test.ts tests/cli/ packages/app-web/tests/collection-as-hal.test.ts: 65 pass, 0 fail.
• bun test tests/mcp tests/domain tests/consumer: 113 pass, 0 fail.
• bun run check:quick: all 25 passed. check:cli: 23 assertions passed. check:binary: OK.

Measured with the compiled binary

The binary was built with bun run cli:build and run against a throwaway record created with --db in a scratch directory. It was seeded through the write commands: an enquiry, observations, an analysis, two concluded claims (CLM_4, CLM_5), and a note on CLM_4.

$ labkit list Claim
Claim 1-2

CLM_4  Claim

  kind           exploratory
  name           the schedule moves convergence

  note:concerns            NOTE_6
  evidence:supports        EV_4
    recorded_in:artefact     ART_3
    evidenceunit:produces    EU_3

CLM_5  Claim

  kind           exploratory
  name           the effect is larger at depth 20

  evidence:supports        EV_5
    recorded_in:artefact     ART_3
    evidenceunit:produces    EU_3
[exit 0]

$ labkit list Claim --json --depth 1
{
  "count": 2,
  "limit": 25,
  "_links": {
    "self": {
      "href": "/collections/Claim?limit=25&offset=0"
    }
  },
  "offset": 0,
  "_embedded": {
    "Claim": [
      {
        "id": "CLM_4",
        "kind": "exploratory",
        "name": "the schedule moves convergence",
        "type": "Claim",
        "_links": {
          "self": {
            "href": "/graph/CLM_4",
            "type": "Claim"
          },
          "start": {
            "href": "/graph/CLM_4",
            "type": "Claim"
          },
          "note:concerns": [
            {
              "dir": "in",
              "href": "/graph/NOTE_6",
              "type": "Note"
            }
          ],
          "evidence:supports": [
            {
              "dir": "in",
              "href": "/graph/EV_4",
              "type": "Evidence"
            }
          ]
        },
        "_embedded": {
          "note:concerns": [
            {
              "id": "NOTE_6",
              "dir": "in",
              "text": "the depth 20 runs used a different seed",
              "type": "Note",
              "depth": 1,
              "_links": {
                "self": {
                  "href": "/graph/NOTE_6",
                  "type": "Note"
                }
              }
            }
          ],
          "evidence:supports": [
            {
              "id": "EV_4",
              "dir": "in",
              "type": "Evidence",
              "depth": 1,
              "_links": {
                "self": {
                  "href": "/graph/EV_4",
                  "type": "Evidence"
                },
                "recorded_in:artefact": [
                  {
                    "dir": "out",
                    "href": "/graph/ART_3",
                    "type": "Artefact"
                  }
                ],
                "evidenceunit:produces": [
                  {
                    "dir": "in",
                    "href": "/graph/EU_3",
                    "type": "EvidenceUnit"
                  }
                ]
              },
              "statement": "~3 steps earlier at every depth"
            }
          ]
        }
      },
      {
        "id": "CLM_5",
        "kind": "exploratory",
        "name": "the effect is larger at depth 20",
        "type": "Claim",
        "_links": {
          "self": {
            "href": "/graph/CLM_5",
            "type": "Claim"
          },
          "start": {
            "href": "/graph/CLM_5",
            "type": "Claim"
          },
          "evidence:supports": [
            {
              "dir": "in",
              "href": "/graph/EV_5",
              "type": "Evidence"
            }
          ]
        },
        "_embedded": {
          "evidence:supports": [
            {
              "id": "EV_5",
              "dir": "in",
              "type": "Evidence",
              "depth": 1,
              "_links": {
                "self": {
                  "href": "/graph/EV_5",
                  "type": "Evidence"
                },
                "recorded_in:artefact": [
                  {
                    "dir": "out",
                    "href": "/graph/ART_3",
                    "type": "Artefact"
                  }
                ],
                "evidenceunit:produces": [
                  {
                    "dir": "in",
                    "href": "/graph/EU_3",
                    "type": "EvidenceUnit"
                  }
                ]
              },
              "statement": "5 steps at depth 20"
            }
          ]
        }
      }
    ]
  }
}
[exit 0]

$ labkit get CLM_4
CLM_4  Claim

  kind           exploratory
  name           the schedule moves convergence

  note:concerns            NOTE_6
  evidence:supports        EV_4
    recorded_in:artefact     ART_3
    evidenceunit:produces    EU_3
[exit 0]

$ labkit --depth 1 get CLM_4
CLM_4  Claim

  kind           exploratory
  name           the schedule moves convergence

  note:concerns            NOTE_6
  evidence:supports        EV_4
[exit 0]

$ labkit list Clam
labkit: no node type `Clam`; the types are Question, LineOfEnquiry, EvidenceUnit, Evidence, Claim, Decision, Criterion, CriterionEvaluation, Gate, Review, Artefact, Computation, Task, Note
[exit 1]

$ labkit list Claim --limit 1
Claim 1-1

CLM_4  Claim

  kind           exploratory
  name           the schedule moves convergence

  note:concerns            NOTE_6
  evidence:supports        EV_4
    recorded_in:artefact     ART_3
    evidenceunit:produces    EU_3

More: --offset 1
[exit 0]

$ labkit list Claim --limit 201
labkit: Too big: expected number to be <=200
[exit 1]

labkit get CLM_4 with no --depth shows the second hop (ART_3, EU_3 beneath EV_4). --depth 1 does not.

🤖 Generated with Claude Code

https://claude.ai/code/session_01FWZHuy7xJbVqxyLipnvwdY