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
All checks were successful
CI / Node 22 (push) Successful in 12m16s
CI / Node 24 (push) Successful in 12m13s
CI / Bun (latest) (push) Successful in 12m20s

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.
This commit is contained in:
David Snelling 2026-08-11 08:37:38 -07:00
parent 67c606be69
commit 214c98b4d5
23 changed files with 833 additions and 154 deletions

View file

@ -96,11 +96,15 @@ describe('8.0 Db API — generational MVCC', () => {
}
/** Open (and track) a filesystem brain rooted at a fresh temp directory. */
async function openFsBrain(dir?: string): Promise<{ brain: Brainy; dir: string }> {
async function openFsBrain(
dir?: string,
logAuthority?: 'adopt' | 'defer'
): Promise<{ brain: Brainy; dir: string }> {
const rootDirectory = dir ?? makeTempDir()
const brain = new Brainy({
requireSubtype: false,
storage: { type: 'filesystem', path: rootDirectory }
storage: { type: 'filesystem', path: rootDirectory },
...(logAuthority ? { logAuthority } : {})
})
await brain.init()
brains.push(brain)
@ -647,7 +651,13 @@ describe('8.0 Db API — generational MVCC', () => {
// ==========================================================================
it('proof 8 — a crash before the manifest rename recovers to the exact pre-transaction state', async () => {
const dir = makeTempDir()
const { brain: first } = await openFsBrain(dir)
// 'defer' (tree authority): this proof pins the TREE commit-point
// contract — the manifest rename is the commit, so a crash before it
// rolls back. Under the adopt-at-open default (log authority) the same
// crash point legitimately REPLAYS the fsynced fact at reopen and the
// transaction lands — that contract is pinned in the durability kill
// matrix's at-ack rows, not here.
const { brain: first } = await openFsBrain(dir, 'defer')
await first.transact([
{
@ -689,9 +699,10 @@ describe('8.0 Db API — generational MVCC', () => {
// the realistic worst case for the recovery path.
await first.close()
// Reopen: recovery rolls the uncommitted generation back and rebuilds
// the indexes from the repaired records.
const { brain: second } = await openFsBrain(dir)
// Reopen ('defer' again — a reopen under the adopt default would adopt
// and change the recovery path): recovery rolls the uncommitted
// generation back and rebuilds the indexes from the repaired records.
const { brain: second } = await openFsBrain(dir, 'defer')
const recovered = await second.get(uid('crash-e'))
expect((recovered?.metadata as { v: number }).v).toBe(1)
expect(await second.get(uid('crash-new'))).toBeNull()
@ -1162,13 +1173,16 @@ describe('8.0 Db API — generational MVCC', () => {
const brain = await openMemoryBrain()
// Model-B: a single-op write is its OWN generation and IS logged (no meta —
// tx metadata is a transact()-only concept). It is generation 1 on a fresh
// brain (init-time infrastructure writes are the un-versioned gen-0 baseline).
// tx metadata is a transact()-only concept). Relative baseline: under the
// adopt-at-open fleet default the open-time baseline backfill is itself a
// logged single-op generation, so the log is not empty on a fresh brain —
// every pin below is expressed against that baseline.
const baseGens = (await brain.transactionLog()).map((entry) => entry.generation)
await brain.add({ id: uid('txlog-solo'), type: NounType.Document, data: 'solo', vector: vec(99), subtype: 'note' })
const soloLog = await brain.transactionLog()
expect(soloLog.map((entry) => entry.generation)).toEqual([1])
const soloGen = brain.generation()
expect(soloLog.map((entry) => entry.generation)).toEqual([soloGen, ...baseGens])
expect(soloLog[0].meta).toBeUndefined()
const soloGen = 1
const first = await brain.transact(
[{ op: 'add', id: uid('txlog-a'), type: NounType.Document, data: 'a', vector: vec(100), metadata: {} }],
@ -1181,12 +1195,14 @@ describe('8.0 Db API — generational MVCC', () => {
const third = await brain.transact([{ op: 'update', id: uid('txlog-a'), metadata: { v: 3 } }])
const entries = await brain.transactionLog()
// Newest first: the three transacts, then the single-op solo write (gen 1).
// Newest first: the three transacts, then the single-op solo write, then
// whatever the open baseline logged (the adopt-at-open backfill).
expect(entries.map((entry) => entry.generation)).toEqual([
third.generation,
second.generation,
first.generation,
soloGen
soloGen,
...baseGens
])
expect(entries[1].meta).toEqual({ author: 'job-2' })
expect(entries[2].meta).toEqual({ author: 'job-1' })
@ -1238,21 +1254,24 @@ describe('8.0 Db API — generational MVCC', () => {
const brain = await openMemoryBrain()
const a = uid('ov-a')
const b = uid('ov-b')
await (
await brain.transact([
{ op: 'add', id: a, type: NounType.Document, data: 'a', vector: vec(1), metadata: { v: 1 } },
{ op: 'add', id: b, type: NounType.Document, data: 'b', vector: vec(2), metadata: { v: 1 } }
])
).release()
const at1 = await brain.asOf(1)
// Pin RELATIVELY at the transact's own generation (not an absolute 1 —
// the adopt-at-open baseline backfill owns the first generation).
const tx = await brain.transact([
{ op: 'add', id: a, type: NounType.Document, data: 'a', vector: vec(1), metadata: { v: 1 } },
{ op: 'add', id: b, type: NounType.Document, data: 'b', vector: vec(2), metadata: { v: 1 } }
])
const txGen = tx.generation
await tx.release()
const at1 = await brain.asOf(txGen)
// A single-op REMOVE of `b` lands AFTER the pin and is NOT flushed (pending).
await brain.remove(b)
const liveIds = (await brain.find({})).map((r) => r.id)
const pastIds = (await at1.find({})).map((r) => r.id)
// Live: `b` is gone. Historical (pinned at gen 1): the un-flushed removal is
// overlaid out, so `b` is still present at its pinned state.
// Live: `b` is gone. Historical (pinned at the transact's generation): the
// un-flushed removal is overlaid out, so `b` is still present at its
// pinned state.
expect(liveIds).toContain(a)
expect(liveIds).not.toContain(b)
expect(pastIds).toContain(a)
@ -1262,11 +1281,14 @@ describe('8.0 Db API — generational MVCC', () => {
it('Model-B retention — explicit caps reclaim single-op history; committed history survives reopen', async () => {
const { brain, dir } = await openFsBrain()
// Relative baseline: the adopt-at-open backfill holds the first
// generation(s), so the 6 writes below land at base+1..base+6.
const base = brain.generation()
const a = uid('ret-a')
await brain.add({ id: a, type: NounType.Document, data: 'a', vector: vec(1), metadata: { v: 1 } })
for (let v = 2; v <= 6; v++) await brain.update({ id: a, metadata: { v } })
await brain.flush() // persist the per-write generations to disk
expect(brain.generation()).toBe(6)
expect(brain.generation()).toBe(base + 6)
// Cap to the 2 most recent generations — older single-op history is reclaimed.
const res = await brain.compactHistory({ maxGenerations: 2 })

View file

@ -36,6 +36,9 @@ import { GenerationCompactedError } from '../../src/db/errors.js'
import type { GenerationStore } from '../../src/db/generationStore.js'
import { NounType } from '../../src/types/graphTypes.js'
/** The VFS root — re-committed by the adopt-at-open baseline backfill. */
const VFS_ROOT = '00000000-0000-0000-0000-000000000000'
/** Deterministic 384-dim vector so no test ever invokes the embedder. */
function vec(seed: number): number[] {
return Array.from({ length: 384 }, (_, i) => ((seed * 31 + i * 7) % 100) / 100)
@ -133,7 +136,11 @@ describe('8.0 Db API — temporal range verbs', () => {
expect(viaDb).toEqual(viaGen)
expect(viaDb.fromGeneration).toBe(g1)
expect(viaDb.nouns).toEqual([a, b].sort()) // a (updated after g1) + b (added after g1)
expect(viaEpoch.nouns).toEqual([a, b].sort()) // (0, now] also includes a's creation, still {a, b}
// (0, now] also includes a's creation — still {a, b} among user rows. The
// adopt-at-open baseline backfill re-commits the VFS root as a real
// generation, so the full-epoch window legitimately reports it too;
// filter it to keep this pin about the user writes.
expect(viaEpoch.nouns.filter((n) => n !== VFS_ROOT)).toEqual([a, b].sort())
// direction guard: an older view cannot be `since` a newer lower bound
const older = await brain.asOf(1)
@ -163,7 +170,11 @@ describe('8.0 Db API — temporal range verbs', () => {
}
const all = await brain.transactionLog()
expect(all.map((e) => e.generation)).toEqual([...gens].reverse()) // newest first
// Newest first — compared above the open baseline (the adopt-at-open
// backfill logs its own generation(s) below the first user write).
expect(all.map((e) => e.generation).filter((g) => g >= gens[0])).toEqual(
[...gens].reverse()
)
// INCLUSIVE both ends — gens[1] AND gens[3] are present (contrast since's exclusive lower).
const windowed = await brain.transactionLog({ from: gens[1], to: gens[3] })
@ -334,19 +345,22 @@ describe('8.0 Db API — temporal range verbs', () => {
// 7. Granularity (Model-B) ---------------------------------------------------
it('granularity: single-operation writes ARE versioned and visible to the temporal verbs', async () => {
const brain = await openMemoryBrain()
// Relative baseline: the adopt-at-open backfill already logged its own
// generation(s) — pin the DELTA this test's writes add, not a count.
const baseCount = (await brain.transactionLog()).length
const a = uid('gran-a')
const r1 = await brain.transact([
{ op: 'add', id: a, type: NounType.Document, data: 'a', vector: vec(1), metadata: { v: 1 } }
])
await r1.release()
expect((await brain.transactionLog()).length).toBe(1)
expect((await brain.transactionLog()).length).toBe(baseCount + 1)
// Model-B: a single-op write is its OWN immutable generation — logged,
// diffable, and time-travelable, exactly like a transact() of one op.
await brain.update({ id: a, metadata: { v: 2 } })
// The single-op update appended a generation/log entry.
expect((await brain.transactionLog()).length).toBe(2)
expect((await brain.transactionLog()).length).toBe(baseCount + 2)
expect(brain.generation()).toBe(r1.generation + 1)
// diff sees the single-op update as a modification of `a`.

View file

@ -109,14 +109,14 @@ describe('durability kill matrix — crash at every commit-path step, recover by
/**
* Flip a brain to durable-at-ack (log-authority) mode.
*
* NOT via `adoptLogAuthority()`: the sanctioned flip REFUSES on a freshly
* materialized brain its verification oracle reports the generation-0
* VFS-root baseline as a divergence (`state-differs` even after an
* identity-update backfill; verified 2026-08-10). This helper flips the
* SAME switch the sanctioned path flips (`setLogDurability('at-ack')`) and
* persists the SAME authority artifact, so a reopened brain also runs in
* log-authority mode. The durability semantics under test are governed
* entirely by that switch.
* NOT via `adoptLogAuthority()` (and the helper opens every brain with
* `logAuthority: 'defer'`, opting out of the 10.0.0 adopt-at-open fleet
* default): the sanctioned path runs the oracle and a baseline backfill,
* which appends its own generation shifting the floor arithmetic every
* row pins. This helper flips the SAME switch the sanctioned path flips
* (`setLogDurability('at-ack')`) and persists the SAME authority artifact,
* so a reopened brain also runs in log-authority mode. The durability
* semantics under test are governed entirely by that switch.
*/
async function flipToAtAck(brain: Brainy): Promise<void> {
const storage = (

View file

@ -4,14 +4,13 @@
*
* (1) FSYNC-BEFORE-ACK: an acknowledged write's fact survives an abrupt
* process end (no flush, no close reopen from disk).
* - transact(): HOLDS TODAY the fact is fsync'd before transact returns.
* - single-op: PINNED AS `it.fails` today's group-commit batches
* DURABILITY (ack precedes the group fsync; a hard kill loses the fact
* AND the generation together, coherently the documented Model-B
* contract, fine while the tree is authoritative). The destination
* (ack-at-log) requires group commit to become LATENCY batching: the
* ack waits for the shared fsync. When that lands, this pin flips red
* remove `.fails` and the contract is permanent. No cliff to discover.
* - transact(): HOLDS the fact is fsync'd before transact returns.
* - single-op: HOLDS (was pinned `it.fails` until the ack-at-log
* destination landed): the 10.0.0 adopt-at-open fleet default flips a
* fresh brain to log authority at open, so single-op acks await the
* covering group fsync (durable-at-ack) and recovery REPLAYS intact
* facts above the manifest at the next open. The contract is now
* permanent on every path.
*
* (2) SCAN STABILITY UNDER ROTATION: a scan handle opened before segment
* rotation yields exactly its snapshot byte-identical facts, no gaps,
@ -63,9 +62,11 @@ describe('fsync-before-ack contract (fact durability at the ack boundary)', () =
expect(facts.some((f) => f.generation === receipt.generation)).toBe(true)
})
// PINNED (flips red when group commit becomes latency batching — then
// remove `.fails` and the ack-at-log contract is permanent on every path).
it.fails('single-op: the fact is durable the moment the ack returns (the ack-at-log target)', async () => {
// THE ACK-AT-LOG CONTRACT, HELD (was `.fails` until it landed): under the
// adopt-at-open fleet default this brain runs durable-at-ack from open —
// the ack waits for the covering log fsync, and the log-authority recovery
// path replays the intact fact at the next open instead of truncating it.
it('single-op: the fact is durable the moment the ack returns (the ack-at-log target)', async () => {
await brain.add({ data: 'acked single-op', type: 'document', metadata: { n: 1 } })
const ackedHead = brain.scanFacts()!.headGeneration
// Abrupt end immediately after the ack — before any flush window.

View file

@ -22,8 +22,12 @@ afterEach(async () => {
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 })
async function open(dir: string, logAuthority?: 'adopt' | 'defer'): Promise<Brainy> {
const b = new Brainy({
storage: { type: 'filesystem', path: dir },
requireSubtype: false,
...(logAuthority ? { logAuthority } : {})
})
await b.init()
brains.push(b)
return b
@ -80,4 +84,31 @@ describe('adoptLogAuthority — the sanctioned flip with self-backfill', () => {
expect(report.verdict).toBe('green')
expect(brain.logAuthority().authority).toBe('log')
}, 120000)
// THE OPT-OUT CONTRACT (`logAuthority: 'defer'`): no automatic adoption —
// the fresh brain stays tree-authoritative and writes NO artifact (a
// deferred posture is config, not stored state); the EXPLICIT
// adoptLogAuthority() then flips it exactly as before the fleet default.
it("opt-out: 'defer' stays tree with no artifact until the explicit adoptLogAuthority() flips it", async () => {
const dir = mkdtempSync(join(tmpdir(), 'brainy-adopt-defer-'))
dirs.push(dir)
const brain = await open(dir, 'defer')
await brain.add({ data: 'deferred row', type: NounType.Document, metadata: { n: 1 } })
await brain.flush()
expect(brain.logAuthority().authority, "'defer' skips open-time adoption").toBe('tree')
const storage = (brain as unknown as {
storage: { readRawObject(p: string): Promise<unknown | null> }
}).storage
const artifact = await storage.readRawObject('_system/log-authority.json').catch(() => null)
expect(artifact, "'defer' writes no authority artifact").toBeNull()
const report = await brain.adoptLogAuthority()
expect(report.verdict, 'the explicit flip still lands on green').toBe('green')
expect(brain.logAuthority().authority).toBe('log')
const stored = (await storage.readRawObject('_system/log-authority.json')) as {
authority?: string
} | null
expect(stored?.authority, 'the explicit flip stores the artifact').toBe('log')
}, 120000)
})

View file

@ -1,22 +1,34 @@
/**
* @module tests/integration/log-authority
* @description The guarded log-authority core, end-to-end: the per-brain
* authority switch (default 'tree', stored artifact, checked at open only),
* the verification oracle (replay the fact log, diff latest per-id state
* authority switch (stored artifact, checked at open only), the
* verification oracle (replay the fact log, diff latest per-id state
* against the canonical tree, NAME every divergence by class), the guarded
* flip (refuses on red with the cure in the message; lands on green and
* engages durable-at-ack immediately), and the switch surviving reopen.
*
* THE 10.0.0 FLEET DEFAULT is ADOPT-AT-OPEN (`logAuthority: 'adopt'`): a
* fresh brain with no stored artifact runs the oracle at open, backfills
* curable divergences, and flips to log authority on green so a
* default-config brain opens ALREADY log-authoritative and durable-at-ack.
* The first two pins hold that default and its explicit opt-out
* (`logAuthority: 'defer'`, the pre-10 tree behavior). Every test below
* them that exercises the ORACLE or the EXPLICIT flip opens its brain with
* `'defer'` otherwise the open-time adoption would have pre-flipped the
* brain and pre-cured the very divergences under test.
*
* KNOWN GAPS PINNED WITH `.fails` (real findings, not test bugs see the
* comments on each): a fresh brain is NOT log-complete by construction
* today, because the VFS root is written at init as a baseline
* (generation-less) write that never gets a fact, so the oracle reports it
* as a `pre-log-record` and no fresh brain can flip without a manual
* baseline backfill. The tests that need a green oracle perform that
* backfill explicitly (an identity update of the root as the FINAL write
* final, because derived-index maintenance rewrites canonical noun records
* outside generations, so an earlier fact's after-image goes stale; see the
* module tail comment on `backfillBaseline`).
* as a `pre-log-record`. The open-time adoption (and adoptLogAuthority())
* CURES this by baseline backfill a re-commit, not construction so the
* by-construction pin stays `.fails` on a deferred brain. Tests that need
* a green oracle on a deferred brain perform that backfill explicitly (an
* identity update of the root as the FINAL write final, because
* derived-index maintenance rewrites canonical noun records outside
* generations, so an earlier fact's after-image goes stale; see the module
* tail comment on `backfillBaseline`).
*/
import { describe, it, expect, afterEach } from 'vitest'
import { mkdtempSync, rmSync } from 'node:fs'
@ -88,14 +100,24 @@ describe('log authority — the switch, the oracle, the guarded flip', () => {
const dirs: string[] = []
const brains: Brainy[] = []
const openBrain = async (dir?: string): Promise<{ brain: Brainy; dir: string }> => {
/**
* Open a brain over `dir`. Omit `logAuthority` to exercise the FLEET
* DEFAULT (adopt-at-open); pass `'defer'` for the tests that need a
* tree-authoritative brain so the oracle/explicit-flip path is actually
* the thing under test (the default would pre-flip and pre-backfill).
*/
const openBrain = async (
dir?: string,
logAuthority?: 'adopt' | 'defer'
): Promise<{ brain: Brainy; dir: string }> => {
const d = dir ?? mkdtempSync(join(tmpdir(), 'brainy-log-authority-'))
if (!dir) dirs.push(d)
const brain = new Brainy({
storage: { type: 'filesystem', path: d },
requireSubtype: false,
silent: true,
dimensions: 384
dimensions: 384,
...(logAuthority ? { logAuthority } : {})
})
brains.push(brain)
await brain.init()
@ -109,8 +131,37 @@ describe('log authority — the switch, the oracle, the guarded flip', () => {
for (const d of dirs.splice(0)) rmSync(d, { recursive: true, force: true })
})
it('DEFAULT IS TREE: a fresh brain reports tree authority, stores no artifact, and plain acks never await a log fsync', async () => {
const { brain } = await openBrain()
// THE RULED DEFAULT (10.0.0): with no config and no stored artifact, a
// fresh brain ADOPTS log authority at open — oracle green (the open-time
// baseline backfill cures the generation-0 VFS root), artifact on disk,
// durable-at-ack live from the first write.
it('DEFAULT IS ADOPT-AT-OPEN: a fresh brain opens already log-authoritative — artifact stored, plain acks await the covering log fsync', async () => {
const { brain } = await openBrain() // no logAuthority config = the fleet default
const authority = brain.logAuthority()
expect(authority.authority).toBe('log')
expect(typeof authority.flippedAt).toBe('number')
expect(authority.oracle, 'the open-time flip records its green oracle summary').toBeDefined()
const artifact = (await internals(brain)
.storage.readRawObject(AUTHORITY_ARTIFACT)
.catch(() => null)) as { authority?: string } | null
expect(artifact, 'the adoption wrote the switch artifact').not.toBeNull()
expect(artifact!.authority).toBe('log')
// The MODE assertion (not a timing one): in log authority a single-op
// ack awaits the log's covering-fsync path.
expect(internals(brain).generationStore.logDurability).toBe('at-ack')
const spy = spyEnsureSynced(brain)
await brain.add({ data: 'log mode write', type: 'document', metadata: { n: 1 } })
expect(spy.calls(), 'adopted default: add() awaits the covering fsync').toBeGreaterThanOrEqual(1)
})
// THE EXPLICIT OPT-OUT: `logAuthority: 'defer'` is the pre-10 behavior —
// tree authority, NO artifact written (a deferred posture is config, not
// stored state), and single-op acks never await a log fsync.
it("OPT-OUT ('defer'): the brain stays tree-authoritative, stores no artifact, and plain acks never await a log fsync", async () => {
const { brain } = await openBrain(undefined, 'defer')
expect(brain.logAuthority().authority).toBe('tree')
expect(brain.logAuthority().flippedAt).toBeUndefined()
@ -118,7 +169,7 @@ describe('log authority — the switch, the oracle, the guarded flip', () => {
const artifact = await internals(brain)
.storage.readRawObject(AUTHORITY_ARTIFACT)
.catch(() => null)
expect(artifact, 'no switch artifact exists before any flip').toBeNull()
expect(artifact, "'defer' writes no switch artifact").toBeNull()
// The MODE assertion (not a timing one): in tree authority a single-op
// ack must never call the log's covering-fsync path.
@ -134,10 +185,12 @@ describe('log authority — the switch, the oracle, the guarded flip', () => {
// (00000000-0000-0000-0000-000000000000) is created at init by a baseline
// write with NO generation and NO fact, yet it is enumerated by the
// canonical walk — so the oracle on a fresh brain is red with exactly one
// `pre-log-record` mismatch on the root, and adoptLogAuthority() refuses
// on every fresh brain. Verified empirically on this branch.
// `pre-log-record` mismatch on the root. The adopt-at-open default (and
// adoptLogAuthority()) CURES this by baseline backfill — a re-commit,
// which is why this pin opens with 'defer': it holds the BY-CONSTRUCTION
// intent, which the backfill masks but does not deliver.
it.fails('ORACLE INTENT: a fresh brain is log-complete by construction — verdict green with zero mismatches', async () => {
const { brain } = await openBrain()
const { brain } = await openBrain(undefined, 'defer')
await seedWrites(brain)
await brain.flush()
@ -147,7 +200,9 @@ describe('log authority — the switch, the oracle, the guarded flip', () => {
})
it('a fresh, un-backfilled brain diverges ONLY on the init-time baseline record — every user write is exactly reproduced', async () => {
const { brain } = await openBrain()
// 'defer': the adopt-at-open default would have backfilled the baseline
// already — this pin needs the brain genuinely un-backfilled.
const { brain } = await openBrain(undefined, 'defer')
await seedWrites(brain)
await brain.flush()
@ -166,7 +221,10 @@ describe('log authority — the switch, the oracle, the guarded flip', () => {
})
it('THE ORACLE GOES GREEN on a log-complete brain: adds + update + remove, every canonical row exactly reproduced', async () => {
const { brain } = await openBrain()
// 'defer' + manual backfill: the exact-count pins below (5 generations)
// depend on the log holding ONLY this test's writes — the adopt-at-open
// default would inject its own backfill generation at init.
const { brain } = await openBrain(undefined, 'defer')
await seedWrites(brain)
await backfillBaseline(brain) // final write — see the helper's contract
await brain.flush()
@ -184,7 +242,7 @@ describe('log authority — the switch, the oracle, the guarded flip', () => {
})
it('THE ORACLE NAMES pre-log records: a canonical row no fact ever recorded reports pre-log-record, by id', async () => {
const { brain } = await openBrain()
const { brain } = await openBrain(undefined, 'defer')
await seedWrites(brain)
await backfillBaseline(brain)
await brain.flush()
@ -226,7 +284,9 @@ describe('log authority — the switch, the oracle, the guarded flip', () => {
// and the flip proceeds; ONLY log-AHEAD divergences (the log claims
// state canonical denies) refuse, because no backfill can make the log
// un-claim a live row. This test stages exactly that incurable shape.
const { brain } = await openBrain()
// 'defer': the brain must still be tree-authoritative (no artifact) so
// the refusal's nothing-written pins below have meaning.
const { brain } = await openBrain(undefined, 'defer')
const { kept } = await seedWrites(brain)
await backfillBaseline(brain)
await brain.flush()
@ -254,7 +314,9 @@ describe('log authority — the switch, the oracle, the guarded flip', () => {
})
it('THE FLIP LANDS ON GREEN: the report is the receipt, the artifact is on disk, and durable-at-ack engages immediately', async () => {
const { brain } = await openBrain()
// 'defer': this pin exercises the EXPLICIT flip — the adopt-at-open
// default would have landed it before the test began.
const { brain } = await openBrain(undefined, 'defer')
await seedWrites(brain)
await backfillBaseline(brain)
await brain.flush()
@ -284,7 +346,7 @@ describe('log authority — the switch, the oracle, the guarded flip', () => {
})
it('THE SWITCH SURVIVES REOPEN: authority restored at open with no re-verification, durable-at-ack active in the new session', async () => {
const { brain, dir } = await openBrain()
const { brain, dir } = await openBrain(undefined, 'defer')
await seedWrites(brain)
await backfillBaseline(brain)
await brain.flush()
@ -292,7 +354,10 @@ describe('log authority — the switch, the oracle, the guarded flip', () => {
const flipReceipt = brain.logAuthority()
await (brain as unknown as { close: () => Promise<void> }).close()
const { brain: reopened } = await openBrain(dir)
// Reopen with 'defer' too: the restored authority below can then ONLY
// come from the stored artifact (a stored artifact always wins; had the
// default re-adopted, flippedAt/oracle would differ from the receipt).
const { brain: reopened } = await openBrain(dir, 'defer')
const restored = reopened.logAuthority()
expect(restored.authority).toBe('log')
// No re-verification happened at open: the restored record IS the stored
@ -308,7 +373,7 @@ describe('log authority — the switch, the oracle, the guarded flip', () => {
})
it('STATE-DIFFERS: canonical drift the write path never saw is named, by id', async () => {
const { brain } = await openBrain()
const { brain } = await openBrain(undefined, 'defer')
const { kept } = await seedWrites(brain)
await backfillBaseline(brain)
await brain.flush()

View file

@ -43,6 +43,13 @@ describe('transact durability barrier — entity writes fsync before the counter
})
await brain.init()
// Drain the pending tier BEFORE instrumenting: the adopt-at-open fleet
// default re-commits the init-time baseline as a buffered single-op
// generation, and transact() flushes buffered single-ops first — that
// flush's manifest sync would otherwise be recorded ahead of the
// transact's own commit point and break the first-index ordering pins.
await brain.flush()
// Instrument the real filesystem storage: record every fsync batch in order,
// and count barrier open/flush, delegating to the originals.
syncCalls = []