feat: route access on the code-graph worklist, boundary suggestions and checks, boundary claims in the hypothesis ledger

[Animesh-Sri-bugb]

Rebased onto main after #49 (SARIF enrichment) merged, so the diff below is only this PR's five commits. The two PRs touched some of the same files; the combined tree is what was tested.

What

A @boundary claims that trust changes between two sides, and its description says what holds the line. Until now nothing checked one. This PR has the optional code graph inform boundaries and check them, and lets the hypothesis ledger record the result of testing one.

1. Route access levels on the worklist. loadWorklist asks the code graph's codegraph_auth_boundary in the same process as the attack surface and the routes. The query is an optional call: a server that does not publish it still yields the worklist. Each entry gains access[] (level public | authenticated | elevated | unknown, basis, unknown_reason, a summary of the evidence, the guard text with its file:line, and caveats). The worklist gains auth_verdict, access_withheld_reason and resolver_density. Levels are carried only under the classified verdict. Any other verdict withholds them and the prompt says why, and unknown is never rendered as public. guardlink_worklist returns these fields too.

2. Boundary suggestions in the annotate prompt. For the rows it shows, the worklist block adds Boundaries the graph suggests:

   • a caller boundary per classified route, naming the guard the graph cites as what enforces it;
   • a data, process, egress or filesystem boundary per sink class the handler reaches (data_layer, exec, network, filesystem), anchored at the example sink.

3. Boundary checks. guardlink validate --code-graph, and guardlink_validate with code_graph: true, emit four warnings:

   • boundary-access-contradicted: a boundary, or an @assumes on its inner asset, says "authenticated" or "admin", and a route on the inner side is classified below that;
   • boundary-access-unknown: the same claim, on a route the graph could not classify;
   • boundary-missing: a route handler reaches a sink, and no asset its file names has a boundary to the outside;
   • boundary-unused: no declared flow crosses the boundary, and no recognised entry point reaches either side.

   The outer side is inferred the way guardlink paths infers entries: an undeclared endpoint, or an External.* asset. A boundary between two inside assets has no known direction, so the access checks skip it.

4. Boundary claims in the hypothesis ledger.

   • guardlink hypothesis contradict|support <key | #id | file:line> --evidence … records an outcome. A contradiction is held to the same evidence bar as a confirmation.
   • guardlink hypothesis boundaries [--json] lists every boundary's state (guardlink.boundary-claims/v1): unverified, supported, contradicted, or retest. Outcomes expire with the code, the way exposure outcomes do.
   • confirm --from-scan records a finding whose claim key names a @boundary as that boundary's outcome. It also reads boundary_claim_key/boundaryClaimKey placed beside an exposure's key, and then records both.
   • A boundary key on its own never falls through to the coarse exposure joins.

Compatibility

• No graph: the annotate prompt is byte-identical, as the existing test asserts for every no-graph status and playbook. validate without the flag and guardlink_validate without code_graph are unchanged.
• A graph without codegraph_auth_boundary: the rendered worklist is byte-identical. A test asserts this, for MCP and bravos stand-ins alike.
• SARIF: untouched. None of the boundary checks become results.
• Ledger:
  • the schema stays guardlink.hypotheses/v1, and boundary and exposure outcomes share entries, told apart by their outcome;
  • the reader refuses an entry whose history mixes the two kinds;
  • an older GuardLink reads a ledger that holds a boundary outcome as corrupt, so it refuses to write rather than dropping the entry.
• Behaviour change: in --from-scan, a finding stamped with a boundary's claim key used to be reported stale. It is now recorded as that boundary's outcome.

Review notes

• statedAccess reads the claimed level from the description's words (login/authenticated/API key → authenticated; admin/role/permission → elevated). It skips text that says the line is open ("unauthenticated", "anonymous", "no login"). It is a heuristic, so every warning quotes the word it matched.
• A route belongs to an asset when its handler's file names that asset. Flows are not used for this, because a flow line names both of its ends. An outer-facing boundary attributes only its inner side.

Verification (local; CI did not run)

• On main (which now includes feat(sarif): carry each finding's declared context, additively; rewrite SPEC §6 #49) plus this branch: npm test reports 114 files, 2043 passed, 1 skipped. The skipped test is the live-graph test, which needs real graph tooling. npm run lint and tsc --noEmit are clean.
• New tests:
  • tests/boundary-check.test.ts (12): every check, the verdict gates, the no-graph path, and validate --code-graph through the real CLI against a stand-in codegraph-mcp;
  • tests/hypothesis-boundary.test.ts (13): resolving targets, evidence rules, expiry, reader validation, every scan-import route, and the CLI round trip;
  • tests/codegraph.test.ts: access levels, withheld verdicts, the unchanged worklist when the query is unsupported, suggestions, both transports, and the MCP surfaces.
• guardlink validate . --artifacts: current and drawable. guardlink diff origin/main: +4 flows. Two exposures moved down a few lines because the doc-block grew; the risk is unchanged.
• tests/query-views.test.ts was re-measured in Chrome, not bumped. I rendered both diagrams with mermaid@11 under the dashboard's options at 1440×900: filtered {34 nodes, 89 links, 8 clusters}, whole model {48 nodes, 180 links}. The counter agrees.
• Not verified against a real graph build. The graph tooling installed locally predates the route and attack-surface queries. The transports run against stand-in executables, and the fixtures follow the shape of codegraph_auth_boundary's answer (verdict, verdict_note, resolver_density, and routes[].access with level, basis, unknown_reason, summary, evidence[] and caveats[]).