feat(log): log authority is the fleet default — adopt-at-open, oracle-gated; plus the power-cut throw-site cures and the loud torn-record contract

THE DEFAULT FLIP (ruled on proven evidence — at-ack survived 301/301
acked-writes-through-power-cut in block-layer fault injection; deferred
tree authority demonstrably loses flush-covered acks): a brain with NO
stored authority artifact now ADOPTS LOG AUTHORITY AT OPEN. The oracle
gates the flip exactly as the guarded adoption path always did — curable
divergences baseline-backfilled, the flip lands ONLY on a green verdict —
and a brain that cannot verify STAYS tree-authoritative loudly, with the
refusal recorded on the switch artifact so subsequent opens are cheap.
config logAuthority: 'defer' is the explicit documented opt-out (no
automatic adoption; declared flush-window loss; adoptLogAuthority() flips
later). A stored artifact always wins. RELEASES.md carries the posture.

Two standing .fails debt pins FLIP TO HOLDING under the default: the
at-ack crash-survival gap and the ack-at-log durability target — both now
permanent asserted truths, not aspirations.

POWER-CUT THROW SITES (fault-injection findings, brainy-alone config):
- A manifest-listed-but-unloadable column segment QUARANTINES at
  discovery (loud once, counted always, quarantinedSegments() exposed for
  the heal) and the field serves its remaining segments DEGRADED — never
  a raw throw killing every query on the field. Real storage faults still
  propagate untouched.
- Torn generation artifacts (NaN/garbage in manifest or counter) DISCARD
  with narration at the store's open and recovery re-derives — plus a
  defensive finite-integer guard at the init consumer. Never a RangeError
  killing an open.

THE LOUD TORN-RECORD CONTRACT: an existing-but-unparseable stored record
now surfaces as a typed, counted TornRecordError on every entity-read
surface (including fifteen previously-blind per-item batch catches);
ENOENT stays clean-absent; artifact readers with designed absent-recovery
keep null-tolerance behind the loud floor. Disk corruption can no longer
read as silent data invisibility.

Suite migration: the default's pins inverted deliberately, generation
baselines made relative, quarantine-contract pins rewritten to the ruled
behavior.

Gates: tsc 0 · unit 2065/2065 (159 files) · integration 826 (93 files) ·
conformance 31/31 · kill-matrix 15/15 · torn-open guards 2/2.

tests/unit/db/bounded-chains.test.ts

@@ -477,14 +477,17 @@ describe('materializeAtGeneration — bounded & deadlock-free (GA #33)', () => {
     const store = (brain as any).generationStore
 
     const N = 400
+    // Relative, not absolute: under the adopt-at-open default the open-time
+    // baseline backfill takes a generation of its own, so the first add is
+    // NOT generation 1 — pin the deep generation to the first add's commit.
+    let deepGen = 0
     for (let i = 0; i < N; i++) {
       await brain.add({ data: `doc ${i}`, type: NounType.Document, subtype: 'note', metadata: { i }, vector: VEC })
+      if (i === 0) deepGen = brain.generation()
     }
     const R = brain.generation() // ≈ N (each add is its own generation)
     expect(R).toBeGreaterThanOrEqual(N)
 
-    const deepGen = 1
-
     // Count getDelta invocations during the materialize.
     const realGetDelta = store.getDelta.bind(store)
     let getDeltaCalls = 0
@@ -509,7 +512,8 @@ describe('materializeAtGeneration — bounded & deadlock-free (GA #33)', () => {
     expect(getDeltaCalls).toBeLessThan(R * 5)
     expect(getDeltaCalls).toBeLessThan(N * N) // the regression guard
 
-    // The materialized at-gen-1 brain holds exactly the one entity that existed.
+    // The materialized brain at the first add's generation holds exactly the
+    // one user entity that existed.
     const atGen1 = await handle.find({ limit: N + 10 })
     expect(atGen1.length).toBe(1)
     await handle.close()

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

@@ -7,12 +7,13 @@
  * one), a solo writer syncs immediately, and at the brain level an at-ack
  * ack resolving means the write's fact is on disk.
  *
- * One pin is marked `.fails` (real finding, not a test bug): the at-ack
- * durability contract says an acked write's fact survives power loss, but
- * FactLog.open() truncates every fact beyond the store's committed
- * generation watermark — which only advances at the pending-tier flush. A
- * crash-shaped reopen (acks landed, flush never ran) therefore DISCARDS the
- * fsynced facts at open. See the test comment for the exact mechanism.
+ * The final pin holds the at-ack durability contract END TO END: an acked
+ * write's fact survives a crash-shaped reopen. This was a `.fails` known
+ * gap (FactLog.open() truncated every fact beyond the committed watermark,
+ * which only advances at the pending-tier flush) — CURED by the 10.0.0
+ * adopt-at-open fleet default: a fresh brain stores the log-authority
+ * artifact at open, and under 'log' authority recovery REPLAYS intact
+ * facts above the manifest instead of truncating them.
  */
 import { describe, it, expect, beforeEach, afterEach } from 'vitest'
 import { mkdtempSync, rmSync } from 'node:fs'
@@ -188,9 +189,9 @@ describe('durable-at-ack through the brain (group commit end-to-end)', () => {
 
   it('at-ack: N concurrent add() acks all resolve, every ack was covered by a log sync, and every fact is on disk after reopen', async () => {
     const { brain, dir } = await openBrain()
-    // White-box: engage the at-ack durability mode directly (the guarded
-    // authority flip that normally enables it is covered by the integration
-    // suite — this test pins the durability machinery itself).
+    // The 10.0.0 fleet default already adopted log authority at open, so
+    // the brain is at-ack; the white-box engage stays so this pin holds the
+    // durability MACHINERY itself independent of the open-time posture.
     brain.generationStore.setLogDurability('at-ack')
 
     const factLog = brain.generationStore.getFactLog()
@@ -231,19 +232,17 @@ describe('durable-at-ack through the brain (group commit end-to-end)', () => {
     }
   })
 
-  // KNOWN GAP (marked .fails — remove the marker when fixed in src): the
-  // at-ack contract is that an acked write's fact survives power loss. The
-  // fsync at ack does put the fact's bytes on disk — but FactLog.open()
-  // truncates every fact with generation > the store's committed watermark,
-  // and that watermark only advances at the pending-tier flush
-  // (flushPendingSingleOps). So on a crash-shaped reopen (acks landed, flush
-  // never ran) the store logs "[FactLog] truncating N uncommitted fact(s)"
-  // and DISCARDS the acked, fsynced facts. Until recovery treats the log as
-  // authoritative past the tree's watermark (or the watermark goes durable
-  // at ack), durable-at-ack does not survive the very crash it exists for.
-  it.fails('at-ack CONTRACT: acked facts survive a crash-shaped reopen (no flush ever ran)', async () => {
+  // THE AT-ACK CONTRACT, HELD (was a `.fails` known gap): an acked write's
+  // fact survives a crash-shaped reopen. Fixed by the 10.0.0 adopt-at-open
+  // fleet default — this brain adopted LOG authority at open (artifact
+  // stored, durable-at-ack live), and under 'log' authority FactLog
+  // recovery REPLAYS intact facts above the committed watermark at the next
+  // open instead of truncating them back. Durable-at-ack now survives the
+  // very crash it exists for.
+  it('at-ack CONTRACT: acked facts survive a crash-shaped reopen (no flush ever ran)', async () => {
     const { brain, dir } = await openBrain()
-    brain.generationStore.setLogDurability('at-ack')
+    expect(brain.logAuthority().authority, 'the fleet default adopted at open').toBe('log')
+    expect(brain.generationStore.logDurability).toBe('at-ack')
     // Crash simulation: the pending-tier durability flush never happens
     // (every trigger routes through flushPendingSingleOps), and the brain is
     // abandoned without close() — exactly the power-loss shape at-ack is for.

tests/unit/db/torn-open-guards.test.ts

@@ -0,0 +1,97 @@
+/**
+ * @module tests/unit/db/torn-open-guards
+ * @description Power-cut throw-site cures (brainy-alone fault-injection
+ * findings, both release-gating):
+ * 1. A torn generation manifest/counter (NaN/garbage where a generation
+ *    belongs) DISCARDS with narration and re-derives — never a RangeError
+ *    killing the open.
+ * 2. A manifest-listed-but-unloadable column segment QUARANTINES at
+ *    discovery with narration; the field serves its remaining segments
+ *    DEGRADED — never a raw throw killing every query on the field.
+ */
+import { describe, it, expect, afterEach } from 'vitest'
+import { mkdtempSync, rmSync, readdirSync, writeFileSync, readFileSync, existsSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { gzipSync } from 'node:zlib'
+import { Brainy } from '../../../src/index.js'
+import { NounType } from '../../../src/types/graphTypes.js'
+
+const dirs: string[] = []
+const brains: Brainy[] = []
+afterEach(async () => {
+  for (const b of brains.splice(0)) await b.close().catch(() => {})
+  for (const d of dirs.splice(0)) rmSync(d, { recursive: true, force: true })
+})
+
+async function open(dir: string): Promise<Brainy> {
+  const b = new Brainy({ storage: { type: 'filesystem', path: dir }, requireSubtype: false })
+  await b.init()
+  brains.push(b)
+  return b
+}
+
+describe('torn-open guards', () => {
+  it('a torn generation manifest (NaN) opens with narrated discard — never a RangeError', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'brainy-torn-gen-'))
+    dirs.push(dir)
+    let brain = await open(dir)
+    const id = await brain.add({ data: 'survivor row', type: NounType.Document, metadata: { k: 1 } })
+    await brain.flush()
+    await brain.close()
+    brains.pop()
+
+    // The power-cut shape: the manifest's generation field is garbage.
+    const sys = join(dir, '_system')
+    const manifestPath = ['manifest.json', 'manifest.json.gz']
+      .map((f) => join(sys, f))
+      .find((p) => existsSync(p))!
+    const torn = { version: 1, generation: 'NaN-garbage', committedAt: 'x', horizon: null }
+    if (manifestPath.endsWith('.gz')) writeFileSync(manifestPath, gzipSync(JSON.stringify(torn)))
+    else writeFileSync(manifestPath, JSON.stringify(torn))
+
+    // Open MUST succeed (narrated discard + recovery re-derivation), and the
+    // durable row must still serve (log-authority replay recovers it).
+    brain = await open(dir)
+    expect((await brain.get(id))!.data).toContain('survivor row')
+    // Writes continue with a sane monotonic generation.
+    await brain.add({ data: 'post-recovery', type: NounType.Document, metadata: { k: 2 } })
+    expect(Number.isSafeInteger(brain.generation())).toBe(true)
+  }, 120000)
+
+  it('a torn column segment quarantines at discovery; the field serves remaining segments degraded — never a raw throw', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'brainy-torn-seg-'))
+    dirs.push(dir)
+    let brain = await open(dir)
+    for (let i = 0; i < 6; i++) {
+      await brain.add({ data: `row ${i}`, type: NounType.Document, metadata: { bucket: i % 2 } })
+    }
+    await brain.flush()
+    await brain.close()
+    brains.pop()
+
+    // Tear ONE column segment's bytes on disk (manifest keeps listing it) —
+    // the QUERIED field's own segment, so the quarantine path provably
+    // engages. Column segments live under the raw-blob root:
+    // `<root>/_blobs/_column_index/<field>/L<level>-<id>.bin`.
+    const segDir = join(dir, '_blobs', '_column_index', 'bucket')
+    let tornOne = false
+    if (existsSync(segDir)) {
+      for (const f of readdirSync(segDir, { withFileTypes: true })) {
+        if (!f.isDirectory() && /^L\d+-.*\.bin$/.test(f.name)) {
+          writeFileSync(join(segDir, f.name), Buffer.from([0x00, 0x01, 0x02])) // garbage
+          tornOne = true
+          break
+        }
+      }
+    }
+    expect(tornOne, 'found a segment file to tear (layout probe)').toBe(true)
+
+    // Queries on the field MUST NOT throw — degraded-announced service.
+    brain = await open(dir)
+    const rows = await brain.find({ where: { bucket: 0 }, limit: 10 })
+    expect(Array.isArray(rows), 'query survives the torn segment').toBe(true)
+    // Full completeness is NOT asserted (the torn segment's rows may be
+    // absent — that is the documented degraded contract until heal).
+  }, 120000)
+})

tests/unit/indexes/columnStore/segment-load-fault.test.ts

@@ -5,19 +5,22 @@
  * doing so dropped every entity in that segment out of `filter`/`rangeQuery`/
  * `sortTopK` with no error, so a corrupt index looked like a merely short result.
  *
- * The three failure classes and their required behaviour:
+ * The three failure classes and their required behaviour (torn-segment
+ * QUARANTINE contract — a raw throw at query time killed every query on the
+ * field forever; a silent skip hid the loss; quarantine is the middle):
  *  - a real storage IO fault (EIO) PROPAGATES verbatim — a present-but-unreadable
  *    segment is not "absent", so it must not read as an empty result;
- *  - a manifest-listed segment with undecodable bytes throws `ColumnSegmentLoadError`;
- *  - a manifest-listed segment with NO bytes (gone on disk) throws `ColumnSegmentLoadError`.
+ *  - a manifest-listed segment with undecodable bytes is QUARANTINED at
+ *    discovery: the query serves the field's remaining segments degraded and
+ *    `quarantinedSegments()` reports the torn segment (loud once, counted
+ *    always, healable);
+ *  - a manifest-listed segment with NO bytes (gone on disk) quarantines the
+ *    same way.
  * Only genuine absence stays benign: querying a field that has no manifest at all
  * returns empty (nothing was ever written for it) — that is not a fault.
  */
 import { describe, it, expect, beforeEach } from 'vitest'
-import {
-  ColumnStore,
-  ColumnSegmentLoadError
-} from '../../../../src/indexes/columnStore/ColumnStore.js'
+import { ColumnStore } from '../../../../src/indexes/columnStore/ColumnStore.js'
 import { MemoryStorage } from '../../../../src/storage/adapters/memoryStorage.js'
 import { EntityIdMapper } from '../../../../src/utils/entityIdMapper.js'
 
@@ -80,30 +83,44 @@ describe('ColumnStore segment-load faults surface loudly, absence stays benign (
     return s
   }
 
-  it('propagates a storage IO fault verbatim — not [] and not a ColumnSegmentLoadError', async () => {
+  it('propagates a storage IO fault verbatim — not [] and not a quarantine (a present-but-unreadable segment is not torn)', async () => {
     storage.faultMode = 'io'
     const store = await reopen()
     await expect(store.filter('createdAt', 300)).rejects.toMatchObject({
       code: 'EIO'
     })
+    // An IO fault is NOT quarantined — the segment may be fine once the disk
+    // recovers; only torn/absent bytes enter the ledger.
+    expect(store.quarantinedSegments('createdAt')).toEqual([])
     await store.close()
   })
 
-  it('throws ColumnSegmentLoadError when a manifest-listed segment is undecodable', async () => {
+  it('QUARANTINES an undecodable manifest-listed segment at discovery — the query serves degraded, the ledger names the tear', async () => {
     storage.faultMode = 'corrupt'
     const store = await reopen()
-    await expect(
-      store.sortTopK('createdAt', 'desc', 10)
-    ).rejects.toBeInstanceOf(ColumnSegmentLoadError)
+    // Degraded-announced serve: the field's only segment is torn, so the
+    // result is empty — but the query completes instead of throwing.
+    const sorted = await store.sortTopK('createdAt', 'desc', 10)
+    expect(sorted).toEqual([])
+    const ledger = store.quarantinedSegments('createdAt')
+    expect(ledger).toHaveLength(1)
+    expect(ledger[0].error).toMatch(/decode failed/)
+    expect(ledger[0].hits).toBeGreaterThanOrEqual(1)
+    // Subsequent queries keep serving (skip + count), never a throw.
+    const hitsBefore = ledger[0].hits
+    await expect(store.filter('createdAt', 300)).resolves.toBeDefined()
+    expect(store.quarantinedSegments('createdAt')[0].hits).toBeGreaterThan(hitsBefore)
     await store.close()
   })
 
-  it('throws ColumnSegmentLoadError when a manifest-listed segment has no loadable bytes', async () => {
+  it('QUARANTINES a manifest-listed segment with no loadable bytes — degraded serve, ledger entry, never a throw', async () => {
     storage.faultMode = 'missing'
     const store = await reopen()
-    await expect(
-      store.rangeQuery('createdAt', 100, 500)
-    ).rejects.toBeInstanceOf(ColumnSegmentLoadError)
+    const bitmap = await store.rangeQuery('createdAt', 100, 500)
+    expect(bitmap.size).toBe(0)
+    const ledger = store.quarantinedSegments('createdAt')
+    expect(ledger).toHaveLength(1)
+    expect(ledger[0].error).toMatch(/no loadable bytes/)
     await store.close()
   })