diff --git a/NORTHSTAR.md b/NORTHSTAR.md index bc777ac..f1f3124 100644 --- a/NORTHSTAR.md +++ b/NORTHSTAR.md @@ -59,6 +59,15 @@ or host projection as the primary ontology. The shared boundary is witnessed causal history plus the Continuum-authored contract families that make that history admissible, observable, exportable, and importable. +The critical migration distinction is: + +```text +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 stack split is: | Layer | Owner | Responsibility | @@ -130,6 +139,8 @@ 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 - **payload identity**: digest, version, schema, or generated artifact id - **typed payload**: the actual Graft-owned structural answer @@ -144,7 +155,7 @@ The long-term path is: ```text Continuum shared family -> Wesley-generated artifacts - -> Echo or git-warp runtime publication + -> Echo runtime publication or translated git-warp adapter evidence -> ObservationRequest / ObserverPlan -> ReadingEnvelope-backed runtime result -> Graft structural payload @@ -154,6 +165,8 @@ Continuum shared family 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. - Continuum owns shared runtime-boundary nouns such as `ObserverPlan`, `ObservationRequest`, `ReadingEnvelope`, `WitnessedSuffixShell`, @@ -223,7 +236,8 @@ The move is: git-warp-shaped implementation -> substrate-neutral structural reading port -> git-warp adapter behind the port - -> Continuum runtime-boundary fixtures + -> 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 ``` @@ -236,9 +250,9 @@ architecture honest. 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. -4. Add fixture-backed Continuum runtime-boundary coverage for `ObserverPlan`, - `ObservationRequest`, and `ReadingEnvelope`. + 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. @@ -258,7 +272,7 @@ 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. - API, CLI, and MCP callers receive the same basis, freshness, residual, - support, and payload identity posture. + support, evidence-status, and payload identity posture. - `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 69266f9..9bf2d94 100644 --- a/docs/BEARING.md +++ b/docs/BEARING.md @@ -11,14 +11,24 @@ timeline ## Active Gravity -### 1. Entrypoint Convergence +### 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. + +### 2. Entrypoint Convergence - Formalizing API, CLI, and MCP as equal first-class entry points. - Extracting application services so those three surfaces stop owning business flow. - Establishing baseline capability posture and parity expectations before more surface growth lands. -### 2. WARP Ontology & Causal Collapse +### 3. WARP Ontology & Causal Collapse - Explicit definition of session, strand, and checkout epoch. - Implementation of strand-aware causal collapse (admission of speculative work into canonical history). - Strengthening of symbol identity and rename continuity for precise slicing. @@ -27,12 +37,12 @@ timeline WARP reference and precision paths have been mitigated; medium-severity local-history and newer structural-metric reads remain tracked. -### 3. Multi-Repo Coordination +### 4. Multi-Repo Coordination - Refinement of the Shared Daemon trust boundaries. - System-wide resource pressure and fairness summaries across multiple repos. - Authorization-filtered multi-repo overview surfaces. -### 4. Agentic Observability +### 5. Agentic Observability - Implementation of the Deterministic Scenario Replay pipeline. - Machine-readable between-commit activity views for agents and humans. @@ -58,25 +68,28 @@ enhance, governed-edit, path-boundary, and Dockerized validation spine. `v0.7.1` followed with npm package hygiene: built `dist/` runtime artifacts, no published `src/`, development-only `tsx`, and release publish guards. +`v0.8.0` shipped Review Truth: structural PR summaries, provenance +signals, symbol history, removed-symbol evidence, structural +test-reference signals, review readiness, and broader language/config +parsing. ## Next Target -The immediate focus is **v0.8.0 release prep**, not more feature work. +The immediate focus is the **Continuum-shaped structural reading port**, not a +runtime rewrite. -1. Keep `main` release-clean after `v0.7.1`. -2. Land `v0.8.0` as a **Review Truth** release: structural PR review - summaries, bounded provenance hints, symbol history, removed-symbol - evidence, structural test-reference signals, automated review - readiness, and the first language-breadth stack for Rust, GraphQL, - Python, Go, JSON, TOML, and YAML. -3. Treat remaining `docs/method/backlog/v0.8.0/` cards as follow-up - candidates unless release validation exposes a direct blocker. -4. Do not add METHOD-specific backlog/status features to Graft. METHOD +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 backlog lanes, cards, retros, dependency DAGs, and release truth surfaces belong in Method MCP / Method CLI. -5. Keep `WARP_lsp-enrichment` and `CORE_migrate-to-slice-first-reads` - out of this release. LSP enrichment remains valid optional scope; +6. 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. -6. Treat daemon live refresh and daemon control-plane actions as a - separate daemon-operator lane, not part of the v0.8.0 cut. +7. Treat daemon live refresh and daemon control-plane actions as a + separate daemon-operator lane, not part of this slice. diff --git a/docs/method/backlog/up-next/CORE_continuum-structural-reading-port.md b/docs/method/backlog/up-next/CORE_continuum-structural-reading-port.md index 6d87607..de9c0e5 100644 --- a/docs/method/backlog/up-next/CORE_continuum-structural-reading-port.md +++ b/docs/method/backlog/up-next/CORE_continuum-structural-reading-port.md @@ -12,10 +12,12 @@ requirements: - "Existing Graft WARP/git-warp review, symbol-history, dead-symbol, provenance-hint, and structural-test-reference surfaces" - "Existing API / CLI / MCP capability posture" acceptance_criteria: - - "Graft exposes one substrate-neutral structural reading port that does not import Echo, git-warp, or warp-ttd concrete runtime types" + - "StructuralReadingPort exists as the only Graft-facing structural read boundary" - "The existing git-warp-backed committed-history implementation sits behind that port without changing v0.8.0 review behavior" - - "At least one fixture-backed Continuum runtime-boundary reading drives a Graft structural projection test" - - "Structural reading results name basis, freshness, residual posture, witness or shell reference, and payload identity" + - "git-warp readings are explicitly marked translated/non-Continuum-native" + - "No git-warp commit/range evidence is modeled as a Continuum witness" + - "At least one fixture-backed or Echo-backed test proves the Continuum-native evidence branch" + - "API, CLI, MCP, and rendering paths consume the normalized Graft structural payload instead of substrate-specific facts" - "The design names Graft's proposed Continuum registry role without making Graft the semantic owner of shared families" --- @@ -23,13 +25,16 @@ acceptance_criteria: ## Hill -Make Graft's structural memory boundary Continuum-shaped instead of -`git-warp`-shaped. +Make Graft's structural memory boundary Continuum-shaped, not +Continuum-native. By the end of this slice, Graft should have one explicit structural reading -port that can support the current cold committed-history implementation while -preparing for Echo/live-frontier readings through Continuum-authored boundary -families. +port that accepts Continuum-shaped boundary concepts without requiring every +substrate to publish native Continuum artifacts. + +The first implementation must support the current cold committed-history +implementation while preparing for Echo/live-frontier readings through +Continuum-authored boundary families. ## Why @@ -57,7 +62,9 @@ The stack direction is now clearer: - Graft is the structural-code observer and review engine. Graft should therefore consume and emit structural readings over witnessed -causal history, not treat a materialized graph as the primary ontology. +causal history where native evidence exists, and over explicitly translated +substrate evidence where it does not. A Continuum-shaped payload is not the +same thing as a Continuum-native witness. ## Proposed Continuum role @@ -72,16 +79,48 @@ the same interchange semantics. If a structural payload family becomes shared across tools, promote it into Continuum through the normal family promotion rules instead of copying local DTOs. +## Evidence rule + +Graft may normalize readings into Continuum-compatible shape. Only +Continuum-producing runtimes may claim Continuum-native witnesshood. + +The port should model evidentiary status directly: + +```ts +type StructuralReadingEvidence = + | ContinuumNativeEvidence + | TranslatedSubstrateEvidence; + +type ContinuumNativeEvidence = { + kind: "continuum-native"; + envelope: ReadingEnvelope; + witness?: WitnessedSuffixShell; +}; + +type TranslatedSubstrateEvidence = { + kind: "translated-substrate"; + substrate: "git-warp"; + basis: GitWarpCommittedBasis; + evidence: GitWarpEvidence; + nativeContinuumWitness: false; +}; +``` + +The ugly `nativeContinuumWitness: false` marker is intentional. It prevents a +Git commit/range, git-warp graph fact, or adapter-produced compatibility object +from being laundered into a Continuum witness. + ## Expected shape The first port should describe Graft's needs, not a generic graph database: -- source/basis identity +- basis identity - observation request identity - structural reading kind - current/stale/incomparable freshness - complete/partial/plural/budget-limited/rights-limited/unavailable posture -- witness, receipt, shell, or hologram reference when present +- evidence status: Continuum-native or translated-substrate +- witness, receipt, shell, or hologram reference only when genuinely present - payload digest or identity - typed payload for Graft-owned structural facts @@ -91,6 +130,7 @@ The current git-warp-backed implementation should become one adapter: Graft review / symbol history / dead symbols / test references -> StructuralReadingPort -> git-warp committed-history adapter + -> translated-substrate evidence ``` A future Echo/live-frontier implementation should become another adapter: @@ -100,6 +140,7 @@ Graft live frontier structural projection -> StructuralReadingPort -> Continuum runtime-boundary family -> Echo or jedit head/frontier basis + -> continuum-native evidence ``` `warp-ttd` should consume Graft structural readings as observer artifacts. It @@ -110,20 +151,28 @@ hand-normalized against Echo and `git-warp`. 1. Define the structural reading port in `src/ports/` or the existing core boundary that best matches the local architecture. -2. Model only the minimum basis, request, residual posture, witness reference, - and payload identity needed by current Review Truth behavior. +2. Define `StructuralReadingEvidence` as a union of Continuum-native evidence + and translated substrate evidence. 3. Move current git-warp-facing review/symbol/dead-symbol/test-reference reads behind the port without changing their public output contracts. -4. Add a fixture-backed Continuum runtime-boundary test using the existing - GraphQL fixture posture as input evidence, then replace the fixture with - generated artifacts when the stack is ready. -5. Document the Graft/Continuum/warp-ttd split in the design packet and keep +4. Mark every git-warp committed-history reading as `translated-substrate` with + `nativeContinuumWitness: false`. +5. Add a fixture-backed or Echo-backed Continuum runtime-boundary test proving + the Continuum-native branch, then replace fixtures with generated artifacts + when the stack is ready. +6. Route API, CLI, MCP, and rendering paths through the normalized Graft + structural payload instead of substrate-specific facts. +7. Document the Graft/Continuum/warp-ttd split in the design packet and keep [NORTHSTAR.md](../../../../NORTHSTAR.md) aligned. ## Non-goals - Do not rewrite `v0.8.0` release scope. - Do not replace git-warp in one step. +- Do not require git-warp to publish native Continuum artifacts before it can + back Graft's structural port. +- Do not model git-warp commit/range evidence as a Continuum witness. +- Do not let "Continuum-shaped" imply "Continuum-native". - Do not add a direct Echo dependency before the port boundary exists. - Do not make Graft the owner of Continuum runtime-boundary nouns. - Do not make `warp-ttd` the structural-review engine.