David Snelling
ff43de1ada
The fold checkpoint (_system/fold-checkpoint.json) is stamped strictly after a canonical-sync barrier over every live entity touched since the last stamp (syncEntityCanonical: ids → canonical paths → fsync; an absent file fsyncs its parent directory so deletes are as durable as writes). An unclean open under log authority now folds only (checkpoint, head]; the chain bootstraps at an empty brain's adoption (three-phase hooks around adoptLogAuthority) or at a brain's first whole-log fold — existing brains converge at their first crash with zero regression. Rollback restores sync immediately; abort paths feed the barrier; a failed barrier retains the old bound (bigger fold later, never a lost write). Five structural pins including boundedness itself. Also: the production-shaped write-flow gate leg (mixed traffic racing flushes, crash mid-traffic, every ack survives — from a consumer-reported gate miss), and two release-ceremony cures (tag-first push so the publish never queues behind the release commit's CI run; raw-curl npmjs shasum probe with propagation grace instead of a one-shot false divergence).
200 lines
9 KiB
TypeScript
200 lines
9 KiB
TypeScript
/**
|
||
* @module tests/integration/fold-checkpoint-bound
|
||
* @description The fold-checkpoint bound (crash recovery's log fold, bounded):
|
||
* `_system/fold-checkpoint.json` at generation G asserts every entity whose
|
||
* latest fact is ≤ G has DURABLE canonical bytes — each stamp strictly follows
|
||
* a canonical-sync barrier over every live entity touched since the last one
|
||
* (stamp-after-data). An unclean open then folds only `(G, head]` instead of
|
||
* the whole log. These pins prove the four load-bearing properties:
|
||
*
|
||
* 1. The stamp exists and tracks the committed watermark (flush + close).
|
||
* 2. The fold is genuinely BOUNDED — facts ≤ G are skipped — while facts in
|
||
* `(G, head]` are re-applied even BELOW the manifest.
|
||
* 3. A failed barrier NEVER advances the stamp (the bound can lag, growing
|
||
* a later fold — it can never overstate durability, losing a write).
|
||
* 4. A pre-checkpoint brain (the 10.0 shape) bootstraps its chain at its
|
||
* first whole-log fold; a tree-authority brain never stamps at all.
|
||
*/
|
||
import { describe, it, expect, afterEach, vi } from 'vitest'
|
||
import * as fs from 'node:fs'
|
||
import * as zlib from 'node:zlib'
|
||
import { join } from 'node:path'
|
||
import { Brainy } from '../../src/brainy.js'
|
||
import { NounType } from '../../src/types/graphTypes.js'
|
||
import {
|
||
abandonAsCrashed,
|
||
dropCanonicalNoun,
|
||
makeTempDir,
|
||
openBrain,
|
||
storeOf
|
||
} from '../helpers/durabilityKillMatrix.js'
|
||
|
||
const CHECKPOINT = join('_system', 'fold-checkpoint.json')
|
||
|
||
/** Read the fold-checkpoint artifact's generation from disk, or null. */
|
||
function readCheckpoint(dir: string): number | null {
|
||
for (const candidate of [join(dir, `${CHECKPOINT}.gz`), join(dir, CHECKPOINT)]) {
|
||
if (!fs.existsSync(candidate)) continue
|
||
const raw = fs.readFileSync(candidate)
|
||
const text = candidate.endsWith('.gz') ? zlib.gunzipSync(raw).toString('utf8') : raw.toString('utf8')
|
||
const parsed = JSON.parse(text) as { generation?: number }
|
||
return Number.isSafeInteger(parsed.generation) ? (parsed.generation as number) : null
|
||
}
|
||
return null
|
||
}
|
||
|
||
function removeArtifact(dir: string, rel: string): void {
|
||
for (const candidate of [join(dir, `${rel}.gz`), join(dir, rel)]) {
|
||
fs.rmSync(candidate, { force: true })
|
||
}
|
||
}
|
||
|
||
function committedOf(brain: Brainy): number {
|
||
return (storeOf(brain) as unknown as { committed: number }).committed
|
||
}
|
||
|
||
describe('fold-checkpoint bound — crash recovery folds (checkpoint, head], never less durability than stamped', () => {
|
||
const dirs: string[] = []
|
||
const liveBrains: Brainy[] = []
|
||
afterEach(async () => {
|
||
vi.restoreAllMocks()
|
||
for (const b of liveBrains.splice(0)) await b.close().catch(() => {})
|
||
for (const d of dirs.splice(0)) fs.rmSync(d, { recursive: true, force: true })
|
||
})
|
||
function trackDir(): string {
|
||
const dir = makeTempDir()
|
||
dirs.push(dir)
|
||
return dir
|
||
}
|
||
|
||
it('a fresh adopt brain stamps at flush and again at close — the stamp tracks the committed watermark', async () => {
|
||
const dir = trackDir()
|
||
const brain = await openBrain(dir, { logAuthority: 'adopt' })
|
||
liveBrains.push(brain)
|
||
expect(brain.logAuthority().authority).toBe('log')
|
||
|
||
await brain.add({ data: 'first', type: NounType.Document, metadata: { n: 1 } })
|
||
await brain.add({ data: 'second', type: NounType.Document, metadata: { n: 2 } })
|
||
await brain.flush()
|
||
const afterFlush = readCheckpoint(dir)
|
||
expect(afterFlush).toBe(committedOf(brain))
|
||
expect(afterFlush!).toBeGreaterThan(0)
|
||
|
||
await brain.add({ data: 'third', type: NounType.Document, metadata: { n: 3 } })
|
||
const closingCommit = liveBrains.pop()!
|
||
await closingCommit.close()
|
||
// Close flushes, so the stamp advanced with it — and the clean-shutdown
|
||
// marker it writes afterward never vouches for bytes the stamp has not.
|
||
expect(readCheckpoint(dir)).toBeGreaterThanOrEqual(afterFlush!)
|
||
}, 120000)
|
||
|
||
it('BOUNDED fold: facts ≤ checkpoint are skipped, facts in (checkpoint, head] are re-applied even below the manifest; a failed barrier retains the old bound', async () => {
|
||
const dir = trackDir()
|
||
const brain = await openBrain(dir, { logAuthority: 'adopt' })
|
||
liveBrains.push(brain)
|
||
|
||
// Window 1 — flushed and stamped: the checkpoint's covered past.
|
||
const idA = await brain.add({ data: 'covered by the stamp', type: NounType.Document, metadata: { w: 1 } })
|
||
await brain.flush()
|
||
const checkpoint1 = readCheckpoint(dir)
|
||
expect(checkpoint1).toBe(committedOf(brain))
|
||
|
||
// Window 2 — committed BELOW a new manifest but with the checkpoint stamp
|
||
// FAILING: the barrier throws once, so the manifest advances while the
|
||
// stamp stays at checkpoint1 (pin 3: a failed barrier never advances it).
|
||
const storage = (brain as unknown as {
|
||
storage: { syncEntityCanonical(n: string[], v: string[]): Promise<void> }
|
||
}).storage
|
||
const realBarrier = storage.syncEntityCanonical.bind(storage)
|
||
let failedOnce = false
|
||
vi.spyOn(storage, 'syncEntityCanonical').mockImplementation(async (n: string[], v: string[]) => {
|
||
if (!failedOnce) {
|
||
failedOnce = true
|
||
throw new Error('injected barrier failure (device hiccup)')
|
||
}
|
||
return realBarrier(n, v)
|
||
})
|
||
const idB = await brain.add({ data: 'below manifest, above checkpoint', type: NounType.Document, metadata: { w: 2 } })
|
||
await brain.flush()
|
||
expect(failedOnce).toBe(true)
|
||
expect(readCheckpoint(dir)).toBe(checkpoint1) // stamp did NOT advance
|
||
expect(committedOf(brain)).toBeGreaterThan(checkpoint1!) // manifest DID
|
||
|
||
// Crash. Vaporize BOTH canonical records: idB's fact lives in
|
||
// (checkpoint, manifest] — the bounded fold MUST restore it; idA's fact
|
||
// is ≤ checkpoint — the fold must SKIP it (its loss here is synthetic:
|
||
// the stamp's barrier fsynced it, a power cut cannot take it, and the
|
||
// skip is exactly what makes the fold bounded instead of whole-log).
|
||
await abandonAsCrashed(liveBrains.pop()!)
|
||
dropCanonicalNoun(dir, idA)
|
||
dropCanonicalNoun(dir, idB)
|
||
|
||
const reopened = await openBrain(dir, { logAuthority: 'adopt' })
|
||
liveBrains.push(reopened)
|
||
const restoredB = await reopened.get(idB)
|
||
expect(restoredB, 'a fact above the checkpoint is re-applied even below the manifest').not.toBeNull()
|
||
const skippedA = await reopened.get(idA)
|
||
expect(skippedA, 'a fact at-or-below the checkpoint is outside the fold — the bound is real').toBeNull()
|
||
// And recovery re-stamped at its new committed watermark.
|
||
expect(readCheckpoint(dir)).toBe(committedOf(reopened))
|
||
}, 120000)
|
||
|
||
it('a pre-checkpoint brain (the 10.0 shape) folds the WHOLE log once, then its chain is established', async () => {
|
||
const dir = trackDir()
|
||
const brain = await openBrain(dir, { logAuthority: 'adopt' })
|
||
liveBrains.push(brain)
|
||
const idA = await brain.add({ data: 'ten-point-oh resident', type: NounType.Document, metadata: { era: '10.0' } })
|
||
await brain.flush()
|
||
await liveBrains.pop()!.close()
|
||
|
||
// Rewind the brain to the 10.0 shape: no checkpoint artifact, and an
|
||
// unclean shutdown (marker gone) — exactly what an existing fleet brain
|
||
// looks like at its first crash under 10.1.
|
||
removeArtifact(dir, CHECKPOINT)
|
||
removeArtifact(dir, join('_system', 'clean-shutdown.json'))
|
||
dropCanonicalNoun(dir, idA)
|
||
|
||
const reopened = await openBrain(dir, { logAuthority: 'adopt' })
|
||
liveBrains.push(reopened)
|
||
expect(await reopened.get(idA), 'no checkpoint ⇒ whole-log fold ⇒ every acked write restored').not.toBeNull()
|
||
const stamped = readCheckpoint(dir)
|
||
expect(stamped, 'the first whole-log fold is the chain’s base case — it stamps').toBe(committedOf(reopened))
|
||
}, 120000)
|
||
|
||
it('a tree-authority brain never stamps a checkpoint', async () => {
|
||
const dir = trackDir()
|
||
const brain = await openBrain(dir, { logAuthority: 'defer' })
|
||
liveBrains.push(brain)
|
||
expect(brain.logAuthority().authority).not.toBe('log')
|
||
await brain.add({ data: 'tree resident', type: NounType.Document, metadata: { n: 1 } })
|
||
await brain.flush()
|
||
await liveBrains.pop()!.close()
|
||
expect(readCheckpoint(dir)).toBeNull()
|
||
}, 120000)
|
||
|
||
it('a delete rides the barrier: the tombstoned id is in the synced set and the stamp advances past it', async () => {
|
||
const dir = trackDir()
|
||
const brain = await openBrain(dir, { logAuthority: 'adopt' })
|
||
liveBrains.push(brain)
|
||
const id = await brain.add({ data: 'short-lived', type: NounType.Document, metadata: { n: 1 } })
|
||
await brain.flush()
|
||
|
||
const storage = (brain as unknown as {
|
||
storage: { syncEntityCanonical(n: string[], v: string[]): Promise<void> }
|
||
}).storage
|
||
const seen: string[][] = []
|
||
const realBarrier = storage.syncEntityCanonical.bind(storage)
|
||
vi.spyOn(storage, 'syncEntityCanonical').mockImplementation(async (n: string[], v: string[]) => {
|
||
seen.push([...n])
|
||
return realBarrier(n, v)
|
||
})
|
||
|
||
await brain.remove(id)
|
||
await brain.flush()
|
||
expect(
|
||
seen.some((nouns) => nouns.includes(id)),
|
||
'the deleted id must reach the canonical barrier (absence is durable state too)'
|
||
).toBe(true)
|
||
expect(readCheckpoint(dir)).toBe(committedOf(brain))
|
||
}, 120000)
|
||
})
|