From 61ab9db2c8dd99981e753014e265649d5bb1e29d Mon Sep 17 00:00:00 2001 From: David Snelling Date: Tue, 4 Aug 2026 09:00:32 -0700 Subject: [PATCH] =?UTF-8?q?docs:=209.0=20namespace-migration=20guide=20?= =?UTF-8?q?=E2=80=94=20the=20simple=20story=20+=20the=20mechanical=20sweep?= =?UTF-8?q?=20checklist,=20published=20for=20humans=20and=20tooling=20alik?= =?UTF-8?q?e?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/concepts/field-addressing.md | 1 + docs/guides/namespace-migration.md | 99 ++++++++++++++++++++++++++++++ 2 files changed, 100 insertions(+) create mode 100644 docs/guides/namespace-migration.md diff --git a/docs/concepts/field-addressing.md b/docs/concepts/field-addressing.md index dcae1057..c459021b 100644 --- a/docs/concepts/field-addressing.md +++ b/docs/concepts/field-addressing.md @@ -7,6 +7,7 @@ template: concept order: 7 description: The one rule for every query-surface field name — a bare name always means your metadata, system. reaches the ten engine scalars explicitly, and anything else refuses by name. next: + - guides/namespace-migration - concepts/consistency-model --- diff --git a/docs/guides/namespace-migration.md b/docs/guides/namespace-migration.md new file mode 100644 index 00000000..fad3c766 --- /dev/null +++ b/docs/guides/namespace-migration.md @@ -0,0 +1,99 @@ +--- +title: Migrating to 9.0 — your fields and system fields +slug: guides/namespace-migration +public: true +category: guides +template: guide +order: 1 +description: The simple story of the 9.0 field-addressing change and the mechanical checklist for updating your call sites — every miss fails loudly with the fix in the error. +next: + - concepts/field-addressing +--- + +# Migrating to 9.0 — your fields and system fields + +The one-sentence version: **your data's field names are now completely +yours, the engine's own fields all live behind one `system.` prefix, and +nothing in between can silently go wrong anymore.** + +## What changed, simply + +**1. Any field name just works.** Before 9.0 the engine quietly owned +certain names. A field called `level` could be shadowed by the engine's +internal index layer of the same name (sorts silently returned insertion +order); names like `confidence` or `subtype` were rejected inside +`metadata`; names like `content` or `id` were silently never indexed, so +filtering on them returned nothing. All of that is gone. Any name — +`level`, `confidence`, `type`, `id`, `content`, anything — is stored +exactly as written and works with every feature: filtering, sorting, +grouping, aggregation, search, and time-travel reads. + +**2. The engine's fields moved behind `system.`.** The engine still keeps +its own per-record bookkeeping — creation time, type, confidence, and so +on. Those are reached one way only now: spelled out, e.g. +`system.createdAt`, `system.type`. They are just as queryable and sortable +as before. `orderBy: 'createdAt'` means *your* field named `createdAt`; +`orderBy: 'system.createdAt'` means the engine's timestamp. No guessing, +no priority rules. + +**3. Storage keeps the two physically separate.** New records store your +metadata in its own nested compartment, so a user field named +`confidence` and the engine's confidence live side by side, both intact, +through restarts, index rebuilds, and `asOf()` history. Old records stay +readable forever; nothing rewrites your data. + +**4. Mistakes are loud.** An ambiguous or unknown field name is a typed +error naming the fix. Unimplemented options refuse instead of being +ignored. The only forbidden name in your metadata is one literally +starting with `system.`. + +## The mechanical checklist + +Every missed site fails **loudly** with the correction in the error +message — nothing silently changes meaning. Sweep these patterns: + +| Before (8.x) | After (9.0) | +|---|---| +| `orderBy: 'createdAt'` (meaning the engine timestamp) | `orderBy: 'system.createdAt'` | +| `where: { subtype: 'invoice' }` (the engine subtype) | `where: { 'system.subtype': 'invoice' }` | +| `where: { confidence: { greaterThan: 0.8 } }` (the engine scalar) | `where: { 'system.confidence': { greaterThan: 0.8 } }` | +| `groupBy: ['noun']` or `groupBy: ['type']` | `groupBy: ['system.type']` | +| `where: { visibility: 'internal' }` / `{ service: … }` (engine values) | `'system.visibility'` / `'system.service'` | +| `metadata: { confidence: 0.9 }` expecting a throw or a lift to the engine scalar | it is YOUR field now — set the engine scalar via the `confidence` param | +| `new Brainy({ reservedFieldPolicy: … })` | remove the option (it throws with this note) | +| `find({ cursor })` / `includeRelations` / `writeOnly` | refuse with `UnsupportedFindOptionError` — they were silently ignored before | + +If a bare name in a query was genuinely *your* field all along (`orderBy: +'score'`, `where: { status: 'active' }`), **change nothing** — bare names +mean your fields, always. + +## What happens at first open + +Each existing database rebuilds its derived indexes once, automatically, +at the first open on 9.0 (index epoch 3 — the index keys split the two +namespaces). One-time cost, observable via `getIndexStatus()`; no manual +step, and your stored data is not modified. + +## For tooling and raw-record readers + +If you read raw stored records (fact-log scanners, export tooling), use +the exported shape-aware splitters — they handle both record eras: + +```typescript +import { splitNounMetadataRecord } from '@soulcraft/brainy' +const { reserved, custom } = splitNounMetadataRecord(rawRecord) +// reserved = engine fields · custom = the user's bag, ANY names +``` + +Feature detection (never version-sniff): + +```typescript +import * as brainy from '@soulcraft/brainy' +const lawActive = 'FIELD_ADDRESSING_CAPABILITY' in brainy // 'field-addressing/v1' +``` + +## Where to go next + +- [Field addressing](../concepts/field-addressing.md) — the full contract: + the ten system scalars, the relation mirror, refusal semantics, and the + cross-engine ordering guarantees.