From 68da66024ceee640e0a8b59aa77e8b4a9562010d Mon Sep 17 00:00:00 2001 From: David Snelling Date: Tue, 7 Jul 2026 10:39:00 -0700 Subject: [PATCH] docs: correct rc-era time-travel staleness + record the embedding-model ordering constraint MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - data-storage-architecture.md described transact() as 'the unit of history' (rc.2 era). Single-op retention has been the model since 8.0 — every write gets its own generation; transact() only groups several into one. Corrected. - RELEASE-GUIDE.md now records the hard ordering constraint: no embedding-model change ships before vector model-version stamping + hard-error-on-mismatch lands. --- docs/RELEASE-GUIDE.md | 11 ++++++++++- docs/architecture/data-storage-architecture.md | 5 ++++- 2 files changed, 14 insertions(+), 2 deletions(-) diff --git a/docs/RELEASE-GUIDE.md b/docs/RELEASE-GUIDE.md index ce7d32c5..94c6a6cb 100644 --- a/docs/RELEASE-GUIDE.md +++ b/docs/RELEASE-GUIDE.md @@ -119,4 +119,13 @@ gh release create vY.Y.Y --generate-notes - **Most releases should be MINOR or PATCH** - **Major versions should be RARE** - **When in doubt, it's probably MINOR** -- **NEVER use "BREAKING CHANGE" for internal changes** \ No newline at end of file +- **NEVER use "BREAKING CHANGE" for internal changes** +## Hard Ordering Constraints (check before EVERY release) + +- **Embedding model changes are SEQUENCED, not free.** No release may change the + embedding model (or its quantization/dimensions) before **vector model-version + stamping + hard-error-on-mismatch** ships. Stored vectors carry no model version + today; mixing vectors from two models silently corrupts every similarity + comparison. If a model bump is ever proposed, the stamping work moves ahead of + it in the schedule — coordinate with the native provider so both engines stamp + and enforce identically. (Registered with the native-provider team 2026-07-07.) diff --git a/docs/architecture/data-storage-architecture.md b/docs/architecture/data-storage-architecture.md index a51ebf05..48064757 100644 --- a/docs/architecture/data-storage-architecture.md +++ b/docs/architecture/data-storage-architecture.md @@ -369,7 +369,10 @@ await brain.restore('/backups/today', { confirm: true }) // replace store stat through the metadata index, not the filesystem. - **`_system/`** holds singletons plus 256 hash buckets of index state. - **`_generations/` + `manifest.json` + `tx-log.jsonl`** implement - generational MVCC; `transact()` is the unit of history. + generational MVCC. History is per-write: every `add()`/`update()`/`remove()`/ + `relate()` gets its own generation, and `transact()` groups several ops into + one atomic generation. (Single-op retention has been the model since 8.0; + you never need to route a write through `transact()` just to keep its history.) - **`_column_index/` + `_blobs/`** hold the columnar metadata runs and binary blobs (VFS content included). - **`locks/`** coordinates the single writer and reader flush requests, and