Add structural reading port

AGENTS.md

@@ -13,6 +13,11 @@ This guide is for AI agents and human operators recovering context in the Graft
 
 Do not audit the repository by recursively walking the filesystem. Follow the authoritative manifests:
 
+Design packets come first. Before implementation, repair, or RED/GREEN work on
+a backlog item, pull the work into `docs/design/` and make the hill, acceptance
+criteria, playback questions, and non-goals explicit. Implementation starts
+from that packet, not from an unrecorded chat plan.
+
 ### 1. The Entrance
 - **`README.md`**: Public front door, core value prop, and quick start.
 - **`GUIDE.md`**: Orientation, fast path, and system orchestration.

CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+### Changed
+
+- **Structural reading boundary**: `graft_review` impact counts and
+  `graft_dead_symbols` now read through a Graft-owned
+  `StructuralReadingPort` with explicit Continuum-native vs translated
+  git-warp evidence status, preserving existing public response shapes.
+
+### Fixed
+
+- **Structural reading residual posture**: Reference-count readings now
+  report a partial residual posture when committed import-scan fallback
+  evidence is unavailable after a zero-count WARP graph reading.
+
 ## [0.8.0] - 2026-05-13
 
 ### Added

METHOD.md

@@ -8,6 +8,8 @@ The Graft work doctrine: A backlog, a loop, and honest bookkeeping.
 - **The filesystem is the coordination layer.** Directories are priorities; filenames are identities; moves are decisions.
 - **Tests are the executable spec.** Design names the problem; tests prove the answer.
 - **Reproducibility is the definition of done.** Results must be re-runnable proof, not static artifacts.
+- **Design packets come first.** Every implementation cycle starts by making
+  the design packet explicit before RED/GREEN work begins.
 
 ## Structure
 
@@ -38,20 +40,24 @@ The Graft work doctrine: A backlog, a loop, and honest bookkeeping.
 stateDiagram-v2
     direction LR
     [*] --> Pull: asap/
-    Pull --> Branch: cycle/
+    Pull --> Design: docs/design/
+    Design --> Branch: cycle/
     Branch --> Red: failing tests
     Red --> Green: passing tests
     Green --> Retro: findings/debt
     Retro --> Ship: PR to main
     Ship --> [*]
 ```
 
-1. **Pull**: Move an item from `asap/` to `docs/design/`.
-2. **Branch**: Create `cycle/<cycle_name>`.
-3. **Red**: Write failing tests based on the design's playback questions.
-4. **Green**: Implement the solution until tests pass.
-5. **Retro**: Document findings and follow-on debt in the cycle doc.
-6. **Ship**: Open a PR to `main`. Update `BEARING.md` and `CHANGELOG.md` after merge.
+1. **Pull**: Select the backlog item from `asap/` or `up-next/`.
+2. **Design**: Create or update the `docs/design/` packet first. The packet
+   must name the hill, acceptance criteria, playback questions, non-goals, and
+   the expected test strategy before implementation begins.
+3. **Branch**: Create `cycle/<cycle_name>`.
+4. **Red**: Write failing tests based on the design's playback questions.
+5. **Green**: Implement the solution until tests pass.
+6. **Retro**: Document findings and follow-on debt in the cycle doc.
+7. **Ship**: Open a PR to `main`. Update `BEARING.md` and `CHANGELOG.md` after merge.
 
 ## Naming Convention
 Backlog and cycle files follow: `<LEGEND>_<slug>.md`

docs/design/CORE_continuum-structural-reading-port.md

@@ -0,0 +1,275 @@
+---
+title: "Continuum-shaped structural reading port"
+legend: "CORE"
+cycle: "CORE_continuum-structural-reading-port"
+source_backlog: "docs/method/backlog/up-next/CORE_continuum-structural-reading-port.md"
+---
+
+# Continuum-shaped structural reading port
+
+Source backlog item: `docs/method/backlog/up-next/CORE_continuum-structural-reading-port.md`
+Legend: CORE
+
+## Sponsors
+
+- Human: Backlog operator
+- Agent: Implementation agent
+
+These labels are abstract roles. In this design, `user` means the served
+perspective, like in a user story, not a literal named person or specific agent
+instance.
+
+## Hill
+
+By the end of this cycle, Graft has one explicit structural reading boundary:
+`StructuralReadingPort`.
+
+The port accepts Continuum-shaped boundary concepts, but it does not require
+every backing substrate to publish native Continuum artifacts. Existing
+git-warp committed-history reads must sit behind this port and be marked as
+translated, non-Continuum-native evidence. Future Echo or other
+Continuum-producing runtimes may enter through the same boundary as
+Continuum-native evidence only when they provide real Continuum witness
+artifacts.
+
+The phrase to preserve is:
+
+> Continuum-shaped, not Continuum-native.
+
+## Playback Questions
+
+### Human
+
+- [ ] Can a human point to one Graft-owned structural read boundary instead of
+      finding direct git-warp reads scattered through MCP tools and renderers?
+- [ ] Can a human tell whether a reading is Continuum-native or merely
+      translated into a Continuum-compatible shape?
+- [ ] Does the design prevent git-warp commit/range evidence from being
+      misrepresented as a Continuum witness?
+- [ ] Can a future Echo-backed implementation plug in without changing the
+      public review, dead-symbol, or structural rendering contracts?
+
+### Agent
+
+- [ ] Does `src/ports/structural-reading.ts` define the only Graft-facing
+      structural read port and evidence union?
+- [ ] Does the git-warp adapter mark every committed-history reading as
+      `translated-substrate` with `nativeContinuumWitness: false`?
+- [ ] Does at least one deterministic fixture-backed test prove the
+      `continuum-native` evidence branch?
+- [ ] Do `graft_review` and `graft_dead_symbols` consume normalized Graft
+      structural payloads instead of calling substrate-specific facts directly?
+- [ ] Do public API, CLI, MCP, and renderer outputs remain compatible unless a
+      later design packet explicitly changes their schemas?
+
+## Doctrine
+
+Graft may normalize readings into Continuum-compatible shape. Only
+Continuum-producing runtimes may claim Continuum-native witnesshood.
+
+The port must model evidentiary status as data, not prose:
+
+```ts
+type StructuralReadingEvidence =
+  | ContinuumNativeEvidence
+  | TranslatedSubstrateEvidence;
+
+type ContinuumNativeEvidence = {
+  kind: "continuum-native";
+  envelope: ReadingEnvelope;
+  witness?: WitnessedSuffixShell;
+};
+
+type TranslatedSubstrateEvidence = {
+  kind: "translated-substrate";
+  substrate: "git-warp";
+  basis: GitWarpCommittedBasis;
+  evidence: GitWarpEvidence;
+  nativeContinuumWitness: false;
+};
+```
+
+The `nativeContinuumWitness: false` marker is deliberately ugly. It makes fraud
+hard at the type boundary.
+
+## Boundary Shape
+
+The first Graft-owned port should be narrower than a generic graph database and
+more explicit than today's direct `WarpContext` helper calls:
+
+- basis identity: committed Git history, live frontier, or imported runtime
+  envelope
+- observation request identity: the review, symbol, or structural query being
+  asked
+- reading kind: reference impact, dead symbols, symbol history, structural test
+  coverage, or later live-frontier projection
+- freshness: current, stale, or incomparable
+- residual posture: complete, partial, plural, budget-limited, rights-limited,
+  or unavailable
+- evidence status: Continuum-native or translated substrate
+- typed Graft payload: the structural fact consumed by API, CLI, MCP, or
+  renderer code
+
+The implementation should begin with only the payloads needed by the current
+slice:
+
+```ts
+interface StructuralReadingPort {
+  countSymbolReferences(request: SymbolReferenceReadingRequest):
+    Promise<StructuralReadingResult<SymbolReferenceReadingPayload>>;
+  findDeadSymbols(request: DeadSymbolsReadingRequest):
+    Promise<StructuralReadingResult<DeadSymbolsReadingPayload>>;
+}
+```
+
+Additional methods should be added only as existing surfaces are moved behind
+the boundary. The port is not a license to invent a broad, speculative
+abstraction.
+
+## Evidence Types
+
+Graft should define local structural DTOs rather than importing Echo,
+git-warp, or warp-ttd concrete runtime types through API and MCP surfaces.
+
+The first type family should be:
+
+- `StructuralReadingEvidence`
+- `ContinuumNativeEvidence`
+- `TranslatedSubstrateEvidence`
+- `StructuralReadingResult<TPayload>`
+- `StructuralReadingFreshness`
+- `StructuralReadingResidualPosture`
+- `GitWarpCommittedBasis`
+- `GitWarpEvidence`
+
+`ContinuumNativeEvidence` may use local structural references for Continuum
+artifacts until generated Continuum contracts are ready in this repository. The
+important invariant is that native evidence must carry a Continuum reading
+envelope, and translated git-warp evidence must carry `nativeContinuumWitness:
+false`.
+
+## First Adapter
+
+The first adapter is a git-warp committed-history adapter:
+
+```text
+MCP / CLI / API use case
+  -> StructuralReadingPort
+  -> git-warp committed-history adapter
+  -> translated-substrate evidence
+  -> normalized Graft payload
+```
+
+It should call existing WARP helpers rather than rewriting structural logic:
+
+- `countSymbolReferencesFromGraph(...)` for review impact counts
+- `countNamedImportReferencesAtRef(...)` as the current committed-history
+  fallback for review impact counts
+- `findDeadSymbols(...)` for dead-symbol readings
+
+The fallback import-reference count is still translated substrate evidence. It
+is based on committed repository content at a Git ref, not on a native
+Continuum witness.
+
+## First Consumers
+
+Move the smallest set of substrate-specific consumers behind the port:
+
+- `graft_review`: reference impact counts should come from
+  `StructuralReadingPort.countSymbolReferences(...)`
+- `graft_dead_symbols`: dead-symbol payloads should come from
+  `StructuralReadingPort.findDeadSymbols(...)`
+
+The first implementation should preserve the public response bodies for
+`graft_review`, `struct_review`, and `graft_dead_symbols`. The normalized
+reading and evidence metadata can remain inside the Graft boundary until a
+separate API/schema design packet chooses how to expose it.
+
+Renderers must continue to consume the existing public models. They should not
+learn git-warp facts directly.
+
+## Continuum-Native Fixture
+
+This slice must include one deterministic unit test proving that the
+Continuum-native evidence branch is representable and cannot be confused with
+translated git-warp evidence.
+
+Fixture requirements:
+
+- construct a `StructuralReadingResult<T>` with
+  `evidence.kind === "continuum-native"`
+- include a Continuum-shaped `envelope`
+- include a Continuum-shaped `witness`
+- assert that translated substrate evidence has
+  `nativeContinuumWitness === false`
+- avoid wall-clock timing, randomness, stdout/stderr assertions, and code
+  introspection as behavioral proof
+
+The fixture may be local and minimal until generated Continuum runtime-boundary
+artifacts are consumable from Graft.
+
+## Graft Registry Role
+
+This cycle should preserve Graft's proposed Continuum registry role without
+making Graft the semantic owner of shared Continuum families:
+
+| Repo | Registry role | Must not become |
+| :--- | :--- | :--- |
+| Graft | Structural observer and review engine; consumes runtime-boundary, receipt, settlement, neighborhood, and observer families; produces code-aware structural reading payloads. | A runtime implementation, debugger product, shadow Continuum semantic owner, or permanent host-normalization layer. |
+
+If a Graft structural payload becomes useful to another repo, promote that
+family into Continuum through the normal family-promotion process instead of
+copying local DTOs across repositories.
+
+## Accessibility and Assistive Reading
+
+- Linear truth / reduced-complexity posture: Evidence status must be visible in
+  one structural type instead of explained through scattered comments.
+- Non-visual or alternate-reading expectations: The port and fixture tests
+  should read as plain source and plain markdown. No diagrams are required to
+  understand whether evidence is native or translated.
+
+## Localization and Directionality
+
+- Locale / wording / formatting assumptions: Stable contract labels such as
+  `continuum-native`, `translated-substrate`, and `nativeContinuumWitness`
+  should not rely on English prose to carry semantics.
+- Logical direction / layout assumptions: The adapter direction should remain
+  linear: surface code asks Graft for a reading; Graft chooses an adapter; the
+  adapter labels its evidence.
+
+## Agent Inspectability and Explainability
+
+- What must be explicit and deterministic for agents: Agents must be able to
+  inspect a `StructuralReadingResult` and determine the payload, basis,
+  freshness, residual posture, and evidence status without opening an adapter.
+- What must be attributable, evidenced, or governed: Tests must prove that
+  git-warp readings are translated substrate evidence and that the
+  Continuum-native branch is separate.
+
+## Non-goals
+
+- [ ] Replacing git-warp in this cycle.
+- [ ] Adding a direct Echo dependency before the port boundary exists.
+- [ ] Modeling git-warp commit, range, graph, or import-reference evidence as a
+      Continuum witness.
+- [ ] Making Graft the semantic owner of Continuum runtime-boundary nouns.
+- [ ] Making warp-ttd the structural-review engine.
+- [ ] Exposing new evidence metadata through MCP/API/CLI response schemas in
+      the first implementation slice.
+- [ ] Migrating every WARP read path, including precision, churn, blame, stale
+      docs, and local-history graph reads, in one cycle.
+- [ ] Solving the slice-first observer-geometry backlog while this port is
+      being introduced.
+
+## Expected Artifacts
+
+- `src/ports/structural-reading.ts` with the Graft-owned port, evidence union,
+  status types, and payload contracts.
+- A git-warp committed-history adapter behind the port.
+- `graft_review` routed through the port for symbol reference impact counts.
+- `graft_dead_symbols` routed through the port for dead-symbol readings.
+- Deterministic unit coverage for translated git-warp evidence and the
+  Continuum-native evidence branch.
+- Public response compatibility coverage for the touched MCP/CLI surfaces.
+- No tag, release, or public schema change as part of this slice.