Structural history schema and Echo migration

NORTHSTAR.md

@@ -68,27 +68,46 @@ Continuum-shaped, not Continuum-native.
 Graft may normalize structural readings into a Continuum-compatible shape.
 Only Continuum-producing runtimes may claim Continuum-native witnesshood.
 
+The second migration distinction is:
+
+```text
+schema authority before substrate migration.
+```
+
+Graft must define its structural history in GraphQL first. Wesley then
+generates the TypeScript read model, validators, Echo-consumable contracts,
+SQL/storage artifacts, and other runtime targets from that single source of
+truth. This does not imply changing Wesley or Echo. Graft authors schema and
+integration config, then consumes the existing Wesley compiler outputs and the
+existing Echo substrate. Echo is the primary causal-history substrate for Graft
+after parity is proven. git-warp is the legacy committed-history import and
+compatibility source, not the canonical model of Graft structural history.
+
 The stack split is:
 
 | Layer | Owner | Responsibility |
 | :--- | :--- | :--- |
 | Shared semantics | Continuum | Shared contract families, witness language, admission and compatibility nouns, registry truth. |
-| Compilation | Wesley | Generated artifacts, manifests, codecs, bundle identity, TTD surfaces, and witness tooling. |
-| Hot runtime | Echo | Low-latency admission, observation, retained readings, receipts, replay, and live/frontier runtime machinery. |
-| Cold runtime | `git-warp` | Git-backed, committed-history runtime implementation and durable structural history adapter. |
+| Graft structural schema | Graft | Canonical GraphQL structural history facts, code-aware reading semantics, and migration parity rules. |
+| Compilation | Wesley | Existing compiler and generated-contract rules for artifacts, manifests, codecs, TypeScript read models, validators, SQL/storage artifacts, Echo-consumable contracts, and witness tooling. |
+| Primary substrate | Echo | Fast causal-history storage and execution for Graft's schema-generated structural history. |
+| Legacy compatibility | `git-warp` | Provenance-preserving committed-history import source and temporary fallback-translated adapter. |
 | Debugger/operator surface | `warp-ttd` | Wide-aperture navigation through lanes, frames, receipts, effects, sessions, delivery observations, and counterfactuals. |
 | Structural intelligence | Graft | Code-aware readings, review truth, symbol/reference history, structural test signals, provenance hints, and agent-facing context governance. |
 
-Echo and `git-warp` are sibling Continuum runtime implementations. Neither is
-the real graph. Neither is the subordinate half of the other. Runtime posture
-can differ: hot, cold, browser-hosted, archival, offline-first, editor-native,
-Git-backed. Shared meaning must still cross the Continuum boundary through
-authored families and witnessed artifacts.
+Echo and `git-warp` are substrates, not Graft's ontology. Both can converge on
+Wesley GraphQL contracts, but Graft must not copy git-warp's graph model into
+Echo and call that architecture. Runtime posture can differ: browser-hosted,
+archival, offline-first, editor-native, Git-backed, or massive-history
+optimized. Shared meaning must still cross the authored schema and Continuum
+boundary through generated contracts and witnessed artifacts where native
+witnesses exist.
 
 ## What Graft Owns
 
 Graft owns the code-aware observer layer:
 
+- the canonical GraphQL structural history schema
 - policy-governed reads and explicit refusals
 - structural outlines, diffs, and projections
 - symbol, reference, rename, and removed-symbol evidence
@@ -112,6 +131,7 @@ Graft must not become:
 - a runtime implementation competing with Echo or `git-warp`
 - the semantic owner of Continuum shared families
 - a hidden graph database API
+- a consumer of git-warp-native concepts as canonical structural history
 - a debugger product replacing `warp-ttd`
 - a permanent hand-normalization layer for incompatible host stories
 - a prose-only review assistant whose claims cannot be inspected
@@ -139,8 +159,9 @@ A reading should name:
   rights-limited, unavailable, obstructed, or intentionally degraded
 - **support**: witness, receipt, shell, retained artifact, provenance payload,
   or explicit absence of support
-- **evidence status**: Continuum-native when backed by a native Continuum
-  witness, or translated-substrate when adapted from a non-native substrate
+- **evidence status**: Echo-native, git-warp-imported, or
+  fallback-translated for Graft structural history; Continuum-native only when
+  backed by a native Continuum witness
 - **payload identity**: digest, version, schema, or generated artifact id
 - **typed payload**: the actual Graft-owned structural answer
 
@@ -153,26 +174,29 @@ truth.
 The long-term path is:
 
 ```text
-Continuum shared family
-  -> Wesley-generated artifacts
-  -> Echo runtime publication or translated git-warp adapter evidence
+Graft GraphQL structural history schema
+  -> existing Wesley compiler outputs for TypeScript / Zod / Echo / SQL
+  -> Echo-backed primary structural history
   -> ObservationRequest / ObserverPlan
-  -> ReadingEnvelope-backed runtime result
-  -> Graft structural payload
+  -> StructuralReadingPort
+  -> Graft structural reading payload
   -> API / CLI / MCP / warp-ttd presentation
 ```
 
 In practice:
 
-- `git-warp` remains the right adapter for cold, Git-backed committed history.
-  Until it publishes Continuum boundary artifacts directly, its evidence is
-  translated substrate evidence, not a Continuum-native witness.
-- Echo becomes the right adapter for hot, live, frontier-oriented histories.
+- Graft defines canonical structural facts in GraphQL.
+- Graft invokes the existing Wesley toolchain so TypeScript, validators,
+  SQL/storage artifacts, and Echo-consumable files cannot drift from that file.
+- Echo becomes the primary substrate for Graft structural history after parity
+  is proven.
+- `git-warp` becomes the provenance-preserving legacy import source and an
+  optional fallback compatibility adapter.
+- Evidence labels distinguish `echo-native`, `git-warp-imported`, and
+  `fallback-translated` facts.
 - Continuum owns shared runtime-boundary nouns such as `ObserverPlan`,
   `ObservationRequest`, `ReadingEnvelope`, `WitnessedSuffixShell`,
   `CausalSuffixBundle`, and `ImportOutcome`.
-- Wesley-generated artifacts replace shadow schemas and hand-normalized DTOs
-  where the boundary is shared.
 - Graft owns the code-aware structural payload at the edge of the reading.
 - `warp-ttd` may display Graft readings as observer artifacts, but should not
   become the long-term owner of code-review meaning.
@@ -207,23 +231,29 @@ outcome is that every caller gets the same truth posture.
 
 ## Boundary Laws
 
-1. Graft must not treat any materialized graph as the primary ontology.
-2. Graft must keep runtime admission, observation, import, export, and
+1. Graft owns structural semantics.
+2. Wesley owns the compiler and generated-contract rules; Graft only supplies
+   schema and integration config.
+3. Echo owns causal-history storage and execution; Graft does not change Echo.
+4. git-warp owns only legacy import and compatibility.
+5. No git-warp-native concept becomes canonical by accident.
+6. Graft must not treat any materialized graph as the primary ontology.
+7. Graft must keep runtime admission, observation, import, export, and
    settlement concerns behind explicit ports.
-3. Graft must not mutate Echo state directly.
-4. Graft must not make `warp-ttd` carry permanent host-normalization or
+8. Graft must not mutate Echo state directly.
+9. Graft must not make `warp-ttd` carry permanent host-normalization or
    structural-review debt.
-5. Graft must not re-author Continuum-owned shared nouns locally.
-6. Graft may own app/tool-local structural payloads until a second repo needs
+10. Graft must not re-author Continuum-owned shared nouns locally.
+11. Graft may own app/tool-local structural payloads until a second repo needs
    the same semantics.
-7. Shared structural payloads should graduate to Continuum only when promotion
+12. Shared structural payloads should graduate to Continuum only when promotion
    reduces drift rather than freezing confusion.
-8. API, CLI, MCP, and debugger presentation should expose the same
+13. API, CLI, MCP, and debugger presentation should expose the same
    structural-reading posture through their own appropriate contracts.
-9. Observer-side summaries must not be presented as canonical runtime
+14. Observer-side summaries must not be presented as canonical runtime
    admission unless the runtime actually admitted that collapse and can name
    the corresponding support.
-10. Every degraded or refused answer must say why.
+15. Every degraded or refused answer must say why.
 
 ## Migration Principle
 
@@ -234,12 +264,13 @@ The move is:
 
 ```text
 git-warp-shaped implementation
-  -> substrate-neutral structural reading port
-  -> git-warp adapter behind the port
-  -> translated-substrate evidence with nativeContinuumWitness: false
-  -> Continuum-native runtime-boundary fixtures
-  -> Echo/live-frontier adapter
-  -> generated shared artifacts where the family is no longer Graft-local
+  -> Graft GraphQL structural history schema
+  -> existing Wesley compiler outputs
+  -> Echo-backed primary structural store/read model
+  -> git-warp one-time import with provenance
+  -> parity validation against current public outputs
+  -> normal operation stops opening git-warp
+  -> optional fallback-translated compatibility for remaining gaps
 ```
 
 This keeps the current Review Truth behavior shippable while making the next
@@ -248,35 +279,48 @@ architecture honest.
 ## Near-Term Path
 
 1. Ship `v0.8.0` as the final git-warp-first Review Truth release.
-2. Introduce a substrate-neutral structural reading port in Graft.
-3. Keep the existing git-warp committed-history implementation behind that
-   port and mark its evidence as translated/non-Continuum-native.
-4. Add fixture-backed or Echo-backed Continuum runtime-boundary coverage for
-   `ObserverPlan`, `ObservationRequest`, `ReadingEnvelope`, and evidence status.
-5. Prove one Echo or `jedit` live-frontier structural reading.
-6. Shape Graft-owned structural payloads so they can be wrapped in
-   `ReadingEnvelope` posture without making Continuum own premature app nouns.
-7. Let `warp-ttd` display Graft structural readings as observer artifacts, not
+2. Keep the landed `StructuralReadingPort` as the Graft-facing read boundary,
+   but treat its hand-authored payloads as transitional.
+3. Define Graft's canonical structural history facts in GraphQL.
+4. Use the existing Wesley toolchain to derive the TypeScript read model,
+   validators, Echo-consumable contracts, and storage artifacts from that
+   schema.
+5. Import existing git-warp structural data into Echo with preserved
+   provenance and `git-warp-imported` evidence.
+6. Validate parity against current git-warp-backed review, dead-symbol, blame,
+   difficulty, structural log, churn, and precision/code lookup outputs.
+7. Mark remaining compatibility reads as `fallback-translated` and never as
+   Continuum-native witnesses.
+8. Stop opening git-warp during normal operation once parity is proven.
+9. Let `warp-ttd` display Graft structural readings as observer artifacts, not
    debugger-native facts.
-8. Promote only the structural payloads that truly need cross-repo meaning into
+10. Promote only the structural payloads that truly need cross-repo meaning into
    Continuum.
 
 The first concrete post-`v0.8.0` slice is:
 
-- [CORE_continuum-structural-reading-port](./docs/method/backlog/up-next/CORE_continuum-structural-reading-port.md)
+- [CORE_structural-history-schema-and-echo-migration](./docs/method/backlog/up-next/CORE_structural-history-schema-and-echo-migration.md)
 
 ## Success State
 
 We know the north star is becoming real when these things are boring:
 
 - A PR review over committed Git history and a live editor reading over Echo
-  both return evidence-bearing structural readings.
+  both return evidence-bearing structural readings through the same generated
+  Graft schema.
 - API, CLI, and MCP callers receive the same basis, freshness, residual,
   support, evidence-status, and payload identity posture.
+- Generated TypeScript, validators, Echo-consumable contracts, and storage
+  artifacts trace back to the same GraphQL source without hand-maintained drift.
+- Normal Graft operation no longer opens git-warp after import parity is
+  proven.
+- Legacy git-warp facts remain inspectable as imported provenance, not hidden
+  authority.
 - `warp-ttd` can show a Graft structural reading alongside runtime receipts
   without hand-normalizing host-specific stories.
-- Continuum owns the shared families; Wesley generates the artifacts; runtimes
-  emit and admit witnessed history; Graft reads code meaning from that history.
+- Continuum owns the shared families; Wesley supplies the compiler and
+  generated-contract rules; runtimes emit and admit witnessed history; Graft
+  reads code meaning from that history.
 - No one has to ask which graph is real.
 
 The answer is always: the graph is a chart. The work is witnessed causal

docs/BEARING.md

@@ -11,15 +11,19 @@ timeline
 
 ## Active Gravity
 
-### 1. Continuum-Shaped Structural Reading Port
-- Defining `StructuralReadingPort` as the only Graft-facing structural read
-  boundary.
-- Keeping the current git-warp committed-history behavior behind that port
-  while marking its evidence as translated/non-Continuum-native.
-- Proving at least one fixture-backed or Echo-backed Continuum-native reading
-  branch without making Graft a Continuum semantic owner.
-- Routing API, CLI, MCP, and rendering paths through normalized Graft structural
-  payloads rather than substrate-specific facts.
+### 1. Structural History Schema and Echo Migration
+- Graft defines canonical structural history facts in GraphQL.
+- Graft consumes the existing Wesley toolchain to derive TypeScript read
+  models, validators, Echo-consumable contracts, SQL/storage artifacts, and
+  drift witnesses from that schema.
+- Echo becomes the primary causal-history substrate for Graft's structural
+  history after parity is proven.
+- git-warp is demoted to provenance-preserving legacy import and temporary
+  fallback compatibility.
+- Evidence labels distinguish `echo-native`, `git-warp-imported`, and
+  `fallback-translated` facts.
+- The landed `StructuralReadingPort` remains the Graft-facing read boundary,
+  but its hand-authored payloads are transitional.
 
 ### 2. Entrypoint Convergence
 - Formalizing API, CLI, and MCP as equal first-class entry points.
@@ -49,7 +53,10 @@ timeline
 ## Tensions
 
 - **Daemon Authz Isolation**: Ensuring that transport-scoped sessions cannot "hop" to unauthorized workspace slices via ID guessing.
-- **Git Subprocess Churn**: Frequent spawning of `git` for repo state observation in large repositories impacts latency.
+- **git-warp Substrate Strain**: Very large histories and ref sets push
+  git-warp through Git performance limits; Graft should move normal operation
+  to Echo after schema-backed parity rather than hand-translating git-warp's
+  graph model into Echo.
 - **Session Semantic Drift**: The term `session` remains too transport-scoped in the code; it needs to move toward a strand-scoped causal envelope.
 - **Warp Level 1 Debt**: Some WARP follow-on work is implemented ahead
   of the release bookkeeping that describes it. Release and METHOD
@@ -75,21 +82,28 @@ parsing.
 
 ## Next Target
 
-The immediate focus is the **Continuum-shaped structural reading port**, not a
-runtime rewrite.
+The immediate focus is **schema authority before substrate migration**.
 
 1. Keep `main` clean after the `v0.8.0` release.
-2. Introduce `StructuralReadingPort` as Graft's single structural read boundary.
-3. Put git-warp committed-history reads behind the port and label them as
-   translated/non-Continuum-native evidence.
-4. Prove the Continuum-native branch with fixture-backed or Echo-backed
-   evidence before any adapter claims native witnesshood.
-5. Do not add METHOD-specific backlog/status features to Graft. METHOD
+2. Pull
+   [CORE_structural-history-schema-and-echo-migration](./method/backlog/up-next/CORE_structural-history-schema-and-echo-migration.md)
+   as the next design/implementation cycle.
+3. Define Graft's canonical structural history facts in GraphQL before
+   adapting more git-warp output.
+4. Use the existing Wesley toolchain to derive the TypeScript/Zod read model,
+   Echo-consumable contracts, storage artifacts, and drift witnesses from that
+   schema.
+5. Preserve current public command behavior while validating Echo-backed
+   outputs against git-warp-backed outputs.
+6. Treat git-warp evidence as `git-warp-imported` or `fallback-translated`,
+   never as Continuum-native witnesshood.
+7. Stop opening git-warp during normal Graft operation once parity is proven.
+8. Do not add METHOD-specific backlog/status features to Graft. METHOD
    backlog lanes, cards, retros, dependency DAGs, and release truth
    surfaces belong in Method MCP / Method CLI.
-6. Keep `WARP_lsp-enrichment` and `CORE_migrate-to-slice-first-reads`
+9. Keep `WARP_lsp-enrichment` and `CORE_migrate-to-slice-first-reads`
    out of this slice. LSP enrichment remains valid optional scope;
    slice-first reads remain externally blocked until git-warp observer
    geometry APIs land.
-7. Treat daemon live refresh and daemon control-plane actions as a
+10. Treat daemon live refresh and daemon control-plane actions as a
    separate daemon-operator lane, not part of this slice.

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

@@ -2,14 +2,26 @@
 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"
+source_backlog: "docs/method/graveyard/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`
+Source backlog item: `docs/method/graveyard/CORE_continuum-structural-reading-port.md`
 Legend: CORE
 
+## Disposition
+
+The first port slice landed in PR #55. The remaining architecture direction is
+now superseded by
+[Structural history schema and Echo migration](./CORE_structural-history-schema-and-echo-migration.md).
+
+This packet remains useful as the historical explanation for
+`StructuralReadingPort` and the phrase "Continuum-shaped, not
+Continuum-native." New work should not extend the hand-authored port model as
+the canonical schema. It should move schema authority into Graft GraphQL and
+Wesley-generated artifacts.
+
 ## Sponsors
 
 - Human: Backlog operator