diff --git a/RELEASES.md b/RELEASES.md index bb95511b..7e2adc8f 100644 --- a/RELEASES.md +++ b/RELEASES.md @@ -10,7 +10,67 @@ Full auto-generated changelog: `CHANGELOG.md` · Releases: https://github.com/so --- -## v8.0.0 — release candidate (`8.0.0-rc.9` published 2026-07-01 on npm tag `rc`) +## v8.0.0 — 2026-07-02 (GA, npm tag `latest`) + +**8.0.0 is the first stable major on the u64-id core.** It ships in lockstep with the optional +native provider's `3.0` (the billion-scale path). Everything below works standalone on the open-core +JS engine — a native provider is feature-detected and only changes the scale ceiling, never the API. + +**Upgrading from 7.x: nothing to script.** The first time 8.0 opens a 7.x brain it upgrades itself — +an automatic, observable, **coordinated migration lock** rebuilds every derived index from your +canonical records while Brainy **blocks and queues** reads and writes, so no operation ever touches a +half-built index and no write is ever lost. Budget seconds-to-minutes per brain at large sizes; small +brains rebuild inline on open. A pre-upgrade hard-link **backup** is taken automatically (removed on +success, kept on failure for rollback). Observe it via `getIndexStatus().migration`; a caller that +hits the window gets a typed, retryable **`MigrationInProgressError`** (catch → HTTP 503 + +`Retry-After`). Bounded by `migrationWaitTimeoutMs` (default 30 s — it bounds *your wait*, not the +rebuild). Opt out of the backup with `migrationBackup: false`. + +### Headline changes + +- **The cold-open silent-`[]` class is gone.** On a cold reopen, filtered finds (`find({ where })`) + and graph reads (`find({ connected })` / `neighbors()` / `related()`) never silently return `[]` + for data that is actually present. With a native provider the durable indexes cold-serve every + filter and edge with zero rebuild; the open-core engine adds belt-and-suspenders guards that + self-heal from canonical data or throw a loud, typed error — never a silent empty result. Two new + exported errors: **`MetadataIndexNotReadyError`**, **`GraphIndexNotReadyError`**. + +- **Faster vector search (open-core).** The JS distance functions are allocation-free loops instead + of `reduce`: **~6× cosine, ~1.4× euclidean** (MEASURED — `tests/benchmarks/distance-microbench.mjs`, + 384-dim, median of 41). Numerically identical, so recall is unchanged. Exact metadata-filter + pushdown and scale-aware search width keep `find()` recall-correct as data grows. + +- **Per-write immutable history.** Every write is generation-stamped; `now()` / `asOf()` / + `transact()` read a consistent point in time, and a retention knob bounds history growth. Single + writes participate in the same immutable timeline as transactions. + +- **Billion-scale resident memory.** Nothing is O(N)-resident on the write or time-travel path — + per-id caches removed, the committed-generation ledger is an interval set, per-id history chains + are bounded (hot-window + LRU). Resident memory is independent of entity count. + +- **Deterministic, round-trip-free writes.** Supply your own ids, forward-reference not-yet-written + entities inside a `transact()`, `ifAbsent` upsert, and `brain.newId()` (uuidv7) — write graphs + without a write→wait→get round-trip. + +### Breaking changes (summary — the full migration guide follows below) + +- **Runtime floor: Node ≥ 22 / Bun ≥ 1.1** (Bun recommended). Compiler target ES2023; the DOM lib is + dropped — 8.0 is a Node/Bun/Deno engine with no browser path. +- **`neural()` removed** and **`Db.search` removed** — use `find()` on the brain. +- **Storage config is one `path` key.** Removed aliases now throw with a message pointing at `path`. +- **`get()` omits the vector by default** — pass `{ includeVectors: true }` when you need it. +- **Export/import type is `PortableGraph`** (was `BackupData`; wire tag `brainy-backup` → + `brainy-portable-graph`). Re-export any snapshots you version outside Brainy. +- **Reserved `visibility` field** (`public` / `internal` / `system`) on nouns and verbs; `internal` + and `system` are excluded from normal reads by default. +- **4 deprecated query operators removed** (`is`/`isNot`/`greaterEqual`/`lessEqual`) and reserved + keys in a `metadata` bag now **throw** by default — details in the rc notes below. + +> Post-rc.9 hardening folded into GA (no on-disk or provider-contract change vs `8.0.0-rc.9`): +> the metadata cold-read guard, the auto pre-upgrade backup (with an `_id_mapper/*` mmap byte-copy +> correctness fix), and a CI fix so a fresh clone builds green. + +### RC history (rc.1 → rc.9, npm tag `rc`) > **rc.9 changes (2026-07-01):** > - **Whole-brain auto-upgrade is now a coordinated, observable LOCK — supersedes rc.8's no-freeze @@ -74,8 +134,8 @@ Full auto-generated changelog: `CHANGELOG.md` · Releases: https://github.com/so surfaces, hard renames (no aliases, no deprecation period), and one flipped default. This entry **is** the migration guide: the find/replace pairs, the sed snippet, and the upgrade checklist below are the complete story — there is -no separate migration doc. **`8.0.0-rc.6` is live** — install with -`npm i @soulcraft/brainy@rc` to try it; the `latest` tag stays on 7.x until GA. +no separate migration doc. **`8.0.0` is GA on `latest`** — install with +`npm i @soulcraft/brainy@latest`. > **rc.3–rc.5 additions (2026-06-24):** > - **Showcase-quality GA hardening (rc.5).** A full readiness audit closed a cold-init