From bc7695aad0589667197d3af478f40a5ab84a34c6 Mon Sep 17 00:00:00 2001 From: James Ross Date: Sat, 16 May 2026 11:56:59 -0700 Subject: [PATCH 1/2] docs: define structural history echo migration --- NORTHSTAR.md | 137 +++-- docs/BEARING.md | 52 +- .../CORE_continuum-structural-reading-port.md | 16 +- ...tural-history-schema-and-echo-migration.md | 309 ++++++++++ ...rp-reads-bypass-structural-reading-port.md | 29 +- docs/method/backlog/dependency-dag.dot | 2 +- docs/method/backlog/dependency-dag.svg | 568 +++++++++--------- ...tural-history-schema-and-echo-migration.md | 134 +++++ .../CORE_continuum-structural-reading-port.md | 14 +- 9 files changed, 901 insertions(+), 360 deletions(-) create mode 100644 docs/design/CORE_structural-history-schema-and-echo-migration.md create mode 100644 docs/method/backlog/up-next/CORE_structural-history-schema-and-echo-migration.md rename docs/method/{backlog/up-next => graveyard}/CORE_continuum-structural-reading-port.md (92%) diff --git a/NORTHSTAR.md b/NORTHSTAR.md index f1f3124..d98971d 100644 --- a/NORTHSTAR.md +++ b/NORTHSTAR.md @@ -68,27 +68,44 @@ 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-facing contracts, +SQL/storage artifacts, and other runtime targets from that single source of +truth. 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 | Generated artifacts, manifests, codecs, TypeScript read models, validators, SQL/storage artifacts, Echo-facing 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 +129,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 +157,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 +172,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 + -> Wesley-generated TypeScript / Zod / Echo / SQL artifacts + -> 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. +- Wesley generates every contract target from that file so TypeScript, + validators, SQL/storage artifacts, and Echo-facing files cannot drift. +- 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 +229,28 @@ 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 generated contracts. +3. Echo owns causal-history storage and execution. +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 +261,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 + -> Wesley-generated contracts + -> 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,31 +276,42 @@ 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 Wesley to generate the TypeScript read model, validators, Echo-facing + 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-facing 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 diff --git a/docs/BEARING.md b/docs/BEARING.md index 9bf2d94..c49d4be 100644 --- a/docs/BEARING.md +++ b/docs/BEARING.md @@ -11,15 +11,18 @@ 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. +- Wesley generates TypeScript read models, validators, Echo-facing 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 +52,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 +81,27 @@ 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 Wesley to generate the TypeScript/Zod read model, Echo-facing + 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. diff --git a/docs/design/CORE_continuum-structural-reading-port.md b/docs/design/CORE_continuum-structural-reading-port.md index 5831a51..cdd1410 100644 --- a/docs/design/CORE_continuum-structural-reading-port.md +++ b/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 diff --git a/docs/design/CORE_structural-history-schema-and-echo-migration.md b/docs/design/CORE_structural-history-schema-and-echo-migration.md new file mode 100644 index 0000000..947a26a --- /dev/null +++ b/docs/design/CORE_structural-history-schema-and-echo-migration.md @@ -0,0 +1,309 @@ +--- +title: "Structural history schema and Echo migration" +legend: "CORE" +cycle: "CORE_structural-history-schema-and-echo-migration" +source_backlog: "docs/method/backlog/up-next/CORE_structural-history-schema-and-echo-migration.md" +--- + +# Structural history schema and Echo migration + +Source backlog item: `docs/method/backlog/up-next/CORE_structural-history-schema-and-echo-migration.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 + +Graft's structural history becomes schema-first under Wesley and Echo-backed by +default, while git-warp is demoted to a provenance-preserving migration source +and optional compatibility bridge. + +This cycle is not "swap storage adapters." It is the architectural correction +that makes Graft's structural semantics explicit before any substrate migration +can fossilize git-warp's model. + +## Laws + +1. Graft owns structural semantics. +2. Wesley owns generated contracts. +3. Echo owns causal-history storage and execution. +4. git-warp owns only legacy import and compatibility. +5. No git-warp-native concept becomes canonical by accident. + +## Playback Questions + +### Human + +- [ ] Can a human point to one GraphQL schema as the canonical definition of + Graft structural history? +- [ ] Can a human see that public Graft commands keep their behavior while the + substrate changes underneath? +- [ ] Can a human distinguish Echo-native, git-warp-imported, and + fallback-translated evidence in the design and tests? +- [ ] Can a human see when git-warp is no longer opened during normal + operation? +- [ ] Can a human verify that git-warp remains a provenance-preserving legacy + source instead of a hidden authority? + +### Agent + +- [ ] Does GraphQL define canonical Graft structural facts? +- [ ] Does Wesley generate TypeScript read models, validators, and Echo-facing + contracts from that single source of truth? +- [ ] Do drift tests fail when generated artifacts or runtime contracts stop + matching the GraphQL schema? +- [ ] Do migration parity tests compare Echo-backed outputs against the current + git-warp-backed outputs? +- [ ] Do `graft_review`, `graft_dead_symbols`, blame, difficulty, structural + log, churn, and precision/code lookup consume normalized Graft structural + payloads rather than substrate-specific facts? +- [ ] Does normal operation stop opening git-warp after parity is proven? + +## Decision + +The dangerous wrong path is: + +```text +git-warp graph model + -> hand-translated Echo model + -> Graft keeps depending on old concepts +``` + +That keeps git-warp in authority while moving bytes somewhere faster. + +The correct path is: + +```text +Graft GraphQL structural history schema + -> Wesley-generated TypeScript / Zod / Echo / SQL artifacts + -> Echo-backed primary structural history + -> git-warp one-time import and fallback compatibility +``` + +Schema authority comes first. Echo is a fast causal-history substrate. Wesley is +the compiler that prevents drift across TypeScript, validators, SQL, Echo Rust +files, and other generated artifacts. Graft owns the structural facts being +modeled. + +## Canonical Model Boundary + +The GraphQL schema should name Graft-owned structural facts, not git-warp's +internal implementation shape. + +Canonical Graft facts include: + +- repository, worktree, basis, and observed ref identity +- file identity and file versions +- parser runs and parser diagnostics +- symbols, declarations, exports, imports, references, calls, and source spans +- structural diffs and changed regions +- review impacts and test-reference links +- dead-symbol findings, blame/symbol-history findings, difficulty inputs, log + entries, and churn summaries when they are structural facts +- structural readings, residual posture, freshness, payload identity, evidence + labels, and provenance +- migration batches, imported source identity, parity results, and retirement + decisions + +git-warp implementation details must not become canonical merely because the +legacy adapter exposes them: + +- observer cache layout +- traversal mechanics +- lazy indexing mechanics +- tick implementation details +- optimization artifacts +- private graph node names that do not describe Graft semantics + +## Evidence Model + +The migration needs at least these evidence statuses: + +```ts +type StructuralHistoryEvidence = + | EchoNativeEvidence + | GitWarpImportedEvidence + | FallbackTranslatedEvidence; + +type EchoNativeEvidence = { + kind: "echo-native"; + schema: GraftStructuralHistorySchemaId; + basis: EchoStructuralBasis; +}; + +type GitWarpImportedEvidence = { + kind: "git-warp-imported"; + schema: GraftStructuralHistorySchemaId; + importedFrom: GitWarpImportBasis; + migrationBatch: MigrationBatchId; + parity: MigrationParityStatus; +}; + +type FallbackTranslatedEvidence = { + kind: "fallback-translated"; + substrate: "git-warp"; + basis: GitWarpCommittedBasis; + nativeContinuumWitness: false; +}; +``` + +The evidence labels are about Graft's structural history source. They do not +authorize Continuum witness claims. The earlier rule still stands: + +```text +Continuum-shaped, not Continuum-native. +``` + +Only Continuum-producing runtimes may claim Continuum-native witnesshood. Graft +may normalize structural readings into Continuum-compatible shape. + +## Migration Flow + +The migration should be explicit and auditable: + +1. Create the Wesley-owned schema generation boundary. +2. Make Echo the primary write/read substrate for new structural facts. +3. Import current git-warp structural data into the canonical schema with + `git-warp-imported` evidence. +4. Compare Echo-backed outputs against current git-warp-backed outputs for + existing public behavior. +5. Keep a git-warp fallback adapter only for gaps, labeled + `fallback-translated`. +6. Remove git-warp from normal operation once parity is proven. +7. Retain git-warp compatibility as a deliberate migration/debug path, not as a + hidden authority. + +Parity should cover the public surfaces users already rely on: + +- `graft_review` and `struct_review` +- `graft_dead_symbols` +- symbol history and blame +- refactor difficulty +- structural log and churn +- precision/code lookup paths when they expose structural facts + +## Wesley Contract + +The GraphQL file is the single source of truth. Wesley-generated outputs are +derived artifacts: + +- TypeScript read model +- Zod or equivalent runtime validators +- Echo-facing contracts and Rust files +- SQL/storage artifacts where needed +- schema identity, generation manifest, and drift witness + +The repo must not allow parallel models to diverge: + +- no hand-maintained TypeScript model that silently differs from GraphQL +- no hand-maintained Zod schema that silently differs from TypeScript +- no hand-maintained Echo model that silently differs from GraphQL +- no migration importer that smuggles git-warp-only concepts into the canonical + schema + +## Echo Boundary + +Echo is deliberately dumb from Graft's perspective. Graft should not change Echo +to understand Graft semantics manually. + +Graft declares structural history in GraphQL. Wesley compiles the Echo-facing +contracts. Echo stores and executes causal history through those generated +contracts. Graft consumes normalized structural payloads through its own ports. + +That keeps substrate performance and semantic authority separate. + +## git-warp Boundary + +git-warp remains important during the migration: + +- current committed-history evidence source +- one-time import source for existing structural history +- fallback compatibility adapter while parity gaps are closed +- provenance source for explaining imported facts + +git-warp must stop being the default authority for normal Graft operation after +parity is proven. No new Graft schema concept should exist solely because a +git-warp graph detail happened to exist first. + +## StructuralReadingPort Role + +`StructuralReadingPort` remains the Graft-facing structural read boundary, but +the current hand-authored payloads are transitional. The port should move toward +Wesley-generated payloads and evidence labels as the schema lands. + +The intended flow becomes: + +```text +API / CLI / MCP use case + -> StructuralReadingPort + -> Wesley-generated Graft read model + -> Echo-backed primary store + -> normalized structural reading payload +``` + +The fallback flow is explicit: + +```text +API / CLI / MCP use case + -> StructuralReadingPort + -> git-warp compatibility adapter + -> fallback-translated evidence + -> normalized structural reading payload +``` + +## Accessibility and Assistive Reading + +- Linear truth / reduced-complexity posture: The schema, generated artifact + manifest, and evidence labels must let a reader tell which model is + authoritative without reconstructing repository history. +- Non-visual or alternate-reading expectations: The migration plan must remain + understandable as plain text and plain source. Diagrams may help, but they + must not be required to know whether a fact is Echo-native, + git-warp-imported, or fallback-translated. + +## Localization and Directionality + +- Locale / wording / formatting assumptions: Stable evidence labels such as + `echo-native`, `git-warp-imported`, and `fallback-translated` carry contract + meaning and should not depend on English prose. +- Logical direction / layout assumptions: The migration direction is schema + authority first, then generated contracts, then Echo primary operation, then + git-warp compatibility retirement. + +## Non-goals + +- Do not hand-port git-warp's graph model into Echo. +- Do not change Echo to understand Graft semantics manually. +- Do not model git-warp internals as canonical Graft facts. +- Do not change public command behavior during the migration unless a later + packet explicitly authorizes a surface change. +- Do not remove git-warp support before import parity and fallback behavior are + proven. +- Do not keep parallel hand-maintained TypeScript, Zod, SQL, and Echo Rust + models once Wesley generation exists. +- Do not claim Continuum-native witnesshood for imported or translated + git-warp evidence. + +## Expected Test Strategy + +The implementation phase should add deterministic tests in this order: + +1. Schema drift tests proving generated artifacts match the GraphQL source. +2. Structural reading tests proving public payload behavior remains stable. +3. Evidence-label tests proving Echo-native, git-warp-imported, and + fallback-translated facts cannot be confused. +4. Migration parity fixtures comparing imported Echo-backed outputs against + current git-warp-backed outputs. +5. Retirement tests proving normal operation does not open git-warp after + parity is marked complete. + +Tests must assert observable behavior. They should not depend on wall-clock +timing, unseeded randomness, stdout/stderr text, or source-code introspection as +proof. diff --git a/docs/method/backlog/bad-code/CLEAN_remaining-structural-warp-reads-bypass-structural-reading-port.md b/docs/method/backlog/bad-code/CLEAN_remaining-structural-warp-reads-bypass-structural-reading-port.md index d86d715..a77325a 100644 --- a/docs/method/backlog/bad-code/CLEAN_remaining-structural-warp-reads-bypass-structural-reading-port.md +++ b/docs/method/backlog/bad-code/CLEAN_remaining-structural-warp-reads-bypass-structural-reading-port.md @@ -30,17 +30,36 @@ That is acceptable for the first port slice, but it means the long-term rule is not fully true yet: Graft does not have every structural read behind a single Continuum-shaped evidence boundary. +The deeper correction is now schema-first, not port-extension-first. Graft must +define canonical structural history facts in GraphQL, Wesley must generate the +contracts, and Echo must become the primary substrate. The remaining direct +WARP reads should move behind that generated structural model instead of +teaching the hand-authored transitional port to mirror git-warp's shape. + ## Risk If these paths remain as direct WARP reads, future Echo or Continuum-native adapter work can drift surface by surface. That makes it easier to accidentally treat Continuum-shaped compatibility data as native witness evidence. +There is a second risk: a quick Echo migration could hand-translate the +git-warp graph model into Echo and leave Graft depending on git-warp-native +concepts as if they were canonical. That would make the migration faster in the +short term and structurally wrong in the long term. + ## Desired Outcome -Move the remaining structural WARP-backed surfaces behind -`StructuralReadingPort` in follow-up slices, preserving public response schemas -unless a separate design packet explicitly changes them. +Move the remaining structural WARP-backed surfaces behind the schema-first +structural reading boundary: + +1. GraphQL defines canonical Graft structural facts. +2. Wesley generates the read model, validators, and Echo-facing contracts. +3. Echo becomes the default structural history substrate. +4. Existing git-warp facts are imported as provenance-preserving + `git-warp-imported` evidence or read through temporary + `fallback-translated` compatibility. +5. Public response schemas stay stable unless a separate design packet + explicitly changes them. ## Acceptance Criteria @@ -50,3 +69,7 @@ unless a separate design packet explicitly changes them. - Precision/code lookup paths either consume normalized structural readings or are explicitly documented as non-structural WARP utilities. - No git-warp committed-history evidence is modeled as a Continuum witness. +- No git-warp-native concept becomes canonical in the Graft GraphQL schema by + accident. +- Normal Graft operation no longer opens git-warp after Echo import parity is + proven. diff --git a/docs/method/backlog/dependency-dag.dot b/docs/method/backlog/dependency-dag.dot index c83b9d4..78c1c52 100644 --- a/docs/method/backlog/dependency-dag.dot +++ b/docs/method/backlog/dependency-dag.dot @@ -13,7 +13,7 @@ digraph backlog { subgraph cluster_up_next { label="up-next (1)" labeljust=l fontsize=9 fontcolor="#555555" style=rounded color="#cccccc" bgcolor="#fafafa" - up_next_CORE_continuum_structural_reading_port [label="CORE-continuum-structural-reading-port - L" fillcolor="#E5E7EB" penwidth=2] + up_next_CORE_structural_history_schema_and_echo_migration [label="CORE-structural-history-schema-and-echo-migration - XL" fillcolor="#E5E7EB" penwidth=2] } subgraph cluster_v0_8_0 { diff --git a/docs/method/backlog/dependency-dag.svg b/docs/method/backlog/dependency-dag.svg index a2277e6..60bdf34 100644 --- a/docs/method/backlog/dependency-dag.svg +++ b/docs/method/backlog/dependency-dag.svg @@ -4,815 +4,815 @@ - + backlog - -Active backlog graph generated from docs/method/backlog/*/*.md + +Active backlog graph generated from docs/method/backlog/*/*.md cluster_up_next - + up-next (1) cluster_v0_8_0 - -v0.8.0 (26) + +v0.8.0 (26) cluster_bad_code - -bad-code (1) + +bad-code (1) cluster_cool_ideas - -Cool Ideas (74) + +Cool Ideas (74) cluster_external - -External blockers + +External blockers cluster_unresolved - -Unresolved internal refs + +Unresolved internal refs cluster_legend - -Legend + +Legend - + -up_next_CORE_continuum_structural_reading_port - -CORE-continuum-structural-reading-port - L +up_next_CORE_structural_history_schema_and_echo_migration + +CORE-structural-history-schema-and-echo-migration - XL v0_8_0_CORE_c_structural_parsing - -CORE-c-structural-parsing - M + +CORE-c-structural-parsing - M v0_8_0_CORE_cpp_structural_parsing - -CORE-cpp-structural-parsing - L + +CORE-cpp-structural-parsing - L v0_8_0_CORE_csharp_structural_parsing - -CORE-csharp-structural-parsing - M + +CORE-csharp-structural-parsing - M v0_8_0_CORE_go_structural_parsing - -CORE-go-structural-parsing - S + +CORE-go-structural-parsing - S v0_8_0_CORE_hcl_structured_config - -CORE-hcl-structured-config - M + +CORE-hcl-structured-config - M v0_8_0_CORE_java_structural_parsing - -CORE-java-structural-parsing - M + +CORE-java-structural-parsing - M v0_8_0_CORE_json_structured_config - -CORE-json-structured-config - S + +CORE-json-structured-config - S v0_8_0_CORE_jupyter_notebook_structure - -CORE-jupyter-notebook-structure - M + +CORE-jupyter-notebook-structure - M v0_8_0_CORE_kotlin_structural_parsing - -CORE-kotlin-structural-parsing - M + +CORE-kotlin-structural-parsing - M v0_8_0_CORE_php_structural_parsing - -CORE-php-structural-parsing - M + +CORE-php-structural-parsing - M v0_8_0_CORE_pr_review_structural_summary - -CORE-pr-review-structural-summary - M + +CORE-pr-review-structural-summary - M v0_8_0_CORE_python_structural_parsing - -CORE-python-structural-parsing - S + +CORE-python-structural-parsing - S v0_8_0_CORE_ruby_structural_parsing - -CORE-ruby-structural-parsing - M + +CORE-ruby-structural-parsing - M v0_8_0_CORE_shell_structural_parsing - -CORE-shell-structural-parsing - M + +CORE-shell-structural-parsing - M v0_8_0_CORE_sql_structural_parsing - -CORE-sql-structural-parsing - M + +CORE-sql-structural-parsing - M v0_8_0_CORE_structural_test_coverage_map - -CORE-structural-test-coverage-map - M + +CORE-structural-test-coverage-map - M v0_8_0_CORE_swift_structural_parsing - -CORE-swift-structural-parsing - M + +CORE-swift-structural-parsing - M v0_8_0_CORE_toml_structured_config - -CORE-toml-structured-config - S + +CORE-toml-structured-config - S v0_8_0_CORE_tool_context_injection_contracts - -CORE-tool-context-injection-contracts - M + +CORE-tool-context-injection-contracts - M v0_8_0_CORE_yaml_structured_config - -CORE-yaml-structured-config - M + +CORE-yaml-structured-config - M v0_8_0_SURFACE_git_graft_enhance_provenance_hints - -SURFACE-git-graft-enhance-provenance-hints + +SURFACE-git-graft-enhance-provenance-hints v0_8_0_SURFACE_pr_feedback_resolution_ledger - -SURFACE-pr-feedback-resolution-ledger - M + +SURFACE-pr-feedback-resolution-ledger - M v0_8_0_SURFACE_review_cooldown_status - -SURFACE-review-cooldown-status - S + +SURFACE-review-cooldown-status - S v0_8_0_TEST_bounded_subprocess_policy - -TEST-bounded-subprocess-policy - S + +TEST-bounded-subprocess-policy - S v0_8_0_WARP_dead_symbol_detection - -WARP-dead-symbol-detection - S + +WARP-dead-symbol-detection - S v0_8_0_WARP_symbol_history_timeline - -WARP-symbol-history-timeline - S + +WARP-symbol-history-timeline - S cool_ideas_WARP_temporal_structural_search - -WARP-temporal-structural-search - M + +WARP-temporal-structural-search - M v0_8_0_WARP_symbol_history_timeline->cool_ideas_WARP_temporal_structural_search - - -blocked_by/blocking + + +blocked_by/blocking bad_code_CLEAN_remaining_structural_warp_reads_bypass_structural_reading_port - -CLEAN-remaining-structural-warp-reads-bypass-structural-reading-port - M + +CLEAN-remaining-structural-warp-reads-bypass-structural-reading-port - M cool_ideas_bounded_neighborhood_for_references - -bounded-neighborhood-for-references - S + +bounded-neighborhood-for-references - S cool_ideas_CI_001_causal_collapse_visualizer - -CI-001-causal-collapse-visualizer - L + +CI-001-causal-collapse-visualizer - L cool_ideas_CI_002_deterministic_scenario_replay - -CI-002-deterministic-scenario-replay - L + +CI-002-deterministic-scenario-replay - L cool_ideas_CI_003_mcp_native_diff_protocol - -CI-003-mcp-native-diff-protocol - M + +CI-003-mcp-native-diff-protocol - M cool_ideas_CLEAN_CODE_parallel_agent_merge_shared_file_loss - -CLEAN-CODE-parallel-agent-merge-shared-file-loss - M + +CLEAN-CODE-parallel-agent-merge-shared-file-loss - M cool_ideas_CORE_agent_handoff_protocol - -CORE-agent-handoff-protocol - M + +CORE-agent-handoff-protocol - M cool_ideas_CORE_auto_focus - -CORE-auto-focus - L + +CORE-auto-focus - L cool_ideas_CORE_capture_range - -CORE-capture-range - S + +CORE-capture-range - S cool_ideas_CORE_constructor_in_disguise_lint - -CORE-constructor-in-disguise-lint - M + +CORE-constructor-in-disguise-lint - M cool_ideas_CORE_context_budget_forecasting - -CORE-context-budget-forecasting - M + +CORE-context-budget-forecasting - M cool_ideas_CORE_conversation_primer - -CORE-conversation-primer - M + +CORE-conversation-primer - M cool_ideas_CORE_cross_session_resume - -CORE-cross-session-resume - S + +CORE-cross-session-resume - S cool_ideas_CORE_graft_as_teacher - -CORE-graft-as-teacher - S + +CORE-graft-as-teacher - S cool_ideas_CORE_graft_teach_learning_receipts - -CORE-graft-teach-learning-receipts - S + +CORE-graft-teach-learning-receipts - S cool_ideas_CORE_graft_tool_client - -CORE-graft-tool-client - M + +CORE-graft-tool-client - M cool_ideas_CORE_horizon_of_readability - -CORE-horizon-of-readability - M + +CORE-horizon-of-readability - M cool_ideas_CORE_lagrangian_policy - -CORE-lagrangian-policy - XL + +CORE-lagrangian-policy - XL cool_ideas_CORE_migrate_to_slice_first_reads - -CORE-migrate-to-slice-first-reads + +CORE-migrate-to-slice-first-reads cool_ideas_CORE_multi_agent_conflict_detection - -CORE-multi-agent-conflict-detection - L + +CORE-multi-agent-conflict-detection - L cool_ideas_CORE_policy_playground - -CORE-policy-playground - S + +CORE-policy-playground - S cool_ideas_CORE_policy_profiles - -CORE-policy-profiles - M + +CORE-policy-profiles - M cool_ideas_CORE_self_tuning_governor - -CORE-self-tuning-governor - M + +CORE-self-tuning-governor - M cool_ideas_CORE_session_knowledge_map - -CORE-session-knowledge-map - S + +CORE-session-knowledge-map - S cool_ideas_CORE_speculative_read_cost - -CORE-speculative-read-cost - S + +CORE-speculative-read-cost - S cool_ideas_CORE_structural_session_replay - -CORE-structural-session-replay - M + +CORE-structural-session-replay - M cool_ideas_CORE_wire_primitives_into_runtime - -CORE-wire-primitives-into-runtime - M + +CORE-wire-primitives-into-runtime - M cool_ideas_monitor_tick_ceiling_tracking - -monitor-tick-ceiling-tracking - S + +monitor-tick-ceiling-tracking - S cool_ideas_WARP_background_indexing - -WARP-background-indexing - M + +WARP-background-indexing - M cool_ideas_monitor_tick_ceiling_tracking->cool_ideas_WARP_background_indexing - - -blocked_by/blocking + + +blocked_by/blocking cool_ideas_SURFACE_active_causal_workspace_status - -SURFACE-active-causal-workspace-status - M + +SURFACE-active-causal-workspace-status - M cool_ideas_SURFACE_ide_native_graft_integration - -SURFACE-ide-native-graft-integration - XL + +SURFACE-ide-native-graft-integration - XL cool_ideas_SURFACE_active_causal_workspace_status->cool_ideas_SURFACE_ide_native_graft_integration - - -blocked_by/blocking + + +blocked_by/blocking cool_ideas_SURFACE_attach_to_existing_causal_session - -SURFACE-attach-to-existing-causal-session - M + +SURFACE-attach-to-existing-causal-session - M cool_ideas_SURFACE_bijou_daemon_control_plane_actions - -SURFACE-bijou-daemon-control-plane-actions - L + +SURFACE-bijou-daemon-control-plane-actions - L cool_ideas_SURFACE_bijou_daemon_status_live_refresh - -SURFACE-bijou-daemon-status-live-refresh - M + +SURFACE-bijou-daemon-status-live-refresh - M cool_ideas_SURFACE_git_graft_enhance_expanded_git_subcommands - -SURFACE-git-graft-enhance-expanded-git-subcommands + +SURFACE-git-graft-enhance-expanded-git-subcommands cool_ideas_SURFACE_graft_review_pr_number_adapter - -SURFACE-graft-review-pr-number-adapter - M + +SURFACE-graft-review-pr-number-adapter - M cool_ideas_SURFACE_init_dry_run - -SURFACE-init-dry-run - S + +SURFACE-init-dry-run - S cool_ideas_SURFACE_local_history_dag_render_mode_and_count_legend - -SURFACE-local-history-dag-render-mode-and-count-legend - S + +SURFACE-local-history-dag-render-mode-and-count-legend - S cool_ideas_SURFACE_non_codex_instruction_bootstrap_parity - -SURFACE-non-codex-instruction-bootstrap-parity - M + +SURFACE-non-codex-instruction-bootstrap-parity - M cool_ideas_SURFACE_offer_rename_refactor - -SURFACE-offer-rename-refactor - L + +SURFACE-offer-rename-refactor - L cool_ideas_SURFACE_terminal_activity_browser_tui - -SURFACE-terminal-activity-browser-tui - L + +SURFACE-terminal-activity-browser-tui - L cool_ideas_traverse_plus_query_hydration_helper - -traverse-plus-query-hydration-helper - S + +traverse-plus-query-hydration-helper - S cool_ideas_WARP_adaptive_projection_selection - -WARP-adaptive-projection-selection - L + +WARP-adaptive-projection-selection - L cool_ideas_WARP_agent_action_provenance - -WARP-agent-action-provenance - XL + +WARP-agent-action-provenance - XL cool_ideas_WARP_agent_action_provenance->cool_ideas_CI_001_causal_collapse_visualizer - - -blocked_by/blocking + + +blocked_by/blocking cool_ideas_WARP_causal_write_tracking - -WARP-causal-write-tracking - L + +WARP-causal-write-tracking - L cool_ideas_WARP_agent_action_provenance->cool_ideas_WARP_causal_write_tracking - - -blocked_by/blocking + + +blocked_by/blocking cool_ideas_WARP_intent_and_decision_events - -WARP-intent-and-decision-events - M + +WARP-intent-and-decision-events - M cool_ideas_WARP_agent_action_provenance->cool_ideas_WARP_intent_and_decision_events - - -blocked_by/blocking + + +blocked_by/blocking cool_ideas_WARP_provenance_dag - -WARP-provenance-dag - L + +WARP-provenance-dag - L cool_ideas_WARP_agent_action_provenance->cool_ideas_WARP_provenance_dag - - -blocked_by/blocking + + +blocked_by/blocking cool_ideas_WARP_auto_breaking_change_detection - -WARP-auto-breaking-change-detection - L + +WARP-auto-breaking-change-detection - L cool_ideas_WARP_budget_elasticity - -WARP-budget-elasticity - M + +WARP-budget-elasticity - M cool_ideas_WARP_causal_blame_for_staged_artifacts - -WARP-causal-blame-for-staged-artifacts - L + +WARP-causal-blame-for-staged-artifacts - L cool_ideas_WARP_codebase_entropy_trajectory - -WARP-codebase-entropy-trajectory - M + +WARP-codebase-entropy-trajectory - M cool_ideas_WARP_counterfactual_refactoring - -WARP-counterfactual-refactoring - XL + +WARP-counterfactual-refactoring - XL cool_ideas_WARP_codebase_entropy_trajectory->cool_ideas_WARP_counterfactual_refactoring - - -blocked_by/blocking + + +blocked_by/blocking cool_ideas_WARP_codebase_signature - -WARP-codebase-signature - L + +WARP-codebase-signature - L cool_ideas_WARP_structural_impact_prediction - -WARP-structural-impact-prediction - XL + +WARP-structural-impact-prediction - XL cool_ideas_WARP_counterfactual_refactoring->cool_ideas_WARP_structural_impact_prediction - - -blocked_by/blocking + + +blocked_by/blocking cool_ideas_WARP_degeneracy_warning - -WARP-degeneracy-warning - M + +WARP-degeneracy-warning - M cool_ideas_WARP_drift_sentinel - -WARP-drift-sentinel - M + +WARP-drift-sentinel - M cool_ideas_WARP_footprint_parallelism - -WARP-footprint-parallelism - XL + +WARP-footprint-parallelism - XL cool_ideas_WARP_graft_pack - -WARP-graft-pack - M + +WARP-graft-pack - M cool_ideas_WARP_grouped_aggregate_queries - -WARP-grouped-aggregate-queries - M + +WARP-grouped-aggregate-queries - M cool_ideas_WARP_intentional_degeneracy_privacy - -WARP-intentional-degeneracy-privacy - M + +WARP-intentional-degeneracy-privacy - M cool_ideas_WARP_minimum_viable_context - -WARP-minimum-viable-context - M + +WARP-minimum-viable-context - M cool_ideas_WARP_outline_diff_commit_trailer - -WARP-outline-diff-commit-trailer - S + +WARP-outline-diff-commit-trailer - S cool_ideas_WARP_projection_safety_classes - -WARP-projection-safety-classes - M + +WARP-projection-safety-classes - M cool_ideas_WARP_provenance_dag->cool_ideas_WARP_causal_blame_for_staged_artifacts - - -blocked_by/blocking + + +blocked_by/blocking cool_ideas_WARP_reasoning_trace_replay - -WARP-reasoning-trace-replay - M + +WARP-reasoning-trace-replay - M cool_ideas_WARP_provenance_dag->cool_ideas_WARP_reasoning_trace_replay - - -blocked_by/blocking + + +blocked_by/blocking cool_ideas_WARP_rulial_heat_map - -WARP-rulial-heat-map - L + +WARP-rulial-heat-map - L cool_ideas_WARP_semantic_drift_in_sessions - -WARP-semantic-drift-in-sessions - M + +WARP-semantic-drift-in-sessions - M cool_ideas_WARP_semantic_merge_conflict_prediction - -WARP-semantic-merge-conflict-prediction - L + +WARP-semantic-merge-conflict-prediction - L cool_ideas_WARP_session_filtration - -WARP-session-filtration - L + +WARP-session-filtration - L cool_ideas_WARP_shadow_structural_workspaces - -WARP-shadow-structural-workspaces - XL + +WARP-shadow-structural-workspaces - XL cool_ideas_WARP_speculative_merge - -WARP-speculative-merge - XL + +WARP-speculative-merge - XL cool_ideas_WARP_stale_docs_checker - -WARP-stale-docs-checker - M + +WARP-stale-docs-checker - M cool_ideas_WARP_stale_docs_checker->cool_ideas_WARP_drift_sentinel - - -blocked_by/blocking + + +blocked_by/blocking cool_ideas_WARP_structural_drift_detection - -WARP-structural-drift-detection - M + +WARP-structural-drift-detection - M cool_ideas_WARP_symbol_heatmap - -WARP-symbol-heatmap - M + +WARP-symbol-heatmap - M cool_ideas_WARP_technical_debt_curvature - -WARP-technical-debt-curvature - L + +WARP-technical-debt-curvature - L external_git_warp_observer_geometry_ladder__Rung_2_4_ - -git-warp observer geometry ladder (Rung 2-4) + +git-warp observer geometry ladder (Rung 2-4) external_git_warp_observer_geometry_ladder__Rung_2_4_->cool_ideas_CORE_migrate_to_slice_first_reads - - -blocked_by_external + + +blocked_by_external unresolved_CLEAN_CODE_export_diff_semver_signature_as_patch - -missing: CLEAN_CODE_export-diff-semver-signature-as-patch + +missing: CLEAN_CODE_export-diff-semver-signature-as-patch unresolved_CLEAN_CODE_export_diff_semver_signature_as_patch->cool_ideas_WARP_auto_breaking_change_detection - - -blocked_by + + +blocked_by unresolved_CLEAN_CODE_export_diff_semver_signature_as_patch->cool_ideas_WARP_semantic_merge_conflict_prediction - - -blocked_by + + +blocked_by leg_v08 - -v0.8.0 + +v0.8.0 leg_v07 - -v0.7.0 + +v0.7.0 leg_bad - -bad-code + +bad-code leg_idea - -cool-ideas + +cool-ideas leg_external - -external blocker + +external blocker leg_unresolved - -unresolved ref + +unresolved ref diff --git a/docs/method/backlog/up-next/CORE_structural-history-schema-and-echo-migration.md b/docs/method/backlog/up-next/CORE_structural-history-schema-and-echo-migration.md new file mode 100644 index 0000000..1eec420 --- /dev/null +++ b/docs/method/backlog/up-next/CORE_structural-history-schema-and-echo-migration.md @@ -0,0 +1,134 @@ +--- +title: "Structural history schema and Echo migration" +feature: core +kind: architecture +legend: CORE +lane: up-next +priority: 1 +effort: XL +requirements: + - "Graft owns structural semantics" + - "Wesley owns generated contracts" + - "Echo owns causal-history storage and execution" + - "git-warp remains available as legacy import and compatibility input" + - "Existing public Graft commands preserve their behavior through migration" +acceptance_criteria: + - "GraphQL defines canonical Graft structural facts" + - "Wesley generates the TypeScript read model, validators, and Echo-facing contracts" + - "Existing public Graft commands keep their behavior" + - "Evidence labels distinguish Echo-native, git-warp-imported, and fallback-translated facts" + - "Migration validates parity against current git-warp-backed outputs" + - "Normal operation no longer opens git-warp after parity is proven" +--- + +# Structural history schema and Echo migration + +## Hill + +Graft's structural history becomes schema-first under Wesley and Echo-backed by +default, while git-warp is demoted to a provenance-preserving migration source +and optional compatibility bridge. + +This is not a storage-adapter swap. The real decision is that Graft stops +treating git-warp's model as authority and defines its own structural history +schema. + +## Laws + +1. Graft owns structural semantics. +2. Wesley owns generated contracts. +3. Echo owns causal-history storage and execution. +4. git-warp owns only legacy import and compatibility. +5. No git-warp-native concept becomes canonical by accident. + +## Why + +Echo is the faster and more scalable causal-history substrate for Graft's long +histories. git-warp remains useful as the current committed-history source, but +Graft should not keep treating git-warp's graph model as the canonical shape of +code history. + +The dangerous path is: + +```text +git-warp graph model + -> hand-translated Echo model + -> Graft keeps depending on old concepts +``` + +That would preserve adapter-shaped technical debt while pretending to migrate. + +The correct path is schema authority first: + +```text +Graft GraphQL structural history schema + -> Wesley-generated contracts + -> Echo-backed primary structural history + -> git-warp one-time import and fallback compatibility +``` + +Both Echo and git-warp can move toward Wesley GraphQL contracts, but Graft's +structural facts must still be named by Graft. Echo is a substrate, not the +semantic owner of code structure. + +## Implementation path + +1. Define the canonical Graft structural history model in GraphQL. +2. Make Wesley generate the TypeScript read model, Zod validators, Echo-facing + contracts, and storage artifacts from that single source of truth. +3. Add drift checks that fail if generated artifacts or runtime contracts are + edited by hand or fall out of sync with the GraphQL schema. +4. Teach Graft's structural reads to consume the generated read model through + `StructuralReadingPort`. +5. Import current git-warp structural history into Echo as + `git-warp-imported` evidence with provenance. +6. Keep a fallback git-warp adapter only as `fallback-translated` evidence while + migration parity is being proven. +7. Validate parity for current public surfaces such as review, dead symbols, + blame, difficulty, structural log, churn, and precision/code lookup where + they expose structural facts. +8. Stop opening git-warp during normal Graft operation after parity is proven. + +## Evidence labels + +Graft's structural reading evidence must make the provenance status explicit: + +- `echo-native`: facts written, stored, and read through the Wesley-generated + Echo-backed structural history model. +- `git-warp-imported`: facts imported once from git-warp into the canonical + Graft schema with preserved source provenance. +- `fallback-translated`: facts read through git-warp compatibility after the + schema exists, useful only while parity gaps remain. + +These labels are separate from Continuum witnesshood. A fact can be +Continuum-shaped without being a Continuum-native witness. + +## Non-goals + +- Do not hand-port git-warp's graph model into Echo. +- Do not change Echo to understand Graft semantics manually. +- Do not treat git-warp concepts as canonical because they are convenient. +- Do not change public command behavior during the migration unless a later + packet explicitly authorizes a surface change. +- Do not delete git-warp support until import parity and fallback behavior are + proven. +- Do not keep parallel hand-maintained TypeScript, Zod, SQL, and Echo Rust + models after Wesley generation exists. + +## First slice + +The first implementation slice should create the schema authority, not the full +runtime migration: + +1. Add the initial Graft structural history GraphQL schema. +2. Add or configure Wesley generation for at least the TypeScript/Zod side and + the Echo-facing contract target expected by the stack. +3. Add deterministic drift tests around generated artifacts. +4. Map the current `StructuralReadingPort` payloads to the generated model + without changing public command outputs. +5. Document which current git-warp facts will become imported evidence versus + fallback-translated evidence. + +This may feel slower than adapting git-warp output straight into Echo. That +slowness is the guardrail: schema authority must exist before migration so the +migration does not become the architecture. diff --git a/docs/method/backlog/up-next/CORE_continuum-structural-reading-port.md b/docs/method/graveyard/CORE_continuum-structural-reading-port.md similarity index 92% rename from docs/method/backlog/up-next/CORE_continuum-structural-reading-port.md rename to docs/method/graveyard/CORE_continuum-structural-reading-port.md index de9c0e5..0058f84 100644 --- a/docs/method/backlog/up-next/CORE_continuum-structural-reading-port.md +++ b/docs/method/graveyard/CORE_continuum-structural-reading-port.md @@ -3,9 +3,10 @@ title: "Continuum structural reading port" feature: core kind: architecture legend: CORE -lane: up-next +lane: graveyard priority: 1 effort: L +status: superseded requirements: - "v0.8.0 Review Truth release branch remains release-focused" - "Continuum runtime-boundary family: ObserverPlan, ObservationRequest, ReadingEnvelope, WitnessedSuffixShell, CausalSuffixBundle, ImportOutcome" @@ -23,6 +24,17 @@ acceptance_criteria: # Continuum structural reading port +## Disposition + +The first slice of this card landed in PR #55 and introduced +`StructuralReadingPort` for `graft_review` and `graft_dead_symbols`. + +The remaining direction is superseded by +[CORE_structural-history-schema-and-echo-migration](../backlog/up-next/CORE_structural-history-schema-and-echo-migration.md). +The active correction is schema authority first: Graft owns structural +semantics, Wesley generates contracts, Echo becomes the primary causal-history +substrate, and git-warp becomes legacy import/compatibility. + ## Hill Make Graft's structural memory boundary Continuum-shaped, not From bbad46c81670f3203521ec5e2f6d241a67775755 Mon Sep 17 00:00:00 2001 From: James Ross Date: Sat, 16 May 2026 12:03:52 -0700 Subject: [PATCH 2/2] docs: clarify echo wesley integration boundary --- NORTHSTAR.md | 37 +++++++++------- docs/BEARING.md | 10 +++-- ...tural-history-schema-and-echo-migration.md | 43 ++++++++++++------- ...tural-history-schema-and-echo-migration.md | 33 ++++++++------ 4 files changed, 76 insertions(+), 47 deletions(-) diff --git a/NORTHSTAR.md b/NORTHSTAR.md index d98971d..e56e9b7 100644 --- a/NORTHSTAR.md +++ b/NORTHSTAR.md @@ -75,11 +75,13 @@ schema authority before substrate migration. ``` Graft must define its structural history in GraphQL first. Wesley then -generates the TypeScript read model, validators, Echo-facing contracts, +generates the TypeScript read model, validators, Echo-consumable contracts, SQL/storage artifacts, and other runtime targets from that single source of -truth. 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. +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: @@ -87,7 +89,7 @@ The stack split is: | :--- | :--- | :--- | | Shared semantics | Continuum | Shared contract families, witness language, admission and compatibility nouns, registry truth. | | Graft structural schema | Graft | Canonical GraphQL structural history facts, code-aware reading semantics, and migration parity rules. | -| Compilation | Wesley | Generated artifacts, manifests, codecs, TypeScript read models, validators, SQL/storage artifacts, Echo-facing contracts, and witness tooling. | +| 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. | @@ -173,7 +175,7 @@ The long-term path is: ```text Graft GraphQL structural history schema - -> Wesley-generated TypeScript / Zod / Echo / SQL artifacts + -> existing Wesley compiler outputs for TypeScript / Zod / Echo / SQL -> Echo-backed primary structural history -> ObservationRequest / ObserverPlan -> StructuralReadingPort @@ -184,8 +186,8 @@ Graft GraphQL structural history schema In practice: - Graft defines canonical structural facts in GraphQL. -- Wesley generates every contract target from that file so TypeScript, - validators, SQL/storage artifacts, and Echo-facing files cannot drift. +- 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 @@ -230,8 +232,9 @@ outcome is that every caller gets the same truth posture. ## Boundary Laws 1. Graft owns structural semantics. -2. Wesley owns generated contracts. -3. Echo owns causal-history storage and execution. +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. @@ -262,7 +265,7 @@ The move is: ```text git-warp-shaped implementation -> Graft GraphQL structural history schema - -> Wesley-generated contracts + -> existing Wesley compiler outputs -> Echo-backed primary structural store/read model -> git-warp one-time import with provenance -> parity validation against current public outputs @@ -279,8 +282,9 @@ architecture honest. 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 Wesley to generate the TypeScript read model, validators, Echo-facing - contracts, and storage artifacts from that schema. +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, @@ -306,7 +310,7 @@ We know the north star is becoming real when these things are boring: Graft schema. - API, CLI, and MCP callers receive the same basis, freshness, residual, support, evidence-status, and payload identity posture. -- Generated TypeScript, validators, Echo-facing contracts, and storage +- 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. @@ -314,8 +318,9 @@ We know the north star is becoming real when these things are boring: 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 diff --git a/docs/BEARING.md b/docs/BEARING.md index c49d4be..ddb7038 100644 --- a/docs/BEARING.md +++ b/docs/BEARING.md @@ -13,8 +13,9 @@ timeline ### 1. Structural History Schema and Echo Migration - Graft defines canonical structural history facts in GraphQL. -- Wesley generates TypeScript read models, validators, Echo-facing contracts, - SQL/storage artifacts, and drift witnesses from that schema. +- 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 @@ -89,8 +90,9 @@ The immediate focus is **schema authority before substrate migration**. as the next design/implementation cycle. 3. Define Graft's canonical structural history facts in GraphQL before adapting more git-warp output. -4. Use Wesley to generate the TypeScript/Zod read model, Echo-facing - contracts, storage artifacts, and drift witnesses from that schema. +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`, diff --git a/docs/design/CORE_structural-history-schema-and-echo-migration.md b/docs/design/CORE_structural-history-schema-and-echo-migration.md index 947a26a..c6eea70 100644 --- a/docs/design/CORE_structural-history-schema-and-echo-migration.md +++ b/docs/design/CORE_structural-history-schema-and-echo-migration.md @@ -32,8 +32,9 @@ can fossilize git-warp's model. ## Laws 1. Graft owns structural semantics. -2. Wesley owns generated contracts. -3. Echo owns causal-history storage and execution. +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. @@ -51,12 +52,15 @@ can fossilize git-warp's model. operation? - [ ] Can a human verify that git-warp remains a provenance-preserving legacy source instead of a hidden authority? +- [ ] Can a human verify that the cycle does not require Echo or Wesley repo + changes? ### Agent - [ ] Does GraphQL define canonical Graft structural facts? -- [ ] Does Wesley generate TypeScript read models, validators, and Echo-facing - contracts from that single source of truth? +- [ ] Does Graft use the existing Wesley toolchain to derive TypeScript read + models, validators, and Echo-consumable contracts from that single source + of truth? - [ ] Do drift tests fail when generated artifacts or runtime contracts stop matching the GraphQL schema? - [ ] Do migration parity tests compare Echo-backed outputs against the current @@ -82,15 +86,20 @@ The correct path is: ```text Graft GraphQL structural history schema - -> Wesley-generated TypeScript / Zod / Echo / SQL artifacts + -> existing Wesley compiler outputs for TypeScript / Zod / Echo / SQL -> Echo-backed primary structural history -> git-warp one-time import and fallback compatibility ``` Schema authority comes first. Echo is a fast causal-history substrate. Wesley is -the compiler that prevents drift across TypeScript, validators, SQL, Echo Rust -files, and other generated artifacts. Graft owns the structural facts being -modeled. +the existing compiler that prevents drift across TypeScript, validators, SQL, +Echo-consumable contract artifacts, and other generated outputs. Graft owns the +structural facts being modeled. + +This design does not require modifying Echo or Wesley. If the existing Wesley +compiler or Echo contract surface cannot support the schema, that is an +upstream blocker to record separately rather than work to fold into this Graft +cycle. ## Canonical Model Boundary @@ -168,7 +177,7 @@ may normalize structural readings into Continuum-compatible shape. The migration should be explicit and auditable: -1. Create the Wesley-owned schema generation boundary. +1. Create the Graft-owned GraphQL schema boundary and local Wesley invocation. 2. Make Echo the primary write/read substrate for new structural facts. 3. Import current git-warp structural data into the canonical schema with `git-warp-imported` evidence. @@ -196,7 +205,7 @@ derived artifacts: - TypeScript read model - Zod or equivalent runtime validators -- Echo-facing contracts and Rust files +- Echo-consumable contract artifacts produced by the existing Wesley toolchain - SQL/storage artifacts where needed - schema identity, generation manifest, and drift witness @@ -207,15 +216,18 @@ The repo must not allow parallel models to diverge: - no hand-maintained Echo model that silently differs from GraphQL - no migration importer that smuggles git-warp-only concepts into the canonical schema +- no Graft branch that changes Wesley just to make a Graft-local schema concept + work ## Echo Boundary Echo is deliberately dumb from Graft's perspective. Graft should not change Echo to understand Graft semantics manually. -Graft declares structural history in GraphQL. Wesley compiles the Echo-facing -contracts. Echo stores and executes causal history through those generated -contracts. Graft consumes normalized structural payloads through its own ports. +Graft declares structural history in GraphQL. The existing Wesley toolchain +compiles the Echo-consumable contracts. Echo stores and executes causal history +through those generated contracts. Graft consumes normalized structural payloads +through its own ports. That keeps substrate performance and semantic authority separate. @@ -281,13 +293,14 @@ API / CLI / MCP use case - Do not hand-port git-warp's graph model into Echo. - Do not change Echo to understand Graft semantics manually. +- Do not change Wesley to understand Graft semantics manually. - Do not model git-warp internals as canonical Graft facts. - Do not change public command behavior during the migration unless a later packet explicitly authorizes a surface change. - Do not remove git-warp support before import parity and fallback behavior are proven. -- Do not keep parallel hand-maintained TypeScript, Zod, SQL, and Echo Rust - models once Wesley generation exists. +- Do not keep parallel hand-maintained TypeScript, Zod, SQL, and + Echo-consumable contract models once Wesley generation exists. - Do not claim Continuum-native witnesshood for imported or translated git-warp evidence. diff --git a/docs/method/backlog/up-next/CORE_structural-history-schema-and-echo-migration.md b/docs/method/backlog/up-next/CORE_structural-history-schema-and-echo-migration.md index 1eec420..ca36cd4 100644 --- a/docs/method/backlog/up-next/CORE_structural-history-schema-and-echo-migration.md +++ b/docs/method/backlog/up-next/CORE_structural-history-schema-and-echo-migration.md @@ -8,13 +8,13 @@ priority: 1 effort: XL requirements: - "Graft owns structural semantics" - - "Wesley owns generated contracts" - - "Echo owns causal-history storage and execution" + - "Graft consumes existing Wesley compiler outputs" + - "Echo remains an unchanged causal-history storage and execution substrate" - "git-warp remains available as legacy import and compatibility input" - "Existing public Graft commands preserve their behavior through migration" acceptance_criteria: - "GraphQL defines canonical Graft structural facts" - - "Wesley generates the TypeScript read model, validators, and Echo-facing contracts" + - "Graft uses the existing Wesley toolchain to derive the TypeScript read model, validators, and Echo-consumable contracts" - "Existing public Graft commands keep their behavior" - "Evidence labels distinguish Echo-native, git-warp-imported, and fallback-translated facts" - "Migration validates parity against current git-warp-backed outputs" @@ -36,8 +36,9 @@ schema. ## Laws 1. Graft owns structural semantics. -2. Wesley owns generated contracts. -3. Echo owns causal-history storage and execution. +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. @@ -62,7 +63,7 @@ The correct path is schema authority first: ```text Graft GraphQL structural history schema - -> Wesley-generated contracts + -> existing Wesley compiler outputs -> Echo-backed primary structural history -> git-warp one-time import and fallback compatibility ``` @@ -71,11 +72,17 @@ Both Echo and git-warp can move toward Wesley GraphQL contracts, but Graft's structural facts must still be named by Graft. Echo is a substrate, not the semantic owner of code structure. +This card does not require changing Echo or Wesley. If Graft cannot express the +needed schema through the existing Wesley toolchain and Echo contract surface, +that is an upstream blocker to file separately, not scope to smuggle into this +cycle. + ## Implementation path 1. Define the canonical Graft structural history model in GraphQL. -2. Make Wesley generate the TypeScript read model, Zod validators, Echo-facing - contracts, and storage artifacts from that single source of truth. +2. Wire Graft to the existing Wesley toolchain so the TypeScript read model, + Zod validators, Echo-consumable contracts, and storage artifacts derive from + that single source of truth. 3. Add drift checks that fail if generated artifacts or runtime contracts are edited by hand or fall out of sync with the GraphQL schema. 4. Teach Graft's structural reads to consume the generated read model through @@ -107,13 +114,14 @@ Continuum-shaped without being a Continuum-native witness. - Do not hand-port git-warp's graph model into Echo. - Do not change Echo to understand Graft semantics manually. +- Do not change Wesley to understand Graft semantics manually. - Do not treat git-warp concepts as canonical because they are convenient. - Do not change public command behavior during the migration unless a later packet explicitly authorizes a surface change. - Do not delete git-warp support until import parity and fallback behavior are proven. -- Do not keep parallel hand-maintained TypeScript, Zod, SQL, and Echo Rust - models after Wesley generation exists. +- Do not keep parallel hand-maintained TypeScript, Zod, SQL, and + Echo-consumable contract models after Wesley generation exists. ## First slice @@ -121,8 +129,9 @@ The first implementation slice should create the schema authority, not the full runtime migration: 1. Add the initial Graft structural history GraphQL schema. -2. Add or configure Wesley generation for at least the TypeScript/Zod side and - the Echo-facing contract target expected by the stack. +2. Add only Graft-local Wesley invocation/configuration for at least the + TypeScript/Zod side and the Echo-consumable contract target expected by the + stack. 3. Add deterministic drift tests around generated artifacts. 4. Map the current `StructuralReadingPort` payloads to the generated model without changing public command outputs.