From 73ed3ffcc5fae8d3e0e78c4b785b58e5124ff915 Mon Sep 17 00:00:00 2001 From: James Ross Date: Mon, 25 May 2026 08:31:04 -0700 Subject: [PATCH 01/10] docs: Establish v18 release-prep baseline --- docs/BEARING.md | 45 +++++++++++++--- .../v18-release-prep-baseline.md | 51 +++++++++++++++++++ 2 files changed, 88 insertions(+), 8 deletions(-) create mode 100644 docs/design/0245-v18-release-prep-baseline/v18-release-prep-baseline.md diff --git a/docs/BEARING.md b/docs/BEARING.md index c479c881..1ad855ec 100644 --- a/docs/BEARING.md +++ b/docs/BEARING.md @@ -39,18 +39,18 @@ of handwritten adapter folklore. Current branch state at this boundary: -- Current branch: `v18-continuum-slices-66-75` +- Current branch: `v18-release-prep-slices-97-102` - Base branch: `main` -- Current `origin/main`: `d379eb81` -- Latest merged PR: #105, v18 release runway planning +- Current `origin/main`: `023c7d75` +- Latest merged PR: #106, v18 release-candidate evidence and review cleanup - Latest released package line: `17.0.1` - Latest completed implementation cycle: `0244-v18-backlog-reconciliation` -- Current work: backlog reconciliation after the v18 release-candidate - evidence packet, with the next goalpost narrowed to public release-prep - gates and residual-risk decisions. -- Cleanup checkpoint: this branch is ahead of `origin/main` with the v18 - release-candidate evidence and backlog-reconciliation work. +- Current work: release-prep hardening for `v18.0.0`, with the next goalpost + narrowed to gate evidence, package metadata, public operator notes, and a + residual raw content/property storage decision. +- Cleanup checkpoint: PR #106 is merged to `main`; this branch starts from that + merge and must not widen the v18 promise while preparing the public tag. The current v18 graph-model posture is: @@ -215,6 +215,18 @@ PR #102 landed v18 slices 36 through 40: - ordered migration history input; - migration manifest serialization. +PR #106 landed v18 slices 66 through 96: + +- production-runtime scratch replay and public-read wet-run proof; +- guarded CLI finalization behind reviewed JSON confirmation; +- generated Continuum runtime-boundary contract conformance and `warp-ttd` + smoke evidence; +- raw content/property retired-boundary ratchet; +- release-candidate evidence packet; +- backlog reconciliation after the release-candidate evidence; +- review follow-up that tightened runtime replay validation, finalization JSON + evidence binding, fixture coverage, and migration script structure. + Slice 36 is complete on this branch. The migration manifest root now exists as a frozen domain noun, with runtime-backed basis, mapping, warning, and fatal-error entries. It does not serialize, read Git, or write graph history. @@ -406,6 +418,16 @@ goalpost is a release-prep branch that runs the full gate set, freezes package and release notes, and decides whether remaining raw content/property storage retirement blocks the public tag or ships as explicit residual risk. +### Release-Prep Checklist + +- [x] 97. Establish the v18 release-prep baseline: + [0245](design/0245-v18-release-prep-baseline/v18-release-prep-baseline.md). +- [ ] 98. Run the release-prep gate baseline and record the evidence. +- [ ] 99. Decide residual raw content/property storage risk. +- [ ] 100. Freeze public operator release notes and non-goals. +- [ ] 101. Align package, JSR, lockfile, and changelog metadata for `v18.0.0`. +- [ ] 102. Replan from final release-prep evidence before PR review. + ### Next Thirty-Slice Checklist - [x] 66. Design production-runtime scratch replay conformance: @@ -757,3 +779,10 @@ and concrete checks live in `docs/invariants/`. - [x] 95. Cut v18 release-candidate docs, changelog, and go/no-go evidence. - [x] 96. Reconcile the v18 backlog after release-candidate evidence: [0244](design/0244-v18-backlog-reconciliation/v18-backlog-reconciliation.md). +- [x] 97. Establish the v18 release-prep baseline: + [0245](design/0245-v18-release-prep-baseline/v18-release-prep-baseline.md). +- [ ] 98. Run the release-prep gate baseline and record the evidence. +- [ ] 99. Decide residual raw content/property storage risk. +- [ ] 100. Freeze public operator release notes and non-goals. +- [ ] 101. Align package, JSR, lockfile, and changelog metadata for `v18.0.0`. +- [ ] 102. Replan from final release-prep evidence before PR review. diff --git a/docs/design/0245-v18-release-prep-baseline/v18-release-prep-baseline.md b/docs/design/0245-v18-release-prep-baseline/v18-release-prep-baseline.md new file mode 100644 index 00000000..12224a1f --- /dev/null +++ b/docs/design/0245-v18-release-prep-baseline/v18-release-prep-baseline.md @@ -0,0 +1,51 @@ +--- +cycle: 0245 +task_id: V18_release_prep_baseline +status: Complete +sponsors: + human: James + agent: Codex +started_at: 2026-05-25 +completed_at: 2026-05-25 +release_home: v18.0.0 +bearing_task: 97 +--- + +# V18 Release-Prep Baseline + +## Hill + +Reset the public-release branch from the merged v18 release-candidate evidence +and make the next release-prep work explicit. + +## Context + +PR #106 merged the v18 release-candidate evidence packet through slice 96. The +next work is not another feature tranche. It is release hygiene: prove the +gate set, decide residual raw content/property risk, freeze operator release +notes, align package metadata, and replan from evidence before tagging. + +## Design + +This slice updates `docs/BEARING.md` so it names the current branch and merged +PR accurately. It also adds a short release-prep checklist for slices 97 +through 102. + +The checklist deliberately keeps residual raw content/property storage as a +decision point. The executable closeout audit still names many compatibility +boundaries, so this branch must either retire more storage with evidence or +ship the remaining boundary as an explicit release risk. + +## Acceptance Criteria + +- `BEARING` no longer says the current branch is the merged slice-66-through-75 + feature branch. +- `BEARING` names PR #106 as the latest merged PR. +- Slices 97 through 102 have named release-prep scope. +- The release-prep direction does not widen v18 into v19 or v20 claims. + +## Test Plan + +- Run Markdown lint for edited docs. +- Run `git diff --check`. +- Inspect the diff before committing. From f8d41e5ffc1890f5fd55519c2c5b4a697e017065 Mon Sep 17 00:00:00 2001 From: James Ross Date: Mon, 25 May 2026 08:35:52 -0700 Subject: [PATCH 02/10] docs: Record v18 release gate baseline --- docs/BEARING.md | 6 ++- .../v18-release-gate-baseline.md | 53 +++++++++++++++++++ 2 files changed, 57 insertions(+), 2 deletions(-) create mode 100644 docs/design/0246-v18-release-gate-baseline/v18-release-gate-baseline.md diff --git a/docs/BEARING.md b/docs/BEARING.md index 1ad855ec..0d56fb95 100644 --- a/docs/BEARING.md +++ b/docs/BEARING.md @@ -422,7 +422,8 @@ retirement blocks the public tag or ships as explicit residual risk. - [x] 97. Establish the v18 release-prep baseline: [0245](design/0245-v18-release-prep-baseline/v18-release-prep-baseline.md). -- [ ] 98. Run the release-prep gate baseline and record the evidence. +- [x] 98. Run the release-prep gate baseline and record the evidence: + [0246](design/0246-v18-release-gate-baseline/v18-release-gate-baseline.md). - [ ] 99. Decide residual raw content/property storage risk. - [ ] 100. Freeze public operator release notes and non-goals. - [ ] 101. Align package, JSR, lockfile, and changelog metadata for `v18.0.0`. @@ -781,7 +782,8 @@ and concrete checks live in `docs/invariants/`. [0244](design/0244-v18-backlog-reconciliation/v18-backlog-reconciliation.md). - [x] 97. Establish the v18 release-prep baseline: [0245](design/0245-v18-release-prep-baseline/v18-release-prep-baseline.md). -- [ ] 98. Run the release-prep gate baseline and record the evidence. +- [x] 98. Run the release-prep gate baseline and record the evidence: + [0246](design/0246-v18-release-gate-baseline/v18-release-gate-baseline.md). - [ ] 99. Decide residual raw content/property storage risk. - [ ] 100. Freeze public operator release notes and non-goals. - [ ] 101. Align package, JSR, lockfile, and changelog metadata for `v18.0.0`. diff --git a/docs/design/0246-v18-release-gate-baseline/v18-release-gate-baseline.md b/docs/design/0246-v18-release-gate-baseline/v18-release-gate-baseline.md new file mode 100644 index 00000000..8a33c37d --- /dev/null +++ b/docs/design/0246-v18-release-gate-baseline/v18-release-gate-baseline.md @@ -0,0 +1,53 @@ +--- +cycle: 0246 +task_id: V18_release_gate_baseline +status: Complete +sponsors: + human: James + agent: Codex +started_at: 2026-05-25 +completed_at: 2026-05-25 +release_home: v18.0.0 +bearing_task: 98 +--- + +# V18 Release Gate Baseline + +## Hill + +Run the release-prep gate set before changing package metadata so the branch +starts from known-good evidence. + +## Evidence + +The following gates passed on branch `v18-release-prep-slices-97-102`: + +| Gate | Result | +|------|--------| +| `npm run lint` | Pass | +| tracked Markdown lint via `git ls-files '*.md' \| xargs npx markdownlint` | Pass | +| `npm run typecheck:src` | Pass | +| `npm run typecheck:test` | Pass | +| `npm run test:local` | Pass, 521 files and 7126 tests | +| `npm run release:preflight` | Pass for current `17.0.1` metadata | + +`release:preflight` produced the expected branch warning because release-prep +work runs before merge to `main`. It also reported one moderate npm audit item +and no high or critical runtime vulnerabilities. + +## Local Workspace Note + +`npm run lint:md` failed locally only because the untracked side-project file +`TECHNICAL_TEARDOWN.md` contains unlabeled fenced code blocks. That file is not +tracked and is not part of the release branch. Tracked Markdown passed. + +## Interpretation + +The branch has a clean pre-version baseline. The public v18 release still +requires a second preflight after `package.json`, `jsr.json`, +`package-lock.json`, and `CHANGELOG.md` move to `18.0.0`. + +## Test Plan + +- Preserve this evidence in `BEARING`. +- Re-run release preflight after slice 101 version metadata changes. From 4ae2bbb367f309f5e91a5dabafc84cbb53e13515 Mon Sep 17 00:00:00 2001 From: James Ross Date: Mon, 25 May 2026 08:36:58 -0700 Subject: [PATCH 03/10] docs: Decide v18 residual storage risk --- docs/BEARING.md | 6 +- .../v18-residual-raw-storage-risk-decision.md | 76 +++++++++++++++++++ .../PROTO_content-attachment-plane-cutover.md | 6 +- docs/method/backlog/v18.0.0/README.md | 4 +- .../RELEASE_v18-public-release-blockers.md | 16 +++- 5 files changed, 98 insertions(+), 10 deletions(-) create mode 100644 docs/design/0247-v18-residual-raw-storage-risk-decision/v18-residual-raw-storage-risk-decision.md diff --git a/docs/BEARING.md b/docs/BEARING.md index 0d56fb95..54ff8836 100644 --- a/docs/BEARING.md +++ b/docs/BEARING.md @@ -424,7 +424,8 @@ retirement blocks the public tag or ships as explicit residual risk. [0245](design/0245-v18-release-prep-baseline/v18-release-prep-baseline.md). - [x] 98. Run the release-prep gate baseline and record the evidence: [0246](design/0246-v18-release-gate-baseline/v18-release-gate-baseline.md). -- [ ] 99. Decide residual raw content/property storage risk. +- [x] 99. Decide residual raw content/property storage risk: + [0247](design/0247-v18-residual-raw-storage-risk-decision/v18-residual-raw-storage-risk-decision.md). - [ ] 100. Freeze public operator release notes and non-goals. - [ ] 101. Align package, JSR, lockfile, and changelog metadata for `v18.0.0`. - [ ] 102. Replan from final release-prep evidence before PR review. @@ -784,7 +785,8 @@ and concrete checks live in `docs/invariants/`. [0245](design/0245-v18-release-prep-baseline/v18-release-prep-baseline.md). - [x] 98. Run the release-prep gate baseline and record the evidence: [0246](design/0246-v18-release-gate-baseline/v18-release-gate-baseline.md). -- [ ] 99. Decide residual raw content/property storage risk. +- [x] 99. Decide residual raw content/property storage risk: + [0247](design/0247-v18-residual-raw-storage-risk-decision/v18-residual-raw-storage-risk-decision.md). - [ ] 100. Freeze public operator release notes and non-goals. - [ ] 101. Align package, JSR, lockfile, and changelog metadata for `v18.0.0`. - [ ] 102. Replan from final release-prep evidence before PR review. diff --git a/docs/design/0247-v18-residual-raw-storage-risk-decision/v18-residual-raw-storage-risk-decision.md b/docs/design/0247-v18-residual-raw-storage-risk-decision/v18-residual-raw-storage-risk-decision.md new file mode 100644 index 00000000..651fd58a --- /dev/null +++ b/docs/design/0247-v18-residual-raw-storage-risk-decision/v18-residual-raw-storage-risk-decision.md @@ -0,0 +1,76 @@ +--- +cycle: 0247 +task_id: V18_residual_raw_storage_risk_decision +status: Complete +sponsors: + human: James + agent: Codex +started_at: 2026-05-25 +completed_at: 2026-05-25 +release_home: v18.0.0 +bearing_task: 99 +--- + +# V18 Residual Raw Storage Risk Decision + +## Hill + +Decide whether the remaining raw content/property compatibility boundaries +block the public v18 tag. + +## Evidence + +The executable closeout audit still names 25 `src/domain` files that mention +raw compatibility content or property storage: + +- legacy `_content*` compatibility key ownership; +- runtime mutation and compatibility operation execution; +- reducer, replay, serialization, snapshot, scope, and index boundaries; +- operation helper classes that still carry the legacy property-map shape. + +The audit also has a retired-boundary ratchet: `CoordinateFactExport.ts` must +not regain raw content/property spelling. + +## Decision + +The remaining raw content/property boundaries do **not** block `v18.0.0`. + +They ship as explicit residual compatibility risk because: + +- v18's public promise is graph-model convergence plus migration evidence, not + total storage-plane retirement; +- the canonical v17 fixture proves zero public-read mismatches through the + migration wet-run path; +- production-runtime scratch replay and guarded finalization now exist for the + canonical path; +- a broad last-minute storage retirement would be riskier than shipping the + named compatibility boundary with an executable ratchet. + +## Release Condition + +The v18 public notes must say: + +- legacy `_content*` and raw property-map compatibility storage still exists; +- the remaining compatibility files are audited by + `test/unit/scripts/v18-content-property-closeout-audit.test.ts`; +- any future boundary retirement must reduce the audited file set or add a new + explicit release note; +- end-to-end graph streaming reads and writes are not part of v18. + +## Non-Goals + +- Do not retire the remaining storage plane in this slice. +- Do not claim v18 has native Continuum witnesshood. +- Do not claim v18 has end-to-end graph streaming. + +## Acceptance Criteria + +- `RELEASE_v18-public-release-blockers.md` records the residual risk decision. +- `PROTO_content-attachment-plane-cutover.md` records that remaining storage + dependency is accepted for v18 and remains future work. +- `BEARING` marks slice 99 complete. + +## Test Plan + +- Run Markdown lint for edited docs. +- Run `git diff --check`. diff --git a/docs/method/backlog/v18.0.0/PROTO_content-attachment-plane-cutover.md b/docs/method/backlog/v18.0.0/PROTO_content-attachment-plane-cutover.md index 45f40734..dd719b95 100644 --- a/docs/method/backlog/v18.0.0/PROTO_content-attachment-plane-cutover.md +++ b/docs/method/backlog/v18.0.0/PROTO_content-attachment-plane-cutover.md @@ -36,9 +36,9 @@ wet-run equivalence path and aligned fixture content attachment evidence with runtime content object ids. This item remains partially open because content persistence still has named -legacy `_content*` compatibility boundaries. V18 release notes must either -accept that residual risk explicitly or a final retirement slice must remove -the remaining storage dependency before public release. +legacy `_content*` compatibility boundaries. Slice 99 accepts that remaining +storage dependency as explicit v18 residual risk. Total storage-plane +retirement remains future work; the v18 public release must not claim it. ## Starting points diff --git a/docs/method/backlog/v18.0.0/README.md b/docs/method/backlog/v18.0.0/README.md index 8da8bb50..b954ba58 100644 --- a/docs/method/backlog/v18.0.0/README.md +++ b/docs/method/backlog/v18.0.0/README.md @@ -102,7 +102,7 @@ The remaining public v18 work is release hygiene and residual-risk review: - package/version/tag work for the public release; - operator release notes that distinguish graph-model convergence from later Continuum admission shells; -- an explicit decision on remaining raw content/property storage retirement - risk; +- explicit release notes that accept remaining raw content/property storage + compatibility as residual v18 risk; - an explicit non-claim that v18 does not provide end-to-end graph streaming reads and writes. diff --git a/docs/method/backlog/v18.0.0/RELEASE_v18-public-release-blockers.md b/docs/method/backlog/v18.0.0/RELEASE_v18-public-release-blockers.md index a2fb9273..74e37e4b 100644 --- a/docs/method/backlog/v18.0.0/RELEASE_v18-public-release-blockers.md +++ b/docs/method/backlog/v18.0.0/RELEASE_v18-public-release-blockers.md @@ -39,6 +39,7 @@ migration safety than the repository can prove. | Wet-run fixture harness | Complete for the canonical v17 fixture and zero-mismatch report. | | Continuum contract tie-back | Complete for generated runtime-boundary fixtures and `warp-ttd` smoke. | | Release-candidate evidence packet | Complete with public-tag gates and residual risks. | +| Residual raw content/property decision | Accepted as explicit v18 residual risk with an executable audit ratchet. | ## Current Public-Release Blockers @@ -46,14 +47,23 @@ migration safety than the repository can prove. |---------|------------------------------------|-------------------| | Final release-prep gates | Release-candidate evidence is not a public tag. | `npm run release:preflight`, local required gates, and GitHub CI pass on the final release branch. | | Package, version, and tag work | The package line is still `17.0.1`. | `package.json`, `jsr.json` if applicable, changelog, tag, and publish artifacts agree. | -| Residual raw content/property risk | v18 still carries named legacy compatibility boundaries. | Release notes either accept the residual risk explicitly or a final retirement slice removes the blocker. | | Operator release notes | Users need exact migration and finalization guidance. | Public notes explain dry run, scratch writing, guarded finalization, archives, rollback posture, and non-goals. | | Streaming overclaim guard | v18 has stream foundations but not end-to-end graph streaming. | Public docs state that full graph streaming reads and writes are a v20 goal, not a v18 claim. | +## Accepted Residual Risk + +`v18.0.0` ships with named raw content/property compatibility boundaries still +present. This is accepted residual risk, not hidden completeness debt. The +release promise is graph-model convergence and migration proof, not total +storage-plane retirement. + +The guard is executable: +`test/unit/scripts/v18-content-property-closeout-audit.test.ts` lists the +remaining raw compatibility files and fails on unreviewed boundary drift. +`CoordinateFactExport.ts` is retired and must stay retired. + ## Next pull candidates - Run the final release-prep gate set on a release branch. -- Decide whether remaining raw content/property storage retirement blocks - public v18 or becomes explicitly accepted residual risk. - Freeze public release notes and migration operator docs. - Cut package/version/tag changes only after the gates pass. From 6eba202a9cb33fe313efb3d511560d2ac67ab71c Mon Sep 17 00:00:00 2001 From: James Ross Date: Mon, 25 May 2026 08:39:32 -0700 Subject: [PATCH 04/10] docs: Freeze v18 operator release notes --- docs/BEARING.md | 6 +- .../v18-public-operator-release-notes.md | 46 ++++++ .../RELEASE_v18-public-release-blockers.md | 5 +- docs/releases/v18.0.0/README.md | 154 ++++++++++++++++++ 4 files changed, 206 insertions(+), 5 deletions(-) create mode 100644 docs/design/0248-v18-public-operator-release-notes/v18-public-operator-release-notes.md create mode 100644 docs/releases/v18.0.0/README.md diff --git a/docs/BEARING.md b/docs/BEARING.md index 54ff8836..3804388b 100644 --- a/docs/BEARING.md +++ b/docs/BEARING.md @@ -426,7 +426,8 @@ retirement blocks the public tag or ships as explicit residual risk. [0246](design/0246-v18-release-gate-baseline/v18-release-gate-baseline.md). - [x] 99. Decide residual raw content/property storage risk: [0247](design/0247-v18-residual-raw-storage-risk-decision/v18-residual-raw-storage-risk-decision.md). -- [ ] 100. Freeze public operator release notes and non-goals. +- [x] 100. Freeze public operator release notes and non-goals: + [0248](design/0248-v18-public-operator-release-notes/v18-public-operator-release-notes.md). - [ ] 101. Align package, JSR, lockfile, and changelog metadata for `v18.0.0`. - [ ] 102. Replan from final release-prep evidence before PR review. @@ -787,6 +788,7 @@ and concrete checks live in `docs/invariants/`. [0246](design/0246-v18-release-gate-baseline/v18-release-gate-baseline.md). - [x] 99. Decide residual raw content/property storage risk: [0247](design/0247-v18-residual-raw-storage-risk-decision/v18-residual-raw-storage-risk-decision.md). -- [ ] 100. Freeze public operator release notes and non-goals. +- [x] 100. Freeze public operator release notes and non-goals: + [0248](design/0248-v18-public-operator-release-notes/v18-public-operator-release-notes.md). - [ ] 101. Align package, JSR, lockfile, and changelog metadata for `v18.0.0`. - [ ] 102. Replan from final release-prep evidence before PR review. diff --git a/docs/design/0248-v18-public-operator-release-notes/v18-public-operator-release-notes.md b/docs/design/0248-v18-public-operator-release-notes/v18-public-operator-release-notes.md new file mode 100644 index 00000000..a2d34dd5 --- /dev/null +++ b/docs/design/0248-v18-public-operator-release-notes/v18-public-operator-release-notes.md @@ -0,0 +1,46 @@ +--- +cycle: 0248 +task_id: V18_public_operator_release_notes +status: Complete +sponsors: + human: James + agent: Codex +started_at: 2026-05-25 +completed_at: 2026-05-25 +release_home: v18.0.0 +bearing_task: 100 +--- + +# V18 Public Operator Release Notes + +## Hill + +Freeze public operator notes for `v18.0.0` so the release says exactly what is +proved and exactly what is not. + +## Design + +The release notes live at `docs/releases/v18.0.0/README.md`. They translate the +release-candidate evidence into operator-facing instructions: + +- what v18 adds; +- how to run dry-run, scratch, equivalence, and guarded finalization paths; +- how archive refs preserve rollback evidence; +- which risks are accepted; +- which claims are explicitly out of scope. + +## Acceptance Criteria + +- Public notes describe dry-run, scratch writing, equivalence gating, + production-runtime replay, guarded finalization, archive refs, and rollback + posture. +- Public notes state that remaining raw content/property compatibility storage + is accepted residual risk. +- Public notes state that end-to-end graph streaming reads and writes are a + v20 goal, not a v18 claim. +- Public notes keep Continuum language sibling-participant accurate. + +## Test Plan + +- Run Markdown lint for the release notes and this design doc. +- Run `git diff --check`. diff --git a/docs/method/backlog/v18.0.0/RELEASE_v18-public-release-blockers.md b/docs/method/backlog/v18.0.0/RELEASE_v18-public-release-blockers.md index 74e37e4b..02c54658 100644 --- a/docs/method/backlog/v18.0.0/RELEASE_v18-public-release-blockers.md +++ b/docs/method/backlog/v18.0.0/RELEASE_v18-public-release-blockers.md @@ -40,6 +40,7 @@ migration safety than the repository can prove. | Continuum contract tie-back | Complete for generated runtime-boundary fixtures and `warp-ttd` smoke. | | Release-candidate evidence packet | Complete with public-tag gates and residual risks. | | Residual raw content/property decision | Accepted as explicit v18 residual risk with an executable audit ratchet. | +| Operator release notes | Complete in `docs/releases/v18.0.0/README.md`. | ## Current Public-Release Blockers @@ -47,8 +48,7 @@ migration safety than the repository can prove. |---------|------------------------------------|-------------------| | Final release-prep gates | Release-candidate evidence is not a public tag. | `npm run release:preflight`, local required gates, and GitHub CI pass on the final release branch. | | Package, version, and tag work | The package line is still `17.0.1`. | `package.json`, `jsr.json` if applicable, changelog, tag, and publish artifacts agree. | -| Operator release notes | Users need exact migration and finalization guidance. | Public notes explain dry run, scratch writing, guarded finalization, archives, rollback posture, and non-goals. | -| Streaming overclaim guard | v18 has stream foundations but not end-to-end graph streaming. | Public docs state that full graph streaming reads and writes are a v20 goal, not a v18 claim. | +| Streaming overclaim guard | Release notes now state the non-claim, but CI/PR review must still preserve it. | Public docs state that full graph streaming reads and writes are a v20 goal, not a v18 claim. | ## Accepted Residual Risk @@ -65,5 +65,4 @@ remaining raw compatibility files and fails on unreviewed boundary drift. ## Next pull candidates - Run the final release-prep gate set on a release branch. -- Freeze public release notes and migration operator docs. - Cut package/version/tag changes only after the gates pass. diff --git a/docs/releases/v18.0.0/README.md b/docs/releases/v18.0.0/README.md new file mode 100644 index 00000000..85385b39 --- /dev/null +++ b/docs/releases/v18.0.0/README.md @@ -0,0 +1,154 @@ +# V18.0.0 Release Notes + +Status: public release notes for the `v18.0.0` release-prep branch. + +Date: 2026-05-25. + +## Release Scope + +`v18.0.0` is the graph-model convergence release. It makes the v18 migration +path inspectable and guarded without pretending that `git-warp` has become a +different runtime. + +This release adds: + +- runtime-backed graph-model records for nodes, edges, attachments, content, + node properties, and edge properties; +- projection-backed compatibility reads for legacy content and property state; +- a dry-run graph-model migration planner and deterministic manifest adapter; +- restored v17 golden graph-history fixtures; +- scratch migration writing under `refs/warp-migration-scratch/*`; +- genesis-equivalence gating between legacy and migrated readings; +- production-runtime scratch replay for the canonical wet-run path; +- deterministic operator reports; +- guarded archive-preserving finalization behind reviewed JSON confirmation; +- generated Continuum runtime-boundary contract evidence; +- a first `warp-ttd` generated-family smoke fact. + +`git-warp` remains an independent Continuum participant. Continuum is the +protocol for exchanging witnessed causal history. Echo and `git-warp` are +sibling participants, not halves of one runtime. + +## Operator Path + +### 1. Run dry-run planning + +Use the dry-run entry point to validate request JSON and produce deterministic +planning evidence before writing scratch history: + +```bash +node scripts/v18.0.0/migrations/graph-model/dry-run.ts \ + --request ./migration-request.json \ + --manifest-out ./v18-migration-manifest.json +``` + +The dry run must complete without fatal migration notices before continuing. + +### 2. Write scratch history and report evidence + +Use the command wrapper to write lowered migration operations only under a +scratch ref: + +```bash +node scripts/v18.0.0/migrations/graph-model/migrate.ts \ + --repo ./restored-v17-repo \ + --request ./migration-request.json \ + --legacy-fixture-manifest ./fixtures/v17/graph-model-golden/manifest.json \ + --scratch-ref refs/warp-migration-scratch/v17-golden-graph/release-check \ + --report-out ./v18-migration-report.txt +``` + +The command report includes dry-run, lowering, scratch, equivalence, and +finalization sections. Without a finalization request, finalization is skipped. + +### 3. Review equivalence and runtime replay + +Before any live ref moves, the operator report must show: + +```text +dryRun: passed +lowering: passed +scratch: written +equivalence: passed +mismatches: 0 +``` + +For the canonical v17 fixture path, the wet-run harness also proves migrated +scratch operations can replay through the production runtime write and +materialization path. + +### 4. Finalize only with reviewed JSON + +Direct finalization flags are intentionally refused. Finalization must use a +reviewed JSON request: + +```bash +node scripts/v18.0.0/migrations/graph-model/migrate.ts \ + --repo ./restored-v17-repo \ + --request ./migration-request.json \ + --legacy-fixture-manifest ./fixtures/v17/graph-model-golden/manifest.json \ + --scratch-ref refs/warp-migration-scratch/v17-golden-graph/release-check \ + --finalization-request ./finalization-request.json \ + --report-out ./v18-finalization-report.txt +``` + +The reviewed finalization request must match the observed scratch ref, scratch +head, equivalence evidence, runtime witness, live-ref expected head, archive +ref, and confirmation token. Stale or edited evidence blocks finalization. + +### 5. Preserve archive evidence + +Successful finalization preserves old live lineage under an archive ref before +advancing the live ref. The report prints: + +```text +liveRef: refs/warp//... +archiveRef: refs/warp-migration-archive//... +previousLiveHead: +archiveHead: +finalizedLiveHead: +archivePreserved: yes +``` + +Rollback is an operator action, not an automatic background behavior. The +archive ref is the evidence needed to inspect or restore the previous lineage. + +## Accepted Residual Risk + +`v18.0.0` still carries named legacy raw content/property compatibility +boundaries. The release does not claim total storage-plane retirement. + +The guard is executable: + +```bash +npm exec vitest run test/unit/scripts/v18-content-property-closeout-audit.test.ts +``` + +That audit enumerates the remaining raw compatibility files and keeps retired +raw-boundary classes from returning silently. + +## Non-Goals + +`v18.0.0` does not provide: + +- full native Continuum witnesshood; +- Echo runtime parity; +- a full Continuum admission shell; +- total raw content/property storage retirement; +- end-to-end graph streaming reads and writes; +- v20 observer/support/index execution semantics; +- v21 distributed braid or plural-admission semantics. + +Full graph streaming reads and writes are explicitly a `v20.0.0` goal. + +## Release Gates + +Before tagging, run: + +```bash +npm run release:preflight +``` + +The release-prep branch must also pass GitHub CI after PR review. Tag only from +merged `main`, after package metadata, JSR metadata, lockfile, and changelog +all agree on `18.0.0`. From e065c3778977d2f4e7e618aef0313a3ab5516d8d Mon Sep 17 00:00:00 2001 From: James Ross Date: Mon, 25 May 2026 09:01:24 -0700 Subject: [PATCH 05/10] release: Prepare v18.0.0 metadata --- CHANGELOG.md | 2 + docs/BEARING.md | 12 ++-- .../v18-version-tag-readiness.md | 64 +++++++++++++++++++ .../RELEASE_v18-public-release-blockers.md | 6 +- jsr.json | 2 +- package-lock.json | 10 +-- package.json | 2 +- packages/warp-adapters/package.json | 2 +- packages/warp-kernel/package.json | 2 +- packages/warp-orset/package.json | 2 +- 10 files changed, 88 insertions(+), 16 deletions(-) create mode 100644 docs/design/0249-v18-version-tag-readiness/v18-version-tag-readiness.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 5db7753b..e609da45 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [18.0.0] — 2026-05-25 + ### Added - V18 release-candidate evidence now records guarded CLI finalization, diff --git a/docs/BEARING.md b/docs/BEARING.md index 3804388b..998cb440 100644 --- a/docs/BEARING.md +++ b/docs/BEARING.md @@ -44,8 +44,9 @@ Current branch state at this boundary: - Current `origin/main`: `023c7d75` - Latest merged PR: #106, v18 release-candidate evidence and review cleanup - Latest released package line: `17.0.1` +- Release-prep package metadata: `18.0.0`, not tagged or published yet - Latest completed implementation cycle: - `0244-v18-backlog-reconciliation` + `0249-v18-version-tag-readiness` - Current work: release-prep hardening for `v18.0.0`, with the next goalpost narrowed to gate evidence, package metadata, public operator notes, and a residual raw content/property storage decision. @@ -155,7 +156,8 @@ The current v18 graph-model posture is: finalization only through a reviewed JSON request that matches observed runtime evidence. - V18 release-candidate blockers are now explicit: full release-prep gates, - GitHub CI, package/versioning work, and residual raw content/property risk. + GitHub CI, post-merge tag/publish work, and the accepted residual raw + content/property risk. That is useful progress, not a finish line. The repo now has migration safety, wet-run proof, guarded finalization, generated Continuum contract tie-back, @@ -428,7 +430,8 @@ retirement blocks the public tag or ships as explicit residual risk. [0247](design/0247-v18-residual-raw-storage-risk-decision/v18-residual-raw-storage-risk-decision.md). - [x] 100. Freeze public operator release notes and non-goals: [0248](design/0248-v18-public-operator-release-notes/v18-public-operator-release-notes.md). -- [ ] 101. Align package, JSR, lockfile, and changelog metadata for `v18.0.0`. +- [x] 101. Align package, JSR, lockfile, and changelog metadata for `v18.0.0`: + [0249](design/0249-v18-version-tag-readiness/v18-version-tag-readiness.md). - [ ] 102. Replan from final release-prep evidence before PR review. ### Next Thirty-Slice Checklist @@ -790,5 +793,6 @@ and concrete checks live in `docs/invariants/`. [0247](design/0247-v18-residual-raw-storage-risk-decision/v18-residual-raw-storage-risk-decision.md). - [x] 100. Freeze public operator release notes and non-goals: [0248](design/0248-v18-public-operator-release-notes/v18-public-operator-release-notes.md). -- [ ] 101. Align package, JSR, lockfile, and changelog metadata for `v18.0.0`. +- [x] 101. Align package, JSR, lockfile, and changelog metadata for `v18.0.0`: + [0249](design/0249-v18-version-tag-readiness/v18-version-tag-readiness.md). - [ ] 102. Replan from final release-prep evidence before PR review. diff --git a/docs/design/0249-v18-version-tag-readiness/v18-version-tag-readiness.md b/docs/design/0249-v18-version-tag-readiness/v18-version-tag-readiness.md new file mode 100644 index 00000000..9e93accf --- /dev/null +++ b/docs/design/0249-v18-version-tag-readiness/v18-version-tag-readiness.md @@ -0,0 +1,64 @@ +# V18 Version And Tag Readiness + +## Hill + +Prepare release metadata for `v18.0.0` without cutting the public tag from a +feature branch. + +## Why + +The release-candidate packet and operator notes already describe the v18 +promise. The remaining package metadata had still identified the branch as +`17.0.1`, which meant release preflight could not prove version agreement for +the intended public tag. + +This slice turns version readiness into explicit branch evidence while keeping +the actual tag and publish steps reserved for merged `main`. + +## Scope + +This slice updates: + +- root `package.json`; +- private workspace `package.json` files; +- `package-lock.json`; +- `jsr.json`; +- `CHANGELOG.md`; +- `docs/BEARING.md`; +- the v18 public-release blocker ledger. + +It does not create a tag, publish an artifact, or claim that GitHub CI has +already passed for the final PR branch. + +## Design + +The version source of truth remains boring and inspectable: + +- npm package metadata reports `18.0.0`; +- JSR metadata reports `18.0.0`; +- the lockfile root and private workspace entries report `18.0.0`; +- the changelog has a dated `18.0.0` entry; +- public release notes still instruct operators to tag only after merge to + `main`. + +Private workspace package versions are aligned even though those packages are +not public publish targets. Keeping them aligned removes an avoidable +review-time ambiguity in the lockfile and makes the release branch easier to +audit. + +## Acceptance Criteria + +- `package.json`, `jsr.json`, and `package-lock.json` agree on `18.0.0`. +- Private workspace manifests agree on `18.0.0`. +- `CHANGELOG.md` contains a dated `18.0.0` section. +- `docs/BEARING.md` marks slice 101 complete and keeps tag/publish work + explicitly pending until merged `main`. +- No public tag is created from this branch. + +## Test Plan + +- Inspect package and workspace metadata with a JSON reader. +- Run markdown lint on the edited docs. +- Run `git diff --check`. +- Run the final release preflight in the next slice after committing this + metadata, because preflight requires a clean working tree. diff --git a/docs/method/backlog/v18.0.0/RELEASE_v18-public-release-blockers.md b/docs/method/backlog/v18.0.0/RELEASE_v18-public-release-blockers.md index 02c54658..6a7c737d 100644 --- a/docs/method/backlog/v18.0.0/RELEASE_v18-public-release-blockers.md +++ b/docs/method/backlog/v18.0.0/RELEASE_v18-public-release-blockers.md @@ -41,13 +41,14 @@ migration safety than the repository can prove. | Release-candidate evidence packet | Complete with public-tag gates and residual risks. | | Residual raw content/property decision | Accepted as explicit v18 residual risk with an executable audit ratchet. | | Operator release notes | Complete in `docs/releases/v18.0.0/README.md`. | +| Version metadata | Root package, private workspaces, lockfile, JSR metadata, and changelog now point at `18.0.0`. | ## Current Public-Release Blockers | Blocker | Why it still blocks public release | Required evidence | |---------|------------------------------------|-------------------| | Final release-prep gates | Release-candidate evidence is not a public tag. | `npm run release:preflight`, local required gates, and GitHub CI pass on the final release branch. | -| Package, version, and tag work | The package line is still `17.0.1`. | `package.json`, `jsr.json` if applicable, changelog, tag, and publish artifacts agree. | +| Post-merge tag and publish work | Package metadata now points at `18.0.0`, but the tag and publish artifacts must be cut from merged `main`. | Signed or annotated tag, pushed tag, npm pack/publish evidence, and JSR publish evidence agree on `18.0.0`. | | Streaming overclaim guard | Release notes now state the non-claim, but CI/PR review must still preserve it. | Public docs state that full graph streaming reads and writes are a v20 goal, not a v18 claim. | ## Accepted Residual Risk @@ -65,4 +66,5 @@ remaining raw compatibility files and fails on unreviewed boundary drift. ## Next pull candidates - Run the final release-prep gate set on a release branch. -- Cut package/version/tag changes only after the gates pass. +- Cut the public tag and publish artifacts only after this branch merges and + the final gates pass on `main`. diff --git a/jsr.json b/jsr.json index 78c8774b..0e33521d 100644 --- a/jsr.json +++ b/jsr.json @@ -1,6 +1,6 @@ { "name": "@git-stunts/git-warp", - "version": "17.0.1", + "version": "18.0.0", "imports": { "roaring": "npm:roaring@^2.7.0" }, diff --git a/package-lock.json b/package-lock.json index 7f3e4bf5..cfd37905 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "@git-stunts/git-warp", - "version": "17.0.1", + "version": "18.0.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@git-stunts/git-warp", - "version": "17.0.1", + "version": "18.0.0", "license": "Apache-2.0", "workspaces": [ "packages/*" @@ -6385,7 +6385,7 @@ }, "packages/warp-adapters": { "name": "@git-stunts/warp-adapters", - "version": "17.0.0", + "version": "18.0.0", "license": "Apache-2.0", "engines": { "node": ">=22.0.0" @@ -6393,7 +6393,7 @@ }, "packages/warp-kernel": { "name": "@git-stunts/warp-kernel", - "version": "17.0.0", + "version": "18.0.0", "license": "Apache-2.0", "engines": { "node": ">=22.0.0" @@ -6401,7 +6401,7 @@ }, "packages/warp-orset": { "name": "@git-stunts/warp-orset", - "version": "17.0.0", + "version": "18.0.0", "license": "Apache-2.0", "engines": { "node": ">=22.0.0" diff --git a/package.json b/package.json index 7b4791b4..70370b98 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@git-stunts/git-warp", - "version": "17.0.1", + "version": "18.0.0", "description": "Deterministic WARP graph over Git: graph-native storage, traversal, and tooling.", "type": "module", "license": "Apache-2.0", diff --git a/packages/warp-adapters/package.json b/packages/warp-adapters/package.json index 04036a98..76230716 100644 --- a/packages/warp-adapters/package.json +++ b/packages/warp-adapters/package.json @@ -1,6 +1,6 @@ { "name": "@git-stunts/warp-adapters", - "version": "17.0.0", + "version": "18.0.0", "description": "Infrastructure adapters: Git/CAS, crypto, and HTTP for git-warp.", "private": true, "type": "module", diff --git a/packages/warp-kernel/package.json b/packages/warp-kernel/package.json index 22033add..e5caabfa 100644 --- a/packages/warp-kernel/package.json +++ b/packages/warp-kernel/package.json @@ -1,6 +1,6 @@ { "name": "@git-stunts/warp-kernel", - "version": "17.0.0", + "version": "18.0.0", "description": "Domain engine: services, WarpState, and controllers for git-warp.", "private": true, "type": "module", diff --git a/packages/warp-orset/package.json b/packages/warp-orset/package.json index 3c4a0441..eb6e70e2 100644 --- a/packages/warp-orset/package.json +++ b/packages/warp-orset/package.json @@ -1,6 +1,6 @@ { "name": "@git-stunts/warp-orset", - "version": "17.0.0", + "version": "18.0.0", "description": "ORSet engine: trie, cursor, cache, and session primitives for git-warp.", "private": true, "type": "module", From 70675784fdb768ad0f92cbb296eac9b54743d3c7 Mon Sep 17 00:00:00 2001 From: James Ross Date: Mon, 25 May 2026 09:08:01 -0700 Subject: [PATCH 06/10] Fix: Align release policy test with v18 metadata --- test/unit/scripts/release-policy-shape.test.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/test/unit/scripts/release-policy-shape.test.ts b/test/unit/scripts/release-policy-shape.test.ts index 43a0e139..6642e514 100644 --- a/test/unit/scripts/release-policy-shape.test.ts +++ b/test/unit/scripts/release-policy-shape.test.ts @@ -36,7 +36,7 @@ const roadmap = readFileSync( describe('release policy shape', () => { it('keeps package and jsr versions aligned on the release branch', () => { expect(packageJson.version).toBe(jsrJson.version); - expect(packageJson.version).toBe('17.0.1'); + expect(packageJson.version).toBe('18.0.0'); }); it('does not require a README release feed anymore', () => { From 32371bb77eb3e7769de710eab4f21731ffbf9f47 Mon Sep 17 00:00:00 2001 From: James Ross Date: Mon, 25 May 2026 09:12:05 -0700 Subject: [PATCH 07/10] docs: Replan v18 release prep after final gates --- docs/BEARING.md | 25 +++--- .../v18-final-release-prep-replan.md | 82 +++++++++++++++++++ .../RELEASE_v18-public-release-blockers.md | 6 +- 3 files changed, 100 insertions(+), 13 deletions(-) create mode 100644 docs/design/0250-v18-final-release-prep-replan/v18-final-release-prep-replan.md diff --git a/docs/BEARING.md b/docs/BEARING.md index 998cb440..e3d0d871 100644 --- a/docs/BEARING.md +++ b/docs/BEARING.md @@ -46,10 +46,10 @@ Current branch state at this boundary: - Latest released package line: `17.0.1` - Release-prep package metadata: `18.0.0`, not tagged or published yet - Latest completed implementation cycle: - `0249-v18-version-tag-readiness` -- Current work: release-prep hardening for `v18.0.0`, with the next goalpost - narrowed to gate evidence, package metadata, public operator notes, and a - residual raw content/property storage decision. + `0250-v18-final-release-prep-replan` +- Current work: release-prep PR review for `v18.0.0`; local release preflight + is green for `18.0.0` metadata, and the remaining public-release gates are + PR review, GitHub CI, merge to `main`, tag, and publish. - Cleanup checkpoint: PR #106 is merged to `main`; this branch starts from that merge and must not widen the v18 promise while preparing the public tag. @@ -155,14 +155,15 @@ The current v18 graph-model posture is: command-owned readings, emits the command report, and permits live-ref finalization only through a reviewed JSON request that matches observed runtime evidence. -- V18 release-candidate blockers are now explicit: full release-prep gates, - GitHub CI, post-merge tag/publish work, and the accepted residual raw - content/property risk. +- V18 release-candidate blockers are now explicit: GitHub CI, PR review, + post-merge tag/publish work, and the accepted residual raw content/property + risk. That is useful progress, not a finish line. The repo now has migration safety, wet-run proof, guarded finalization, generated Continuum contract tie-back, -and a release-candidate packet. Public v18 still needs full release-prep -gates, CI, package/tag work, and explicit residual-risk review. +release-candidate docs, `18.0.0` package metadata, and a green local release +preflight. Public v18 still needs PR review, GitHub CI, merge to `main`, tag, +and publish. ## What Just Shipped @@ -432,7 +433,8 @@ retirement blocks the public tag or ships as explicit residual risk. [0248](design/0248-v18-public-operator-release-notes/v18-public-operator-release-notes.md). - [x] 101. Align package, JSR, lockfile, and changelog metadata for `v18.0.0`: [0249](design/0249-v18-version-tag-readiness/v18-version-tag-readiness.md). -- [ ] 102. Replan from final release-prep evidence before PR review. +- [x] 102. Replan from final release-prep evidence before PR review: + [0250](design/0250-v18-final-release-prep-replan/v18-final-release-prep-replan.md). ### Next Thirty-Slice Checklist @@ -795,4 +797,5 @@ and concrete checks live in `docs/invariants/`. [0248](design/0248-v18-public-operator-release-notes/v18-public-operator-release-notes.md). - [x] 101. Align package, JSR, lockfile, and changelog metadata for `v18.0.0`: [0249](design/0249-v18-version-tag-readiness/v18-version-tag-readiness.md). -- [ ] 102. Replan from final release-prep evidence before PR review. +- [x] 102. Replan from final release-prep evidence before PR review: + [0250](design/0250-v18-final-release-prep-replan/v18-final-release-prep-replan.md). diff --git a/docs/design/0250-v18-final-release-prep-replan/v18-final-release-prep-replan.md b/docs/design/0250-v18-final-release-prep-replan/v18-final-release-prep-replan.md new file mode 100644 index 00000000..e9cd4b62 --- /dev/null +++ b/docs/design/0250-v18-final-release-prep-replan/v18-final-release-prep-replan.md @@ -0,0 +1,82 @@ +# V18 Final Release-Prep Replan + +## Hill + +Close the release-prep slice series with evidence in hand and narrow the +remaining `v18.0.0` work to PR review, CI, merge, tag, and publish. + +## Evidence + +The branch now carries `18.0.0` release metadata and has passed the local +release preflight: + +```text +npm run release:preflight +``` + +Hard-gate result: + +- package and JSR versions agree at `18.0.0`; +- tracked working tree was clean for preflight; +- changelog has a dated `18.0.0` entry; +- ESLint passed; +- source typecheck passed; +- type policy passed; +- consumer type surface passed; +- declaration surface passed; +- unit tests with coverage passed: 521 files, 7126 tests; +- npm pack dry-run passed; +- packed artifact smoke passed; +- JSR publish dry-run passed; +- npm audit reported no high or critical vulnerabilities. + +Expected non-blocking notes: + +- preflight warned that this branch is not `main`; +- npm audit reported one moderate advisory under + `glob/node_modules/brace-expansion`. + +## Discovery During Preflight + +The first preflight run found a stale release-policy test that still expected +`17.0.1` after the metadata moved to `18.0.0`. That was fixed in commit +`70675784`, and the focused release-policy test passed before the full +preflight was rerun. + +## Remaining Public-Release Gate + +The branch is locally ready for PR review, but not yet a public release. +Remaining gates are: + +- open or update the release-prep PR to `main`; +- resolve all PR feedback; +- wait for GitHub CI to pass on the final branch tip; +- merge to `main`; +- tag `v18.0.0` from merged `main`; +- publish npm and JSR artifacts from the tagged release path. + +## Replan + +Do not expand v18 scope now. The public release promise is graph-model +convergence and guarded migration proof, with residual raw content/property +compatibility risk stated explicitly. + +The next engineering goalpost after `v18.0.0` is a post-release planning slice +that decides whether to continue storage-plane retirement first or start the +v19 native Continuum witnesshood runway. End-to-end graph streaming reads and +writes stay out of v18 and belong in the later v20 graph-execution goalpost. + +## Acceptance Criteria + +- `docs/BEARING.md` marks slice 102 complete. +- The v18 public-release blocker ledger treats local release preflight as + complete and leaves PR review, CI, tag, and publish as the live blockers. +- No tag is cut from the feature branch. +- The unrelated untracked `TECHNICAL_TEARDOWN.md` file remains unstaged. + +## Test Plan + +- `npm exec vitest run test/unit/scripts/release-policy-shape.test.ts` +- `npm run release:preflight` +- `npx markdownlint` on edited release-prep docs. +- `git diff --check` diff --git a/docs/method/backlog/v18.0.0/RELEASE_v18-public-release-blockers.md b/docs/method/backlog/v18.0.0/RELEASE_v18-public-release-blockers.md index 6a7c737d..e3b39473 100644 --- a/docs/method/backlog/v18.0.0/RELEASE_v18-public-release-blockers.md +++ b/docs/method/backlog/v18.0.0/RELEASE_v18-public-release-blockers.md @@ -42,12 +42,13 @@ migration safety than the repository can prove. | Residual raw content/property decision | Accepted as explicit v18 residual risk with an executable audit ratchet. | | Operator release notes | Complete in `docs/releases/v18.0.0/README.md`. | | Version metadata | Root package, private workspaces, lockfile, JSR metadata, and changelog now point at `18.0.0`. | +| Local release preflight | `npm run release:preflight` passes for `18.0.0` metadata on the release-prep branch. | ## Current Public-Release Blockers | Blocker | Why it still blocks public release | Required evidence | |---------|------------------------------------|-------------------| -| Final release-prep gates | Release-candidate evidence is not a public tag. | `npm run release:preflight`, local required gates, and GitHub CI pass on the final release branch. | +| GitHub CI and PR review | Local preflight is green, but release evidence is not a merged public branch. | PR review resolves all comments and GitHub CI is green on the final branch tip. | | Post-merge tag and publish work | Package metadata now points at `18.0.0`, but the tag and publish artifacts must be cut from merged `main`. | Signed or annotated tag, pushed tag, npm pack/publish evidence, and JSR publish evidence agree on `18.0.0`. | | Streaming overclaim guard | Release notes now state the non-claim, but CI/PR review must still preserve it. | Public docs state that full graph streaming reads and writes are a v20 goal, not a v18 claim. | @@ -65,6 +66,7 @@ remaining raw compatibility files and fails on unreviewed boundary drift. ## Next pull candidates -- Run the final release-prep gate set on a release branch. +- Open the release-prep PR and preserve the local preflight evidence through + review. - Cut the public tag and publish artifacts only after this branch merges and the final gates pass on `main`. From 82aa74649c61e5f7f8c33cce22fa76287e6675d2 Mon Sep 17 00:00:00 2001 From: James Ross Date: Mon, 25 May 2026 10:21:21 -0700 Subject: [PATCH 08/10] docs: Add git-warp technical teardown --- TECHNICAL_TEARDOWN.md | 347 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 347 insertions(+) create mode 100644 TECHNICAL_TEARDOWN.md diff --git a/TECHNICAL_TEARDOWN.md b/TECHNICAL_TEARDOWN.md new file mode 100644 index 00000000..c01d8c58 --- /dev/null +++ b/TECHNICAL_TEARDOWN.md @@ -0,0 +1,347 @@ +# git-warp: Zero-to-Hero Technical Teardown + +This document provides an exhaustive, end-to-end technical explanation of the `@git-stunts/git-warp` software project. It is intended for a reader with no prior knowledge of the project or its underlying concepts. + +## Table of Contents + +```text +git-warp Overview ......................................... 27 +Domain Dictionary ......................................... 50 +The Big Idea .............................................. 101 +The Source of Truth ....................................... 115 + In Git Objects .......................................... 118 + In Git Refs ............................................. 124 + In Memory ............................................... 130 +Core Concepts ............................................. 136 + Bootstrapping vs Runtime ................................ 138 + Entry Point: From Package Import To openWarpGraph() ..... 144 + Hexagonal Architecture .................................. 176 + Public API Surface ...................................... 207 +Core Workflows: The Golden Paths .......................... 248 + Writing to the Graph .................................... 250 + Reading from the Graph .................................. 256 + Distributed Operations .................................. 262 +Design and Implementation ................................. 268 + Architectural Trade-offs ................................ 270 + How To Read The Codebase Next ........................... 284 + A Look Inside a git-warp Repository ..................... 310 +Summary ................................................... 333 +``` + +## `git-warp` Overview + +This mind map provides a high-level overview of the entire `git-warp` system, from its core concepts to its architecture and workflows. + +```mermaid +mindmap + root((git-warp)) + Architecture + Hexagonal + Ports + GraphPersistencePort + CryptoPort + Adapters + GitGraphAdapter + InMemoryGraphAdapter + CRDT-based + JoinReducer + WarpState + Concepts + Causal History + Immutable Log + Multi-Writer + Convergence + Git Substrate + Patch Commits + Content Blobs + Writer Refs + Workflows + Write Path + PatchBuilder + CommitmentSurface + Read Path + QueryController + Worldline + Observer + Sync Path + SyncController + SyncProtocol +``` + +## Domain Dictionary + +| Term | Definition | +| --- | --- | +| **WARP** | Acronym for **Recursive Witnessed Admission over Git**. It describes a system where history is stored as an append-only log in Git, writes are "admitted" as patches, and the state is "materialized" from this history. The "witnessed" aspect refers to the goal of having cryptographic proof of every state transition. | +| **Git Substrate** | The underlying storage layer. `git-warp` uses Git as its database, but not in a conventional way. It leverages Git's content-addressable object store and ref system to build a distributed graph database. | +| **Graph** | The primary data structure managed by `git-warp`. It's a directed graph of nodes and edges, where both nodes and edges can have properties and binary content attachments. | +| **Writer** | An independent actor that can write to the graph. Each writer has a unique ID and its own chain of commits. | +| **Patch** | A single, atomic set of operations that modify the graph. A patch contains one or more operations, such as adding a node, setting a property, or deleting an edge. | +| **Patch Commit** | A Git commit that stores a single patch. These commits are the fundamental unit of the graph's history. They point to Git's empty tree (`4b825dc642cb6eb9a060e54bf8d69288fbee4904`) to avoid interfering with the user's working directory. | +| **Writer Ref** | A Git ref that points to the most recent patch commit for a specific writer. These refs are stored under `refs/warp//writers/`. | +| **Frontier** | A version vector that maps each known writer ID to the SHA of its most recent patch commit. The frontier represents the "latest" state of the graph, as known by a particular replica. | +| **Version Vector**| A data structure used to track the state of a distributed system. In `git-warp`, it's used to represent the frontier of the graph. | +| **Lamport Tick** | A logical clock used to order events within a single writer's history. Each patch is assigned a Lamport tick that is one greater than the previous patch from the same writer. This ensures a total ordering of operations from a single writer. | +| **CRDT** | **Conflict-free Replicated Data Type**. A data structure that can be replicated across multiple computers and updated independently and concurrently, without coordination between the replicas. `git-warp` uses CRDTs to merge the histories of different writers into a consistent, convergent state. | +| **JoinReducer** | The engine that implements the CRDT logic. It takes a set of patches and "reduces" them into a single, materialized `WarpState`. It handles conflict resolution according to deterministic rules (e.g., add-wins for nodes, last-writer-wins for properties). | +| **Materialization**| The process of reading a set of patch chains from Git and applying them, in a deterministic order, to produce a single, consistent view of the graph state (`WarpState`). | +| **WarpState** | The in-memory representation of the materialized graph state. It's a collection of CRDTs (OR-Sets and LWW-Registers) that hold the nodes, edges, and properties of the graph. | +| **Worldline** | The primary, high-level read surface. A `Worldline` represents the canonical history of the graph. It provides methods for querying the graph at a specific point in time. | +| **Strand** | A temporary, speculative branch of the graph's history. Strands are used for "what-if" scenarios and for preparing complex changes before merging them into the main worldline. | +| **Braid** | The process of merging a strand back into the worldline. | +| **Observer** | A specialized, filtered read surface. An `Observer` provides a view of the graph through an "aperture", which can filter the visible nodes and properties. Observers are the primary mechanism for implementing read-side access control. | +| **Aperture** | The configuration of an `Observer`, which defines what it can see. | +| **Optic** | A target-model noun for a more advanced, stream-oriented read surface. The v20+ roadmap aims to replace the current materialization-based reading with a more efficient, optic-based system. | +| **Provenance** | The history of a piece of data. `git-warp` is designed to provide full provenance for every value in the graph, tracing it back to the specific patch that created it. | +| **TickReceipt** | A data structure that records the outcome of applying a patch to the graph. TickReceipts are a key part of the provenance system. | +| **BTR** | **Boundary Transition Record**. A record that marks a significant change in the graph's history, such as a schema migration. | +| **Checkpoint** | A snapshot of the materialized graph state at a particular point in time, stored as a Git commit with a tree. Checkpoints are used to speed up materialization by providing a starting point for the `JoinReducer`. | +| **Continuum** | A protocol for exchanging witnessed causal history between different systems. `git-warp` is a Continuum participant. | +| **Wesley** | A compiler for shared contract families within the Continuum ecosystem. | +| **Echo** | Another Continuum participant, responsible for local runtime invocation. | +| **warp-ttd** | A tool for consuming generated contract facts from Wesley. | + +## The Big Idea + +`git-warp` is not a traditional database. It's a **causal-history substrate built on a Git foundation**. Instead of storing the *current state* of data, it stores an **immutable, append-only log of all the changes** that have ever happened. The current state is then *materialized* from this history on demand. + +This approach has several key advantages. First, it allows for **multi-writer, coordination-free writes**. Because each writer has its own independent chain of commits, multiple writers can write to the graph concurrently, even when offline, without any need for a central coordinator. Second, it produces a **convergent state**. `git-warp` uses CRDTs to merge the histories of different writers. This means that as long as two replicas have seen the same set of patches, they will always materialize the exact same state, regardless of the order in which they received the patches. Third, it provides **full provenance**. Because the entire history of the graph is preserved, it's possible to trace any piece of data back to the exact patch that created it, providing a complete audit trail. Finally, it is **distributed by default**. The use of Git as the underlying storage mechanism means that `git-warp` graphs can be synchronized using standard Git protocols (e.g., `git push`, `git pull`). + +## The Source of Truth + +In `git-warp`, the source of truth is not a single database file, but rather the collection of objects and refs in the underlying Git repository. This is a fundamental concept that underpins the entire system. + +### In Git Objects +The immutable history of the graph is stored in Git's object database. +- **Patch Commits**: Each change to the graph is stored as a Git commit. The commit message contains metadata, and the patch payload itself is often stored in a separate blob. +- **Content Blobs**: Binary content attached to nodes or edges is stored in Git blobs, referenced by the graph data. + +### In Git Refs +Git refs are used as pointers to specific points in the graph's history. They act as the "heads" of the different branches of history. +- `refs/warp//writers/`: Points to the latest patch commit for each writer. +- `refs/warp//checkpoints/head`: Points to the most recent checkpoint commit, which is a snapshot of the materialized state. + +### In Memory +The `git-warp` runtime maintains some state in memory for performance. It is crucial to understand that the in-memory state is just a cache; the durable, canonical source of truth is always the data in the Git repository. +- **Materialized State (`WarpState`)**: A cached, in-memory representation of the graph state. +- **Runtime Host**: The main runtime object that manages the graph, including its controllers, services, and caches. + +## Core Concepts + +This section covers the foundational concepts of the `git-warp` architecture. + +### Bootstrapping vs Runtime +There is a clear distinction between the one-time **bootstrapping** process and the ongoing **runtime** operations. The **Bootstrapping** process involves importing `openWarpGraph`, constructing the necessary adapters (like `GitGraphAdapter`), and calling `openWarpGraph()`. This creates the `RuntimeHost`, which instantiates controllers and services, and returns a frozen, immutable `WarpGraph` capability bag to the consumer. **Runtime** operations include creating and committing patches, updating refs, materializing state via the `JoinReducer`, reading data through the various query surfaces, and syncing the history with remote replicas. + +### Entry Point: From Package Import To `openWarpGraph()` +The primary entry point for modern consumers of `git-warp` is the `openWarpGraph` function, which is imported from the main package. + +```mermaid +flowchart TD + A[Consumer App] --> B["Imports openWarpGraph"]; + B --> C{index.ts}; + C --> D{src/domain/WarpGraph.ts}; + D -- exports --> E(openWarpGraph); + A --> F["new GitGraphAdapter(...)"]; + F --> G(deps); + A --> H["new NodeCryptoAdapter(...)"]; + H --> G; + subgraph Bootstrapping + I["openWarpGraph(deps)"] --> J["openWarpGraphRuntime(deps)"]; + J --> K["openWarpGraphRuntimeProduct(deps)"]; + K --> L["openRuntimeHostProduct(deps)"]; + L --> M["new RuntimeHost(deps)"]; + M --> N{Controllers & Services}; + N --> O(Frozen WarpGraph Capability Bag); + end + I --> O; + A --> P(await graph); + O --> P; +``` + +### Hexagonal Architecture +The codebase follows a hexagonal (or ports and adapters) architecture. This keeps the core domain logic separate from the infrastructure it runs on. + +```mermaid +graph TD + subgraph Domain + direction LR + D1(RuntimeHost) + D2(JoinReducer) + D3(PatchBuilder) + end + + subgraph Ports + direction TB + P1(GraphPersistencePort) + P2(CryptoPort) + P3(BlobStoragePort) + end + + subgraph Adapters + direction RL + A1(GitGraphAdapter) + A2(InMemoryGraphAdapter) + A3(NodeCryptoAdapter) + A4(GitCasBlobStorageAdapter) + end + + D1 --> P1 + D1 --> P2 + D3 --> P3 + + P1 -- Implemented by --> A1 + P1 -- Implemented by --> A2 + P2 -- Implemented by --> A3 + P3 -- Implemented by --> A4 + + style Domain fill:#c9f,stroke:#333,stroke-width:2px + style Ports fill:#9cf,stroke:#333,stroke-width:2px + style Adapters fill:#f9c,stroke:#333,stroke-width:2px +``` + +### Public API Surface + +The `WarpGraph` object returned by `openWarpGraph` is a frozen capability bag. It exposes several focused surfaces for interacting with the graph. + +```mermaid +classDiagram + class WarpGraph { + <> + +info: GraphInfo + +patches: CommitmentSurface + +folding: FoldingSurface + +query: RevelationSurface + +governance: GovernanceSurface + } + + class CommitmentSurface { + <> + +createPatch() PatchBuilder + +patch() Promise~string~ + } + + class FoldingSurface { + <> + +join() WarpState + +reduce() WarpState + } + + class RevelationSurface { + <> + +hasNode() Promise~bool~ + +getNodeProps() Promise~object~ + +worldline() Worldline + +observer() Observer + } + + class GovernanceSurface { + <> + +syncWith() Promise~SyncWithResult~ + +createCheckpoint() Promise~string~ + } + + WarpGraph o-- CommitmentSurface + WarpGraph o-- FoldingSurface + WarpGraph o-- RevelationSurface + WarpGraph o-- GovernanceSurface +``` + +## Core Workflows: The Golden Paths + +This section details the primary workflows, or "golden paths", that a user or developer will follow when interacting with `git-warp`. + +### Writing to the Graph +This path covers the process of creating and storing new data in the graph. It begins with the application developer creating a patch and ends with a new commit in the Git repository. The `createPatch()` method returns a `PatchBuilder` instance, which is used to build a set of operations. The `commit()` method then bundles these operations into a patch, writes it to Git, and atomically updates the writer's ref using a `compare-and-swap` operation. + +### Reading from the Graph +This path covers how data is retrieved from the graph. It starts with a query from the application and results in data being returned after a potential state materialization. The materialized graph state is created by the `JoinReducer`, which iterates through all patches from all writers in a deterministic order and applies them to the `WarpState` according to CRDT merge rules (Add-wins for nodes/edges, Last-Writer-Wins for properties). + +### Distributed Operations +This path covers how different replicas of a graph converge to the same state. The core feature is multi-writer convergence, where two writers can write to the same graph without coordination. When they sync, the `JoinReducer` processes all patches from both writers, resulting in an identical, converged `WarpState` on both machines. This is enabled by a pull-based synchronization protocol. + +## Architectural Trade-offs + +`git-warp`'s design makes a number of deliberate trade-offs to achieve its goals. + +| Trade-off | Gains | Costs | +| --- | --- | --- | +| **Git as Storage** | Distributed by default, content-addressable, immutable history, powerful branching and merging primitives. | Higher write/read orchestration complexity compared to a traditional database. Not optimized for high-frequency, small writes. | +| **Independent Writer Refs** | Enables coordination-free, offline-first writes. | Shifts complexity to the materialization process (`JoinReducer`). | +| **CRDT Materialization** | Guarantees eventual consistency and multi-writer convergence. | More complex to reason about than simple last-writer-wins databases. Read operations can be more expensive as they may require materialization. | +| **Hexagonal Architecture** | Excellent testability, allows swapping out adapters (e.g., `GitGraphAdapter` vs. `InMemoryGraphAdapter`). | More files and boilerplate (ports and adapters). | +| **Frozen Capability Bag**| Enforces a clean separation between the public API and the internal implementation. Prevents consumers from depending on internal details. | Less flexibility for power users who might want to access internal state. | + +## How To Read The Codebase Next + +The best way to approach the codebase depends on your goals. Here are a few suggested paths for different personas. + +### For the Application Developer +Your goal is to use `git-warp` to build an application. You should focus on the public API and the core concepts. +1. **Start with the `WarpGraph` interface**: This is your main entry point. Understand the different surfaces it provides (`patches`, `query`, etc.). +2. **Follow Golden Paths 1 and 2**: Master the process of opening a graph and writing a simple patch. +3. **Explore the Query Surfaces**: Learn how to read data using `query`, `worldline`, and `observer`. The tests in `test/unit/domain/WarpGraph.noCoordination.test.ts` are a great resource. + +### For the Data Analyst / Auditor +Your goal is to understand the history of the data and verify its integrity. +1. **Understand the Commit Structure**: Look at the "A Look Inside a `git-warp` Repository" section to see how patches are stored in Git. +2. **Learn about Provenance**: Read "Golden Path 9" to understand how `git-warp` enables you to trace data lineage. +3. **Explore the `JoinReducer`**: The tests in `test/unit/domain/services/JoinReducer.test.ts` will show you how the final state is derived from the history. + +### For the Core Contributor +Your goal is to understand the internals of `git-warp` to fix bugs or add new features. +1. **Start with the Ports and Adapters**: Read `src/ports/GraphPersistencePort.ts` and then compare `src/infrastructure/adapters/GitGraphAdapter.ts` and `InMemoryGraphAdapter.ts`. This will give you a clear understanding of the system's boundaries. +2. **Trace the Write Path**: Start at `PatchController.createPatch()`, then look at `PatchBuilder.ts`, and finally `PatchBuilder.commit()`. +3. **Deep Dive into the `JoinReducer`**: This is the heart of the system. Read `src/domain/services/JoinReducer.ts` and its tests carefully. + +## A Look Inside a `git-warp` Repository + +The concepts of writer refs and patch commits can feel abstract. To make them more concrete, we can examine the `git-warp` repository itself, which uses its own technology to store internal data. + +By running `git for-each-ref refs/warp/`, we can see the `git-warp` graphs stored within the repository: + +```text +ac5882317de52fd207b6035cb9e5a98543b965ab commit refs/warp/demo/writers/alice +c8f867b97e797ddf629c5ad209ce8f8841b0ad58 commit refs/warp/demo/writers/writer-1 +6cbc8bf6dce4be512174c1ffe51b8a5e94e3907b commit refs/warp/graft-ast/checkpoints/head +fecdb406087402fcc0e464ef1aaebfa57fe9c14f commit refs/warp/graft-ast/writers/graft +a44156c0870f3aca2002c563b58693fd841c4e1d commit refs/warp/think/writers/local.jamess-macbook-pro-2.local.cli +``` + +This reveals several internal graphs, but the most interesting is `graft-ast`. This graph is used to store the Abstract Syntax Tree (AST) of a project. Let's look at the history of the `graft` writer in this graph: + +```text +$ git log -n 1 refs/warp/graft-ast/writers/graft + +commit fecdb406087402fcc0e464ef1aaebfa57fe9c14f +Author: James Ross +Date: Mon May 25 08:19:53 2026 -0700 + + warp:patch + + eg-kind: patch + eg-graph: graft-ast + eg-writer: graft + eg-lamport: 224 + eg-patch-oid: 9ef88aaeca1bb42aa8414ce55ade63210f5b5bc3 + eg-schema: 2 +``` + +This log output shows a single patch commit. The commit message is highly structured, using trailers to store metadata: +- `eg-graph`: The name of the graph (`graft-ast`). +- `eg-writer`: The ID of the writer (`graft`). +- `eg-lamport`: The Lamport timestamp of the patch. +- `eg-patch-oid`: The SHA of a Git blob that contains the actual patch payload. + +The commit itself is just a metadata container. The actual operations are in the blob with SHA `9ef88aaeca1bb42aa8414ce55ade63210f5b5bc3`. If we inspect the type of this object: +```console +$ git cat-file -t 9ef88aaeca1bb42aa8414ce55ade63210f5b5bc3 +blob +``` +This confirms it's a blob. The content of this blob is a binary CBOR-encoded representation of the patch operations. + +This internal usage demonstrates the power and flexibility of `git-warp`: it's not just for application data, but can also be used to store and manage complex, structured development artifacts like ASTs, right inside the same Git repository as the code itself. + +## Summary + +`@git-stunts/git-warp` is a novel database architecture that leverages the power of Git to create a distributed, multi-writer, eventually consistent graph database. Its use of an append-only log, CRDT-based materialization, and a clean, port-and-adapter architecture make it a robust and flexible system for managing distributed data with full provenance. While its design introduces complexities not found in traditional databases, it provides powerful capabilities for offline-first, collaborative applications where data integrity and auditability are paramount. From 40b303b4a8099a9566d87b8d588b7c46031c2001 Mon Sep 17 00:00:00 2001 From: James Ross Date: Mon, 25 May 2026 11:05:59 -0700 Subject: [PATCH 09/10] docs: Resolve teardown self-review findings --- TECHNICAL_TEARDOWN.md | 120 +++++++++++++++++++++--------------------- 1 file changed, 59 insertions(+), 61 deletions(-) diff --git a/TECHNICAL_TEARDOWN.md b/TECHNICAL_TEARDOWN.md index c01d8c58..49c40ba6 100644 --- a/TECHNICAL_TEARDOWN.md +++ b/TECHNICAL_TEARDOWN.md @@ -4,29 +4,16 @@ This document provides an exhaustive, end-to-end technical explanation of the `@ ## Table of Contents -```text -git-warp Overview ......................................... 27 -Domain Dictionary ......................................... 50 -The Big Idea .............................................. 101 -The Source of Truth ....................................... 115 - In Git Objects .......................................... 118 - In Git Refs ............................................. 124 - In Memory ............................................... 130 -Core Concepts ............................................. 136 - Bootstrapping vs Runtime ................................ 138 - Entry Point: From Package Import To openWarpGraph() ..... 144 - Hexagonal Architecture .................................. 176 - Public API Surface ...................................... 207 -Core Workflows: The Golden Paths .......................... 248 - Writing to the Graph .................................... 250 - Reading from the Graph .................................. 256 - Distributed Operations .................................. 262 -Design and Implementation ................................. 268 - Architectural Trade-offs ................................ 270 - How To Read The Codebase Next ........................... 284 - A Look Inside a git-warp Repository ..................... 310 -Summary ................................................... 333 -``` +- [`git-warp` Overview](#git-warp-overview) +- [Domain Dictionary](#domain-dictionary) +- [The Big Idea](#the-big-idea) +- [The Source of Truth](#the-source-of-truth) +- [Core Concepts](#core-concepts) +- [Core Workflows: The Golden Paths](#core-workflows-the-golden-paths) +- [Architectural Trade-offs](#architectural-trade-offs) +- [How To Read The Codebase Next](#how-to-read-the-codebase-next) +- [A Look Inside a `git-warp` Repository](#a-look-inside-a-git-warp-repository) +- [Summary](#summary) ## `git-warp` Overview @@ -112,7 +99,9 @@ This approach has several key advantages. First, it allows for **multi-writer, c In `git-warp`, the source of truth is not a single database file, but rather the collection of objects and refs in the underlying Git repository. This is a fundamental concept that underpins the entire system. ### In Git Objects -The immutable history of the graph is stored in Git's object database. + +The immutable history of the graph is stored in Git's object database. + - **Patch Commits**: Each change to the graph is stored as a Git commit. The commit message contains metadata, and the patch payload itself is often stored in a separate blob. - **Content Blobs**: Binary content attached to nodes or edges is stored in Git blobs, referenced by the graph data. @@ -208,45 +197,56 @@ The `WarpGraph` object returned by `openWarpGraph` is a frozen capability bag. I classDiagram class WarpGraph { <> - +info: GraphInfo - +patches: CommitmentSurface + +graphName: string + +writerId: string + +commitment: CommitmentSurface +folding: FoldingSurface - +query: RevelationSurface + +revelation: RevelationSurface +governance: GovernanceSurface + +query: QueryCapability + +patches: PatchCapability + +sync: SyncCapability + +strands: StrandCapability + +checkpoint: CheckpointCapability + +provenance: ProvenanceCapability + +comparison: ComparisonCapability + +subscriptions: SubscriptionCapability } class CommitmentSurface { <> - +createPatch() PatchBuilder - +patch() Promise~string~ + +patches: PatchCapability + +strands: StrandCapability + +comparison: ComparisonCapability } class FoldingSurface { <> - +join() WarpState - +reduce() WarpState + +checkpoint: CheckpointCapability } class RevelationSurface { <> - +hasNode() Promise~bool~ - +getNodeProps() Promise~object~ - +worldline() Worldline - +observer() Observer + +query: QueryCapability + +subscriptions: SubscriptionCapability + +provenance: ProvenanceCapability } class GovernanceSurface { <> - +syncWith() Promise~SyncWithResult~ - +createCheckpoint() Promise~string~ + +sync: SyncCapability } - WarpGraph o-- CommitmentSurface - WarpGraph o-- FoldingSurface - WarpGraph o-- RevelationSurface - WarpGraph o-- GovernanceSurface + WarpGraph o-- CommitmentSurface : commitment + WarpGraph o-- FoldingSurface : folding + WarpGraph o-- RevelationSurface : revelation + WarpGraph o-- GovernanceSurface : governance ``` +The architectural surfaces are the primary shape. The flat aliases +(`graph.query`, `graph.patches`, `graph.sync`, and related capabilities) exist +for ergonomic access to the same underlying capability namespaces. + ## Core Workflows: The Golden Paths This section details the primary workflows, or "golden paths", that a user or developer will follow when interacting with `git-warp`. @@ -285,7 +285,7 @@ Your goal is to use `git-warp` to build an application. You should focus on the ### For the Data Analyst / Auditor Your goal is to understand the history of the data and verify its integrity. 1. **Understand the Commit Structure**: Look at the "A Look Inside a `git-warp` Repository" section to see how patches are stored in Git. -2. **Learn about Provenance**: Read "Golden Path 9" to understand how `git-warp` enables you to trace data lineage. +2. **Learn about Provenance**: Read the provenance entry in the Domain Dictionary and inspect the patch trailers in the repository example to see how `git-warp` enables data-lineage tracing. 3. **Explore the `JoinReducer`**: The tests in `test/unit/domain/services/JoinReducer.test.ts` will show you how the final state is derived from the history. ### For the Core Contributor @@ -296,46 +296,44 @@ Your goal is to understand the internals of `git-warp` to fix bugs or add new fe ## A Look Inside a `git-warp` Repository -The concepts of writer refs and patch commits can feel abstract. To make them more concrete, we can examine the `git-warp` repository itself, which uses its own technology to store internal data. +The concepts of writer refs and patch commits can feel abstract. A fixture-style example makes the storage shape concrete without depending on one developer workstation's local refs. -By running `git for-each-ref refs/warp/`, we can see the `git-warp` graphs stored within the repository: +Running `git for-each-ref refs/warp/` in a repository that stores graph data might produce output shaped like this: ```text -ac5882317de52fd207b6035cb9e5a98543b965ab commit refs/warp/demo/writers/alice -c8f867b97e797ddf629c5ad209ce8f8841b0ad58 commit refs/warp/demo/writers/writer-1 -6cbc8bf6dce4be512174c1ffe51b8a5e94e3907b commit refs/warp/graft-ast/checkpoints/head -fecdb406087402fcc0e464ef1aaebfa57fe9c14f commit refs/warp/graft-ast/writers/graft -a44156c0870f3aca2002c563b58693fd841c4e1d commit refs/warp/think/writers/local.jamess-macbook-pro-2.local.cli +1111111111111111111111111111111111111111 commit refs/warp/example-graph/writers/alice +2222222222222222222222222222222222222222 commit refs/warp/example-graph/writers/bob +3333333333333333333333333333333333333333 commit refs/warp/example-graph/checkpoints/head ``` -This reveals several internal graphs, but the most interesting is `graft-ast`. This graph is used to store the Abstract Syntax Tree (AST) of a project. Let's look at the history of the `graft` writer in this graph: +This reveals the per-writer heads and optional checkpoint head for a graph. Looking at the history of one writer head shows that each patch is represented by a structured commit: ```text -$ git log -n 1 refs/warp/graft-ast/writers/graft +$ git log -n 1 refs/warp/example-graph/writers/alice -commit fecdb406087402fcc0e464ef1aaebfa57fe9c14f -Author: James Ross +commit 1111111111111111111111111111111111111111 +Author: Example Operator Date: Mon May 25 08:19:53 2026 -0700 warp:patch - + eg-kind: patch - eg-graph: graft-ast - eg-writer: graft + eg-graph: example-graph + eg-writer: alice eg-lamport: 224 - eg-patch-oid: 9ef88aaeca1bb42aa8414ce55ade63210f5b5bc3 + eg-patch-oid: aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa eg-schema: 2 ``` This log output shows a single patch commit. The commit message is highly structured, using trailers to store metadata: -- `eg-graph`: The name of the graph (`graft-ast`). -- `eg-writer`: The ID of the writer (`graft`). +- `eg-graph`: The name of the graph (`example-graph`). +- `eg-writer`: The ID of the writer (`alice`). - `eg-lamport`: The Lamport timestamp of the patch. - `eg-patch-oid`: The SHA of a Git blob that contains the actual patch payload. -The commit itself is just a metadata container. The actual operations are in the blob with SHA `9ef88aaeca1bb42aa8414ce55ade63210f5b5bc3`. If we inspect the type of this object: +The commit itself is just a metadata container. The actual operations are in the blob with SHA `aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa`. If we inspect the type of this object: ```console -$ git cat-file -t 9ef88aaeca1bb42aa8414ce55ade63210f5b5bc3 +$ git cat-file -t aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa blob ``` This confirms it's a blob. The content of this blob is a binary CBOR-encoded representation of the patch operations. From 45f721c336f67ebd9f66f7853bdf8ae1ba958e35 Mon Sep 17 00:00:00 2001 From: James Ross Date: Mon, 25 May 2026 11:26:01 -0700 Subject: [PATCH 10/10] docs: Fix WARP teardown terminology --- TECHNICAL_TEARDOWN.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/TECHNICAL_TEARDOWN.md b/TECHNICAL_TEARDOWN.md index 49c40ba6..9ce13891 100644 --- a/TECHNICAL_TEARDOWN.md +++ b/TECHNICAL_TEARDOWN.md @@ -59,7 +59,7 @@ mindmap | Term | Definition | | --- | --- | -| **WARP** | Acronym for **Recursive Witnessed Admission over Git**. It describes a system where history is stored as an append-only log in Git, writes are "admitted" as patches, and the state is "materialized" from this history. The "witnessed" aspect refers to the goal of having cryptographic proof of every state transition. | +| **WARP** | Acronym for **Worldline Algebra for Recursive Provenance**. The runtime uses recursive witnessed admission semantics over Git: history is stored as an append-only log, writes are admitted as patches, and state is materialized from that history. The "witnessed" aspect refers to the goal of having cryptographic proof of every state transition. | | **Git Substrate** | The underlying storage layer. `git-warp` uses Git as its database, but not in a conventional way. It leverages Git's content-addressable object store and ref system to build a distributed graph database. | | **Graph** | The primary data structure managed by `git-warp`. It's a directed graph of nodes and edges, where both nodes and edges can have properties and binary content attachments. | | **Writer** | An independent actor that can write to the graph. Each writer has a unique ID and its own chain of commits. | @@ -67,11 +67,11 @@ mindmap | **Patch Commit** | A Git commit that stores a single patch. These commits are the fundamental unit of the graph's history. They point to Git's empty tree (`4b825dc642cb6eb9a060e54bf8d69288fbee4904`) to avoid interfering with the user's working directory. | | **Writer Ref** | A Git ref that points to the most recent patch commit for a specific writer. These refs are stored under `refs/warp//writers/`. | | **Frontier** | A version vector that maps each known writer ID to the SHA of its most recent patch commit. The frontier represents the "latest" state of the graph, as known by a particular replica. | -| **Version Vector**| A data structure used to track the state of a distributed system. In `git-warp`, it's used to represent the frontier of the graph. | +| **Version Vector** | A data structure used to track the state of a distributed system. In `git-warp`, it's used to represent the frontier of the graph. | | **Lamport Tick** | A logical clock used to order events within a single writer's history. Each patch is assigned a Lamport tick that is one greater than the previous patch from the same writer. This ensures a total ordering of operations from a single writer. | | **CRDT** | **Conflict-free Replicated Data Type**. A data structure that can be replicated across multiple computers and updated independently and concurrently, without coordination between the replicas. `git-warp` uses CRDTs to merge the histories of different writers into a consistent, convergent state. | | **JoinReducer** | The engine that implements the CRDT logic. It takes a set of patches and "reduces" them into a single, materialized `WarpState`. It handles conflict resolution according to deterministic rules (e.g., add-wins for nodes, last-writer-wins for properties). | -| **Materialization**| The process of reading a set of patch chains from Git and applying them, in a deterministic order, to produce a single, consistent view of the graph state (`WarpState`). | +| **Materialization** | The process of reading a set of patch chains from Git and applying them, in a deterministic order, to produce a single, consistent view of the graph state (`WarpState`). | | **WarpState** | The in-memory representation of the materialized graph state. It's a collection of CRDTs (OR-Sets and LWW-Registers) that hold the nodes, edges, and properties of the graph. | | **Worldline** | The primary, high-level read surface. A `Worldline` represents the canonical history of the graph. It provides methods for querying the graph at a specific point in time. | | **Strand** | A temporary, speculative branch of the graph's history. Strands are used for "what-if" scenarios and for preparing complex changes before merging them into the main worldline. | @@ -270,7 +270,7 @@ This path covers how different replicas of a graph converge to the same state. T | **Independent Writer Refs** | Enables coordination-free, offline-first writes. | Shifts complexity to the materialization process (`JoinReducer`). | | **CRDT Materialization** | Guarantees eventual consistency and multi-writer convergence. | More complex to reason about than simple last-writer-wins databases. Read operations can be more expensive as they may require materialization. | | **Hexagonal Architecture** | Excellent testability, allows swapping out adapters (e.g., `GitGraphAdapter` vs. `InMemoryGraphAdapter`). | More files and boilerplate (ports and adapters). | -| **Frozen Capability Bag**| Enforces a clean separation between the public API and the internal implementation. Prevents consumers from depending on internal details. | Less flexibility for power users who might want to access internal state. | +| **Frozen Capability Bag** | Enforces a clean separation between the public API and the internal implementation. Prevents consumers from depending on internal details. | Less flexibility for power users who might want to access internal state. | ## How To Read The Codebase Next