diff --git a/NORTHSTAR.md b/NORTHSTAR.md index f1f3124..e56e9b7 100644 --- a/NORTHSTAR.md +++ b/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 diff --git a/docs/BEARING.md b/docs/BEARING.md index 9bf2d94..ddb7038 100644 --- a/docs/BEARING.md +++ b/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. 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..c6eea70 --- /dev/null +++ b/docs/design/CORE_structural-history-schema-and-echo-migration.md @@ -0,0 +1,322 @@ +--- +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 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. + +## 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? +- [ ] Can a human verify that the cycle does not require Echo or Wesley repo + changes? + +### Agent + +- [ ] Does GraphQL define canonical Graft structural facts? +- [ ] 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 + 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 + -> 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 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 + +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 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. +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-consumable contract artifacts produced by the existing Wesley toolchain +- 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 +- 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. 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. + +## 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 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-consumable contract 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..ca36cd4 --- /dev/null +++ b/docs/method/backlog/up-next/CORE_structural-history-schema-and-echo-migration.md @@ -0,0 +1,143 @@ +--- +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" + - "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" + - "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" + - "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 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. + +## 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 + -> existing Wesley compiler outputs + -> 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. + +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. 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 + `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 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-consumable contract 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 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. +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