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.
This commit is contained in:
parent
67c606be69
commit
214c98b4d5
23 changed files with 833 additions and 154 deletions
|
|
@ -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 })
|
||||
|
|
|
|||
|
|
@ -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`.
|
||||
|
|
|
|||
|
|
@ -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 = (
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
})
|
||||
|
|
|
|||
|
|
@ -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()
|
||||
|
|
|
|||
|
|
@ -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 = []
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue