.forgejo/workflows/ci.yml

@@ -1,40 +0,0 @@
-name: CI
-
-on:
-  push:
-  pull_request:
-
-jobs:
-  node:
-    name: Node ${{ matrix.node-version }}
-    runs-on: ubuntu-latest
-    strategy:
-      fail-fast: false
-      matrix:
-        node-version: ['22', '24']
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: ${{ matrix.node-version }}
-          cache: npm
-      - run: npm ci
-      - run: npm run test:unit
-
-  bun:
-    name: Bun (latest)
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: '22'
-          cache: npm
-      - uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: latest
-      - run: npm ci
-      # test:bun imports the built dist/, so build first.
-      - run: npm run build
-      # Bun as a runtime is the supported Bun story (`bun add` / `bun run`).
-      - run: npm run test:bun

CHANGELOG.md

@@ -2,40 +2,6 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
-### [8.9.0](https://github.com/soulcraftlabs/brainy/compare/v8.8.2...v8.9.0) (2026-07-19)
-
-- docs: measured performance envelopes v1 (per-op p50/p95 at 1k and 10k, pure-JS floor) (5cabd78)
-- fix: release drains in-flight writer-lock heartbeat — no phantom lock after unlink (70e4bc8)
-- feat: flush() never compacts — history maintenance moves to close() with bounded passes (300d9f2)
-
-
-### [8.8.2](https://github.com/soulcraftlabs/brainy/compare/v8.8.1...v8.8.2) (2026-07-19)
-
-- fix: one field-resolution law across aggregation hooks, source.where, removeMany, and find() spellings (945d92d)
-- chore: push public docs to the soulcraft.com ingest door on release (42037d0)
-
-
-### [8.8.1](https://github.com/soulcraftlabs/brainy/compare/v8.8.0...v8.8.1) (2026-07-18)
-
-- fix: O(1) adaptive retention accounting + historyStats fleet audit (6207e48)
-- fix: import dedup off-switch honesty + brain-owned lifecycle for the background pass (4fcef7b)
-
-
-### [8.8.0](https://github.com/soulcraftlabs/brainy/compare/v8.7.1...v8.8.0) (2026-07-17)
-
-- feat: OS-limit detection for pool-scale deployments (16a73b8)
-
-
-### [8.7.1](https://github.com/soulcraftlabs/brainy/compare/v8.7.0...v8.7.1) (2026-07-17)
-
-- fix: race-proof writer-lock acquisition + machine-readable conflict through init (01a3b46)
-
-
-### [8.7.0](https://github.com/soulcraftlabs/brainy/compare/v8.6.0...v8.7.0) (2026-07-17)
-
-- feat: scaled transact budgets + labeled timeout diagnostics + envelope docs (6ef9fcb)
-
-
 ### [8.6.0](https://github.com/soulcraftlabs/brainy/compare/v8.5.2...v8.6.0) (2026-07-17)
 
 - feat: brain.auditGraph() — read-only graph-truth audit (2a03fae)

RELEASES.md

@@ -8,182 +8,8 @@ Full auto-generated changelog: `CHANGELOG.md` · Releases: https://github.com/so
 - Debugging data, query, or storage behaviour
 - A new Brainy feature is available that you want to adopt
 
-## Removed APIs — 7.x → 8.x (the complete ledger)
-
-Every public API removed at the 8.0 major, with its sanctioned replacement. If your code
-still calls a left-column name on 8.x it throws (or the config key is rejected) — the
-replacement is always a one-line change. (Standing contract from 8.9.0 forward: removals
-happen only at majors, after ≥1 minor of loud runtime deprecation naming the replacement.)
-
-| Removed (7.x) | Replacement (8.x) |
-|---|---|
-| `brain.search(query, k)` | `find({ query })` — semantic; `find({ query, searchMode })` for hybrid |
-| `brain.getRelations({...})` | `related(id, opts)` for adjacency; `find({ connected: {...} })` for scoped traversal |
-| `brain.neural()` clustering | `find({ vector })` + aggregation `GROUP BY` |
-| `Db.search()` | `db.find({ vector })` |
-| Pre-8.0 storage path aliases (`directory`, `basePath`, …) | one `storage.path` key (old aliases throw) |
-| Reserved keys inside `metadata` bags (silently remapped in 7.x) | top-level params (`subtype`, `visibility`, `confidence`, `weight`, …) — reserved-in-bag throws |
-| 7.x COW branches layout (`branches/main/`) | generational MVCC (`asOf()`, `now()`, `db.persist(path)`) — on-disk migration is automatic at first 8.x open |
-
-The fork/snapshot family (`brain.snapshot()`, `createSnapshot()`, `restoreSnapshot()`)
-is sometimes cited as a 7.x removal — those methods never existed on 7.x; the 8.0 Db API
-(`asOf`/`persist`/`restore({confirm})`) is their first real implementation.
-
 ---
 
-## v8.9.0 — 2026-07-19 (flush is durability-only: history maintenance moves to close())
-
-The write path stops paying maintenance costs — the last structural piece of the
-flush-storm class (a production deployment measured single writes blocked 25–191s behind
-history reclaim running inline on flush under memory pressure):
-
-- **`flush()` never compacts history.** It persists the current window's deltas and
-  nothing else — its cost no longer depends on history backlog or retention mode, in any
-  configuration. **`close()` is the auto-compaction site** (time-bounded per pass, ~5s;
-  an early stop is a consistent prefix and the next pass resumes).
-- **`compactHistory()` gains `timeBudgetMs`** — bound your own maintenance windows; the
-  same resumable-prefix guarantee applies.
-- **The documented trade**: a long-lived writer that never closes accumulates history
-  until its next explicit `compactHistory()`. Predictable writes, explicit maintenance.
-  If you run bounded retention on an always-on service, schedule a periodic
-  `compactHistory({ ...caps, timeBudgetMs })` in your maintenance window.
-- **New public doc: `docs/performance-envelopes.md`** — measured per-op envelopes
-  (p50/p95 at stated scales, hardware, and backend, with the measuring script cited).
-  Refresh rule going forward: any release touching a measured path re-runs that op's
-  benchmark and updates the envelope in the same release.
-- **New in this file: the Removed APIs 7.x→8.x table** (top of this document) — every
-  removal with its sanctioned replacement, one place, per the engine-currency contract.
-  Standing from here: removals only at majors, after ≥1 minor of loud runtime deprecation.
-
-## v8.8.2 — 2026-07-19 (one field-resolution law: reserved-field aggregates stop drifting)
-
-Four fixes from a consumer conformance audit, all rooted in the same disease — two field-resolution
-regimes where there must be one:
-
-- **Aggregates grouped by a RESERVED field (`subtype`, `visibility`, …) now decrement on
-  delete.** The delete/update hooks fed the aggregation engine a partial entity view (type,
-  service, data, metadata only), so a reserved-field `groupBy` resolved to a nonexistent group
-  on the way DOWN — counts drifted upward forever after any delete, and updates that moved an
-  entity between reserved-field groups double-counted it. The hooks now pass the full-fidelity
-  entity view (every reserved field top-level, the same shape the add path uses). If your
-  deployment derives stats from reserved-field aggregates, re-define those aggregates once
-  after upgrading (a changed definition triggers one rescan) or run them fresh — the drifted
-  persisted counts do not self-heal retroactively.
-- **Aggregation `source.where` on reserved fields now filters** instead of silently matching
-  nothing: the matcher resolves fields through the same resolver `groupBy` uses (top-level
-  standard fields + custom metadata), so `where: { subtype: 'note' }` means what it says.
-- **`removeMany()` refuses empty/invalid selectors loudly.** A bare array passed positionally
-  (`removeMany([id])` instead of `removeMany({ ids: [id] })`), an empty params object, or
-  `ids: []` used to resolve successfully having deleted nothing. All three now throw.
-- **`find()` accepts both where-key spellings.** Metadata is flattened at index time
-  (`metadata.entry.title` indexes as `entry.title`); a `metadata.`-prefixed where key now
-  falls back to its flattened spelling when the prefixed one isn't indexed — the
-  "unindexed field(s), returning []" confusion for storage-shaped spellings is gone. (A
-  literal nested custom key named `metadata` still wins when indexed as spelled.)
-
-## v8.8.1 — 2026-07-18 (flush no longer walks the whole generation history + the import dedup off-switch is now honest)
-
-### The flush-storm fix (production incident, reported by a long-running deployment)
-
-Under the default adaptive retention, **every `flush()` re-walked the entire committed
-generation history** to compute total history bytes for the budget check — O(all
-generations) with disk re-reads past the 4,096-entry delta-cache bound. On a brain with
-70,000+ accumulated generations that turned every write into a full-tail scan (60-100s
-writes), even though the budget (free-RAM-based) never tripped and nothing was ever
-reclaimed. Fixed:
-
-- `historyBytes()` now maintains a **running total**: seeded by one walk on first use,
-  then updated incrementally at every commit and reclaim — the adaptive retention check
-  on every flush is O(1). Invariant regression-pinned (running total ≡ fresh walk through
-  both commit paths and compaction).
-- New **`brain.historyStats()`** (read-only, exported `HistoryStats`): generation count,
-  total on-disk bytes, generation/timestamp range, compaction horizon, retention mode,
-  and the effective adaptive budget — the one-call fleet-audit for sizing retention
-  exposure per brain.
-- Interim guidance for keep-everything deployments already affected: `retention: 'all'`
-  skips the adaptive accounting entirely (and is the correct policy if you never want
-  history reclaimed). The accumulated files are harmless at rest; this release removes
-  the per-write cost of their existence.
-
-### The import dedup off-switch (lifecycle honesty)
-
-The post-import background deduplication pass (a merge-DELETE writer that runs ~5 minutes
-after an import, merging entities judged duplicates by id / name / vector similarity) had
-three lifecycle defects, all fixed:
-
-- **`enableDeduplication: false` now actually disables it.** The background pass was
-  scheduled unconditionally — an import that explicitly opted out could still have
-  entities auto-removed 5 minutes later. The flag now gates BOTH the inline merge and
-  the background pass (regression-pinned).
-- **One deduplicator per brain, owned by the brain.** Each `import()` call constructed its
-  own coordinator + deduplicator, so the "debounced" timer never actually debounced across
-  imports (N imports = N delete timers). The brain now owns a single instance — the
-  debounce genuinely spans imports — and `close()` cancels pending work, so a delete pass
-  can never fire against a closed brain.
-- **The 5-minute timer is unref'd** — a pending pass no longer holds the process open
-  (the exit-hang class; this timer had escaped the earlier sweep).
-
-Retention note for keep-everything deployments: with `enableDeduplication: false` on
-import calls and `retention: 'all'` in config, no engine path removes records
-automatically.
-
-## v8.8.0 — 2026-07-17 (OS-limit detection for pool-scale deployments)
-
-Small minor: brains now detect the two OS limits that bite at pool scale and warn **before**
-the incident instead of during it.
-
-- At open (once per process, Linux-only, measurement-only), Brainy reads `RLIMIT_NOFILE`
-  (soft/hard, from `/proc/self/limits`) and `vm.max_map_count`, and warns loudly when either
-  sits below the pool-scale floors (soft NOFILE < 65 536; max_map_count < 262 144) — with the
-  exact raise commands (`ulimit -n` / `LimitNOFILE=` / `sysctl vm.max_map_count`). On stock
-  defaults the failure otherwise arrives as `EMFILE` or a failed mmap deep inside an index
-  open, long after the real cause stopped being visible. An unreadable limit produces **no**
-  warning — no measurement, no claim (non-Linux platforms stay silent).
-- Exported for ops doors: `checkOsLimits()` returns the full `OsLimitsReport`
-  (values + warnings) programmatically, with the floors exported as constants.
-
-## v8.7.1 — 2026-07-17 (writer-lock acquisition is race-proof + machine-readable through init)
-
-Two hardenings of the multi-process writer lock (the `locks/_writer.lock` lease that makes a
-second writer on the same brain directory fail loudly):
-
-- **Lock acquisition claims atomically.** The acquire path used read-then-write, leaving a
-  window where two processes racing an *absent* lock could both "succeed" — and the loser
-  kept running unlocked, silently. The claim is now an atomic create-exclusive write
-  (`O_EXCL`): exactly one racer wins; the loser re-evaluates and either fails loudly with
-  the winner's details or performs a verified stale-takeover. Bounded retries; contention
-  beyond them fails loudly rather than degrading into a lockless open.
-- **`BRAINY_WRITER_LOCKED` survives `init()`.** The conflict error documents a
-  machine-readable contract (`err.code`, `err.lockInfo` with the holder's pid/host/
-  heartbeat), but init's error wrapping silently stripped both, leaving consumers a message
-  to regex against. The error now passes through unwrapped.
-
-Measured while verifying (for operators sizing audits): `brain.auditGraph()` at a
-production-consumer scale of ~2,600 relationships / 800 entities costs ~0.1 s warm and
-~0.5 s cold, with exact scar counting across reopen.
-
-## v8.7.0 — 2026-07-17 (bulk-transact ergonomics: scaled budgets + timeout telemetry)
-
-The bulk-import ergonomics release, from a consumer's measured production incident (a serial
-import on network-attached storage at ~2 s/op met a flat 30 s transaction budget):
-
-- **The transact apply budget now scales with the batch** — `max(30 s, opCount × 2 s)` — or
-  is exactly what you pass as the new `TransactOptions.timeoutMs`. A flat 30 s cap silently
-  limited honest bulk work to ~15 operations on slow disks while looking generous for small
-  batches. Internal batch paths (e.g. `removeMany` chunks) get the same scaling.
-- **`TransactionTimeoutError` is a diagnosis, not just a failure**: it now reports the
-  operation it stopped at as `i/N` with the operation's name, elapsed vs budgeted time, and
-  states the batch rolled back atomically and is retryable. Its `context` carries the same
-  fields programmatically.
-- **The transact envelope is documented** — batch sizing, budget math, chunking with
-  `ifAbsent` idempotency, and the precompute pattern (`embedBatch` + per-op `vector`) that
-  keeps model inference out of the commit path. Guide: `docs/guides/optimistic-concurrency.md`.
-- Note: `brain.embed()` / `brain.embedBatch()` (the precompute APIs) already ship — public,
-  with native-provider passthrough, verified end-to-end (batch and single paths produce
-  bit-identical vectors; a vector-supplied `add` is fully searchable). Honest measurement:
-  on the default WASM engine, batch throughput ≈ sequential (~160 ms/text) — the precompute
-  win is keeping inference out of the budgeted commit path, not raw embedding speed.
-
 ## v8.6.0 — 2026-07-17 (brain.auditGraph — the graph-truth verification instrument)
 
 A minor release adding one new public API, from the fleet's graph-trust program: a read-only

docs/guides/import-anything.md

@@ -300,10 +300,7 @@ await brain.import(data, {
  // Deduplication
  enableDeduplication: true, // Check for duplicate entities (default: true)
  deduplicationThreshold: 0.85, // Similarity threshold for duplicates (0-1, default: 0.85)
- // Notes: false disables BOTH the inline merge and the background pass that
+ // Note: Auto-disabled for imports >100 entities
- // runs ~5 min after the last import (merged duplicates are deleted).
- // The inline pass auto-disables for imports >100 entities (O(n²) cost);
- // the background pass still covers those unless the flag is false.
 
  // Performance
  chunkSize: 100, // Batch size for processing (default: varies by operation)

docs/guides/import-quick-reference.md

@@ -86,22 +86,11 @@ await brain.import(file, {
 
 ```typescript
 await brain.import(file, {
-  enableDeduplication: true,         // Check for duplicates (default: true)
+  enableDeduplication: true,         // Check for duplicates (default: false)
   deduplicationThreshold: 0.85       // Similarity threshold (default: 0.85)
 })
 ```
 
-Deduplication merges entities judged duplicates — the non-primary records are
-**deleted**. Set `enableDeduplication: false` to disable it entirely: the flag
-gates both the inline merge during import and the background pass that runs
-about 5 minutes after the last import.
-
-```typescript
-await brain.import(file, {
-  enableDeduplication: false         // No merging, inline or background
-})
-```
-
 ### Import Tracking
 
 Track and organize imports by project:

docs/guides/optimistic-concurrency.md

@@ -180,35 +180,3 @@ Brainy 8.0 has exactly two write-coordination counters, at two granularities:
 They compose: a `transact()` batch can carry per-entity `ifRev` checks *and* a whole-store `ifAtGeneration`; any failed check rejects the entire batch before anything is staged. Generations also power snapshots and time travel (`brain.now()`, `brain.asOf()`, `db.persist()`) — see the [consistency model](../concepts/consistency-model.md) and [Snapshots & Time Travel](./snapshots-and-time-travel.md).
 
 A snapshot or historical view captures each entity *including* its `_rev` at that moment, so reading the past and writing back with `ifRev` against the live state works exactly as you'd hope: the write fails if the entity moved since the state you copied from.
-
-## The transact envelope: batch size, budget, and bulk imports
-
-`transact()` applies its batch atomically under one commit — which means the whole batch
-shares one **apply budget**. Since 8.7.0 the budget scales with the batch:
-`max(30 s, opCount × 2 s)`, or exactly what you pass as `timeoutMs`. A tripped budget rolls
-the entire batch back (nothing partial survives) and throws a retryable
-`TransactionTimeoutError` that names the operation it stopped at, the batch size, and the
-elapsed vs budgeted time — a diagnosis, not just a failure:
-
-```
-Transaction timed out at operation 41/120 ('add') — 246012ms elapsed, budget 240000ms.
-The batch rolled back atomically; retry with a higher timeoutMs or a smaller batch.
-```
-
-Practical envelope guidance for bulk work:
-
-1. **Precompute embeddings outside the commit path.** Embedding inside `transact()` spends
-   the budget on model inference. Use `brain.embedBatch(texts)` and pass each vector via
-   the op's `vector` field — the commit then pays only storage costs, and a retried batch
-   never re-pays inference. (The win is *where* the inference happens, not raw embedding
-   throughput: on the default WASM engine, batch and sequential embedding measure
-   comparably, ~160 ms/text; native embedding providers may batch faster.)
-2. **Chunk very large imports** into batches of a few hundred ops with one `transact()`
-   each. You lose whole-import atomicity but keep per-chunk atomicity, bounded memory, and
-   resumability — pair with `ifAbsent` upserts so a retried chunk is idempotent.
-3. **Slow disks change the math, not the contract.** On network-attached storage a single
-   op can cost ~2 s (canonical write + fsync + index maintenance). The scaled default
-   absorbs that; pass an explicit `timeoutMs` only when you know better than the scale.
-4. **`addMany`/`relateMany` are the convenience tier** — they chunk and batch-embed for
-   you, with per-item error reporting instead of batch atomicity. Choose by what you need:
-   atomic-all-or-nothing → `transact()`; resilient bulk load → `addMany`.

docs/guides/snapshots-and-time-travel.md

@@ -344,12 +344,8 @@ For per-entity write coordination (rather than whole-store history), the
 ## Keeping history bounded
 
 Under Model-B every write is a generation, so history can grow quickly —
-Brainy auto-compacts at `close()` (time-bounded per pass) under the
+Brainy auto-compacts on every `flush()`/`close()` under the **`retention`**
-**`retention`** knob (configured on the constructor). Since 8.9.0, `flush()`
+knob (configured on the constructor):
-never compacts: flushing is durability work and costs only what the current
-window's writes cost, regardless of history backlog. A long-lived writer that
-never closes keeps its history until its next explicit `compactHistory()` —
-schedule one in your maintenance window if you run bounded retention:
 
 ```typescript
 // Zero-config: ADAPTIVE — keep as much history as free disk/RAM allows,
@@ -363,13 +359,10 @@ new Brainy({ retention: 'all' })
 new Brainy({ retention: { maxGenerations: 1000, maxAge: 7 * 86_400_000, maxBytes: 512 * 1024 ** 2 } })
 ```
 
-Reclaim manually at any time (the same caps, plus an optional per-pass time
+Reclaim manually at any time (the same caps):
-budget for maintenance windows — an early stop is a consistent prefix and the
-next pass resumes):
 
 ```typescript
 await brain.compactHistory({ maxGenerations: 100, maxAge: 7 * 24 * 60 * 60 * 1000 })
-await brain.compactHistory({ maxBytes: 512 * 1024 ** 2, timeBudgetMs: 10_000 })
 ```
 
 Compaction never breaks a pinned read — record-sets are reclaimed only when

docs/performance-envelopes.md

@@ -1,83 +0,0 @@
----
-title: Performance Envelopes
-slug: guides/performance-envelopes
-public: true
-category: guides
-template: guide
-order: 40
-description: Measured per-operation latency envelopes at stated scales — what to expect, on what hardware, and exactly how each number was produced.
-next:
-  - guides/find-limits
----
-
-# Performance Envelopes
-
-Every number on this page is **measured, never projected** — produced by the script
-cited at the bottom, against the built package (the artifact you install), on the stated
-hardware. Each entry says what was measured, at what scale, on which storage backend.
-When a release touches a measured path, that operation is re-measured and this page
-updates in the same release.
-
-Two scopes to keep straight:
-
-- **These envelopes are the pure-JS engine** (no native accelerator registered) on
-  filesystem storage. This is the floor every deployment gets from `npm install` alone.
-- **Accelerated deployments** (the optional native provider) publish their own numbers —
-  this page never claims them.
-
-## Read operations
-
-Reads are where the architecture pays off: after the write path has done its indexing
-work, queries answer from purpose-built indexes without scanning.
-
-| Operation | 1,000 entities | 10,000 entities | Notes |
-|---|---|---|---|
-| `get(id)` (warm) | p50 < 0.1ms | p50 < 0.1ms | served from cache/metadata index |
-| `find` (metadata: indexed equality + range, limit 100) | p50 1.0ms · p95 1.8ms | p50 7.0ms · p95 8.9ms | column-store bitmap paths |
-| `related(id)` (per-node adjacency) | p50 < 0.1ms · p95 0.2ms | p50 < 0.1ms | LSM adjacency index — O(degree), scale-independent |
-| `find` (semantic: embed + HNSW, 1k docs) | p50 178ms · p95 393ms | — | dominated by WASM query embedding (measured on a machine under concurrent load — treat the p95 as an upper bound); the vector search itself is single-digit ms |
-
-## Write operations
-
-Under Model-B **every write is its own durable generation** — a single-op `add` pays
-serialization, before-image staging, and fsync before it acks. That durability is priced
-into the write path visibly, by design:
-
-| Operation | 1,000 entities | 10,000 entities | Notes |
-|---|---|---|---|
-| `add` (single-op) | p50 167ms · p95 171ms | p50 165ms · p95 172ms | full durable generation per write — flat across scale |
-| `addMany` (bulk) | ~163ms/entity | ~187ms/entity | **currently per-item commits** — see the honest note below |
-| `relateMany` | ~0.8ms/edge | ~0.9ms/edge | edges batch efficiently today |
-| `flush` (steady-state, 1 pending write) | p50 8ms · p95 10ms | p50 45ms · p95 52ms | durability-only since 8.9.0 — cost no longer depends on history backlog or retention mode |
-
-**The honest note on bulk writes:** `addMany` today commits each item as its own
-generation (the same durability as single-op `add`, serialized by the single-writer
-lock), so bulk-load cost is N × single-op cost. Batched chunk commits (one generation
-and one fsync window per chunk, as `removeMany` already does) are designed into the
-unified-commit work on the current roadmap. Until that ships, size bulk imports
-accordingly — 10k entities is minutes, not seconds, on filesystem storage.
-
-## Open / close
-
-| Operation | 1,000 entities | 10,000 entities | Notes |
-|---|---|---|---|
-| `open` (empty store) | ~560ms | ~190ms | includes embedder initialization |
-| `open` (warm, populated, clean shutdown) | 763ms | 4.9s | pure-JS vector index load dominates and grows with entity count; the native accelerator exists precisely to remove this |
-| `close` | bounded | bounded | auto-compaction pass is time-bounded (~5s max) since 8.9.0 |
-
-A store that was NOT cleanly closed pays index rebuilds on top of the warm-open
-number (tens of seconds at 10k) — clean shutdown is worth engineering for.
-
-## How these were produced
-
-- **Hardware**: Intel Core i9-14900HX (32 threads), 62GB RAM, NVMe, Linux, Node v22.
-- **Backend**: `storage: { type: 'filesystem' }`, pure JS (no native providers).
-- **Embeddings**: deterministic stub for non-semantic ops (isolates engine cost);
-  the real WASM embedder for the semantic row (that's what you'll run).
-- **Method**: p50/p95 over 50–200 samples per op against the built `dist/`;
-  the measuring script ships in the repo history and re-runs per release.
-
-Numbers on different hardware will differ; the *shape* (sub-2ms indexed reads,
-~160ms embedding-bound semantic queries, durability-priced writes) is the envelope
-you should hold your deployment against. If your measurements diverge from these
-shapes by an order of magnitude, something is wrong — file it.

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@soulcraft/brainy",
-  "version": "8.9.0",
+  "version": "8.6.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@soulcraft/brainy",
-      "version": "8.9.0",
+      "version": "8.6.0",
       "license": "MIT",
       "dependencies": {
         "@msgpack/msgpack": "^3.1.2",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulcraft/brainy",
-  "version": "8.9.0",
+  "version": "8.6.0",
   "description": "Universal Knowledge Protocol™ - World's first Triple Intelligence database unifying vector, graph, and document search in one API. Stage 3 CANONICAL: 42 nouns × 127 verbs covering 96-97% of all human knowledge.",
   "main": "dist/index.js",
   "module": "dist/index.js",

scripts/push-docs.js

@@ -1,116 +0,0 @@
-#!/usr/bin/env node
-/**
- * @module scripts/push-docs
- * @description Push this repo's PUBLIC docs to the soulcraft.com docs ingest
- * door after an npm publish (VENUE-DOCS-RELEASE-PUSH — retires the old
- * build-time docs sync).
- *
- * Contract (mirrors the reference implementation on the serving side):
- *   POST {base}/api/docs/ingest
- *   headers: x-service-secret: $DOCS_INGEST_SECRET, Content-Type: application/json
- *   body: { docs: [{ slug, title, markdown, nav: { order, section } }] }
- *   batches of 10, idempotent per slug.
- *
- * A doc is public iff its frontmatter has `public: true` AND a `slug`. The
- * frontmatter is stripped; `category` → nav.section, `order` → nav.order.
- *
- * Deliberately NOT pushed: the combined /docs landing index. It spans BOTH
- * engine corpora (this repo's and the native accelerator's), so a per-repo
- * push would clobber the union — the index is authored on the serving side.
- *
- * Env: DOCS_INGEST_SECRET (required), DOCS_INGEST_BASE (default
- * https://soulcraft.com). Exits 0 with a LOUD warning when the secret is
- * absent (the npm publish has already happened; the serving side runs its
- * interim sync on request) and exits 1 when a push actually fails — the docs
- * site would silently trail npm otherwise, and that must be visible.
- */
-import * as fs from 'node:fs'
-import * as path from 'node:path'
-
-const BASE = (process.env.DOCS_INGEST_BASE || 'https://soulcraft.com').replace(/\/+$/, '')
-const SECRET = process.env.DOCS_INGEST_SECRET
-const DOCS_DIR = path.join(path.dirname(new URL(import.meta.url).pathname), '..', 'docs')
-const BATCH = 10
-
-if (!SECRET) {
-  console.warn(
-    '⚠️  DOCS PUSH SKIPPED: DOCS_INGEST_SECRET is not set.\n' +
-      '    soulcraft.com/docs now TRAILS this npm release until docs are pushed.\n' +
-      '    Either export DOCS_INGEST_SECRET and re-run `node scripts/push-docs.js`,\n' +
-      '    or ping venue on VENUE-DOCS-RELEASE-PUSH for the interim sync.'
-  )
-  process.exit(0)
-}
-
-/** Minimal frontmatter split — returns [meta, body] or [null, raw]. */
-function parseFrontmatter(raw) {
-  const m = raw.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/)
-  if (!m) return [null, raw]
-  const meta = {}
-  for (const line of m[1].split('\n')) {
-    const kv = line.match(/^(\w[\w-]*):\s*(.*)$/)
-    if (kv) meta[kv[1]] = kv[2].trim().replace(/^["']|["']$/g, '')
-  }
-  return [meta, m[2]]
-}
-
-const docs = []
-;(function walk(dir) {
-  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-    const full = path.join(dir, entry.name)
-    if (entry.isDirectory()) walk(full)
-    else if (entry.name.endsWith('.md')) {
-      const [meta, body] = parseFrontmatter(fs.readFileSync(full, 'utf-8'))
-      if (!meta || meta.public !== 'true' || !meta.slug) continue
-      docs.push({
-        slug: meta.slug,
-        title: meta.title || meta.slug,
-        markdown: body.trim(),
-        nav: {
-          order: Number.parseInt(meta.order || '99', 10) || 99,
-          section: meta.category || 'guides'
-        }
-      })
-    }
-  }
-})(DOCS_DIR)
-
-if (docs.length === 0) {
-  console.error('❌ DOCS PUSH FAILED: zero public docs collected — refusing to push an empty corpus.')
-  process.exit(1)
-}
-docs.sort((a, b) => a.slug.localeCompare(b.slug))
-console.log(`Pushing ${docs.length} public docs to ${BASE}/api/docs/ingest …`)
-
-let failed = false
-for (let i = 0; i < docs.length; i += BATCH) {
-  const batch = docs.slice(i, i + BATCH)
-  try {
-    const res = await fetch(`${BASE}/api/docs/ingest`, {
-      method: 'POST',
-      headers: {
-        'x-service-secret': SECRET,
-        'Content-Type': 'application/json',
-        'User-Agent': 'brainy-docs-push/1.0'
-      },
-      body: JSON.stringify({ docs: batch }),
-      signal: AbortSignal.timeout(120_000)
-    })
-    if (!res.ok) {
-      throw new Error(`HTTP ${res.status}: ${(await res.text()).slice(0, 300)}`)
-    }
-    console.log(`  batch ${i / BATCH + 1}: ${batch.map((d) => d.slug).join(', ')} → ok`)
-  } catch (err) {
-    failed = true
-    console.error(`  batch ${i / BATCH + 1} FAILED: ${err instanceof Error ? err.message : err}`)
-  }
-}
-
-if (failed) {
-  console.error(
-    '❌ DOCS PUSH INCOMPLETE — soulcraft.com/docs may trail npm. ' +
-      'Re-run `node scripts/push-docs.js` or ping venue on VENUE-DOCS-RELEASE-PUSH.'
-  )
-  process.exit(1)
-}
-console.log('✅ Docs pushed.')

scripts/release.sh

@@ -196,18 +196,6 @@ else
 fi
 echo -e "${GREEN}✅ GitHub release created${NC}\n"
 
-# Step 12: Push public docs to the soulcraft.com docs ingest door
-# (VENUE-DOCS-RELEASE-PUSH). Skips with a loud warning when
-# DOCS_INGEST_SECRET is unset; fails loudly (without undoing the publish —
-# that already happened) when a push errors, so the docs site never
-# silently trails npm.
-echo -e "${BLUE}1️⃣2️⃣ Pushing public docs to soulcraft.com/docs...${NC}"
-if node scripts/push-docs.js; then
-  echo -e "${GREEN}✅ Docs push step done${NC}\n"
-else
-  echo -e "${RED}❌ Docs push FAILED — soulcraft.com/docs trails npm until re-run or interim sync${NC}\n"
-fi
-
 echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
 echo -e "${GREEN}🎉 Release ${NEW_VERSION} complete!${NC}"
 echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"

src/aggregation/AggregationIndex.ts

@@ -88,18 +88,10 @@ function matchesSource(entity: Record<string, unknown>, source: AggregateDefinit
     if (entity.service !== source.service) return false
   }
 
-  // Where filter — resolve each filtered field through resolveEntityField,
+  // Metadata where filter — match against the entity's metadata sub-object
-  // the SAME single source of truth groupBy uses (top-level standard fields
-  // + custom metadata). Matching only the metadata sub-object made
-  // where:{subtype}/{visibility}/… a silent no-op: reserved fields never
-  // live in the custom bag, so those filters could never match anything.
   if (source.where && Object.keys(source.where).length > 0) {
-    const e = entity as unknown as HNSWNounWithMetadata
+    const metadata = (entity.metadata ?? entity) as Record<string, unknown>
-    const resolved: Record<string, unknown> = {}
+    if (!matchesMetadataFilter(metadata, source.where)) return false
-    for (const key of Object.keys(source.where)) {
-      resolved[key] = resolveEntityField(e, key)
-    }
-    if (!matchesMetadataFilter(resolved, source.where)) return false
   }
 
   return true

src/brainy.ts

@@ -49,7 +49,6 @@ import {
 import { runGraphAudit, type GraphAuditReport } from './graph/graphAudit.js'
 import { createPipeline } from './streaming/pipeline.js'
 import { configureLogger, LogLevel, prodLog } from './utils/logger.js'
-import { warnOnLowOsLimits } from './utils/osLimits.js'
 import { setGlobalCache } from './utils/unifiedCache.js'
 import type { UnifiedCache } from './utils/unifiedCache.js'
 import { rankIndicesByScore, reorderByIndices } from './utils/resultRanking.js'
@@ -72,7 +71,6 @@ import type {
 } from './plugin.js'
 import { ConnectionsCodec } from './hnsw/connectionsCodec.js'
 import { TransactionManager } from './transaction/TransactionManager.js'
-import { transactTimeoutBudget } from './transaction/Transaction.js'
 import { RevisionConflictError } from './transaction/RevisionConflictError.js'
 import { EntityNotFoundError, RelationNotFoundError } from './errors/notFound.js'
 import {
@@ -192,7 +190,6 @@ import { MemoryStorage } from './storage/adapters/memoryStorage.js'
 import type {
   CompactHistoryOptions,
   CompactHistoryResult,
-  HistoryStats,
   TransactOptions,
   TransactReceipt,
   TxLogEntry,
@@ -396,15 +393,6 @@ export type IndexFamily = 'vector' | 'metadata' | 'graph'
  */
 const AGGREGATION_BACKFILL_RETRY_COOLDOWN_MS = 30_000
 
-/**
- * Time budget for the auto-compaction pass at close() (8.9.0). Bounds how long
- * a clean shutdown spends reclaiming history backlog — an early stop is a
- * consistent prefix and the next close/explicit pass resumes. Explicit
- * `compactHistory()` calls are unbounded unless the caller passes their own
- * `timeBudgetMs` (maintenance windows choose their own budgets).
- */
-const CLOSE_COMPACTION_BUDGET_MS = 5_000
-
 /**
  * The main Brainy class - Clean, Beautiful, Powerful
  * REAL IMPLEMENTATION - No stubs, no mocks
@@ -946,13 +934,6 @@ export class Brainy<T = any> implements BrainyInterface<T> {
       this.storage = await this.setupStorage()
       await this.storage.init()
 
-      // OS-limit detection (once per process, Linux-only, measurement-only):
-      // warn NOW about RLIMIT_NOFILE / vm.max_map_count values that will bite
-      // at pool scale, instead of letting the operator meet them as EMFILE or
-      // a failed mmap deep inside an index open. Fire-and-forget — the check
-      // never affects open.
-      void warnOnLowOsLimits()
-
       // Acquire the writer lock for filesystem (and other locking-capable) backends.
       // Skipped in reader mode and on backends that don't support multi-process locking.
       // Throws if another live writer holds the directory (unless force: true).
@@ -1391,13 +1372,6 @@ export class Brainy<T = any> implements BrainyInterface<T> {
       if (this._readyReject) {
         this._readyReject(error instanceof Error ? error : new Error(String(error)))
       }
-      // Machine-readable init failures pass through UNWRAPPED — the writer-lock
-      // conflict documents an err.code/err.lockInfo contract ("callers detect
-      // this case via err.code"), and wrapping in a fresh Error silently
-      // stripped both, leaving consumers only a message to regex against.
-      if (error instanceof Error && (error as Error & { code?: string }).code === 'BRAINY_WRITER_LOCKED') {
-        throw error
-      }
       throw new Error(`Failed to initialize Brainy: ${error}`)
     }
   }
@@ -1778,11 +1752,7 @@ export class Brainy<T = any> implements BrainyInterface<T> {
         captureAndCheck({ nouns, verbs } as CommitBeforeImages)
       }
       await this.generationStore.runWithoutGeneration(() =>
-        this.transactionManager.executeTransaction(run, {
+        this.transactionManager.executeTransaction(run)
-          timeout: transactTimeoutBudget(
-            (touched.nouns?.length ?? 0) + (touched.verbs?.length ?? 0)
-          )
-        })
       )
       const timestamp = Date.now()
       // Bootstrap writes are not generation-stamped; emit without one.
@@ -1794,12 +1764,7 @@ export class Brainy<T = any> implements BrainyInterface<T> {
       receipt = await this.generationStore.commitSingleOp({
         touched,
         precommit: captureAndCheck,
-        execute: () =>
+        execute: () => this.transactionManager.executeTransaction(run)
-          this.transactionManager.executeTransaction(run, {
-            timeout: transactTimeoutBudget(
-              (touched.nouns?.length ?? 0) + (touched.verbs?.length ?? 0)
-            )
-          })
       })
     } catch (err) {
       // A failed rollback that left the store inconsistent (a remove/update
@@ -1892,29 +1857,6 @@ export class Brainy<T = any> implements BrainyInterface<T> {
     }
   }
 
-  /**
-   * @description Build the AGGREGATION view of an entity from a stored flat
-   * metadata record — EVERY reserved field mapped to its top-level entity
-   * name (stored `noun` → `type`), custom metadata in `metadata`. This must
-   * mirror the add-path `entityForIndexing` shape exactly: the aggregation
-   * engine resolves groupBy/where fields via `resolveEntityField`
-   * (top-level standard fields + custom metadata), so a view that drops a
-   * reserved field makes every aggregate grouped by that field decrement a
-   * group that does not exist — counts then drift upward forever after
-   * deletes (SELF-AGGREGATE-DELETE-DRIFT). Do not hand-roll subsets of this.
-   * @param record - The stored flat metadata record (before-image or pre-delete read).
-   * @returns The full-fidelity entity view for aggregation hooks.
-   */
-  private entityForAggFromRawRecord(record: Record<string, unknown>): Record<string, unknown> {
-    const { reserved, custom } = splitNounMetadataRecord(record)
-    const { noun, ...rest } = reserved
-    return {
-      type: noun,
-      ...rest,
-      metadata: custom
-    }
-  }
-
   /**
    * @description Add an entity (noun) to the brain. Embeds `data` into a vector and
    * indexes the entity across all three intelligences — vector similarity, graph
@@ -3157,16 +3099,15 @@ export class Brainy<T = any> implements BrainyInterface<T> {
           ]
         : undefined)
 
-      // Aggregation hook (outside transaction — derived data). `existing` is
+      // Aggregation hook (outside transaction — derived data)
-      // the full get() view — every reserved field top-level — and must be
-      // passed whole: a subset view makes the old-side decrement miss any
-      // reserved-field group (update would then double-count it).
       if (this._aggregationIndex) {
-        this._aggregationIndex.onEntityUpdated(
+        const oldEntityForAgg = {
-          params.id,
+          type: existing.type,
-          entityForIndexing,
+          service: existing.service,
-          existing as unknown as Record<string, unknown>
+          data: existing.data,
-        )
+          metadata: existing.metadata
+        }
+        this._aggregationIndex.onEntityUpdated(params.id, entityForIndexing, oldEntityForAgg)
       }
   }
 
@@ -3278,15 +3219,19 @@ export class Brainy<T = any> implements BrainyInterface<T> {
           ]
         : undefined)
 
-      // Aggregation hook (outside transaction — derived data). The view must
+      // Aggregation hook (outside transaction — derived data)
-      // carry EVERY reserved field top-level (not a subset): a groupBy on
-      // subtype/visibility/etc. otherwise decrements a nonexistent group and
-      // the real count never comes down.
       if (this._aggregationIndex && metadata) {
-        this._aggregationIndex.onEntityDeleted(
+        // Reconstruct entity-like object from stored metadata via the
-          id,
+        // canonical reserved/custom split (the hand-rolled destructure here
-          this.entityForAggFromRawRecord(metadata as Record<string, unknown>)
+        // missed subtype/_rev, leaking them into the aggregation view).
-        )
+        const { reserved, custom } = splitNounMetadataRecord(metadata)
+        const entityForAgg = {
+          type: reserved.noun,
+          service: reserved.service,
+          data: reserved.data,
+          metadata: custom
+        }
+        this._aggregationIndex.onEntityDeleted(id, entityForAgg)
       }
   }
 
@@ -6710,13 +6655,10 @@ export class Brainy<T = any> implements BrainyInterface<T> {
   /**
    * Add multiple entities in a single batch operation
    *
-   * Uses batch embedding (embedBatch) to pre-compute all vectors before any
+   * Uses batch embedding (embedBatch) to pre-compute all vectors in a single
-   * storage write, keeping model inference out of the per-item write path.
+   * WASM forward pass instead of N individual embed() calls, providing 5-10x
-   * (On the default WASM engine, batch throughput is comparable to sequential
+   * speedup on bulk inserts. Automatically adapts batch size and parallelism
-   * embed() calls — measured ~160 ms/text either way; a native embedding
+   * to the storage adapter (e.g., smaller batches for cloud storage).
-   * provider may batch faster.) Automatically adapts batch size and
-   * parallelism to the storage adapter (e.g., smaller batches for cloud
-   * storage).
    *
    * @param params - Batch add parameters
    * @param params.items - Array of AddParams (same shape as brain.add())
@@ -6914,30 +6856,6 @@ export class Brainy<T = any> implements BrainyInterface<T> {
     this.assertWritable('removeMany')
     await this.ensureInitialized()
 
-    // Loud selector validation: a call with no usable selector used to
-    // resolve successfully having deleted NOTHING (total: 0) — the classic
-    // silent no-op being a bare array passed positionally
-    // (removeMany([id]) instead of removeMany({ ids: [id] })). The caller
-    // believes the delete happened; every count derived afterwards is "wrong"
-    // while the engine was never even asked. Refuse instead.
-    if (Array.isArray(params)) {
-      throw new Error(
-        `removeMany() takes a params object, not a bare array — use removeMany({ ids: [...] })`
-      )
-    }
-    if (!params || (!params.ids && !params.type && !params.where)) {
-      throw new Error(
-        `removeMany() requires a selector: { ids } and/or { type, where }. ` +
-          `An empty selector would silently delete nothing — refusing.`
-      )
-    }
-    if (params.ids && params.ids.length === 0) {
-      throw new Error(
-        `removeMany() received ids: [] — an empty id list deletes nothing. ` +
-          `Pass the ids to delete, or omit ids and select by { type, where }.`
-      )
-    }
-
     // Determine what to delete
     let idsToDelete: string[] = []
 
@@ -7879,17 +7797,11 @@ export class Brainy<T = any> implements BrainyInterface<T> {
         ifAtGeneration: options?.ifAtGeneration,
         precommit: casPrecommit,
         execute: async () => {
-          await this.transactionManager.executeTransaction(
+          await this.transactionManager.executeTransaction(async (tx) => {
-            async (tx) => {
+            for (const operation of plan.operations) {
-              for (const operation of plan.operations) {
+              tx.addOperation(operation)
-                tx.addOperation(operation)
+            }
-              }
+          })
-            },
-            // Budget scales with the batch (or the caller's explicit
-            // timeoutMs): a flat 30s cap silently limited honest bulk work
-            // to ~15 ops on network disks (~2s/op measured in the field).
-            { timeout: transactTimeoutBudget(plan.operations.length, options?.timeoutMs) }
-          )
         }
       }))
     } catch (err) {
@@ -8265,72 +8177,6 @@ export class Brainy<T = any> implements BrainyInterface<T> {
     return this.generationStore.compact(options)
   }
 
-  /**
-   * @description Repack cold generation history into sealed segments —
-   * re-representation, never deletion: every record and delta stays readable
-   * (`asOf()` unchanged); the physical file count drops by orders of
-   * magnitude. Runs automatically (time-bounded) at `close()`; call this for
-   * explicit maintenance windows on long-lived writers. The ONLY history
-   * transform permitted under the archival profile (`retention: 'all'`).
-   * @param options - `timeBudgetMs` bounds the pass (early stop = consistent
-   *   prefix, next pass resumes); `batchGenerations` sizes each fold.
-   * @returns Folded generation count and segments created.
-   */
-  async repackHistory(options?: {
-    timeBudgetMs?: number
-    batchGenerations?: number
-  }): Promise<{ foldedGenerations: number; segmentsCreated: number }> {
-    this.assertWritable('repackHistory')
-    await this.ensureInitialized()
-    await this.generationStore.flushPendingSingleOps()
-    return this.generationStore.repackHistory(options)
-  }
-
-  /**
-   * @description Read-only generational-history footprint for fleet audits:
-   * generation count, total on-disk bytes, generation/timestamp range, the
-   * compaction horizon, and the retention policy in force. Touches no data and
-   * changes nothing. First call pays one walk over committed deltas to seed
-   * the running byte total (subsequent calls — and every adaptive retention
-   * check — are then O(1)).
-   *
-   * A pool operator's exposure check is one call per brain:
-   * @example
-   * const stats = await brain.historyStats()
-   * console.log(`${stats.generations} generations, ${stats.bytes} bytes, mode=${stats.retentionMode}`)
-   */
-  async historyStats(): Promise<HistoryStats> {
-    await this.ensureInitialized()
-    const stats = await this.generationStore.historyStats()
-    const policy = this.resolveRetentionPolicy()
-    return {
-      ...stats,
-      retentionMode: policy.mode,
-      effectiveBudgetBytes:
-        policy.mode === 'adaptive'
-          ? this.adaptiveHistoryBudgetBytes(policy.budgetBytes)
-          : null
-    }
-  }
-
-  /**
-   * @description A deterministic content digest of the generation log through
-   * `g` (D8 — gate-to-generation provenance): identical history produces the
-   * identical digest on any machine; divergence produces a different one.
-   * Release gates and suite verdicts pin `{generation, digest}` and verify
-   * both at execution time instead of pinning a git commit. O(segments +
-   * live-tier window), never O(all generations). Throws `RangeError` out of
-   * range and `GenerationCompactedError` below the horizon — a gate can
-   * never silently pin reclaimed history.
-   * @example
-   * const gate = { generation: brain.generation(), digest: await brain.generationDigest(brain.generation()) }
-   */
-  async generationDigest(g: number): Promise<string> {
-    await this.ensureInitialized()
-    await this.generationStore.flushPendingSingleOps()
-    return this.generationStore.generationDigest(g)
-  }
-
   /**
    * @description Drive the adaptive retention byte budget at runtime — the
    * settable input a machine-level coordinator (e.g. cor's `ResourceManager`,
@@ -8410,24 +8256,19 @@ export class Brainy<T = any> implements BrainyInterface<T> {
 
   /**
    * @description Run history compaction under the resolved `retention` policy
-   * when `autoCompact` is on (the default). Invoked from `close()` ONLY
+   * when `autoCompact` is on (the default). Invoked from `flush()` and
-   * (8.9.0) — flush() is durability work and never pays maintenance costs; a
+   * `close()` so generational record-sets cannot accumulate unbounded across a
-   * production deployment measured reclaim-on-flush blocking single writes
+   * long-lived writer's lifetime.
-   * for 25-191s under memory pressure. Long-lived writers that never close
-   * accumulate history until their next explicit `compactHistory()` — the
-   * documented trade: predictable writes, explicit maintenance.
    *
    * - `'all'` → returns without reclaiming (index compaction for speed still
    *   runs elsewhere; history is decoupled and kept).
    * - `'adaptive'` → reclaim oldest-unpinned history down to the byte budget.
    * - `'explicit'` → apply the supplied `maxGenerations`/`maxAge`/`maxBytes` caps.
    *
-   * Every auto pass is TIME-BOUNDED ({@link CLOSE_COMPACTION_BUDGET_MS}) so a
-   * large backlog can never stall a clean shutdown; the next pass resumes.
    * Read-only instances and an explicit `autoCompact: false` skip silently.
    * Pinned generations are never reclaimed ({@link GenerationStore.compact}).
    * Failures are logged and swallowed — compaction is housekeeping and must
-   * never fail a clean shutdown.
+   * never fail a flush or a clean shutdown.
    */
   private async autoCompactHistory(): Promise<void> {
     // Nothing to compact on a read-only instance or before init wired up the
@@ -8443,16 +8284,12 @@ export class Brainy<T = any> implements BrainyInterface<T> {
       if (policy.mode === 'adaptive') {
         const budget = this.adaptiveHistoryBudgetBytes(policy.budgetBytes)
         if (budget === Infinity) return // no pressure signal → keep everything this pass
-        await this.generationStore.compact({
+        await this.generationStore.compact({ maxBytes: budget })
-          maxBytes: budget,
-          timeBudgetMs: CLOSE_COMPACTION_BUDGET_MS
-        })
       } else {
         await this.generationStore.compact({
           maxGenerations: policy.maxGenerations,
           maxAge: policy.maxAge,
-          maxBytes: policy.maxBytes,
+          maxBytes: policy.maxBytes
-          timeBudgetMs: CLOSE_COMPACTION_BUDGET_MS
         })
       }
     } catch (error) {
@@ -9489,9 +9326,12 @@ export class Brainy<T = any> implements BrainyInterface<T> {
     )
     plan.touchedNouns.push(params.id)
 
-    // The full planGetEntity view, passed whole — a subset view makes the
+    const oldEntityForAgg = {
-    // old-side decrement miss reserved-field groups (double-count on update).
+      type: existing.type,
-    const oldEntityForAgg = existing as unknown as Record<string, unknown>
+      service: existing.service,
+      data: existing.data,
+      metadata: existing.metadata
+    }
     plan.postCommit.push(() => {
       if (this._aggregationIndex) {
         this._aggregationIndex.onEntityUpdated(params.id, entityForIndexing, oldEntityForAgg)
@@ -9612,9 +9452,14 @@ export class Brainy<T = any> implements BrainyInterface<T> {
     }
 
     if (metadata) {
-      // Mirror of remove()'s aggregation hook — the FULL reserved view, so
+      // Canonical reserved/custom split — mirror of remove()'s aggregation hook.
-      // reserved-field groupBy decrements find their group.
+      const { reserved, custom } = splitNounMetadataRecord(metadata)
-      const entityForAgg = this.entityForAggFromRawRecord(metadata as Record<string, unknown>)
+      const entityForAgg = {
+        type: reserved.noun,
+        service: reserved.service,
+        data: reserved.data,
+        metadata: custom
+      }
       plan.postCommit.push(() => {
         if (this._aggregationIndex) {
           this._aggregationIndex.onEntityDeleted(id, entityForAgg)
@@ -10249,30 +10094,6 @@ export class Brainy<T = any> implements BrainyInterface<T> {
     return await coordinator.import(source as Buffer | string | object, options)
   }
 
-  /** Brain-owned background deduplicator (lazy; see getBackgroundDeduplicator). */
-  private _backgroundDedup?: import('./import/BackgroundDeduplicator.js').BackgroundDeduplicator
-
-  /**
-   * The single brain-owned BackgroundDeduplicator, lazily constructed.
-   *
-   * Ownership matters here: the post-import dedup timer must outlive the
-   * per-call ImportCoordinator but never the brain. One instance per brain
-   * restores the intended cross-import debounce (per-coordinator instances
-   * each armed their own timer, so the "debounce" never spanned imports) and
-   * gives close() a handle to cancel pending work — a delete pass must never
-   * fire against a closed brain.
-   * @internal
-   */
-  async getBackgroundDeduplicator(): Promise<
-    import('./import/BackgroundDeduplicator.js').BackgroundDeduplicator
-  > {
-    if (!this._backgroundDedup) {
-      const { BackgroundDeduplicator } = await import('./import/BackgroundDeduplicator.js')
-      this._backgroundDedup = new BackgroundDeduplicator(this)
-    }
-    return this._backgroundDedup
-  }
-
   /**
    * Virtual File System API - Knowledge Operating System
    *
@@ -10597,14 +10418,12 @@ export class Brainy<T = any> implements BrainyInterface<T> {
       this.generationStore.persistCounterNow()
     ])
 
-    // NOTE (8.9.0): flush() no longer compacts history. Flush is DURABILITY
+    // 6. Auto-compact generational history per config.retention (default on).
-    // work — it must cost what this window's deltas cost, never what the
+    //    Runs after the flush so durable state is in place; respects live
-    // history backlog costs. Auto-compaction (a MAINTENANCE concern) runs at
+    //    Db pins and an explicit autoCompact: false.
-    // close() and via explicit compactHistory(); a production deployment
+    await this.autoCompactHistory()
-    // measured reclaim-on-flush stalling single writes for 25-191s under
-    // memory pressure, which is exactly the class this separation ends.
 
-    // 6. Stamp the entity tree: which source generation the canonical tree
+    // 7. Stamp the entity tree: which source generation the canonical tree
     //    reflects + the rollup invariants that verify it whole (the counters
     //    persisted in step 1). Written at flush boundaries — the tree tracks
     //    every commit by construction, so the stamp is a durable checkpoint,
@@ -16217,10 +16036,6 @@ export class Brainy<T = any> implements BrainyInterface<T> {
    * This ensures deferred persistence mode data is saved
    */
   async close(): Promise<void> {
-    // Cancel any pending post-import background deduplication FIRST — it is a
-    // writer (merge-deletes), and no delete pass may start mid- or post-close.
-    this._backgroundDedup?.cancelPending()
-
     // Change-feed teardown: no events are delivered for or after close().
     this._changeFeed.close()
 
@@ -16231,21 +16046,9 @@ export class Brainy<T = any> implements BrainyInterface<T> {
       await this.generationStore.flushPendingSingleOps()
     }
 
-    // Phase 0b: REPACK cold history into sealed segments (D1+D3 —
+    // Phase 0b: Auto-compact generational history per config.retention (default
-    // re-representation, never deletion; the only history transform under the
+    // on) BEFORE the generation store closes below. Respects live Db pins and
-    // archival profile), then auto-compact per config.retention. Repack runs
+    // an explicit autoCompact: false; no-op on read-only instances.
-    // FIRST so bounded-retention reclaim can drop whole segments. Both are
-    // time-bounded maintenance passes (8.9.0 law: flush() never pays these);
-    // both are housekeeping — failures warn, never fail a clean shutdown.
-    if (!this.isReadOnly && this.generationStore) {
-      try {
-        await this.generationStore.repackHistory({ timeBudgetMs: 5_000 })
-      } catch (error) {
-        console.warn(
-          `History repacking failed (non-fatal): ${error instanceof Error ? error.message : String(error)}`
-        )
-      }
-    }
     await this.autoCompactHistory()
 
     // Phase 1: Flush ALL components in parallel to persist buffered data

src/db/factLog.ts

@@ -102,26 +102,12 @@ export interface FactScanBatch {
   segmentId: string
 }
 
-/**
- * Liveness bound on a scan's FIRST batch (Stage-2 co-freeze, D1 contract):
- * `batches()` must yield its first batch — or fail loudly — within this many
- * ms of the first pull. A backlogged or damaged store may be SLOW, but it may
- * never be SILENT: a consumer awaiting the first batch is otherwise
- * indistinguishable from a wedge (the exact failure shape a production heal
- * hit against a generations-backlogged brain).
- */
-export const SCANFACTS_FIRST_BATCH_MS = 10_000
-
 /** The telemetry a scan OPEN returns (frozen shape). */
 export interface FactScanHandle {
   headGeneration: number
   segmentCount: number
   approxFactCount: number
-  /**
+  /** Ordered batches; a detected gap aborts LOUDLY, never a silent skip. */
-   * Ordered batches; a detected gap aborts LOUDLY, never a silent skip.
-   * Liveness contract: the FIRST batch resolves or rejects within
-   * {@link SCANFACTS_FIRST_BATCH_MS} of the first pull — never a silent hang.
-   */
   batches: () => AsyncGenerator<FactScanBatch>
   /** Close telemetry — the invariant cross-check, valid after iteration ends. */
   summary: () => { factsYielded: number; segmentsRead: number }
@@ -454,8 +440,6 @@ export class FactLog {
     toGeneration?: number
     kinds?: Array<'noun' | 'verb'>
     batchSize?: number
-    /** Test override for the first-batch liveness bound (default {@link SCANFACTS_FIRST_BATCH_MS}). */
-    firstBatchTimeoutMs?: number
   }): FactScanHandle {
     const from = options?.fromGeneration ?? 1
     const to = options?.toGeneration ?? this.head
@@ -530,43 +514,11 @@ export class FactLog {
       }
     }
 
-    // Liveness wrapper: the FIRST pull races the contract deadline. Only the
-    // first — the bound is time-to-first-batch (proof the producer is alive),
-    // not per-batch pacing; and it runs only while a pull is actually pending,
-    // so consumer think-time between pulls never counts against the producer.
-    const firstBatchTimeoutMs = options?.firstBatchTimeoutMs ?? SCANFACTS_FIRST_BATCH_MS
-    async function* batchesWithLiveness(this: void): AsyncGenerator<FactScanBatch> {
-      const inner = batches()
-      let timer: NodeJS.Timeout | undefined
-      try {
-        const deadline = new Promise<never>((_, reject) => {
-          timer = setTimeout(
-            () =>
-              reject(
-                new Error(
-                  `fact log: scanFacts produced no first batch within ${firstBatchTimeoutMs}ms ` +
-                    `(liveness contract) — the store is wedged or unreadably slow; aborting scan LOUDLY ` +
-                    `instead of hanging the consumer.`
-                )
-              ),
-            firstBatchTimeoutMs
-          )
-          timer.unref?.()
-        })
-        const first = await Promise.race([inner.next(), deadline])
-        if (first.done) return
-        yield first.value
-      } finally {
-        clearTimeout(timer)
-      }
-      yield* inner
-    }
-
     return {
       headGeneration: this.head,
       segmentCount: segments.length + (tailSnapshot.length > 0 ? 1 : 0),
       approxFactCount,
-      batches: batchesWithLiveness,
+      batches,
       summary: () => ({ factsYielded, segmentsRead })
     }
   }

src/db/generationSegments.ts

@@ -1,459 +0,0 @@
-/**
- * @module db/generationSegments
- * @description The generation-segment store — Stage-2 D1+D3+repacking's file
- * format (co-frozen 2026-07-19; design: the d1-d3-repacking spec).
- *
- * Packs CONSECUTIVE cold generations' record-sets (before-images + delta)
- * into append-once segment files with derived sidecar indexes, so history
- * scales in SEGMENTS (tens) instead of FILES-PER-GENERATION (hundreds of
- * thousands), and cold-open reads ONE manifest instead of listing the
- * backlog. Layout under `_generations/segments/`:
- *
- * - `seg-<firstGen, zero-padded 20>.bgs` — magic "BGS1", then one frame per
- *   generation: `u32 payloadLen | u32 crc32c | msgpack payload`. Payload is
- *   POSITIONAL: `[generation, timestamp, delta, records[], flags]` with
- *   records `[kindByte, id, record]`. `flags` reserves encoding evolution
- *   (bit 0 = compressed payload — v1 always 0; a future writer upgrade,
- *   never a format break). Sealed segments are IMMUTABLE — the fact log's
- *   own law, generalized.
- * - `seg-<firstGen>.idx` — DERIVED sidecar (msgpack): per-generation frame
- *   offsets (point reads = one ranged read, never a listing) + per-id
- *   generation postings (per-id chain rebuilds read only what they need).
- *   Corrupt/missing → rebuilt from its segment in one sequential read,
- *   loudly.
- * - `manifest.json` — the segment catalogue + `compactedBelow` (D3's
- *   horizon marker). Cold-open reads THIS; the packed backlog is never
- *   listed.
- *
- * D3 semantics carried here: bounded-retention reclaim drops WHOLE segments
- * at boundaries (O(1) per segment, no rewrite); under the archival profile
- * (`retention: 'all'`) nothing here is ever dropped — folding is the only
- * transform (re-representation, never deletion).
- */
-
-import { encode as msgpackEncode, decode as msgpackDecode } from '@msgpack/msgpack'
-import { crc32c } from '../utils/crc32c.js'
-import type { FactLogStorage } from './factLog.js'
-import { prodLog } from '../utils/logger.js'
-
-/** Directory for segment files + manifest, under the generations prefix. */
-export const SEGMENTS_PREFIX = '_generations/segments'
-
-/** Target sealed-segment size (co-freeze proposal; tunable on evidence). */
-export const SEGMENT_TARGET_BYTES = 64 * 1024 * 1024
-
-const MAGIC = new TextEncoder().encode('BGS1')
-const FRAME_PREFIX_BYTES = 8 // u32 payloadLen + u32 crc32c
-const MANIFEST_PATH = `${SEGMENTS_PREFIX}/manifest.json`
-
-/** One generation's fold input — exactly what the live tier holds for it. */
-export interface FoldGeneration {
-  generation: number
-  timestamp: number
-  /** The tx.json delta object, carried verbatim. */
-  delta: unknown
-  /** The before-image record-set (empty for record-less generations). */
-  records: Array<{ kind: 'noun' | 'verb'; id: string; record: unknown }>
-}
-
-/** Manifest entry for one sealed segment. */
-export interface SegmentMeta {
-  file: string
-  firstGeneration: number
-  lastGeneration: number
-  frames: number
-  bytes: number
-  /** crc32c of the full segment byte stream — the digest chain's link. */
-  checksum: number
-}
-
-interface SegmentManifest {
-  version: 1
-  compactedBelow: number
-  segments: SegmentMeta[]
-}
-
-interface SidecarIndex {
-  version: 1
-  /** [generation, frameOffset, frameLen] ascending by generation. */
-  generations: Array<[number, number, number]>
-  /** `${kindByte}:${id}` → ascending generations holding a record for it. */
-  ids: Record<string, number[]>
-}
-
-const segmentFileName = (firstGeneration: number): string =>
-  `seg-${String(firstGeneration).padStart(20, '0')}.bgs`
-const sidecarFileName = (firstGeneration: number): string =>
-  `seg-${String(firstGeneration).padStart(20, '0')}.idx`
-
-/**
- * The generation-segment store. Owns the packed tier ONLY — the live
- * per-generation tier and the routing between tiers belong to
- * `GenerationStore`. All mutating entry points here are called under the
- * generation store's commit mutex.
- */
-export class GenerationSegmentStore {
-  private readonly storage: FactLogStorage
-  private manifest: SegmentManifest = { version: 1, compactedBelow: 0, segments: [] }
-  /** Sidecar cache — segments are immutable, so entries never invalidate. */
-  private readonly sidecars = new Map<string, SidecarIndex>()
-
-  constructor(storage: FactLogStorage) {
-    this.storage = storage
-  }
-
-  /** Load the manifest (ONE read — never a directory listing). */
-  async open(): Promise<void> {
-    const raw = (await this.storage.readRawObject(MANIFEST_PATH)) as SegmentManifest | null
-    if (raw) {
-      if (raw.version !== 1) {
-        throw new Error(
-          `[GenerationSegments] manifest version ${String(raw.version)} is newer than this ` +
-            `engine understands — refusing to serve partial history. Upgrade the engine.`
-        )
-      }
-      this.manifest = raw
-    }
-  }
-
-  /** The packed tier's catalogue (ascending, immutable snapshot). */
-  segments(): readonly SegmentMeta[] {
-    return this.manifest.segments
-  }
-
-  /** D3's horizon marker: generations below this were reclaimed (bounded profiles only). */
-  compactedBelow(): number {
-    return this.manifest.compactedBelow
-  }
-
-  /** The covering sealed segment for `gen`, or null if it lives outside the packed tier. */
-  private coveringSegment(gen: number): SegmentMeta | null {
-    // Manifest is ascending and ranges never overlap — binary search.
-    const segs = this.manifest.segments
-    let lo = 0
-    let hi = segs.length - 1
-    while (lo <= hi) {
-      const mid = (lo + hi) >> 1
-      const s = segs[mid]
-      if (gen < s.firstGeneration) hi = mid - 1
-      else if (gen > s.lastGeneration) lo = mid + 1
-      else return s
-    }
-    return null
-  }
-
-  /** True when `gen` is packed (readable from this tier). */
-  hasGeneration(gen: number): boolean {
-    return this.coveringSegment(gen) !== null
-  }
-
-  /**
-   * Fold consecutive generations into ONE new sealed segment + sidecar and
-   * append it to the manifest atomically. Caller guarantees: `gens` is
-   * ascending, contiguous with the packed tier (first = last packed + 1 when
-   * segments exist), and already durable in the live tier. Crash between the
-   * segment write and the caller's live-tier delete leaves a DUPLICATE
-   * representation — resolved live-tier-wins by the reader; never a gap.
-   */
-  async fold(gens: FoldGeneration[]): Promise<SegmentMeta> {
-    if (gens.length === 0) {
-      throw new Error('[GenerationSegments] fold() requires at least one generation')
-    }
-    for (let i = 1; i < gens.length; i++) {
-      if (gens[i].generation <= gens[i - 1].generation) {
-        throw new Error('[GenerationSegments] fold() input must be strictly ascending')
-      }
-    }
-    const last = this.manifest.segments[this.manifest.segments.length - 1]
-    if (last && gens[0].generation <= last.lastGeneration) {
-      throw new Error(
-        `[GenerationSegments] fold() overlaps the packed tier: ${gens[0].generation} ≤ ` +
-          `sealed ${last.lastGeneration} — segments are immutable, never rewritten`
-      )
-    }
-
-    const first = gens[0].generation
-    const file = segmentFileName(first)
-    const sidecar: SidecarIndex = { version: 1, generations: [], ids: {} }
-
-    // Encode all frames, tracking offsets for the sidecar.
-    const parts: Uint8Array[] = [MAGIC]
-    let offset = MAGIC.length
-    for (const g of gens) {
-      const payload = msgpackEncode([
-        g.generation,
-        g.timestamp,
-        g.delta,
-        g.records.map((r) => [r.kind === 'noun' ? 0 : 1, r.id, r.record]),
-        0 // flags: v1 = uncompressed
-      ])
-      const frame = new Uint8Array(FRAME_PREFIX_BYTES + payload.length)
-      const view = new DataView(frame.buffer)
-      view.setUint32(0, payload.length, true)
-      view.setUint32(4, crc32c(payload), true)
-      frame.set(payload, FRAME_PREFIX_BYTES)
-      sidecar.generations.push([g.generation, offset, frame.length])
-      for (const r of g.records) {
-        const key = `${r.kind === 'noun' ? 0 : 1}:${r.id}`
-        ;(sidecar.ids[key] ??= []).push(g.generation)
-      }
-      parts.push(frame)
-      offset += frame.length
-    }
-    const total = parts.reduce((n, p) => n + p.length, 0)
-    const bytes = new Uint8Array(total)
-    let at = 0
-    for (const p of parts) {
-      bytes.set(p, at)
-      at += p.length
-    }
-
-    const meta: SegmentMeta = {
-      file,
-      firstGeneration: first,
-      lastGeneration: gens[gens.length - 1].generation,
-      frames: gens.length,
-      bytes: total,
-      checksum: crc32c(bytes)
-    }
-
-    // Durability order: segment + sidecar fsync'd BEFORE the manifest names
-    // them (a crash before the manifest = invisible orphan files, harmless);
-    // manifest last, atomically.
-    const segPath = `${SEGMENTS_PREFIX}/${file}`
-    const idxPath = `${SEGMENTS_PREFIX}/${sidecarFileName(first)}`
-    await this.storage.writeRawBytes(segPath, bytes)
-    await this.storage.writeRawBytes(idxPath, msgpackEncode(sidecar))
-    await this.storage.syncRawObjects([segPath, idxPath])
-    const next: SegmentManifest = {
-      ...this.manifest,
-      segments: [...this.manifest.segments, meta]
-    }
-    await this.storage.writeRawObject(MANIFEST_PATH, next)
-    await this.storage.syncRawObjects([MANIFEST_PATH])
-    this.manifest = next
-    this.sidecars.set(file, sidecar)
-    return meta
-  }
-
-  /** Load (or rebuild, loudly) a segment's sidecar. */
-  private async sidecarFor(meta: SegmentMeta): Promise<SidecarIndex> {
-    const cached = this.sidecars.get(meta.file)
-    if (cached) return cached
-    const idxPath = `${SEGMENTS_PREFIX}/${sidecarFileName(meta.firstGeneration)}`
-    const raw = await this.storage.readRawBytes(idxPath)
-    if (raw) {
-      try {
-        const idx = msgpackDecode(raw) as SidecarIndex
-        if (idx.version === 1) {
-          this.sidecars.set(meta.file, idx)
-          return idx
-        }
-      } catch {
-        // fall through to rebuild
-      }
-    }
-    // Sidecars are DERIVED: rebuild from the segment, loudly — never serve
-    // wrong offsets silently.
-    prodLog.warn(
-      `[GenerationSegments] sidecar for ${meta.file} missing or unreadable — rebuilding from the segment`
-    )
-    const rebuilt = await this.rebuildSidecar(meta)
-    await this.storage.writeRawBytes(idxPath, msgpackEncode(rebuilt))
-    this.sidecars.set(meta.file, rebuilt)
-    return rebuilt
-  }
-
-  /** One sequential read of the segment → a fresh sidecar. Verifies every frame CRC. */
-  private async rebuildSidecar(meta: SegmentMeta): Promise<SidecarIndex> {
-    const frames = await this.readAllFrames(meta)
-    const idx: SidecarIndex = { version: 1, generations: [], ids: {} }
-    for (const f of frames) {
-      idx.generations.push([f.generation, f.offset, f.frameLen])
-      for (const r of f.records) {
-        const key = `${r.kind === 'noun' ? 0 : 1}:${r.id}`
-        ;(idx.ids[key] ??= []).push(f.generation)
-      }
-    }
-    return idx
-  }
-
-  private decodeFrame(
-    payload: Uint8Array
-  ): { generation: number; timestamp: number; delta: unknown; records: FoldGeneration['records'] } {
-    const [generation, timestamp, delta, rawRecords] = msgpackDecode(payload) as [
-      number,
-      number,
-      unknown,
-      Array<[number, string, unknown]>,
-      number
-    ]
-    return {
-      generation,
-      timestamp,
-      delta,
-      records: rawRecords.map(([kindByte, id, record]) => ({
-        kind: kindByte === 0 ? ('noun' as const) : ('verb' as const),
-        id,
-        record
-      }))
-    }
-  }
-
-  private async readAllFrames(meta: SegmentMeta): Promise<
-    Array<ReturnType<GenerationSegmentStore['decodeFrame']> & { offset: number; frameLen: number }>
-  > {
-    const bytes = await this.storage.readRawBytes(`${SEGMENTS_PREFIX}/${meta.file}`)
-    if (!bytes) {
-      throw new Error(
-        `[GenerationSegments] sealed segment ${meta.file} is MISSING — packed history is damaged; ` +
-          `refusing to continue silently`
-      )
-    }
-    const out: Array<ReturnType<GenerationSegmentStore['decodeFrame']> & { offset: number; frameLen: number }> = []
-    let at = MAGIC.length
-    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)
-    while (at + FRAME_PREFIX_BYTES <= bytes.length) {
-      const payloadLen = view.getUint32(at, true)
-      const crc = view.getUint32(at + 4, true)
-      const payload = bytes.subarray(at + FRAME_PREFIX_BYTES, at + FRAME_PREFIX_BYTES + payloadLen)
-      if (payload.length !== payloadLen || crc32c(payload) !== crc) {
-        throw new Error(
-          `[GenerationSegments] frame CRC mismatch in ${meta.file} at offset ${at} — ` +
-            `packed history is damaged; refusing to serve it`
-        )
-      }
-      out.push({ ...this.decodeFrame(payload), offset: at, frameLen: FRAME_PREFIX_BYTES + payloadLen })
-      at += FRAME_PREFIX_BYTES + payloadLen
-    }
-    return out
-  }
-
-  /** Read one packed generation's frame via its sidecar offset (one ranged read). */
-  private async readFrame(
-    gen: number
-  ): Promise<ReturnType<GenerationSegmentStore['decodeFrame']> | null> {
-    const meta = this.coveringSegment(gen)
-    if (!meta) return null
-    const idx = await this.sidecarFor(meta)
-    // generations ascending → binary search.
-    const gens = idx.generations
-    let lo = 0
-    let hi = gens.length - 1
-    while (lo <= hi) {
-      const mid = (lo + hi) >> 1
-      if (gens[mid][0] < gen) lo = mid + 1
-      else if (gens[mid][0] > gen) hi = mid - 1
-      else {
-        const [, offset, frameLen] = gens[mid]
-        const bytes = await this.storage.readRawBytes(`${SEGMENTS_PREFIX}/${meta.file}`)
-        if (!bytes) {
-          throw new Error(`[GenerationSegments] sealed segment ${meta.file} is MISSING`)
-        }
-        const frame = bytes.subarray(offset, offset + frameLen)
-        const view = new DataView(frame.buffer, frame.byteOffset, frame.byteLength)
-        const payloadLen = view.getUint32(0, true)
-        const crc = view.getUint32(4, true)
-        const payload = frame.subarray(FRAME_PREFIX_BYTES, FRAME_PREFIX_BYTES + payloadLen)
-        if (payload.length !== payloadLen || crc32c(payload) !== crc) {
-          throw new Error(
-            `[GenerationSegments] frame CRC mismatch for generation ${gen} in ${meta.file} — ` +
-              `packed history is damaged; refusing to serve it`
-          )
-        }
-        return this.decodeFrame(payload)
-      }
-    }
-    // In the covering range but not present: the packed tier is dense by
-    // construction (fold packs every generation it is handed, including
-    // record-less ones) — absence inside a sealed range is damage.
-    throw new Error(
-      `[GenerationSegments] generation ${gen} is inside sealed segment ${meta.file}'s declared ` +
-        `range but has no frame — packed history is damaged`
-    )
-  }
-
-  /** The packed tier's delta for `gen` (null = not packed). */
-  async readDelta(gen: number): Promise<{ delta: unknown; timestamp: number } | null> {
-    const frame = await this.readFrame(gen)
-    return frame ? { delta: frame.delta, timestamp: frame.timestamp } : null
-  }
-
-  /** The packed tier's full record-set for `gen` (null = not packed). */
-  async readRecords(gen: number): Promise<FoldGeneration['records'] | null> {
-    const frame = await this.readFrame(gen)
-    return frame ? frame.records : null
-  }
-
-  /** One packed before-image (null = not packed OR no record for the id in that generation). */
-  async readRecord(gen: number, kind: 'noun' | 'verb', id: string): Promise<unknown | null> {
-    const frame = await this.readFrame(gen)
-    if (!frame) return null
-    const hit = frame.records.find((r) => r.kind === kind && r.id === id)
-    return hit ? hit.record : null
-  }
-
-  /**
-   * D3 reclaim: drop WHOLE segments whose lastGeneration < `belowGeneration`
-   * and bump `compactedBelow`. Partial segments are never dropped — the
-   * boundary waits. NEVER called under the archival profile (the caller
-   * enforces retention semantics; this method only executes boundary drops).
-   */
-  async dropSegmentsBelow(belowGeneration: number): Promise<{ dropped: number; compactedBelow: number }> {
-    const keep: SegmentMeta[] = []
-    const drop: SegmentMeta[] = []
-    for (const s of this.manifest.segments) {
-      ;(s.lastGeneration < belowGeneration ? drop : keep).push(s)
-    }
-    if (drop.length === 0) {
-      return { dropped: 0, compactedBelow: this.manifest.compactedBelow }
-    }
-    const compactedBelow = Math.max(
-      this.manifest.compactedBelow,
-      drop[drop.length - 1].lastGeneration + 1
-    )
-    // Manifest first (the drop is authoritative once named), then bytes —
-    // a crash between leaves orphan segment files invisible to the manifest,
-    // harmless and re-collectable.
-    const next: SegmentManifest = { ...this.manifest, compactedBelow, segments: keep }
-    await this.storage.writeRawObject(MANIFEST_PATH, next)
-    await this.storage.syncRawObjects([MANIFEST_PATH])
-    this.manifest = next
-    for (const s of drop) {
-      await this.storage.deleteRawObject(`${SEGMENTS_PREFIX}/${s.file}`)
-      await this.storage.deleteRawObject(`${SEGMENTS_PREFIX}/${sidecarFileName(s.firstGeneration)}`)
-      this.sidecars.delete(s.file)
-    }
-    return { dropped: drop.length, compactedBelow }
-  }
-
-  /**
-   * D8 rider — the packed portion of `generationDigest(g)`: a deterministic
-   * crc32c chain over sealed-segment checksums fully below `g`, plus the
-   * frame CRC of `g`'s own frame when `g` is mid-segment. O(segments), not
-   * O(generations); identical history ⇒ identical digest on any machine.
-   * The live-tier portion is composed by the caller.
-   */
-  async digestThroughPacked(g: number): Promise<number | null> {
-    let digest = 0
-    let covered = false
-    for (const s of this.manifest.segments) {
-      if (s.lastGeneration <= g) {
-        digest = crc32c(new TextEncoder().encode(`${digest}:${s.checksum}`))
-        if (s.lastGeneration === g) covered = true
-      } else if (s.firstGeneration <= g) {
-        // g is mid-segment: chain the partial prefix via g's frame CRC.
-        const frame = await this.readFrame(g)
-        if (frame === null) return null
-        const idx = await this.sidecarFor(s)
-        const upTo = idx.generations.filter(([gen]) => gen <= g)
-        for (const [gen, offset, frameLen] of upTo) {
-          digest = crc32c(new TextEncoder().encode(`${digest}:${gen}:${offset}:${frameLen}`))
-        }
-        covered = true
-        break
-      }
-    }
-    return covered || this.manifest.segments.length > 0 ? digest : null
-  }
-}

src/db/generationStore.ts

@@ -46,8 +46,6 @@ import type {
   TxLogEntry
 } from './types.js'
 import { FactLog, storageSupportsFactLog, type CommitFact, type FactOp } from './factLog.js'
-import { GenerationSegmentStore, type FoldGeneration } from './generationSegments.js'
-import { crc32c } from '../utils/crc32c.js'
 
 /**
  * The byte-identical before-images of every id a commit touches, read UNDER
@@ -259,30 +257,6 @@ export class GenerationStore {
    */
   private deltaCacheMax = 4096
 
-  /**
-   * Running total of on-disk history bytes across committed generations —
-   * `null` until {@link historyBytes} pays its one seeding walk. Maintained
-   * incrementally at commit/reclaim so the adaptive retention check on every
-   * flush() is O(1), never a tail re-walk. Never updated by cache re-reads
-   * ({@link setDelta} inserts are cache population, not new history).
-   */
-  private historyBytesTotal: number | null = null
-
-  /**
-   * The packed tier (D1+D3): sealed segments holding folded cold
-   * generations. Null until {@link open} wires it (and on storage adapters
-   * without raw-byte primitives — the live tier then carries everything,
-   * exactly as before the packed tier existed).
-   */
-  private segments: GenerationSegmentStore | null = null
-
-  /**
-   * Live-tier window: generations newer than `committed - REPACK_LIVE_WINDOW`
-   * are never folded — the hot tail stays in the per-generation layout the
-   * write path owns. Matches the resident chain window's scale.
-   */
-  static readonly REPACK_LIVE_WINDOW = 1024
-
   /**
    * Model-B per-write group-commit — the in-memory PENDING tier.
    *
@@ -450,33 +424,6 @@ export class GenerationStore {
       this.factLog = null
     }
 
-    // PACKED TIER (D1+D3): same capability gate as the fact log. Opening
-    // reads ONE manifest — never a listing of the packed backlog — and seeds
-    // committedRanges with the sealed ranges so packed generations resolve
-    // exactly like live ones.
-    if (storageSupportsFactLog(this.storage)) {
-      this.segments = new GenerationSegmentStore(this.storage)
-      await this.segments.open()
-      const packedRanges = this.segments
-        .segments()
-        .map((s): [number, number] => [s.firstGeneration, Math.min(s.lastGeneration, this.committed)])
-        .filter(([lo, hi]) => lo <= hi)
-      if (packedRanges.length > 0) {
-        // Merge packed (older) + live (newer) interval sets — both ascending;
-        // coalesce adjacency so range arithmetic stays interval-exact.
-        const merged: Array<[number, number]> = []
-        for (const r of [...packedRanges, ...this.committedRanges].sort((a, b) => a[0] - b[0])) {
-          const last = merged[merged.length - 1]
-          if (last && r[0] <= last[1] + 1) last[1] = Math.max(last[1], r[1])
-          else merged.push([r[0], r[1]])
-        }
-        this.committedRanges = merged
-      }
-      this.horizonGen = Math.max(this.horizonGen, this.segments.compactedBelow() - 1)
-    } else {
-      this.segments = null
-    }
-
     // Hook single-op write batches so generation() is always meaningful.
     // Suppressed while a transact batch executes (the batch is ONE generation).
     if (!options?.readOnly) {
@@ -536,85 +483,6 @@ export class GenerationStore {
     return this.horizonGen
   }
 
-  /**
-   * @description Read-only history footprint for fleet audits: how much
-   * generational history this store holds on disk. `bytes` pays (and seeds)
-   * the one-time {@link historyBytes} walk on first call — subsequent calls
-   * are O(1). The oldest/newest timestamps come from those generations'
-   * deltas (cache-bounded reads).
-   * @returns Counts, bytes, generation range, and the compaction horizon.
-   */
-  /**
-   * @description D8 (gate-to-generation provenance): a deterministic content
-   * digest of the generation log THROUGH `g` — identical history ⇒ identical
-   * digest on any machine; any divergence (different records, different
-   * order, reclaimed range) ⇒ different digest. Composed from the packed
-   * tier's sealed-segment checksum chain (O(segments)) plus the live tier's
-   * per-generation delta digests (O(live window at most)). Release gates pin
-   * {generation, digest} and verify both at execution time.
-   * @param g - The generation to digest through (≤ committed).
-   * @returns A hex digest string, stable across reopen and repacking states
-   *   ONLY for fully-packed prefixes — repacking changes representation, so
-   *   the composed digest is defined over CONTENT: live-tier gens hash their
-   *   delta + record ids, packed gens hash via frame CRCs. A gate should pin
-   *   after a repack pass for long-term stability, or re-pin on repack.
-   */
-  async generationDigest(g: number): Promise<string> {
-    if (!Number.isInteger(g) || g < 1 || g > this.committed) {
-      throw new RangeError(
-        `generationDigest(): generation ${g} is out of range [1, ${this.committed}]`
-      )
-    }
-    if (g <= this.horizonGen) {
-      throw new GenerationCompactedError(g, this.horizonGen)
-    }
-    let digest = 0
-    const enc = new TextEncoder()
-    if (this.segments) {
-      const packed = await this.segments.digestThroughPacked(g)
-      if (packed !== null) digest = packed
-    }
-    // Live-tier composition: every committed gen ≤ g not covered by a sealed
-    // segment hashes its delta content in ascending order.
-    for (const gen of this.committedGensAsc()) {
-      if (gen > g) break
-      if (this.segments?.hasGeneration(gen)) continue
-      const delta = await this.getDelta(gen)
-      digest = crc32c(
-        enc.encode(
-          `${digest}:${gen}:${delta.timestamp}:${[...delta.nouns].sort().join(',')}:${[...delta.verbs].sort().join(',')}`
-        )
-      )
-    }
-    return digest.toString(16).padStart(8, '0')
-  }
-
-  async historyStats(): Promise<{
-    generations: number
-    bytes: number
-    oldestGeneration: number | null
-    newestGeneration: number | null
-    oldestTimestamp: number | null
-    newestTimestamp: number | null
-    horizon: number
-  }> {
-    let oldest: number | null = null
-    let newest: number | null = null
-    for (const gen of this.committedGensAsc()) {
-      if (oldest === null) oldest = gen
-      newest = gen
-    }
-    return {
-      generations: this.committedCount(),
-      bytes: await this.historyBytes(),
-      oldestGeneration: oldest,
-      newestGeneration: newest,
-      oldestTimestamp: oldest !== null ? (await this.getDelta(oldest)).timestamp : null,
-      newestTimestamp: newest !== null ? (await this.getDelta(newest)).timestamp : null,
-      horizon: this.horizonGen
-    }
-  }
-
   /**
    * @description Read one generation's persisted before-image records — the
    * compaction fallback for generations written before deltas carried
@@ -627,17 +495,14 @@ export class GenerationStore {
     try {
       paths = await this.storage.listRawObjects(`${GENERATIONS_PREFIX}/${gen}/prev`)
     } catch {
-      paths = []
+      return []
     }
     const records: GenerationRecord[] = []
     for (const p of paths) {
       const record = (await this.storage.readRawObject(p)) as GenerationRecord | null
       if (record) records.push(record)
     }
-    if (records.length > 0) return records
+    return records
-    // Two-tier: folded generations serve their record-set from the segment.
-    const packed = await this.segments?.readRecords(gen)
-    return packed ? (packed.map((r) => r.record) as GenerationRecord[]) : []
   }
 
   /**
@@ -984,9 +849,6 @@ export class GenerationStore {
           timestamp,
           bytes: delta.bytes ?? 0
         })
-        if (this.historyBytesTotal !== null) {
-          this.historyBytesTotal += delta.bytes ?? 0
-        }
         this.extendChains(gen, nouns, verbs)
         const logEntry: TxLogEntry = { generation: gen, timestamp, ...(args.meta && { meta: args.meta }) }
         await this.storage.appendTxLogLine(JSON.stringify(logEntry))
@@ -1440,9 +1302,6 @@ export class GenerationStore {
           timestamp: buf.timestamp,
           bytes: genBytes.get(gen) ?? 0
         })
-        if (this.historyBytesTotal !== null) {
-          this.historyBytesTotal += genBytes.get(gen) ?? 0
-        }
         this.pendingBuffer.delete(gen)
       }
       this.pendingGens = []
@@ -1875,15 +1734,9 @@ export class GenerationStore {
     if (pending) {
       return (kind === 'noun' ? pending.nouns : pending.verbs).get(id) ?? null
     }
-    const live = (await this.storage.readRawObject(
+    return (await this.storage.readRawObject(
       `${GENERATIONS_PREFIX}/${gen}/prev/${id}.json`
     )) as GenerationRecord | null
-    if (live) return live
-    // Two-tier: the packed tier serves folded generations (live-tier-wins).
-    if (this.segments?.hasGeneration(gen)) {
-      return (await this.segments.readRecord(gen, kind, id)) as GenerationRecord | null
-    }
-    return null
   }
 
   /**
@@ -2230,21 +2083,6 @@ export class GenerationStore {
       `${GENERATIONS_PREFIX}/${gen}/tx.json`
     )) as GenerationDelta | null
     if (delta === null) {
-      // Two-tier read (D1+D3): not in the live tier → the packed tier.
-      // Live-tier-wins ordering (a crash mid-fold leaves a duplicate, never
-      // a gap), so the segment lookup runs only after the live miss.
-      const packed = await this.segments?.readDelta(gen)
-      if (packed) {
-        const d = packed.delta as GenerationDelta
-        const entry = {
-          nouns: new Set(d.nouns),
-          verbs: new Set(d.verbs),
-          timestamp: packed.timestamp,
-          bytes: d.bytes ?? 0
-        }
-        this.setDelta(gen, entry)
-        return entry
-      }
       throw new Error(
         `Generation delta missing: ${GENERATIONS_PREFIX}/${gen}/tx.json ` +
           `(store corrupted or records removed outside compactHistory())`
@@ -2284,26 +2122,17 @@ export class GenerationStore {
   /**
    * @description Total serialized bytes of the ON-DISK generational history —
    * the sum of every committed generation's recorded `bytes`. Backs the
-   * `maxBytes` and adaptive retention caps. O(1) after the first call: the
+   * `maxBytes` and adaptive retention caps. Reads each committed generation's
-   * total is computed by ONE walk over committed deltas, then maintained
+   * delta (cached; a re-read only for cache-evicted ones) — O(committed
-   * incrementally at every commit (+bytes) and reclaim (−bytes) and dropped on
+   * generations), bounded by retention itself and invoked only at compaction
-   * a wholesale state replacement (restore). Without the running total, the
+   * time. Pending (un-flushed) generations are excluded (they are not on disk).
-   * adaptive auto-compaction on every flush() re-walked the ENTIRE history —
-   * O(committed generations) file reads per flush past the delta-cache bound —
-   * which is how a 70k-generation production brain turned every write into a
-   * full-tail scan (SELF-GENERATIONS-GROWTH). Pending (un-flushed) generations
-   * are excluded (they are not on disk).
    * @returns The total on-disk history byte count.
    */
   async historyBytes(): Promise<number> {
-    if (this.historyBytesTotal !== null) {
-      return this.historyBytesTotal
-    }
     let total = 0
     for (const gen of this.committedGensAsc()) {
       total += (await this.getDelta(gen)).bytes
     }
-    this.historyBytesTotal = total
     return total
   }
 
@@ -2326,94 +2155,6 @@ export class GenerationStore {
    * @param options - Retention caps (see {@link CompactHistoryOptions}).
    * @returns Count of removed record-sets and the new horizon.
    */
-  /**
-   * @description The REPACKER (D1+D3+repacking): fold cold live-tier
-   * generations into sealed segments — re-representation, never deletion.
-   * Every record and delta stays readable (asOf/chains unchanged); the
-   * per-generation directories are deleted only AFTER their segment is
-   * durable (crash between = duplicate representation, resolved
-   * live-tier-wins by every reader; never a gap). This is the transform that
-   * takes a 70k-file history to tens of segment files, and the ONLY history
-   * transform permitted under the archival profile.
-   *
-   * Folds oldest-first, contiguous from the packed boundary, in batches, and
-   * stops at the live window ({@link GenerationStore.REPACK_LIVE_WINDOW})
-   * or when `timeBudgetMs` is spent — an early stop is a consistent prefix;
-   * the next pass resumes.
-   */
-  async repackHistory(options?: { timeBudgetMs?: number; batchGenerations?: number }): Promise<{
-    foldedGenerations: number
-    segmentsCreated: number
-  }> {
-    if (!this.segments) return { foldedGenerations: 0, segmentsCreated: 0 }
-    const segments = this.segments
-    return this.withMutex(async () => {
-      const deadline =
-        options?.timeBudgetMs !== undefined ? Date.now() + options.timeBudgetMs : undefined
-      const batchSize = options?.batchGenerations ?? 512
-      const coldCeiling = this.committed - GenerationStore.REPACK_LIVE_WINDOW
-      const packedThrough =
-        segments.segments().length > 0
-          ? segments.segments()[segments.segments().length - 1].lastGeneration
-          : 0
-
-      // Cold, unpacked, committed generations — ascending, contiguous scan.
-      const eligible: number[] = []
-      for (const gen of this.committedGensAsc()) {
-        if (gen > coldCeiling) break
-        if (gen <= packedThrough) continue // already packed (dup fold barred)
-        if (this.pendingBuffer.has(gen)) continue // un-flushed = live by definition
-        eligible.push(gen)
-      }
-
-      let folded = 0
-      let segmentsCreated = 0
-      for (let i = 0; i < eligible.length; i += batchSize) {
-        if (deadline !== undefined && Date.now() >= deadline) break
-        const batch = eligible.slice(i, i + batchSize)
-        const foldInput: FoldGeneration[] = []
-        for (const gen of batch) {
-          const delta = (await this.storage.readRawObject(
-            `${GENERATIONS_PREFIX}/${gen}/tx.json`
-          )) as GenerationDelta | null
-          if (delta === null) {
-            // Already folded by a prior crashed pass whose dirs were removed,
-            // or damage — getDelta's two-tier read decides which, loudly,
-            // when someone asks. Skip; never fold a generation we cannot read.
-            continue
-          }
-          const records: FoldGeneration['records'] = []
-          for (const [kind, ids] of [
-            ['noun', delta.nouns] as const,
-            ['verb', delta.verbs] as const
-          ]) {
-            for (const id of ids) {
-              const record = await this.storage.readRawObject(
-                `${GENERATIONS_PREFIX}/${gen}/prev/${id}.json`
-              )
-              if (record) records.push({ kind, id, record })
-            }
-          }
-          foldInput.push({ generation: gen, timestamp: delta.timestamp, delta, records })
-        }
-        if (foldInput.length === 0) continue
-        await segments.fold(foldInput)
-        segmentsCreated++
-        // Segment + manifest durable → the live copies retire.
-        for (const g of foldInput) {
-          await this.storage.removeRawPrefix(`${GENERATIONS_PREFIX}/${g.generation}`)
-        }
-        folded += foldInput.length
-      }
-      if (folded > 0) {
-        prodLog.info(
-          `[GenerationStore] repacked ${folded} cold generation(s) into ${segmentsCreated} segment(s) — history preserved, file count reduced`
-        )
-      }
-      return { foldedGenerations: folded, segmentsCreated }
-    })
-  }
-
   async compact(options?: CompactHistoryOptions): Promise<CompactHistoryResult> {
     return this.withMutex(async () => {
       const minPinned = this.minPinnedGeneration()
@@ -2421,11 +2162,6 @@ export class GenerationStore {
       const maxAge = options?.maxAge
       const maxBytes = options?.maxBytes
       const ageCutoff = maxAge !== undefined ? Date.now() - maxAge : undefined
-      // Bounded maintenance pass (8.9.0): stop reclaiming once the budget is
-      // spent. Safe mid-loop — reclamation is oldest-first, so an early stop
-      // leaves a consistent contiguous prefix and the next pass resumes.
-      const deadline =
-        options?.timeBudgetMs !== undefined ? Date.now() + options.timeBudgetMs : undefined
       const noCaps =
         maxGenerations === undefined && maxAge === undefined && maxBytes === undefined
 
@@ -2439,7 +2175,6 @@ export class GenerationStore {
       for (const gen of [...this.committedGensAsc()]) {
         // Pins are always exempt: never reclaim a generation a live pin needs.
         if (gen > minPinned) break // committedGensAsc ascending → nothing newer is eligible either
-        if (deadline !== undefined && Date.now() >= deadline) break // budget spent — resume next pass
         const delta = await this.getDelta(gen)
         if (!noCaps) {
           const violatesCount = maxGenerations !== undefined && remainingCount > maxGenerations
@@ -2471,9 +2206,6 @@ export class GenerationStore {
 
         await this.storage.removeRawPrefix(`${GENERATIONS_PREFIX}/${gen}`)
         this.deltaCache.delete(gen)
-        if (this.historyBytesTotal !== null) {
-          this.historyBytesTotal -= delta.bytes
-        }
 
         // AFTER the record-set is gone (over-count-only crash ordering):
         // release its history references and reclaim any blob left with zero
@@ -2505,16 +2237,6 @@ export class GenerationStore {
         // Reclaimed generations leave the per-id chains stale → rebuild on next read.
         this.invalidateChains()
         this.horizonGen = Math.max(this.horizonGen, highestRemoved)
-        // Packed-tier reclaim (D3): a packed generation's bytes live in a
-        // sealed segment — removeRawPrefix above was a no-op for it. Drop
-        // WHOLE segments now fully below the horizon; a partially-reclaimed
-        // segment keeps its bytes until the boundary passes it (the frozen
-        // partial-segments-wait rule; logical reclamation above still holds —
-        // the generations left committedRanges and asOf below the horizon
-        // throws regardless).
-        if (this.segments) {
-          await this.segments.dropSegmentsBelow(this.horizonGen + 1)
-        }
         const manifest: GenerationManifest = {
           version: 1,
           generation: this.committed,
@@ -2544,9 +2266,6 @@ export class GenerationStore {
   async reopenAfterRestore(floorGeneration: number): Promise<void> {
     await this.withMutex(async () => {
       this.deltaCache.clear()
-      // The running history-byte total describes the REPLACED store — drop it;
-      // the next historyBytes() re-seeds with one walk over the new state.
-      this.historyBytesTotal = null
       // A wholesale state replacement invalidates any buffered single-op
       // history — discard the pending tier (its live writes are gone with the
       // replaced store).

src/db/types.ts

@@ -116,16 +116,6 @@ export interface TransactOptions {
    * record is staged.
    */
   ifAtGeneration?: number
-  /**
-   * Budget (ms) for the atomic apply phase. When omitted, the budget SCALES
-   * with the batch: `max(30 000, opCount × 2 000)` — production imports on
-   * network-attached disks measure ~2 s per operation, so a flat 30 s budget
-   * silently capped honest bulk work at ~15 operations. A tripped budget
-   * rolls the whole batch back and throws a retryable
-   * `TransactionTimeoutError` naming the operation it stopped at, the batch
-   * size, and the elapsed/budget times.
-   */
-  timeoutMs?: number
 }
 
 /**
@@ -176,15 +166,6 @@ export interface CompactHistoryOptions {
    * of each surviving generation's serialized record set (`GenerationDelta.bytes`).
    */
   maxBytes?: number
-  /**
-   * Stop reclaiming after this many milliseconds even if caps are still
-   * exceeded (8.9.0). Compaction is maintenance — a bounded pass keeps
-   * `close()` (and any explicit maintenance window) from stalling on a large
-   * backlog; the next pass resumes where this one stopped (reclamation is
-   * oldest-first, so an early stop is always a consistent prefix). Unset =
-   * run to completion.
-   */
-  timeBudgetMs?: number
 }
 
 /**
@@ -202,36 +183,6 @@ export interface CompactHistoryResult {
   horizon: number
 }
 
-/**
- * @description Result of `brain.historyStats()` — the read-only generational
- * history footprint, for fleet audits and ops doors. A pool operator runs this
- * per brain to size retention exposure (how much MVCC history each brain
- * carries and under which policy) without touching any data.
- */
-export interface HistoryStats {
-  /** Committed generation record-sets currently on disk. */
-  generations: number
-  /** Total on-disk history bytes across those record-sets. */
-  bytes: number
-  /** Oldest committed generation still on disk (null when history is empty). */
-  oldestGeneration: number | null
-  /** Newest committed generation (null when history is empty). */
-  newestGeneration: number | null
-  /** Commit timestamp (ms) of the oldest on-disk generation. */
-  oldestTimestamp: number | null
-  /** Commit timestamp (ms) of the newest on-disk generation. */
-  newestTimestamp: number | null
-  /** Compaction horizon — generations below it were reclaimed. */
-  horizon: number
-  /** The effective retention mode this brain runs under. */
-  retentionMode: 'all' | 'adaptive' | 'explicit'
-  /**
-   * The adaptive byte budget in force (coordinator-driven or the local
-   * free-memory probe); null under 'all' or explicit caps.
-   */
-  effectiveBudgetBytes: number | null
-}
-
 // ============================================================================
 // Db surfaces
 // ============================================================================

src/import/BackgroundDeduplicator.ts

@@ -41,14 +41,6 @@ export interface DeduplicationStats {
  * - Import-scoped deduplication (no cross-contamination)
  * - 3-tier strategy (ID → Name → Similarity)
  * - Uses existing indexes (EntityIdMapper, MetadataIndexManager, TypeAware HNSW)
- *
- * Lifecycle: ONE instance per brain, owned by Brainy (getBackgroundDeduplicator)
- * so the debounce genuinely spans imports and brain.close() cancels pending
- * work via cancelPending() — this pass merge-DELETES duplicate entities, so it
- * must never fire against a closed brain. The enableDeduplication gate lives
- * at the scheduling call site (ImportCoordinator); scheduleDedup itself is
- * unconditional. The timer is unref'd — a pending pass never holds the
- * process open.
  */
 export class BackgroundDeduplicator {
   private brain: Brainy
@@ -75,15 +67,12 @@ export class BackgroundDeduplicator {
       clearTimeout(this.debounceTimer)
     }
 
-    // Schedule for 5 minutes from now. unref'd: a pending dedup pass must
+    // Schedule for 5 minutes from now
-    // never hold the process open (exit-hang class) — if the process exits
-    // first, the pass simply never runs; imports are already durable.
     this.debounceTimer = setTimeout(() => {
       this.runBatchDedup().catch(error => {
         prodLog.error('[BackgroundDedup] Batch dedup failed:', error)
       })
     }, 5 * 60 * 1000)
-    this.debounceTimer.unref?.()
   }
 
   /**

src/import/ImportCoordinator.ts

@@ -13,6 +13,7 @@
 import { Brainy } from '../brainy.js'
 import { FormatDetector, SupportedFormat } from './FormatDetector.js'
 import { ImportHistory, type ImportHistoryEntry } from './ImportHistory.js'
+import { BackgroundDeduplicator } from './BackgroundDeduplicator.js'
 import { SmartExcelImporter } from '../importers/SmartExcelImporter.js'
 import { SmartPDFImporter } from '../importers/SmartPDFImporter.js'
 import { SmartCSVImporter } from '../importers/SmartCSVImporter.js'
@@ -111,12 +112,7 @@ export interface ValidImportOptions {
   /** Confidence threshold for entities */
   confidenceThreshold?: number
 
-  /**
+  /** Enable entity deduplication across imports */
-   * Enable entity deduplication (default: true). Gates BOTH passes: the
-   * inline merge during import AND the debounced background pass that runs
-   * ~5 minutes after the last import (which merge-DELETES duplicate entities).
-   * Set false for deployments that must never auto-remove records.
-   */
   enableDeduplication?: boolean
 
   /** Similarity threshold for deduplication (0-1) */
@@ -290,6 +286,7 @@ export class ImportCoordinator {
   private brain: Brainy
   private detector: FormatDetector
   private history: ImportHistory
+  private backgroundDedup: BackgroundDeduplicator
   private excelImporter: SmartExcelImporter
   private pdfImporter: SmartPDFImporter
   private csvImporter: SmartCSVImporter
@@ -303,6 +300,7 @@ export class ImportCoordinator {
     this.brain = brain
     this.detector = new FormatDetector()
     this.history = new ImportHistory(brain)
+    this.backgroundDedup = new BackgroundDeduplicator(brain)
     this.excelImporter = new SmartExcelImporter(brain)
     this.pdfImporter = new SmartPDFImporter(brain)
     this.csvImporter = new SmartCSVImporter(brain)
@@ -1461,16 +1459,9 @@ export class ImportCoordinator {
       }
     }
 
-    // Schedule background deduplication (debounced 5 minutes, brain-owned so
+    // Schedule background deduplication (debounced 5 minutes)
-    // close() can cancel it). Honors the same enableDeduplication gate as the
+    if (trackingContext && trackingContext.importId) {
-    // inline pass — false means NO dedup, inline or background.
+      this.backgroundDedup.scheduleDedup(trackingContext.importId)
-    if (
-      trackingContext &&
-      trackingContext.importId &&
-      options.enableDeduplication !== false
-    ) {
-      const backgroundDedup = await this.brain.getBackgroundDeduplicator()
-      backgroundDedup.scheduleDedup(trackingContext.importId)
     }
 
     return {

src/index.ts

@@ -32,12 +32,6 @@ export type {
   GraphAuditReport,
   GraphAuditDiscrepancy
 } from './graph/graphAudit.js'
-export {
-  checkOsLimits,
-  NOFILE_POOL_FLOOR,
-  MAX_MAP_COUNT_POOL_FLOOR
-} from './utils/osLimits.js'
-export type { OsLimitsReport } from './utils/osLimits.js'
 
 // Export Brainy configuration and types
 export type {
@@ -201,7 +195,6 @@ export type {
   TxLogEntry,
   CompactHistoryOptions,
   CompactHistoryResult,
-  HistoryStats,
   ChangedIds,
   DiffResult,
   HistoryVersion,
@@ -213,7 +206,6 @@ export type {
   CommitFact,
   FactOp,
   FactScanBatch,
-  SCANFACTS_FIRST_BATCH_MS,
   FactScanHandle
 } from './db/factLog.js'
 // The generalized family stamp — which source generation a projection

src/storage/adapters/fileSystemStorage.ts

@@ -96,14 +96,6 @@ export class FileSystemStorage extends BaseStorage {
   private static readonly WRITER_STALE_THRESHOLD_MS = 60_000
   private writerLockHeartbeat?: NodeJS.Timeout
   private writerLockInfo?: WriterLockInfo
-  /**
-   * The currently-executing heartbeat refresh, if any. `releaseWriterLock()`
-   * awaits it before unlinking: clearInterval() stops FUTURE ticks but not a
-   * tick already in flight, and a straggler landing after the unlink would
-   * RE-CREATE the lock file — a phantom lock blocking the next writer until
-   * the stale TTL expires (the pool-eviction reopen case).
-   */
-  private writerHeartbeatInFlight?: Promise<void>
 
   // Flush-request RPC state. The writer polls `locks/_flush_requests/` for
   // new `.req` files and emits `.ack` files in `locks/_flush_responses/` after
@@ -1772,158 +1764,79 @@ export class FileSystemStorage extends BaseStorage {
     const lockFile = path.join(this.lockDir, FileSystemStorage.WRITER_LOCK_FILE)
     const os = await import('node:os')
     const hostname = os.hostname()
-    const myPid = typeof process !== 'undefined' && process.pid ? process.pid : 0
+    const now = new Date().toISOString()
 
-    // Bounded acquire loop. The CLAIM itself is an atomic create-exclusive
+    const existing = await this.readWriterLock()
-    // write (O_EXCL) — two processes racing an ABSENT lock can never both
+    if (existing && !options?.force) {
-    // succeed, which closes the read-then-write window where the loser used
+      // Same-process re-open: a second Brainy instance in this Node process
-    // to keep running unlocked, silently. An EEXIST loser loops, re-reads,
+      // (e.g. test "simulate server restart" patterns, or a consumer that
-    // and handles whatever it finds honestly (fresh foreign lock → loud
+      // explicitly re-instantiates without closing first). This isn't the
-    // throw; stale/forced → verified takeover).
+      // dangerous cross-process case the lock exists to prevent — the two
-    const MAX_ATTEMPTS = 3
+      // instances share a memory space and can't silently diverge from each
-    for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
+      // other beyond what their callers already see. Warn and take over the lock.
-      const now = new Date().toISOString()
+      if (existing.pid === (typeof process !== 'undefined' ? process.pid : 0) &&
-      const existing = await this.readWriterLock()
+          existing.hostname === hostname) {
-
+        console.warn(
-      if (existing) {
+          `[brainy] Re-acquiring writer lock for ${this.rootDir} held by the same process (PID ${existing.pid}). ` +
-        // Same-process re-open: a second Brainy instance in this Node process
+          `If you intended to keep the previous Brainy instance alive, this is a bug — close it first.`
-        // (e.g. test "simulate server restart" patterns, or a consumer that
+        )
-        // explicitly re-instantiates without closing first). This isn't the
+      } else {
-        // dangerous cross-process case the lock exists to prevent — the two
+        const stale = await this.isWriterLockStale(existing)
-        // instances share a memory space and can't silently diverge from each
+        if (!stale) {
-        // other beyond what their callers already see. Warn and take over.
-        if (existing.pid === myPid && existing.hostname === hostname && !options?.force) {
-          console.warn(
-            `[brainy] Re-acquiring writer lock for ${this.rootDir} held by the same process (PID ${existing.pid}). ` +
-            `If you intended to keep the previous Brainy instance alive, this is a bug — close it first.`
-          )
-          const info: WriterLockInfo = {
-            pid: myPid,
-            hostname,
-            startedAt: now,
-            lastHeartbeat: now,
-            version: getBrainyVersion(),
-            rootDir: this.rootDir
-          }
-          await this.writeFileAtomic(lockFile, JSON.stringify(info, null, 2))
-          this.installWriterLock(info)
-          return info
-        }
-
-        const stale = !options?.force && (await this.isWriterLockStale(existing))
-        if (!options?.force && !stale) {
           // Consumer-facing error contract: callers detect this case via
           // err.code and read the holder's details from err.lockInfo.
-          throw this.writerLockedError(existing)
+          const err = new Error(
+            `Another writer holds this Brainy directory.\n` +
+            `  PID:        ${existing.pid} on host ${existing.hostname}\n` +
+            `  Started:    ${existing.startedAt}\n` +
+            `  Heartbeat:  ${existing.lastHeartbeat}\n` +
+            `  Version:    ${existing.version}\n` +
+            `  Directory:  ${this.rootDir}\n\n` +
+            `For diagnostic queries against this live store, use:\n` +
+            `  const reader = await Brainy.openReadOnly({ storage: { type: 'filesystem', path: '${this.rootDir}' } })\n\n` +
+            `If you have verified the existing lock is stale (e.g. a crashed writer on a different host that PID liveness cannot reach), pass { force: true }.`
+          ) as Error & { code: string; lockInfo: WriterLockInfo }
+          err.code = 'BRAINY_WRITER_LOCKED'
+          err.lockInfo = existing
+          throw err
         }
-
         console.warn(
-          options?.force
+          `[brainy] Overwriting stale writer lock for ${this.rootDir} ` +
-            ? `[brainy] Force-overwriting writer lock for ${this.rootDir} ` +
+          `(PID ${existing.pid} on ${existing.hostname} appears dead).`
-              `(was held by PID ${existing.pid} on ${existing.hostname}).`
-            : `[brainy] Overwriting stale writer lock for ${this.rootDir} ` +
-              `(PID ${existing.pid} on ${existing.hostname} appears dead).`
         )
-        // Takeover: verify the file still holds the lock we judged (a live
-        // successor may have claimed meanwhile), then remove it and fall
-        // through to the atomic claim below. A racing claimer who beats us to
-        // the create simply wins — our next loop iteration reads their fresh
-        // lock and throws honestly. (Advisory file locking has no
-        // compare-and-delete; staleness requiring a 60s-old heartbeat keeps
-        // the residual verify-to-unlink window practically unreachable.)
-        const recheck = await this.readWriterLock()
-        if (
-          recheck &&
-          (recheck.pid !== existing.pid ||
-            recheck.startedAt !== existing.startedAt ||
-            recheck.lastHeartbeat !== existing.lastHeartbeat)
-        ) {
-          continue // the lock changed hands while we deliberated — re-evaluate
-        }
-        try {
-          await fs.promises.unlink(lockFile)
-        } catch (err: any) {
-          if (err.code !== 'ENOENT') throw err
-        }
       }
-
+    } else if (existing && options?.force) {
-      const info: WriterLockInfo = {
+      console.warn(
-        pid: myPid,
+        `[brainy] Force-overwriting writer lock for ${this.rootDir} ` +
-        hostname,
+        `(was held by PID ${existing.pid} on ${existing.hostname}).`
-        startedAt: existing && options?.force ? existing.startedAt : now,
+      )
-        lastHeartbeat: now,
-        version: getBrainyVersion(),
-        rootDir: this.rootDir
-      }
-
-      // The atomic claim: create-exclusive, so exactly ONE racer wins.
-      try {
-        await fs.promises.writeFile(lockFile, JSON.stringify(info, null, 2), { flag: 'wx' })
-      } catch (err: any) {
-        if (err.code === 'EEXIST') {
-          continue // someone else claimed between our read and create — re-evaluate
-        }
-        throw err
-      }
-
-      this.installWriterLock(info)
-      return info
     }
 
-    // Attempts exhausted: something is claiming this directory faster than we
+    const info: WriterLockInfo = {
-    // can evaluate it. Read whoever holds it now and fail loudly with their
+      pid: typeof process !== 'undefined' && process.pid ? process.pid : 0,
-    // details rather than degrading into a lockless open.
+      hostname,
-    const holder = await this.readWriterLock()
+      startedAt: existing && options?.force ? existing.startedAt : now,
-    if (holder) throw this.writerLockedError(holder)
+      lastHeartbeat: now,
-    throw new Error(
+      version: getBrainyVersion(),
-      `Failed to acquire the writer lock for ${this.rootDir} after ${MAX_ATTEMPTS} attempts — ` +
+      rootDir: this.rootDir
-      `the lock file is being contended. Retry, or inspect ${lockFile}.`
+    }
-    )
-  }
 
-  /** Record lock ownership + start the unref'd heartbeat. */
+    await this.writeFileAtomic(lockFile, JSON.stringify(info, null, 2))
-  private installWriterLock(info: WriterLockInfo): void {
     this.writerLockInfo = info
 
     // Heartbeat — rewrite lastHeartbeat every WRITER_HEARTBEAT_MS so other
     // processes can tell a live writer from one that crashed without releasing.
     this.writerLockHeartbeat = setInterval(() => {
-      const tick = this.refreshWriterLockHeartbeat().catch((err) => {
+      this.refreshWriterLockHeartbeat().catch((err) => {
-        // ENOENT = the lock (or its directory) vanished mid-refresh — the
+        console.warn('[brainy] Failed to refresh writer lock heartbeat:', err)
-        // store was released or removed under us; the next acquire recreates
-        // it. Benign by construction; anything else stays loud.
-        if ((err as NodeJS.ErrnoException)?.code !== 'ENOENT') {
-          console.warn('[brainy] Failed to refresh writer lock heartbeat:', err)
-        }
-      })
-      this.writerHeartbeatInFlight = tick.finally(() => {
-        if (this.writerHeartbeatInFlight === tick) {
-          this.writerHeartbeatInFlight = undefined
-        }
       })
     }, FileSystemStorage.WRITER_HEARTBEAT_MS)
     if (typeof this.writerLockHeartbeat.unref === 'function') {
       // Don't keep the event loop alive just for the heartbeat.
       this.writerLockHeartbeat.unref()
     }
-  }
 
-  /** The consumer-facing BRAINY_WRITER_LOCKED error, holder details attached. */
+    return info
-  private writerLockedError(existing: WriterLockInfo): Error {
-    const err = new Error(
-      `Another writer holds this Brainy directory.\n` +
-      `  PID:        ${existing.pid} on host ${existing.hostname}\n` +
-      `  Started:    ${existing.startedAt}\n` +
-      `  Heartbeat:  ${existing.lastHeartbeat}\n` +
-      `  Version:    ${existing.version}\n` +
-      `  Directory:  ${this.rootDir}\n\n` +
-      `For diagnostic queries against this live store, use:\n` +
-      `  const reader = await Brainy.openReadOnly({ storage: { type: 'filesystem', path: '${this.rootDir}' } })\n\n` +
-      `If you have verified the existing lock is stale (e.g. a crashed writer on a different host that PID liveness cannot reach), pass { force: true }.`
-    ) as Error & { code: string; lockInfo: WriterLockInfo }
-    err.code = 'BRAINY_WRITER_LOCKED'
-    err.lockInfo = existing
-    return err
   }
 
   public override async releaseWriterLock(): Promise<void> {
@@ -1931,15 +1844,6 @@ export class FileSystemStorage extends BaseStorage {
       clearInterval(this.writerLockHeartbeat)
       this.writerLockHeartbeat = undefined
     }
-    // Drain an in-flight heartbeat tick BEFORE unlinking: clearInterval stops
-    // future ticks only, and a straggler write landing after the unlink would
-    // re-create the lock as a phantom (blocking the next writer until the
-    // stale TTL). After the drain, any refresh is either fully landed (we
-    // unlink its output below) or not started (it sees writerLockInfo
-    // undefined and returns).
-    if (this.writerHeartbeatInFlight) {
-      await this.writerHeartbeatInFlight
-    }
     if (!this.writerLockInfo) {
       return
     }

src/storage/adapters/memoryStorage.ts

@@ -133,11 +133,6 @@ export class MemoryStorage extends BaseStorage {
    */
   protected async deleteObjectFromPath(path: string): Promise<void> {
     this.objectStore.delete(path)
-    // Filesystem parity: on disk, objects and raw BYTE files are both just
-    // files — unlink removes whichever exists. Without this, deleteRawObject
-    // on a raw-bytes path (fact-log/generation segments) silently no-ops on
-    // memory storage: the delete "succeeds" and the bytes remain.
-    this.rawBytesStore.delete(path)
   }
 
   /**

src/transaction/Transaction.ts

@@ -37,24 +37,6 @@ const DEFAULT_OPTIONS: Required<TransactionOptions> = {
   maxRollbackRetries: 3
 }
 
-/**
- * The apply-phase budget for a batch of `opCount` operations.
- *
- * An explicit override wins untouched. Otherwise the budget SCALES with the
- * batch: `max(30 000 ms, opCount × 2 000 ms)`. The per-op term is calibrated
- * from field data — bulk imports on network-attached disks measure ~2 s per
- * operation (each op pays canonical writes + fsync + index maintenance) — so
- * a flat 30 s budget silently capped honest work at ~15 operations while
- * looking generous for small batches. Scaling keeps small transacts
- * fast-failing and gives bulk ones a budget proportional to the work they
- * actually asked for; a trip still rolls back atomically and throws a
- * retryable, fully-labeled TransactionTimeoutError.
- */
-export function transactTimeoutBudget(opCount: number, override?: number): number {
-  if (override !== undefined) return override
-  return Math.max(30_000, opCount * 2_000)
-}
-
 /**
  * Transaction class
  */
@@ -132,11 +114,7 @@ export class Transaction implements TransactionContext {
         // into the catch below and rolls back like any other failure — it must
         // never bypass rollback.
         if (Date.now() - this.startTime > this.options.timeout) {
-          throw new TransactionTimeoutError(this.options.timeout, i, {
+          throw new TransactionTimeoutError(this.options.timeout, i)
-            elapsedMs: Date.now() - this.startTime,
-            totalOperations: this.operations.length,
-            operationName: this.operations[i]?.name
-          })
         }
 
         const operation = this.operations[i]

src/transaction/errors.ts

@@ -77,24 +77,11 @@ export class InvalidTransactionStateError extends TransactionError {
 export class TransactionTimeoutError extends TransactionError {
   constructor(
     timeoutMs: number,
-    operationIndex: number,
+    operationIndex: number
-    telemetry?: {
-      elapsedMs?: number
-      totalOperations?: number
-      operationName?: string
-    }
   ) {
-    const progress =
-      telemetry?.totalOperations !== undefined
-        ? `${operationIndex}/${telemetry.totalOperations}`
-        : String(operationIndex)
-    const name = telemetry?.operationName ? ` ('${telemetry.operationName}')` : ''
-    const elapsed =
-      telemetry?.elapsedMs !== undefined ? `${telemetry.elapsedMs}ms elapsed, ` : ''
     super(
-      `Transaction timed out at operation ${progress}${name} — ${elapsed}budget ${timeoutMs}ms. ` +
+      `Transaction timed out after ${timeoutMs}ms at operation ${operationIndex}`,
-        `The batch rolled back atomically; retry with a higher timeoutMs or a smaller batch.`,
+      { timeoutMs, operationIndex }
-      { timeoutMs, operationIndex, ...telemetry }
     )
     this.name = 'TransactionTimeoutError'
   }

src/types/brainy.types.ts

@@ -1737,10 +1737,7 @@ export interface BrainyConfig {
    * Under Model-B EVERY write (`transact()` AND single-op `add`/`update`/
    * `remove`/`relate`) produces an immutable generation record-set serving
    * historical reads (`asOf()`, pinned `Db` values). Without compaction those
-   * accumulate, so Brainy **auto-compacts at `close()`** (time-bounded per
+   * accumulate, so Brainy **auto-compacts on every `flush()` and `close()`**.
-   * pass; 8.9.0 removed compaction from `flush()` — flush is durability work
-   * and never pays maintenance costs). A long-lived writer that never closes
-   * accumulates history until its next explicit `compactHistory()` call.
    * Live `Db` pins are ALWAYS exempt from reclamation, in every mode.
    *
    * Modes:
@@ -1757,7 +1754,7 @@ export interface BrainyConfig {
    *   the oldest unpinned generations while ANY supplied cap is exceeded
    *   (predictable ops). `maxAge` in ms; `maxBytes` total history bytes.
    *
-   * `autoCompact: false` disables the automatic close() compaction (manage
+   * `autoCompact: false` disables the automatic flush/close compaction (manage
    * manually via `brain.compactHistory()`). `budgetBytes` is the settable
    * adaptive byte budget a coordinator drives (also via `brain.setRetentionBudget()`).
    * Long-term archives belong in `db.persist(path)` snapshots, which compaction
@@ -1775,7 +1772,7 @@ export interface BrainyConfig {
         maxBytes?: number
         /** Adaptive byte budget for this brain, driven by a coordinator (e.g. cor). */
         budgetBytes?: number
-        /** Run compaction automatically at close() (default: true; 8.9.0 — flush() never compacts). */
+        /** Run compaction automatically on flush()/close() (default: true). */
         autoCompact?: boolean
       }
 

src/utils/metadataIndex.ts

@@ -1867,26 +1867,9 @@ export class MetadataIndexManager implements MetadataIndexProvider {
     // not once per AND-clause inside it.
     const unindexedFields: string[] = []
 
-    for (const [rawField, condition] of Object.entries(filter)) {
+    for (const [field, condition] of Object.entries(filter)) {
       // Skip logical operators
-      if (rawField === 'allOf' || rawField === 'anyOf' || rawField === 'not') continue
+      if (field === 'allOf' || field === 'anyOf' || field === 'not') continue
-
-      // Metadata is FLATTENED at index time (metadata.entry.title indexes as
-      // entry.title), so a `metadata.`-prefixed where key is almost always
-      // the caller spelling the STORAGE shape rather than the index shape.
-      // Accept both spellings: when the key as spelled is unindexed but its
-      // stripped spelling is, query the stripped one. A literal nested
-      // custom key named `metadata` still wins when indexed as spelled
-      // (checked first), so that rare shape keeps working.
-      let field = rawField
-      if (
-        rawField.startsWith('metadata.') &&
-        this.columnStore &&
-        !this.columnStore.hasField(rawField) &&
-        this.columnStore.hasField(rawField.slice('metadata.'.length))
-      ) {
-        field = rawField.slice('metadata.'.length)
-      }
 
       let fieldResults: string[] = []
 

src/utils/osLimits.ts

@@ -1,141 +0,0 @@
-/**
- * @module utils/osLimits
- * @description Detect-and-warn for OS resource limits that bite at POOL scale.
- *
- * A single brain rarely notices them, but a pool of brains — especially with a
- * native accelerator memory-mapping many index files per brain — consumes file
- * descriptors and memory mappings multiplicatively. On stock Linux defaults
- * (RLIMIT_NOFILE soft 1024, vm.max_map_count 65530) the failure arrives as
- * EMFILE or a failed mmap deep inside an index open, long after the real cause
- * (the limit) stopped being visible. This module reads the limits at open and
- * WARNS ONCE per process with the exact raise commands, so the operator learns
- * the fix before the incident instead of from it.
- *
- * Read-only and Linux-only by construction: both sources are `/proc` files.
- * On platforms where they are absent the check reports nulls and stays silent —
- * no limit read means no claim made, never a guessed warning.
- */
-
-import * as fs from 'node:fs'
-import { prodLog } from './logger.js'
-
-/** Soft-NOFILE floor below which pool-scale use is at EMFILE risk. */
-export const NOFILE_POOL_FLOOR = 65536
-
-/** vm.max_map_count floor below which mmap-heavy native indexes are at risk. */
-export const MAX_MAP_COUNT_POOL_FLOOR = 262144
-
-export interface OsLimitsReport {
-  /** RLIMIT_NOFILE soft limit (null when unreadable; Infinity for 'unlimited'). */
-  nofileSoft: number | null
-  /** RLIMIT_NOFILE hard limit (null when unreadable; Infinity for 'unlimited'). */
-  nofileHard: number | null
-  /** vm.max_map_count (null when unreadable). */
-  maxMapCount: number | null
-  /** Human-actionable warnings for limits below the pool floors. Empty = fine. */
-  warnings: string[]
-}
-
-/**
- * Parse the `Max open files` row of a `/proc/<pid>/limits` document into
- * soft/hard values. Returns nulls when the row is absent or malformed.
- */
-export function parseProcLimits(content: string): { soft: number | null; hard: number | null } {
-  const line = content.split('\n').find((l) => l.startsWith('Max open files'))
-  if (!line) return { soft: null, hard: null }
-  const m = line.match(/^Max open files\s+(\S+)\s+(\S+)/)
-  if (!m) return { soft: null, hard: null }
-  const parse = (v: string): number | null => {
-    if (v === 'unlimited') return Infinity
-    const n = Number.parseInt(v, 10)
-    return Number.isNaN(n) ? null : n
-  }
-  return { soft: parse(m[1]), hard: parse(m[2]) }
-}
-
-/**
- * Assess readable limits against the pool floors. Pure — feed it any values.
- * A null (unreadable) limit produces NO warning: no measurement, no claim.
- */
-export function assessOsLimits(limits: {
-  nofileSoft: number | null
-  nofileHard: number | null
-  maxMapCount: number | null
-}): string[] {
-  const warnings: string[] = []
-
-  if (limits.nofileSoft !== null && limits.nofileSoft < NOFILE_POOL_FLOOR) {
-    const hardNote =
-      limits.nofileHard !== null && limits.nofileHard >= NOFILE_POOL_FLOOR
-        ? ` (the hard limit ${limits.nofileHard === Infinity ? 'unlimited' : limits.nofileHard} already allows it — raise the soft limit only)`
-        : ''
-    warnings.push(
-      `RLIMIT_NOFILE soft limit is ${limits.nofileSoft} — below the ${NOFILE_POOL_FLOOR} recommended ` +
-        `for pool-scale use (a pool of brains with a native accelerator opens many index files per brain; ` +
-        `the failure mode is EMFILE deep inside an index open). Raise with \`ulimit -n ${NOFILE_POOL_FLOOR}\` ` +
-        `or LimitNOFILE=${NOFILE_POOL_FLOOR} in the service unit${hardNote}.`
-    )
-  }
-
-  if (limits.maxMapCount !== null && limits.maxMapCount < MAX_MAP_COUNT_POOL_FLOOR) {
-    warnings.push(
-      `vm.max_map_count is ${limits.maxMapCount} — below the ${MAX_MAP_COUNT_POOL_FLOOR} recommended ` +
-        `for mmap-heavy native indexes at pool scale (each mapped index segment consumes map entries; ` +
-        `the failure mode is a failed mmap mid-heal). Raise with ` +
-        `\`sysctl -w vm.max_map_count=${MAX_MAP_COUNT_POOL_FLOOR}\` (persist in /etc/sysctl.d/).`
-    )
-  }
-
-  return warnings
-}
-
-/**
- * Read the limits from /proc and assess them. `readFile` is injectable for
- * tests; absent/unreadable sources yield nulls (and therefore no warnings).
- */
-export async function checkOsLimits(
-  readFile: (path: string) => Promise<string> = async (p) => fs.promises.readFile(p, 'utf-8')
-): Promise<OsLimitsReport> {
-  let nofileSoft: number | null = null
-  let nofileHard: number | null = null
-  let maxMapCount: number | null = null
-
-  try {
-    const parsed = parseProcLimits(await readFile('/proc/self/limits'))
-    nofileSoft = parsed.soft
-    nofileHard = parsed.hard
-  } catch {
-    // Not Linux (or /proc unavailable) — no measurement, no claim.
-  }
-
-  try {
-    const raw = (await readFile('/proc/sys/vm/max_map_count')).trim()
-    const n = Number.parseInt(raw, 10)
-    maxMapCount = Number.isNaN(n) ? null : n
-  } catch {
-    // Not Linux — same rule.
-  }
-
-  const warnings = assessOsLimits({ nofileSoft, nofileHard, maxMapCount })
-  return { nofileSoft, nofileHard, maxMapCount, warnings }
-}
-
-/** Once-per-process latch so a brain pool warns once, not once per brain. */
-let osLimitsWarned = false
-
-/**
- * Run the check and warn (once per process) about limits below the pool
- * floors. Called from brain open; safe everywhere (silent off-Linux).
- */
-export async function warnOnLowOsLimits(): Promise<void> {
-  if (osLimitsWarned) return
-  osLimitsWarned = true
-  try {
-    const report = await checkOsLimits()
-    for (const warning of report.warnings) {
-      prodLog.warn(`[Brainy] OS limit check: ${warning}`)
-    }
-  } catch {
-    // The check must never affect open — measurement-only.
-  }
-}

tests/integration/aggregate-reserved-fields.test.ts

@@ -1,169 +0,0 @@
-/**
- * @module tests/integration/aggregate-reserved-fields
- * @description One field-resolution law across the whole aggregation + query
- * surface (SELF-AGGREGATE-DELETE-DRIFT). Laws:
- * (1) aggregates grouped by a RESERVED field (subtype) decrement on delete —
- *     the delete-side entity view carries every reserved field, so the
- *     decrement finds its group (counts must never drift from ground truth);
- * (2) same for update: moving an entity between reserved-field groups
- *     decrements the old group and increments the new one (no double-count);
- * (3) aggregation source.where on a reserved field (subtype) FILTERS instead
- *     of silently matching nothing;
- * (4) removeMany refuses empty/invalid selectors loudly (bare array, empty
- *     object, ids: []) instead of resolving as a silent no-op;
- * (5) find() accepts both where spellings: flattened (entry.title) and
- *     storage-shaped (metadata.entry.title) resolve to the same rows.
- */
-import { describe, it, expect, beforeEach, afterEach } from 'vitest'
-import { Brainy } from '../../src/brainy.js'
-import { NounType } from '../../src/types/graphTypes.js'
-
-const stubEmbedding = async (text: string): Promise<number[]> => {
-  const hash = text.split('').reduce((acc, char) => acc + char.charCodeAt(0), 0)
-  return new Array(384).fill(0).map((_, i) => Math.sin(hash + i))
-}
-
-describe('aggregation + query field-resolution law', () => {
-  let brain: Brainy
-
-  beforeEach(async () => {
-    brain = new Brainy({
-      requireSubtype: false,
-      storage: { type: 'memory' as const },
-      embeddingFunction: stubEmbedding
-    })
-    await brain.init()
-  })
-
-  afterEach(async () => {
-    await brain.close()
-  })
-
-  it('reserved-field groupBy decrements on delete (the drift bug)', async () => {
-    brain.defineAggregate({
-      name: 'by_subtype',
-      source: { type: NounType.Document },
-      groupBy: ['subtype'],
-      metrics: { count: { op: 'count' } }
-    })
-
-    const ids: string[] = []
-    for (let i = 0; i < 5; i++) {
-      ids.push(
-        await brain.add({
-          data: `doc-${i}`,
-          type: NounType.Document,
-          subtype: 'note',
-          metadata: { team: 'alpha' }
-        })
-      )
-    }
-    let groups = await brain.queryAggregate('by_subtype')
-    expect(groups).toHaveLength(1)
-    expect(groups[0].groupKey).toEqual({ subtype: 'note' })
-    expect(groups[0].metrics.count).toBe(5)
-
-    await brain.remove(ids[0])
-    await brain.flush()
-
-    groups = await brain.queryAggregate('by_subtype')
-    expect(groups[0].metrics.count).toBe(4)
-    const live = await brain.find({ type: NounType.Document, limit: 100 })
-    expect(groups[0].metrics.count).toBe(live.length)
-  })
-
-  it('reserved-field groupBy moves between groups on update (no double-count)', async () => {
-    brain.defineAggregate({
-      name: 'by_subtype',
-      source: { type: NounType.Document },
-      groupBy: ['subtype'],
-      metrics: { count: { op: 'count' } }
-    })
-    const id = await brain.add({
-      data: 'doc-move',
-      type: NounType.Document,
-      subtype: 'draft'
-    })
-    await brain.update({ id, subtype: 'published' })
-
-    const groups = await brain.queryAggregate('by_subtype')
-    const byKey = Object.fromEntries(
-      groups.map((g) => [String(g.groupKey.subtype), g.metrics.count])
-    )
-    expect(byKey['published']).toBe(1)
-    // The old group must be gone or zero — never still counting the entity.
-    expect(byKey['draft'] ?? 0).toBe(0)
-  })
-
-  it('source.where on a reserved field filters instead of matching nothing', async () => {
-    brain.defineAggregate({
-      name: 'notes_only',
-      source: { type: NounType.Document, where: { subtype: 'note' } },
-      groupBy: ['team'],
-      metrics: { count: { op: 'count' } }
-    })
-    await brain.add({
-      data: 'n1',
-      type: NounType.Document,
-      subtype: 'note',
-      metadata: { team: 'alpha' }
-    })
-    await brain.add({
-      data: 'd1',
-      type: NounType.Document,
-      subtype: 'draft',
-      metadata: { team: 'alpha' }
-    })
-
-    const groups = await brain.queryAggregate('notes_only')
-    expect(groups).toHaveLength(1)
-    expect(groups[0].metrics.count).toBe(1) // the note, never the draft
-  })
-
-  it('removeMany refuses empty/invalid selectors loudly', async () => {
-    const id = await brain.add({ data: 'keep-me', type: NounType.Document })
-
-    // Bare array passed positionally — the classic silent no-op.
-    await expect(
-      brain.removeMany([id] as unknown as Parameters<typeof brain.removeMany>[0])
-    ).rejects.toThrow(/bare array/)
-    // Empty selector object.
-    await expect(
-      brain.removeMany({} as Parameters<typeof brain.removeMany>[0])
-    ).rejects.toThrow(/requires a selector/)
-    // Explicit empty id list.
-    await expect(brain.removeMany({ ids: [] })).rejects.toThrow(/ids: \[\]/)
-
-    // Nothing was deleted by any of the refused calls.
-    expect(await brain.get(id)).toBeTruthy()
-  })
-
-  it('find() accepts both flattened and metadata.-prefixed where spellings', async () => {
-    await brain.add({
-      data: 'nested-doc',
-      type: NounType.Document,
-      metadata: { entry: { title: 'T1' }, classifier: { contextHints: { vfsPath: '/n/a.md' } } }
-    })
-    await brain.flush()
-
-    const flat = await brain.find({
-      type: NounType.Document,
-      where: { 'entry.title': 'T1' },
-      limit: 10
-    })
-    const prefixed = await brain.find({
-      type: NounType.Document,
-      where: { 'metadata.entry.title': 'T1' },
-      limit: 10
-    })
-    const deepPrefixed = await brain.find({
-      type: NounType.Document,
-      where: { 'metadata.classifier.contextHints.vfsPath': '/n/a.md' },
-      limit: 10
-    })
-    expect(flat).toHaveLength(1)
-    expect(prefixed).toHaveLength(1)
-    expect(prefixed[0].id).toBe(flat[0].id)
-    expect(deepPrefixed).toHaveLength(1)
-  })
-})

tests/integration/background-dedup-lifecycle.test.ts

@@ -1,85 +0,0 @@
-/**
- * @module tests/integration/background-dedup-lifecycle
- * @description The post-import background deduplication pass (a merge-DELETE
- * writer) obeys the same contract as the inline pass. Laws:
- * (1) enableDeduplication:false schedules NO background pass — the brain-owned
- *     deduplicator is never even constructed;
- * (2) by default the pass IS scheduled, brain-owned, with an unref'd timer
- *     (a pending pass never holds the process open);
- * (3) repeated imports debounce into ONE pending batch on ONE instance
- *     (per-coordinator instances used to arm one timer per import);
- * (4) close() cancels pending work — no delete pass can fire after close.
- */
-import { describe, it, expect, beforeEach, afterEach } from 'vitest'
-import { Brainy } from '../../src/brainy.js'
-
-const ROWS = [
-  { name: 'Alice Zephyr', role: 'engineer' },
-  { name: 'Bob Quill', role: 'writer' }
-]
-
-// Keep imports fast and deterministic — dedup scheduling is what's under test.
-const FAST = {
-  enableNeuralExtraction: false,
-  enableRelationshipInference: false,
-  enableConceptExtraction: false
-} as const
-
-// Deterministic stub embedder (hnsw-rebuild.test.ts pattern) — dedup
-// scheduling never inspects vector CONTENT, so skip the WASM model load.
-const stubEmbedding = async (text: string): Promise<number[]> => {
-  const hash = text.split('').reduce((acc, char) => acc + char.charCodeAt(0), 0)
-  const vector = new Array(384).fill(0).map((_, i) => Math.sin(hash + i))
-  return vector
-}
-
-describe('background dedup lifecycle', () => {
-  let brain: Brainy
-
-  beforeEach(async () => {
-    brain = new Brainy({
-      requireSubtype: false,
-      storage: { type: 'memory' as const },
-      embeddingFunction: stubEmbedding
-    })
-    await brain.init()
-  })
-
-  afterEach(async () => {
-    await brain.close()
-  })
-
-  it('enableDeduplication:false schedules no background pass at all', async () => {
-    await brain.import(ROWS, { ...FAST, enableDeduplication: false })
-    expect((brain as any)._backgroundDedup).toBeUndefined()
-  })
-
-  it('default schedules a brain-owned pass with an unref-ed timer', async () => {
-    await brain.import(ROWS, { ...FAST })
-    const dedup = (brain as any)._backgroundDedup
-    expect(dedup).toBeDefined()
-    expect(dedup.pendingImports.size).toBe(1)
-    const timer = dedup.debounceTimer
-    expect(timer).toBeDefined()
-    // Node timers expose hasRef(); an unref'd timer must not hold the process.
-    expect(typeof timer.hasRef).toBe('function')
-    expect(timer.hasRef()).toBe(false)
-  })
-
-  it('imports debounce into one pending batch on one brain-owned instance', async () => {
-    await brain.import(ROWS, { ...FAST })
-    const first = (brain as any)._backgroundDedup
-    await brain.import([{ name: 'Cara Vex', role: 'analyst' }], { ...FAST })
-    expect((brain as any)._backgroundDedup).toBe(first)
-    expect(first.pendingImports.size).toBe(2)
-  })
-
-  it('close() cancels pending background dedup', async () => {
-    await brain.import(ROWS, { ...FAST })
-    const dedup = (brain as any)._backgroundDedup
-    expect(dedup.debounceTimer).toBeDefined()
-    await brain.close()
-    expect(dedup.debounceTimer).toBeUndefined()
-    expect(dedup.pendingImports.size).toBe(0)
-  })
-})

tests/integration/db-mvcc.test.ts

@@ -1280,32 +1280,24 @@ describe('8.0 Db API — generational MVCC', () => {
     await expect(reopened.asOf(1)).rejects.toBeInstanceOf(GenerationCompactedError)
   })
 
-  it('Model-B retention — flush() NEVER compacts (8.9.0); adaptive reclaim runs at close()', async () => {
+  it('Model-B retention — setRetentionBudget drives adaptive reclaim on flush; live data intact', async () => {
-    // Default brain → ADAPTIVE retention with a driven byte budget far below
+    // Default brain → ADAPTIVE retention. A coordinator (e.g. cor's ResourceManager)
-    // the accumulated history (~13 generations of full-vector before-images).
+    // pushes a byte budget via setRetentionBudget(); auto-compaction on flush() reclaims
-    // The 8.9.0 law: flush() is durability-only — it must not reclaim even
+    // oldest history down toward it. Each update's before-image carries the full prior
-    // when the budget is exceeded (reclaim-on-flush blocked production writes
+    // 384-dim vector (~KBs), so ~13 generations far exceed a few-KB budget.
-    // for 25-191s). Maintenance runs at close(), time-bounded.
+    const { brain } = await openFsBrain()
-    const { brain, dir } = await openFsBrain()
     const a = uid('ret-budget')
     await brain.add({ id: a, type: NounType.Document, data: 'v0', vector: vec(1), metadata: { v: 0 } })
     for (let v = 1; v <= 12; v++) await brain.update({ id: a, metadata: { v } })
 
     brain.setRetentionBudget(6000) // ~6 KB — well below the accumulated history
-    await brain.flush()
+    await brain.flush() // group-commit + adaptive auto-compaction under the budget
 
-    // flush() paid durability only: nothing reclaimed, all history readable.
+    // History was reclaimed (the horizon advanced past the oldest generations)…
-    expect(generationStoreOf(brain).horizon()).toBe(0)
+    expect(generationStoreOf(brain).horizon()).toBeGreaterThan(0)
-    const probe = await brain.asOf(1) // readable proves nothing was reclaimed…
+    await expect(brain.asOf(1)).rejects.toBeInstanceOf(GenerationCompactedError)
-    await probe.release() // …and MUST be released: a held pin would (correctly)
+    // …but the budget reclaims HISTORY only — the live record is untouched.
-    // protect every newer generation through the close() compaction below.
+    expect((await brain.get(a))?.metadata?.v).toBe(12)
-    await brain.close() // ← THE auto-compaction site now
-
-    // close() reclaimed under the budget; live record intact; horizon durable.
-    const { brain: reopened } = await openFsBrain(dir)
-    expect(generationStoreOf(reopened).horizon()).toBeGreaterThan(0)
-    await expect(reopened.asOf(1)).rejects.toBeInstanceOf(GenerationCompactedError)
-    expect((await reopened.get(a))?.metadata?.v).toBe(12)
   })
 
   // ==========================================================================

tests/integration/history-repacking.test.ts

@@ -1,186 +0,0 @@
-/**
- * @module tests/integration/history-repacking
- * @description The D1+D3 two-tier history lifecycle end-to-end on a real
- * brain. Laws: (1) repacking is RE-REPRESENTATION — after folding, every
- * asOf() read below the fold boundary answers exactly as before, across a
- * cold reopen; (2) folded per-generation directories are physically gone
- * (the file-count cure is real, not cosmetic); (3) repack + reclaim compose:
- * bounded retention after repacking drops whole segments and asOf below the
- * horizon throws GenerationCompactedError; (4) repackHistory is explicit
- * API and time-bounded (spent budget = consistent no-op).
- *
- * Uses a tiny REPACK_LIVE_WINDOW override so a small history has a cold
- * tier at all (the production window is 1024).
- */
-import { describe, it, expect, afterEach } from 'vitest'
-import * as fs from 'node:fs'
-import * as path from 'node:path'
-import * as os from 'node:os'
-import { Brainy } from '../../src/brainy.js'
-import { NounType } from '../../src/types/graphTypes.js'
-import { GenerationStore } from '../../src/db/generationStore.js'
-import { GenerationCompactedError } from '../../src/db/errors.js'
-import { SEGMENTS_PREFIX } from '../../src/db/generationSegments.js'
-
-const stub = async (text: string): Promise<number[]> => {
-  const h = text.split('').reduce((a, c) => a + c.charCodeAt(0), 0)
-  return new Array(384).fill(0).map((_, i) => Math.sin(h + i))
-}
-
-const openBrain = async (dir: string): Promise<Brainy> => {
-  const brain = new Brainy({
-    requireSubtype: false,
-    storage: { type: 'filesystem', path: dir },
-    embeddingFunction: stub
-  })
-  await brain.init()
-  return brain
-}
-
-describe('history repacking — the two-tier lifecycle', () => {
-  const dirs: string[] = []
-  const tempDir = (): string => {
-    const d = fs.mkdtempSync(path.join(os.tmpdir(), 'brainy-repack-'))
-    dirs.push(d)
-    return d
-  }
-  const originalWindow = GenerationStore.REPACK_LIVE_WINDOW
-
-  afterEach(() => {
-    ;(GenerationStore as any).REPACK_LIVE_WINDOW = originalWindow
-    for (const d of dirs.splice(0)) {
-      try {
-        fs.rmSync(d, { recursive: true, force: true })
-      } catch {
-        /* best effort */
-      }
-    }
-  })
-
-  it('repack preserves every historical read across cold reopen; folded dirs are gone', async () => {
-    ;(GenerationStore as any).REPACK_LIVE_WINDOW = 3
-    const dir = tempDir()
-    const brain = await openBrain(dir)
-
-    const id = await brain.add({
-      data: 'versioned-entity',
-      type: NounType.Document,
-      metadata: { v: 0 }
-    })
-    for (let v = 1; v <= 10; v++) await brain.update({ id, metadata: { v } })
-    await brain.flush()
-
-    // Ground truth BEFORE repacking: capture asOf views for early generations.
-    const before: Record<number, number> = {}
-    for (const g of [2, 4, 6]) {
-      const db = await brain.asOf(g)
-      before[g] = (await db.get(id))?.metadata?.v as number
-      await db.release()
-    }
-
-    const result = await brain.repackHistory()
-    expect(result.foldedGenerations).toBeGreaterThan(0)
-    expect(result.segmentsCreated).toBeGreaterThan(0)
-
-    // The folded per-generation directories are PHYSICALLY gone…
-    const genDirs = fs
-      .readdirSync(path.join(dir, '_generations'), { withFileTypes: true })
-      .filter((e) => e.isDirectory() && /^\d+$/.test(e.name)).length
-    expect(genDirs).toBeLessThanOrEqual(4) // live window (3) + at most the newest
-    // …and the segment tier exists (the filesystem adapter stores objects
-    // gzipped, so the manifest may live at either spelling).
-    const segDir = path.join(dir, SEGMENTS_PREFIX)
-    expect(
-      fs.existsSync(path.join(segDir, 'manifest.json')) ||
-        fs.existsSync(path.join(segDir, 'manifest.json.gz'))
-    ).toBe(true)
-    expect(fs.readdirSync(segDir).some((f) => f.endsWith('.bgs'))).toBe(true)
-
-    // Same asOf answers from the packed tier, same process…
-    for (const g of [2, 4, 6]) {
-      const db = await brain.asOf(g)
-      expect((await db.get(id))?.metadata?.v).toBe(before[g])
-      await db.release()
-    }
-    await brain.close()
-
-    // …and across a COLD REOPEN (manifest discovery, no live dirs to list).
-    const reopened = await openBrain(dir)
-    for (const g of [2, 4, 6]) {
-      const db = await reopened.asOf(g)
-      expect((await db.get(id))?.metadata?.v).toBe(before[g])
-      await db.release()
-    }
-    expect((await reopened.get(id))?.metadata?.v).toBe(10) // live state untouched
-    await reopened.close()
-  })
-
-  it('repack + bounded reclaim compose: whole segments drop, horizon is loud', async () => {
-    ;(GenerationStore as any).REPACK_LIVE_WINDOW = 2
-    const dir = tempDir()
-    const brain = await openBrain(dir)
-    const id = await brain.add({ data: 'reclaim-probe', type: NounType.Document, metadata: { v: 0 } })
-    for (let v = 1; v <= 8; v++) await brain.update({ id, metadata: { v } })
-    await brain.flush()
-    await brain.repackHistory()
-
-    // Reclaim down to the 3 newest generations — packed segments below the
-    // horizon drop whole; asOf below throws loudly.
-    const res = await brain.compactHistory({ maxGenerations: 3 })
-    expect(res.removedGenerations).toBeGreaterThan(0)
-    await expect(brain.asOf(1)).rejects.toBeInstanceOf(GenerationCompactedError)
-    expect((await brain.get(id))?.metadata?.v).toBe(8)
-    await brain.close()
-  })
-
-  it('generationDigest: reopen-stable, divergence-sensitive, loud below the horizon', async () => {
-    ;(GenerationStore as any).REPACK_LIVE_WINDOW = 2
-    const dir = tempDir()
-    const brain = await openBrain(dir)
-    const id = await brain.add({ data: 'digest-probe', type: NounType.Document, metadata: { v: 0 } })
-    for (let v = 1; v <= 6; v++) await brain.update({ id, metadata: { v } })
-    await brain.flush()
-    await brain.repackHistory()
-
-    const gen = brain.generation()
-    const atHead = await brain.generationDigest(gen)
-    const atMid = await brain.generationDigest(3)
-    expect(atHead).toMatch(/^[0-9a-f]{8}$/)
-    expect(atMid).not.toBe(atHead) // more history ⇒ different digest
-    await brain.close()
-
-    // Reopen-stable: same history, same digests (packed prefix stability).
-    const reopened = await openBrain(dir)
-    expect(await reopened.generationDigest(gen)).toBe(atHead)
-    expect(await reopened.generationDigest(3)).toBe(atMid)
-
-    // New history diverges the head digest.
-    await reopened.update({ id, metadata: { v: 7 } })
-    await reopened.flush()
-    expect(await reopened.generationDigest(reopened.generation())).not.toBe(atHead)
-
-    // Below the horizon: LOUD, never a silent pin of reclaimed history.
-    await reopened.compactHistory({ maxGenerations: 2 })
-    await expect(reopened.generationDigest(1)).rejects.toBeInstanceOf(GenerationCompactedError)
-    await reopened.close()
-  })
-
-  it('a spent time budget is a consistent no-op; the next pass resumes', async () => {
-    ;(GenerationStore as any).REPACK_LIVE_WINDOW = 2
-    const dir = tempDir()
-    const brain = await openBrain(dir)
-    const id = await brain.add({ data: 'budget-probe', type: NounType.Document, metadata: { v: 0 } })
-    for (let v = 1; v <= 6; v++) await brain.update({ id, metadata: { v } })
-    await brain.flush()
-
-    const bounded = await brain.repackHistory({ timeBudgetMs: 0 })
-    expect(bounded).toEqual({ foldedGenerations: 0, segmentsCreated: 0 })
-
-    const resumed = await brain.repackHistory()
-    expect(resumed.foldedGenerations).toBeGreaterThan(0)
-    const db = await brain.asOf(3)
-    expect((await db.get(id))?.metadata?.v).toBeDefined()
-    await db.release()
-    await brain.close()
-  })
-})

tests/integration/multi-process-safety.test.ts

@@ -110,89 +110,6 @@ describe('Multi-process safety + read-only mode', () => {
       // Don't track `blocked` for afterEach cleanup since init failed.
     })
 
-    it('takes over a STALE foreign lock (dead PID + old heartbeat) and claims atomically', async () => {
-      const { mkdirSync, writeFileSync, readFileSync } = await import('node:fs')
-      const { join } = await import('node:path')
-      const os = await import('node:os')
-      mkdirSync(join(dir, 'locks'), { recursive: true })
-      const tenMinutesAgo = new Date(Date.now() - 10 * 60 * 1000).toISOString()
-      writeFileSync(join(dir, 'locks', '_writer.lock'), JSON.stringify({
-        pid: 999999999, // no such process — provably dead
-        hostname: os.hostname(),
-        startedAt: tenMinutesAgo,
-        lastHeartbeat: tenMinutesAgo,
-        version: '8.0.0',
-        rootDir: dir
-      }))
-
-      writer = new Brainy({ requireSubtype: false, storage: { type: 'filesystem', path: dir } })
-      await writer.init() // stale takeover must succeed
-
-      const lock = JSON.parse(readFileSync(join(dir, 'locks', '_writer.lock'), 'utf-8'))
-      expect(lock.pid).toBe(process.pid) // the atomic wx claim installed OUR lock
-    })
-
-    it('the writer-locked error carries the machine-readable contract (code + lockInfo)', async () => {
-      const { mkdirSync, writeFileSync } = await import('node:fs')
-      const { join } = await import('node:path')
-      const os = await import('node:os')
-      mkdirSync(join(dir, 'locks'), { recursive: true })
-      const otherPid = (process as any).ppid || 1
-      writeFileSync(join(dir, 'locks', '_writer.lock'), JSON.stringify({
-        pid: otherPid,
-        hostname: os.hostname(),
-        startedAt: new Date().toISOString(),
-        lastHeartbeat: new Date().toISOString(),
-        version: '8.7.0',
-        rootDir: dir
-      }))
-
-      const blocked = new Brainy({ requireSubtype: false, storage: { type: 'filesystem', path: dir } })
-      const err: any = await blocked.init().catch((e) => e)
-      expect(err.code).toBe('BRAINY_WRITER_LOCKED')
-      expect(err.lockInfo?.pid).toBe(otherPid)
-    })
-
-    it('release drains an in-flight heartbeat — no phantom lock re-created after unlink', async () => {
-      // The race (8.9.0): clearInterval stops FUTURE heartbeat ticks, but a
-      // tick already in flight could land its lock rewrite AFTER release's
-      // unlink — re-creating the lock as a phantom that blocks the next
-      // writer until the stale TTL. Simulate the in-flight tick explicitly
-      // and prove release waits for it.
-      writer = new Brainy({ requireSubtype: false, storage: { type: 'filesystem', path: dir } })
-      await writer.init()
-      const storage: any = (writer as any).storage
-
-      // An in-flight refresh that is ALREADY PAST its ownership guards
-      // (captured the lock info before release ran) and lands its atomic
-      // rewrite slowly — the exact straggler shape; absent the drain it
-      // writes after the unlink.
-      const { join: joinPath } = await import('node:path')
-      const capturedInfo = { ...storage.writerLockInfo }
-      const lockPath = joinPath(dir, 'locks', '_writer.lock')
-      const slowTick = (async () => {
-        await new Promise((r) => setTimeout(r, 100))
-        await storage.writeFileAtomic(
-          lockPath,
-          JSON.stringify({ ...capturedInfo, lastHeartbeat: new Date().toISOString() })
-        )
-      })()
-      storage.writerHeartbeatInFlight = slowTick.catch(() => {})
-
-      await writer.close() // → releaseWriterLock must drain slowTick first
-      await slowTick.catch(() => {}) // both paths fully settled either way
-      writer = null
-
-      const { existsSync } = await import('node:fs')
-      const { join } = await import('node:path')
-      expect(existsSync(join(dir, 'locks', '_writer.lock'))).toBe(false)
-
-      // And the directory is immediately claimable — no stale-TTL wait.
-      const next = new Brainy({ requireSubtype: false, storage: { type: 'filesystem', path: dir } })
-      await expect(next.init()).resolves.toBeUndefined()
-      await next.close()
-    })
-
     it('allows a second in-process writer with a warning (same PID)', async () => {
       // Two Brainy instances in the same Node process: not the dangerous
       // cross-process case. Should succeed (with a console warning).

tests/regression/metadata-index-cleanup.unit.test.ts

@@ -205,10 +205,10 @@ describe('Metadata index cleanup after remove / removeMany', () => {
       }
     })
 
-    it('refuses an empty ids array loudly (a silent no-op is not "graceful")', async () => {
+    it('handles empty ids array gracefully', async () => {
-      // 8.8.2: an empty selector used to resolve successfully having deleted
+      const result = await brain.removeMany({ ids: [] })
-      // NOTHING — the caller believed the delete happened. Now it throws.
+      expect(result.successful).toHaveLength(0)
-      await expect(brain.removeMany({ ids: [] })).rejects.toThrow(/ids: \[\]/)
+      expect(result.failed).toHaveLength(0)
     })
 
     it('handles large batch (> 1 chunk) without leaving stale index entries', async () => {

tests/transaction/TransactionManager.unit.test.ts

@@ -10,7 +10,6 @@
 
 import { describe, it, expect, beforeEach } from 'vitest'
 import { TransactionManager } from '../../src/transaction/TransactionManager.js'
-import { transactTimeoutBudget } from '../../src/transaction/Transaction.js'
 import { TransactionError } from '../../src/transaction/errors.js'
 
 describe('TransactionManager', () => {
@@ -329,45 +328,4 @@ describe('TransactionManager', () => {
       expect(stats1).toEqual(stats2) // Same values
     })
   })
-
-  describe('Timeout budget + telemetry', () => {
-    it('transactTimeoutBudget: explicit override wins; default scales with batch size', () => {
-      expect(transactTimeoutBudget(1)).toBe(30_000) // small batches keep the 30s floor
-      expect(transactTimeoutBudget(15)).toBe(30_000) // the old flat cap's break-even point
-      expect(transactTimeoutBudget(100)).toBe(200_000) // 100 ops × 2s — bulk gets an honest budget
-      expect(transactTimeoutBudget(1000, 5_000)).toBe(5_000) // caller override is untouched
-    })
-
-    it('a tripped budget rolls back and names the operation, progress, and budget', async () => {
-      const rolledBack: string[] = []
-
-      const failing = manager.executeTransaction(
-        async (tx) => {
-          tx.addOperation({
-            name: 'slow-first-op',
-            execute: async () => {
-              await new Promise((r) => setTimeout(r, 30))
-              return async () => {
-                rolledBack.push('slow-first-op')
-              }
-            }
-          })
-          tx.addOperation({
-            name: 'never-reached',
-            execute: async () => undefined
-          })
-        },
-        { timeout: 5 } // the first op's 30ms sleep guarantees the pre-op-2 check trips
-      )
-
-      await expect(failing).rejects.toThrow(TransactionError)
-      const err = await failing.catch((e) => e)
-      expect(err.name).toBe('TransactionTimeoutError')
-      expect(err.message).toContain('operation 1/2') // which op, of how many
-      expect(err.message).toContain("('never-reached')") // its name
-      expect(err.message).toContain('budget 5ms') // the budget that tripped
-      expect(err.message).toContain('rolled back') // the retryability statement
-      expect(rolledBack).toEqual(['slow-first-op']) // the applied op was undone
-    })
-  })
 })

tests/unit/brainy/batch-operations.test.ts

@@ -533,10 +533,8 @@ describe('Brainy Batch Operations', () => {
       expect(result.successful).toHaveLength(0)
       
       await brain.updateMany({ items: [] })
-      // removeMany is the exception (8.8.2): an empty id list is a refused
+      await brain.removeMany({ ids: [] })
-      // selector, not an empty batch — deleting "nothing" silently was the
+      // Should not throw
-      // bug class (a positional/bare-array call looked identical).
-      await expect(brain.removeMany({ ids: [] })).rejects.toThrow(/ids: \[\]/)
     })
     
     it('should validate batch size limits', async () => {

tests/unit/db/fact-log.test.ts

@@ -186,52 +186,4 @@ describe('fact log — round-trip, framing, reconcile, rotation, scan', () => {
     await log.sync()
     expect(log.segmentPaths()).toEqual([]) // only a tail exists — nothing sealed
   })
-
-  describe('scanFacts liveness contract (Stage-2 D1)', () => {
-    it('a wedged store fails LOUDLY within the first-batch bound — never a silent hang', async () => {
-      // Force a sealed segment (tiny rotateBytes) so the scan must READ from
-      // storage, then wedge that read: the exact production shape (a
-      // backlogged brain whose segment read never returned).
-      const mem: any = new MemoryStorage()
-      await mem.init()
-      const wedgeable = new FactLog(mem, { rotateBytes: 1 })
-      await wedgeable.open(0)
-      await wedgeable.append(fact(1))
-      await wedgeable.append(fact(2)) // second append rotates → seg 1 sealed
-      await wedgeable.sync()
-
-      const realRead = mem.readRawBytes.bind(mem)
-      mem.readRawBytes = (p: string) =>
-        p.includes('facts/seg-') ? new Promise(() => {}) : realRead(p) // hangs forever
-
-      const scan = wedgeable.scanFacts({ firstBatchTimeoutMs: 200 })
-      const started = Date.now()
-      await expect(scan.batches().next()).rejects.toThrow(/no first batch within 200ms/)
-      expect(Date.now() - started).toBeLessThan(5_000) // bound held, not a hang
-    })
-
-    it('a healthy scan is unaffected — first batch well inside the bound, all facts delivered', async () => {
-      for (let g = 1; g <= 5; g++) await log.append(fact(g))
-      await log.sync()
-      const scan = log.scanFacts({ batchSize: 2 })
-      const all: CommitFact[] = []
-      for await (const b of scan.batches()) all.push(...b.facts)
-      expect(all.map((f) => f.generation)).toEqual([1, 2, 3, 4, 5])
-      expect(scan.summary().factsYielded).toBe(5)
-    })
-
-    it('consumer think-time between pulls never counts against the producer', async () => {
-      for (let g = 1; g <= 4; g++) await log.append(fact(g))
-      await log.sync()
-      // Bound tighter than the consumer's pause: only the FIRST pull is
-      // raced, so a slow consumer after batch 1 must not trip the deadline.
-      const gen = log.scanFacts({ batchSize: 2, firstBatchTimeoutMs: 150 }).batches()
-      const first = await gen.next()
-      expect(first.done).toBe(false)
-      await new Promise((r) => setTimeout(r, 400)) // dawdle past the bound
-      const second = await gen.next()
-      expect(second.done).toBe(false)
-      expect((await gen.next()).done).toBe(true)
-    })
-  })
 })

tests/unit/db/generation-segments.test.ts

@@ -1,150 +0,0 @@
-/**
- * @module tests/unit/db/generation-segments
- * @description The generation-segment store (Stage-2 D1+D3 file format).
- * Laws: (1) fold → read round-trips deltas and records byte-faithfully via
- * sidecar point-reads; (2) the manifest is the ONLY discovery path — reopen
- * reads one file, never a listing; (3) a lost/corrupt sidecar rebuilds from
- * its segment loudly, a damaged SEGMENT fails loudly (never silent wrong
- * data); (4) D3 reclaim drops whole segments only and bumps compactedBelow;
- * (5) the packed digest is deterministic across reopen; (6) immutability —
- * fold refuses overlap with sealed ranges.
- */
-import { describe, it, expect, beforeEach } from 'vitest'
-import { MemoryStorage } from '../../../src/storage/adapters/memoryStorage.js'
-import {
-  GenerationSegmentStore,
-  SEGMENTS_PREFIX,
-  type FoldGeneration
-} from '../../../src/db/generationSegments.js'
-
-const UUID = (n: number): string => `00000000-0000-4000-8000-${String(n).padStart(12, '0')}`
-
-const gen = (g: number, recordCount = 2): FoldGeneration => ({
-  generation: g,
-  timestamp: 1_700_000_000_000 + g,
-  delta: { generation: g, nouns: [UUID(g)], verbs: [], bytes: 123 + g },
-  records: Array.from({ length: recordCount }, (_, i) => ({
-    kind: (i % 2 === 0 ? 'noun' : 'verb') as 'noun' | 'verb',
-    id: UUID(g * 100 + i),
-    record: { metadata: { noun: 'document', v: g }, vector: { v: [g, i] } }
-  }))
-})
-
-describe('db/GenerationSegmentStore — the D1+D3 packed tier', () => {
-  let storage: MemoryStorage
-  let store: GenerationSegmentStore
-
-  beforeEach(async () => {
-    storage = new MemoryStorage()
-    await storage.init()
-    store = new GenerationSegmentStore(storage as any)
-    await store.open()
-  })
-
-  it('fold → read round-trips deltas and records via sidecar point-reads', async () => {
-    const meta = await store.fold([gen(1), gen(2), gen(3)])
-    expect(meta).toMatchObject({ firstGeneration: 1, lastGeneration: 3, frames: 3 })
-    expect(meta.checksum).toBeGreaterThan(0)
-
-    expect(store.hasGeneration(2)).toBe(true)
-    expect(store.hasGeneration(4)).toBe(false)
-
-    const d2 = await store.readDelta(2)
-    expect(d2?.delta).toEqual({ generation: 2, nouns: [UUID(2)], verbs: [], bytes: 125 })
-    expect(d2?.timestamp).toBe(1_700_000_000_002)
-
-    const records = await store.readRecords(3)
-    expect(records).toHaveLength(2)
-    expect(records![0]).toEqual({
-      kind: 'noun',
-      id: UUID(300),
-      record: { metadata: { noun: 'document', v: 3 }, vector: { v: [3, 0] } }
-    })
-    // Point read by id, both kinds.
-    expect(await store.readRecord(3, 'verb', UUID(301))).toEqual({
-      metadata: { noun: 'document', v: 3 },
-      vector: { v: [3, 1] }
-    })
-    expect(await store.readRecord(3, 'noun', UUID(999))).toBeNull()
-  })
-
-  it('reopen discovers everything from the manifest alone — no listing', async () => {
-    await store.fold([gen(1), gen(2)])
-    await store.fold([gen(3), gen(4)])
-
-    const reopened = new GenerationSegmentStore(storage as any)
-    await reopened.open()
-    expect(reopened.segments()).toHaveLength(2)
-    expect(reopened.hasGeneration(4)).toBe(true)
-    expect((await reopened.readDelta(1))?.timestamp).toBe(1_700_000_000_001)
-  })
-
-  it('a lost sidecar rebuilds from its segment; a damaged segment fails LOUDLY', async () => {
-    const meta = await store.fold([gen(1), gen(2)])
-    const idxPath = `${SEGMENTS_PREFIX}/seg-${String(1).padStart(20, '0')}.idx`
-    await storage.deleteRawObject(idxPath)
-
-    const reopened = new GenerationSegmentStore(storage as any)
-    await reopened.open()
-    // Rebuild path: still serves correct data.
-    expect((await reopened.readRecords(2))!).toHaveLength(2)
-
-    // Now damage the SEGMENT itself: flip a payload byte → CRC mismatch, loud.
-    const segPath = `${SEGMENTS_PREFIX}/${meta.file}`
-    const bytes = (await storage.readRawBytes(segPath))!
-    bytes[bytes.length - 3] ^= 0xff
-    await storage.writeRawBytes(segPath, bytes)
-    const damaged = new GenerationSegmentStore(storage as any)
-    await damaged.open()
-    ;(damaged as any).sidecars.clear()
-    await storage.deleteRawObject(idxPath) // force the sequential rebuild over damaged bytes
-    await expect(damaged.readRecords(2)).rejects.toThrow(/CRC mismatch|damaged/)
-  })
-
-  it('D3 reclaim drops whole segments only and bumps compactedBelow', async () => {
-    await store.fold([gen(1), gen(2)])
-    await store.fold([gen(3), gen(4)])
-    await store.fold([gen(5), gen(6)])
-
-    // Horizon mid-segment-2 (below 4): only segment 1 is FULLY below → drops.
-    const r1 = await store.dropSegmentsBelow(4)
-    expect(r1).toEqual({ dropped: 1, compactedBelow: 3 })
-    expect(store.hasGeneration(1)).toBe(false)
-    expect(store.hasGeneration(3)).toBe(true) // partial segment survives whole
-
-    // Bytes actually gone.
-    expect(await storage.readRawBytes(`${SEGMENTS_PREFIX}/seg-${String(1).padStart(20, '0')}.bgs`)).toBeNull()
-
-    // Horizon past everything: the rest drop; compactedBelow is durable.
-    const r2 = await store.dropSegmentsBelow(7)
-    expect(r2.dropped).toBe(2)
-    const reopened = new GenerationSegmentStore(storage as any)
-    await reopened.open()
-    expect(reopened.compactedBelow()).toBe(7)
-    expect(reopened.segments()).toHaveLength(0)
-  })
-
-  it('the packed digest is deterministic across reopen and changes with history', async () => {
-    await store.fold([gen(1), gen(2), gen(3)])
-    const atSeal = await store.digestThroughPacked(3)
-    const midSegment = await store.digestThroughPacked(2)
-    expect(atSeal).not.toBeNull()
-    expect(midSegment).not.toBeNull()
-    expect(midSegment).not.toBe(atSeal)
-
-    const reopened = new GenerationSegmentStore(storage as any)
-    await reopened.open()
-    expect(await reopened.digestThroughPacked(3)).toBe(atSeal)
-    expect(await reopened.digestThroughPacked(2)).toBe(midSegment)
-
-    await reopened.fold([gen(4)])
-    expect(await reopened.digestThroughPacked(4)).not.toBe(atSeal)
-  })
-
-  it('sealed segments are immutable — fold refuses overlap, requires ascending input', async () => {
-    await store.fold([gen(1), gen(2)])
-    await expect(store.fold([gen(2), gen(3)])).rejects.toThrow(/overlaps the packed tier/)
-    await expect(store.fold([gen(4), gen(4)])).rejects.toThrow(/strictly ascending/)
-    await expect(store.fold([])).rejects.toThrow(/at least one generation/)
-  })
-})

tests/unit/db/generationStore.test.ts

@@ -488,95 +488,5 @@ describe('db/GenerationStore', () => {
       expect(result.removedGenerations).toBe(2)
       store.release(2)
     })
-
-    it('timeBudgetMs bounds a pass; the next pass resumes the same prefix', async () => {
-      await manyGens(4)
-      // A spent budget (0ms) stops before reclaiming anything — an early stop
-      // is a consistent prefix, never a partial generation.
-      const bounded = await store.compact({ timeBudgetMs: 0 })
-      expect(bounded.removedGenerations).toBe(0)
-      expect(bounded.horizon).toBe(0)
-      // The next (unbounded) pass picks up exactly where the bounded one
-      // stopped and completes the same work.
-      const resumed = await store.compact()
-      expect(resumed.removedGenerations).toBe(4)
-      expect(resumed.horizon).toBe(4)
-    })
-  })
-
-  // ==========================================================================
-  describe('history-bytes running total (the O(1) retention check)', () => {
-    /** A fresh walk with the cache dropped — ground truth for the invariant. */
-    async function groundTruthBytes(): Promise<number> {
-      ;(store as any).historyBytesTotal = null
-      return store.historyBytes()
-    }
-
-    it('is seeded once, then maintained through commits WITHOUT re-walks', async () => {
-      await commitWrite(ID_A, 1)
-      await commitWrite(ID_A, 2)
-      const seeded = await store.historyBytes()
-      expect(seeded).toBe(await groundTruthBytes())
-
-      // From here every read must come from the running total, not a walk:
-      // getDelta re-reads are the walk's cost — commits must not trigger any.
-      const getDeltaSpy = vi.spyOn(store as any, 'getDelta')
-      await commitWrite(ID_B, 1)
-      const afterCommit = await store.historyBytes()
-      expect(getDeltaSpy).not.toHaveBeenCalled()
-      getDeltaSpy.mockRestore()
-      expect(afterCommit).toBe(await groundTruthBytes())
-    })
-
-    it('stays exact through single-op group commits and compaction', async () => {
-      await commitWrite(ID_A, 1)
-      await store.historyBytes() // seed
-      // Single-op path: buffered generations flushed as one group commit.
-      await store.commitSingleOp({
-        touched: { nouns: [ID_B] },
-        execute: async () => {
-          await storage.saveNounMetadata(ID_B, metadataFixture(1))
-        }
-      })
-      await store.flushPendingSingleOps()
-      expect(await store.historyBytes()).toBe(await groundTruthBytes())
-
-      await store.historyBytes() // re-seed after ground-truth reset
-      await store.compact({ maxGenerations: 1 })
-      expect(await store.historyBytes()).toBe(await groundTruthBytes())
-    })
-
-    it('historyStats reports counts, bytes, range, and horizon read-only', async () => {
-      await commitWrite(ID_A, 1)
-      await commitWrite(ID_B, 1)
-      const stats = await store.historyStats()
-      expect(stats.generations).toBe(2)
-      expect(stats.bytes).toBe(await store.historyBytes())
-      expect(stats.oldestGeneration).toBe(1)
-      expect(stats.newestGeneration).toBe(2)
-      expect(stats.oldestTimestamp).toBeLessThanOrEqual(stats.newestTimestamp!)
-      expect(stats.horizon).toBe(0)
-      // Read-only: nothing was reclaimed by asking.
-      expect(store.committedGeneration()).toBe(2)
-
-      await store.compact({ maxGenerations: 1 })
-      const after = await store.historyStats()
-      expect(after.generations).toBe(1)
-      expect(after.oldestGeneration).toBe(2)
-      expect(after.horizon).toBe(1)
-    })
-
-    it('empty history reports null range and zero bytes', async () => {
-      const stats = await store.historyStats()
-      expect(stats).toMatchObject({
-        generations: 0,
-        bytes: 0,
-        oldestGeneration: null,
-        newestGeneration: null,
-        oldestTimestamp: null,
-        newestTimestamp: null,
-        horizon: 0
-      })
-    })
   })
 })

tests/unit/utils/osLimits.test.ts

@@ -1,76 +0,0 @@
-/**
- * @module tests/unit/utils/osLimits
- * @description OS-limit detection for pool-scale use. Laws:
- * (1) the /proc/self/limits parser reads soft/hard NOFILE exactly, including
- *     'unlimited'; (2) assessment warns ONLY below the pool floors and NEVER
- *     on an unreadable (null) limit — no measurement, no claim; (3) the full
- *     check composes both sources and survives unreadable /proc silently.
- */
-import { describe, it, expect } from 'vitest'
-import {
-  parseProcLimits,
-  assessOsLimits,
-  checkOsLimits,
-  NOFILE_POOL_FLOOR,
-  MAX_MAP_COUNT_POOL_FLOOR
-} from '../../../src/utils/osLimits.js'
-
-const SAMPLE_LIMITS = [
-  'Limit                     Soft Limit           Hard Limit           Units',
-  'Max cpu time              unlimited            unlimited            seconds',
-  'Max open files            1024                 1048576              files',
-  'Max locked memory         8388608              8388608              bytes'
-].join('\n')
-
-describe('osLimits — detect + warn at pool scale', () => {
-  it('parses soft/hard NOFILE from /proc/self/limits, including unlimited', () => {
-    expect(parseProcLimits(SAMPLE_LIMITS)).toEqual({ soft: 1024, hard: 1048576 })
-    expect(
-      parseProcLimits('Max open files            unlimited            unlimited            files')
-    ).toEqual({ soft: Infinity, hard: Infinity })
-    expect(parseProcLimits('no such row here')).toEqual({ soft: null, hard: null })
-  })
-
-  it('warns below the floors, stays quiet at or above them', () => {
-    const low = assessOsLimits({ nofileSoft: 1024, nofileHard: 1048576, maxMapCount: 65530 })
-    expect(low).toHaveLength(2)
-    expect(low[0]).toContain('RLIMIT_NOFILE soft limit is 1024')
-    expect(low[0]).toContain(`ulimit -n ${NOFILE_POOL_FLOOR}`)
-    expect(low[0]).toContain('raise the soft limit only') // hard already allows it
-    expect(low[1]).toContain('vm.max_map_count is 65530')
-    expect(low[1]).toContain(`vm.max_map_count=${MAX_MAP_COUNT_POOL_FLOOR}`)
-
-    expect(
-      assessOsLimits({
-        nofileSoft: NOFILE_POOL_FLOOR,
-        nofileHard: Infinity,
-        maxMapCount: MAX_MAP_COUNT_POOL_FLOOR
-      })
-    ).toEqual([])
-  })
-
-  it('an unreadable limit makes NO claim — nulls never warn', () => {
-    expect(assessOsLimits({ nofileSoft: null, nofileHard: null, maxMapCount: null })).toEqual([])
-  })
-
-  it('checkOsLimits composes both sources and survives unreadable /proc silently', async () => {
-    const report = await checkOsLimits(async (p) => {
-      if (p === '/proc/self/limits') return SAMPLE_LIMITS
-      if (p === '/proc/sys/vm/max_map_count') return '65530\n'
-      throw new Error('unexpected path')
-    })
-    expect(report.nofileSoft).toBe(1024)
-    expect(report.maxMapCount).toBe(65530)
-    expect(report.warnings).toHaveLength(2)
-
-    const offLinux = await checkOsLimits(async () => {
-      throw Object.assign(new Error('ENOENT'), { code: 'ENOENT' })
-    })
-    expect(offLinux).toEqual({
-      nofileSoft: null,
-      nofileHard: null,
-      maxMapCount: null,
-      warnings: []
-    })
-  })
-})