From 34841074629f8c657eaa8e2bc1ae66c36fd63cbb Mon Sep 17 00:00:00 2001 From: David Snelling Date: Mon, 10 Aug 2026 09:29:06 -0700 Subject: [PATCH] =?UTF-8?q?feat(log):=20fact-log=20format=20v2=20codec=20?= =?UTF-8?q?=E2=80=94=20record=20envelope,=20type=20registry,=20genesis,=20?= =?UTF-8?q?sector=20seals;=20fault-injection=20shim?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The two-implementation contract surface as one pure module (no I/O): segment header v2 (formatVersion 2 + sealSize in the reserved bytes), per-record [type u8, version u8] envelope killing the unknown-kind misclassification trap, the 12-type registry (after-images with minted ints, tombstones, batch.meta, embed.pending/landed, blob.manifest, projection.note, bootstrap.baseline, log.genesis with id-space width and TYPED width-mismatch refusal), vectorLeg inline|{sameAsGeneration} with writer-enforced single-hop, sector-sealed groups with pad frames, torn-tail discipline, and GOLDEN BYTE VECTORS pinned so a second (native) reader implementation can conform byte-for-byte. 50 format pins + a fault-injecting storage wrapper (tear/drop-sync/fail-append) with 13 self-tests. v1 segments remain readable; nothing writes v2 yet — the live-format cutover is its own commit. --- src/db/factLogFormat.ts | 1220 ++++++++++++++++++++ src/db/faultInjectionStorage.ts | 164 +++ tests/unit/db/factLogFormat.test.ts | 745 ++++++++++++ tests/unit/db/fault-injection-shim.test.ts | 231 ++++ 4 files changed, 2360 insertions(+) create mode 100644 src/db/factLogFormat.ts create mode 100644 src/db/faultInjectionStorage.ts create mode 100644 tests/unit/db/factLogFormat.test.ts create mode 100644 tests/unit/db/fault-injection-shim.test.ts diff --git a/src/db/factLogFormat.ts b/src/db/factLogFormat.ts new file mode 100644 index 00000000..0ca86410 --- /dev/null +++ b/src/db/factLogFormat.ts @@ -0,0 +1,1220 @@ +/** + * @module db/factLogFormat + * @description Fact-log format v2 (record envelope + sector seals) — the pure + * encode/decode functions for the versioned on-disk fact-log byte format. + * No I/O and no storage dependencies live here: this module is the REFERENCE + * IMPLEMENTATION of the format, and a second (native) reader parses these + * exact bytes. Byte-level behavior is a two-implementation contract — bytes + * change only behind a format-version bump, never in place. + * + * ## Segment header (32 bytes, both versions) + * + * magic "BFACTS\0\0" (8B) | formatVersion:u32 LE | firstGeneration:u64 LE | + * v1: reserved 12B (ZEROED, verified) + * v2: sealSize:u16 LE at offset +20 | reserved 10B (ZEROED, verified) + * + * V1 segments remain readable forever via the v1 decode path — never rewritten. + * + * ## Frame (unchanged from v1) + * + * payloadLength:u32 LE | crc32c:u32 LE (of payload) | msgpack payload + * + * A bad length (overruns the buffer) or CRC mismatch is a TORN TAIL: it + * terminates the scan; everything before it is intact. + * + * ## V2 fact payload (msgpack, positional — same 5 positions as v1, but + * position 2 is `records`, not v1's `ops`) + * + * fact := [ generation:u64, timestamp:u64, records, meta|nil, blobHashes|nil ] + * record := [ recordType:u8, recordVersion:u8, ...type-specific fields ] + * + * Record type registry (all recordVersion = 1): + * + * 0 pad [] — length-only filler; readers SKIP; crc-covered + * 1 noun.afterImage [id bin16, entityInt u64, metadata, vectorLeg] + * 2 noun.tombstone [id bin16] + * 3 verb.afterImage [id bin16, verbInt u64, metadata, vectorLeg, + * verb str, sourceId bin16, sourceInt u64, + * targetId bin16, targetInt u64] + * 4 verb.tombstone [id bin16] + * 5 batch.meta [metaMap] — at most ONE per fact + * 6 embed.pending [id bin16, enqueuedAt u64] + * 7 embed.landed [id bin16, vector — INLINE float[] only] + * 8 blob.manifest [hash bin32, size u64, mimeType str, refOp u8 (0=add,1=release)] + * 9 projection.note [noteMap] — opaque map, reserved consumer + * 10 bootstrap.baseline [id bin16, kind u8 (0=noun,1=verb), metadata, vectorLeg] + * 11 log.genesis [idSpaceWidth u8 (32|64), brainId bin16, createdAt u64] + * — MUST be the first record of the first fact in a + * v2 log (first-record-of-fact is enforced here; the + * first-fact-of-log half belongs to the log layer) + * + * vectorLeg := float[] | ['ref', sameAsGeneration u64] | nil + * + * Integer wire discipline (reference encoder): every field declared u64 above + * rides as msgpack uint64 (0xcf, fixed 8 bytes); u8 fields ride as minimal + * msgpack uints (positive fixint). The decoder is liberal and accepts any + * msgpack unsigned-integer width for these fields. `entityInt`/`verbInt`/ + * `sourceInt`/`targetInt` surface as `bigint` (full u64 range); scalar + * counters and timestamps surface as `number` and refuse values beyond + * `Number.MAX_SAFE_INTEGER` loudly. + * + * ## Decoder law + * + * An unknown recordType, or a recordVersion newer than this reader knows, + * throws {@link UnknownLogRecordError} — NEVER skip-and-continue (type 0 pad + * is the sole exception: skipped by definition). A log.genesis whose + * idSpaceWidth disagrees with the caller's expected width throws + * {@link GenesisWidthMismatchError} naming both widths. + * + * ## Sector seals + * + * A "sealed group" is one or more frames padded to the next `sealSize` + * boundary with ONE pad frame — a frame whose fact is + * `[0, 0, [[0, 1, filler?]], nil, nil]` (generation 0 marks filler; real + * facts start at 1). Pad frames are invisible to readers. When the gap to the + * boundary is smaller than the smallest constructible pad frame, the group is + * padded through to the boundary AFTER next (one extra sealSize) — chosen as + * the simpler correct approach over rewriting the previous frame's payload: + * input frames stay byte-immutable, alignment still holds, and the cost is at + * most one sector on a rare (<1%) size coincidence. + */ +import { encode as msgpackEncode, decode as msgpackDecode } from '@msgpack/msgpack' +import { crc32c } from '../utils/crc32c.js' +import type { CommitFact } from './factLog.js' + +// --------------------------------------------------------------------------- +// Constants +// --------------------------------------------------------------------------- + +/** Segment magic: ASCII "BFACTS" + two NULs (shared by v1 and v2 headers). */ +export const FACT_SEGMENT_MAGIC: Uint8Array = new Uint8Array([ + 0x42, 0x46, 0x41, 0x43, 0x54, 0x53, 0x00, 0x00 +]) + +/** Segment format version 1 (ops-shaped facts, 12 zeroed reserved bytes). */ +export const FACT_LOG_FORMAT_V1 = 1 + +/** Segment format version 2 (record envelope + sector seals). */ +export const FACT_LOG_FORMAT_V2 = 2 + +/** Segment header size in bytes (identical for v1 and v2). */ +export const SEGMENT_HEADER_BYTES = 32 + +/** Frame prefix size: payloadLength(4) + crc32c(4). */ +export const FRAME_PREFIX_BYTES = 8 + +/** Default sector-seal size (bytes) when the caller does not probe a device. */ +export const DEFAULT_SEAL_SIZE = 4096 + +/** The record version this reader knows (all registry types are version 1). */ +export const LOG_RECORD_VERSION = 1 + +/** The v2 record-type registry — wire codes for every record type. */ +export const LOG_RECORD_TYPES = { + PAD: 0, + NOUN_AFTER_IMAGE: 1, + NOUN_TOMBSTONE: 2, + VERB_AFTER_IMAGE: 3, + VERB_TOMBSTONE: 4, + BATCH_META: 5, + EMBED_PENDING: 6, + EMBED_LANDED: 7, + BLOB_MANIFEST: 8, + PROJECTION_NOTE: 9, + BOOTSTRAP_BASELINE: 10, + LOG_GENESIS: 11 +} as const + +/** A wire code from the v2 record-type registry. */ +export type LogRecordTypeCode = (typeof LOG_RECORD_TYPES)[keyof typeof LOG_RECORD_TYPES] + +const U64_MAX = (1n << 64n) - 1n + +// --------------------------------------------------------------------------- +// Errors +// --------------------------------------------------------------------------- + +/** + * A record whose type or version this reader does not know. Thrown — never + * skipped — so an old reader can NEVER silently drop data written by a newer + * writer. Carries the offending type/version for programmatic handling. + */ +export class UnknownLogRecordError extends Error { + /** The wire recordType that was not understood. */ + public readonly recordType: number + /** The wire recordVersion that was not understood. */ + public readonly recordVersion: number + + constructor(recordType: number, recordVersion: number, message: string) { + super(message) + this.name = 'UnknownLogRecordError' + this.recordType = recordType + this.recordVersion = recordVersion + } +} + +/** + * A log.genesis record whose id-space width disagrees with the width the + * caller expects. Decoding across id-space widths is refused loudly — the + * error names both widths. + */ +export class GenesisWidthMismatchError extends Error { + /** The width the caller expected (32 or 64). */ + public readonly expectedWidth: number + /** The width the genesis record declares (32 or 64). */ + public readonly actualWidth: number + + constructor(expectedWidth: number, actualWidth: number) { + super( + `fact log v2: log.genesis declares a ${actualWidth}-bit id space but this reader ` + + `expected ${expectedWidth}-bit — refusing to decode across id-space widths` + ) + this.name = 'GenesisWidthMismatchError' + this.expectedWidth = expectedWidth + this.actualWidth = actualWidth + } +} + +// --------------------------------------------------------------------------- +// Record + fact types (the TS surface of the wire registry) +// --------------------------------------------------------------------------- + +/** A vector reference: "same vector as the one generation N carried inline". */ +export interface VectorRef { + /** The generation whose record carried the INLINE vector (single-hop only). */ + sameAsGeneration: number +} + +/** A record's vector leg: inline floats, a single-hop ref, or none. */ +export type VectorLeg = number[] | VectorRef | null + +/** Type 1 — the after-image of a noun: what the entity BECAME. */ +export interface NounAfterImageRecord { + type: 'noun.afterImage' + id: string + /** The entity's u64 integer handle (full range — hence bigint). */ + entityInt: bigint + metadata: unknown + vectorLeg: VectorLeg +} + +/** Type 2 — a body-less noun tombstone: the entity was removed. */ +export interface NounTombstoneRecord { + type: 'noun.tombstone' + id: string +} + +/** Type 3 — the after-image of a verb (relationship), endpoints included. */ +export interface VerbAfterImageRecord { + type: 'verb.afterImage' + id: string + /** The verb's u64 integer handle (full range — hence bigint). */ + verbInt: bigint + metadata: unknown + vectorLeg: VectorLeg + /** The verb name (relationship type). */ + verb: string + sourceId: string + sourceInt: bigint + targetId: string + targetInt: bigint +} + +/** Type 4 — a body-less verb tombstone: the relationship was removed. */ +export interface VerbTombstoneRecord { + type: 'verb.tombstone' + id: string +} + +/** Type 5 — batch-level metadata; at most ONE per fact. */ +export interface BatchMetaRecord { + type: 'batch.meta' + meta: Record +} + +/** Type 6 — an embedding was enqueued for the id (vector not yet available). */ +export interface EmbedPendingRecord { + type: 'embed.pending' + id: string + /** Enqueue time (epoch ms). */ + enqueuedAt: number +} + +/** Type 7 — a deferred embedding landed; carries the INLINE vector only. */ +export interface EmbedLandedRecord { + type: 'embed.landed' + id: string + /** The landed vector — inline floats only; refs are not allowed here. */ + vector: number[] +} + +/** Type 8 — a blob reference-count event (content-addressed by hash). */ +export interface BlobManifestRecord { + type: 'blob.manifest' + /** The blob's content hash — 64 lowercase hex chars (bin32 on the wire). */ + hash: string + size: number + mimeType: string + refOp: 'add' | 'release' +} + +/** Type 9 — an opaque note for a reserved projection consumer. */ +export interface ProjectionNoteRecord { + type: 'projection.note' + note: Record +} + +/** Type 10 — a bootstrap baseline row (initial-load after-image). */ +export interface BootstrapBaselineRecord { + type: 'bootstrap.baseline' + id: string + kind: 'noun' | 'verb' + metadata: unknown + vectorLeg: VectorLeg +} + +/** Type 11 — the log's birth certificate; first record of the first fact. */ +export interface LogGenesisRecord { + type: 'log.genesis' + /** The integer-handle width this log's records use. */ + idSpaceWidth: 32 | 64 + brainId: string + /** Creation time (epoch ms). */ + createdAt: number +} + +/** Any decodable v2 record (pads are skipped, never surfaced). */ +export type LogRecord = + | NounAfterImageRecord + | NounTombstoneRecord + | VerbAfterImageRecord + | VerbTombstoneRecord + | BatchMetaRecord + | EmbedPendingRecord + | EmbedLandedRecord + | BlobManifestRecord + | ProjectionNoteRecord + | BootstrapBaselineRecord + | LogGenesisRecord + +/** One committed generation in v2 shape: a record envelope, not v1 ops. */ +export interface CommitFactV2 { + generation: number + timestamp: number + records: LogRecord[] + meta?: Record + blobHashes?: string[] +} + +/** A parsed segment header (v1 has no sealSize; v2 always carries one). */ +export interface SegmentHeader { + formatVersion: number + firstGeneration: number + /** Sector-seal size (v2 only) — `undefined` on v1 headers. */ + sealSize?: number +} + +/** Options for {@link encodeFactV2}. */ +export interface EncodeFactV2Options { + /** + * Single-hop validator for vector refs: the set (or predicate) of + * generations whose records carried an INLINE vector. REQUIRED whenever any + * record carries a `VectorRef` — encoding an unverifiable ref is refused. + */ + inlineVectorGenerations?: Set | ((generation: number) => boolean) +} + +/** Options for the v2 decode path of {@link decodeFact}. */ +export interface DecodeFactV2Options { + /** + * The id-space width the caller expects. When set and the fact carries a + * log.genesis record, a disagreeing width throws + * {@link GenesisWidthMismatchError}. + */ + expectedIdSpaceWidth?: 32 | 64 +} + +/** The result of decoding a frame group: intact facts + valid byte length. */ +export interface DecodedFrameGroup { + facts: CommitFactV2[] + /** Byte length of the intact prefix (whole frames that decoded cleanly). */ + validBytes: number +} + +// --------------------------------------------------------------------------- +// msgpack wire helpers +// --------------------------------------------------------------------------- + +/** + * The v2 codec: `useBigInt64` makes bigints ride as fixed 8-byte uint64/int64 + * (the u64 wire discipline) while JS numbers keep exact-value round-trips + * (integers ≤ 32-bit ride minimal; larger numbers ride float64, which holds + * every safe integer exactly). + */ +const enc = (value: unknown): Uint8Array => msgpackEncode(value, { useBigInt64: true }) +const dec = (bytes: Uint8Array): unknown => msgpackDecode(bytes, { useBigInt64: true }) + +/** Coerce an encode-side u64 field to bigint, refusing out-of-range values. */ +function toWireU64(value: number | bigint, field: string): bigint { + let big: bigint + if (typeof value === 'bigint') { + big = value + } else if (Number.isSafeInteger(value)) { + big = BigInt(value) + } else { + throw new Error(`fact log v2: ${field} must be a safe integer or bigint; got ${value}`) + } + if (big < 0n || big > U64_MAX) { + throw new Error(`fact log v2: ${field} is out of u64 range: ${big}`) + } + return big +} + +/** Decode-side u64 → bigint (liberal: accepts any msgpack uint width). */ +function wireToBigint(value: unknown, field: string): bigint { + if (typeof value === 'bigint') { + if (value < 0n || value > U64_MAX) { + throw new Error(`fact log v2: ${field} is out of u64 range: ${value}`) + } + return value + } + if (typeof value === 'number' && Number.isSafeInteger(value) && value >= 0) { + return BigInt(value) + } + throw new Error(`fact log v2: ${field} is not an unsigned integer`) +} + +/** Decode-side u64 → number, refusing values beyond safe-integer range. */ +function wireToNumber(value: unknown, field: string): number { + const big = wireToBigint(value, field) + if (big > BigInt(Number.MAX_SAFE_INTEGER)) { + throw new Error(`fact log v2: ${field} ${big} exceeds Number.MAX_SAFE_INTEGER`) + } + return Number(big) +} + +/** Decode-side u8 (record types, kinds, flags). */ +function wireToU8(value: unknown, field: string): number { + const n = typeof value === 'bigint' ? Number(value) : value + if (typeof n !== 'number' || !Number.isInteger(n) || n < 0 || n > 255) { + throw new Error(`fact log v2: ${field} is not a u8`) + } + return n +} + +/** uuid string → 16 raw bytes (bin16 on the wire). */ +function uuidToBytes(id: string): Uint8Array { + const hex = id.replace(/-/g, '') + if (hex.length !== 32 || /[^0-9a-fA-F]/.test(hex)) { + throw new Error(`fact log v2: id is not a uuid: ${id}`) + } + const bytes = new Uint8Array(16) + for (let i = 0; i < 16; i++) { + bytes[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16) + } + return bytes +} + +/** 16 raw bytes → canonical lowercase uuid string. */ +function bytesToUuid(bytes: unknown, field: string): string { + if (!(bytes instanceof Uint8Array) || bytes.length !== 16) { + throw new Error(`fact log v2: ${field} is not a bin16 id`) + } + let hex = '' + for (let i = 0; i < 16; i++) hex += bytes[i].toString(16).padStart(2, '0') + return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}` +} + +/** 64-hex-char content hash → 32 raw bytes (bin32 on the wire). */ +function hashToBytes(hash: string): Uint8Array { + if (typeof hash !== 'string' || !/^[0-9a-fA-F]{64}$/.test(hash)) { + throw new Error(`fact log v2: blob hash must be 64 hex chars; got ${String(hash).slice(0, 80)}`) + } + const bytes = new Uint8Array(32) + for (let i = 0; i < 32; i++) { + bytes[i] = parseInt(hash.slice(i * 2, i * 2 + 2), 16) + } + return bytes +} + +/** 32 raw bytes → 64-char lowercase hex content hash. */ +function bytesToHash(bytes: unknown): string { + if (!(bytes instanceof Uint8Array) || bytes.length !== 32) { + throw new Error('fact log v2: blob hash is not bin32') + } + let hex = '' + for (let i = 0; i < 32; i++) hex += bytes[i].toString(16).padStart(2, '0') + return hex +} + +/** True for a plain map object (not null/array/binary). */ +function isPlainMap(value: unknown): value is Record { + return ( + typeof value === 'object' && + value !== null && + !Array.isArray(value) && + !(value instanceof Uint8Array) + ) +} + +// --------------------------------------------------------------------------- +// Segment header (v1 read + v2 read/write) +// --------------------------------------------------------------------------- + +/** + * Build a v2 segment header: magic + formatVersion 2 + firstGeneration u64 LE + * + sealSize u16 LE at offset +20. The remaining 10 reserved bytes stay zero + * and are verified by every reader. + * + * @param firstGeneration - The first generation this segment will hold. + * @param sealSize - The sector-seal size groups in this segment align to + * (device atomic-write probing is the caller's business; default 4096). + */ +export function encodeSegmentHeaderV2( + firstGeneration: number, + sealSize: number = DEFAULT_SEAL_SIZE +): Uint8Array { + if (!Number.isSafeInteger(firstGeneration) || firstGeneration < 0) { + throw new Error(`fact log v2: firstGeneration must be a non-negative integer; got ${firstGeneration}`) + } + assertValidSealSize(sealSize) + const header = new Uint8Array(SEGMENT_HEADER_BYTES) + header.set(FACT_SEGMENT_MAGIC, 0) + const view = new DataView(header.buffer) + view.setUint32(8, FACT_LOG_FORMAT_V2, true) + view.setBigUint64(12, BigInt(firstGeneration), true) + view.setUint16(20, sealSize, true) + // bytes 22..31 stay zero (reserved, verified) + return header +} + +/** + * Parse a segment header — reads BOTH v1 (version 1, twelve zeroed reserved + * bytes, no sealSize) and v2 (version 2, sealSize u16 LE at +20, ten zeroed + * reserved bytes). Bad magic, non-zero reserved bytes, or an unknown version + * throw loudly; nothing is guessed. + * + * @param bytes - At least the first {@link SEGMENT_HEADER_BYTES} of a segment. + * @returns The parsed header; `sealSize` is `undefined` for v1 headers. + */ +export function parseSegmentHeader(bytes: Uint8Array): SegmentHeader { + if (bytes.length < SEGMENT_HEADER_BYTES) { + throw new Error( + `fact log: segment header needs ${SEGMENT_HEADER_BYTES} bytes; got ${bytes.length}` + ) + } + for (let i = 0; i < FACT_SEGMENT_MAGIC.length; i++) { + if (bytes[i] !== FACT_SEGMENT_MAGIC[i]) { + throw new Error('fact log: bad magic — not a fact segment') + } + } + const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength) + const formatVersion = view.getUint32(8, true) + const firstGenerationBig = view.getBigUint64(12, true) + if (firstGenerationBig > BigInt(Number.MAX_SAFE_INTEGER)) { + throw new Error(`fact log: firstGeneration ${firstGenerationBig} exceeds Number.MAX_SAFE_INTEGER`) + } + const firstGeneration = Number(firstGenerationBig) + + if (formatVersion === FACT_LOG_FORMAT_V1) { + assertReservedZero(bytes, 20) + return { formatVersion, firstGeneration } + } + if (formatVersion === FACT_LOG_FORMAT_V2) { + const sealSize = view.getUint16(20, true) + assertReservedZero(bytes, 22) + return { formatVersion, firstGeneration, sealSize } + } + throw new Error( + `fact log: segment formatVersion ${formatVersion}; this build reads 1 and 2 — ` + + `a newer reader is required` + ) +} + +/** Verify header bytes [from, 32) are zero — anything else is unverifiable. */ +function assertReservedZero(bytes: Uint8Array, from: number): void { + for (let i = from; i < SEGMENT_HEADER_BYTES; i++) { + if (bytes[i] !== 0) { + throw new Error('fact log: non-zero reserved header bytes — unverifiable') + } + } +} + +/** Refuse seal sizes the header cannot carry or a pad frame cannot fill. */ +function assertValidSealSize(sealSize: number): void { + if (!Number.isInteger(sealSize) || sealSize < 64 || sealSize > 0xffff) { + throw new Error( + `fact log v2: sealSize must be an integer in [64, 65535]; got ${sealSize}` + ) + } +} + +// --------------------------------------------------------------------------- +// Frames +// --------------------------------------------------------------------------- + +/** Wrap a msgpack payload in the frame envelope (length + crc32c + payload). */ +function buildFrame(payload: Uint8Array): Uint8Array { + 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) + return frame +} + +/** + * Verify a complete frame (exact length, CRC) and return its msgpack payload + * (a view into the frame — copy if you outlive the frame). The bridge between + * frame-level producers ({@link encodeFactV2}, {@link sealGroup}) and the + * payload-level {@link decodeFact}. + */ +export function framePayload(frame: Uint8Array): Uint8Array { + if (frame.length < FRAME_PREFIX_BYTES) { + throw new Error(`fact log: frame shorter than its ${FRAME_PREFIX_BYTES}-byte prefix`) + } + const view = new DataView(frame.buffer, frame.byteOffset, frame.byteLength) + const length = view.getUint32(0, true) + if (FRAME_PREFIX_BYTES + length !== frame.length) { + throw new Error( + `fact log: frame declares ${length} payload bytes but carries ${frame.length - FRAME_PREFIX_BYTES}` + ) + } + const payload = frame.subarray(FRAME_PREFIX_BYTES) + const expectedCrc = view.getUint32(4, true) + if (crc32c(payload) !== expectedCrc) { + throw new Error('fact log: frame payload fails its crc32c') + } + return payload +} + +// --------------------------------------------------------------------------- +// vectorLeg encode/decode +// --------------------------------------------------------------------------- + +/** Encode a vector leg; refs must pass the single-hop validator. */ +function encodeVectorLeg( + leg: VectorLeg | undefined, + options: EncodeFactV2Options | undefined, + context: string +): unknown { + if (leg === null || leg === undefined) return null + if (Array.isArray(leg)) { + for (const value of leg) { + if (typeof value !== 'number') { + throw new Error(`fact log v2: ${context} inline vector has a non-number element`) + } + } + return leg + } + if (isPlainMap(leg) && typeof (leg as VectorRef).sameAsGeneration === 'number') { + const target = (leg as VectorRef).sameAsGeneration + const validator = options?.inlineVectorGenerations + if (!validator) { + throw new Error( + `fact log v2: ${context} carries a vector ref to generation ${target} but no ` + + `single-hop validator was provided — refusing to encode an unverifiable ref` + ) + } + const targetIsInline = typeof validator === 'function' ? validator(target) : validator.has(target) + if (!targetIsInline) { + throw new Error( + `fact log v2: ${context} vector ref targets generation ${target}, which did not ` + + `carry an inline vector — refs must be single-hop` + ) + } + return ['ref', toWireU64(target, `${context} sameAsGeneration`)] + } + throw new Error(`fact log v2: ${context} has a malformed vector leg`) +} + +/** Decode a vector leg: floats, a single-hop ref, or null. */ +function decodeVectorLeg(wire: unknown, context: string): VectorLeg { + if (wire === null || wire === undefined) return null + if (Array.isArray(wire)) { + if (wire.length === 2 && wire[0] === 'ref') { + return { sameAsGeneration: wireToNumber(wire[1], `${context} sameAsGeneration`) } + } + return wire.map((value, i) => { + if (typeof value === 'number') return value + if (typeof value === 'bigint') return Number(value) + throw new Error(`fact log v2: ${context} vector element ${i} is not a number`) + }) + } + throw new Error(`fact log v2: ${context} has a malformed vector leg`) +} + +// --------------------------------------------------------------------------- +// Record encode/decode +// --------------------------------------------------------------------------- + +/** Encode one record into its positional wire array. */ +function encodeRecord(record: LogRecord, options: EncodeFactV2Options | undefined): unknown[] { + const T = LOG_RECORD_TYPES + const V = LOG_RECORD_VERSION + switch (record.type) { + case 'noun.afterImage': + return [ + T.NOUN_AFTER_IMAGE, + V, + uuidToBytes(record.id), + toWireU64(record.entityInt, 'entityInt'), + record.metadata ?? null, + encodeVectorLeg(record.vectorLeg, options, `noun.afterImage ${record.id}`) + ] + case 'noun.tombstone': + return [T.NOUN_TOMBSTONE, V, uuidToBytes(record.id)] + case 'verb.afterImage': { + if (typeof record.verb !== 'string' || record.verb.length === 0) { + throw new Error(`fact log v2: verb.afterImage ${record.id} needs a non-empty verb name`) + } + return [ + T.VERB_AFTER_IMAGE, + V, + uuidToBytes(record.id), + toWireU64(record.verbInt, 'verbInt'), + record.metadata ?? null, + encodeVectorLeg(record.vectorLeg, options, `verb.afterImage ${record.id}`), + record.verb, + uuidToBytes(record.sourceId), + toWireU64(record.sourceInt, 'sourceInt'), + uuidToBytes(record.targetId), + toWireU64(record.targetInt, 'targetInt') + ] + } + case 'verb.tombstone': + return [T.VERB_TOMBSTONE, V, uuidToBytes(record.id)] + case 'batch.meta': + if (!isPlainMap(record.meta)) { + throw new Error('fact log v2: batch.meta requires a map') + } + return [T.BATCH_META, V, record.meta] + case 'embed.pending': + return [ + T.EMBED_PENDING, + V, + uuidToBytes(record.id), + toWireU64(record.enqueuedAt, 'enqueuedAt') + ] + case 'embed.landed': { + if (!Array.isArray(record.vector) || record.vector.some((v) => typeof v !== 'number')) { + throw new Error( + `fact log v2: embed.landed ${record.id} carries an INLINE float vector only — ` + + `refs and nil are not allowed here` + ) + } + return [T.EMBED_LANDED, V, uuidToBytes(record.id), record.vector] + } + case 'blob.manifest': { + if (typeof record.mimeType !== 'string') { + throw new Error('fact log v2: blob.manifest mimeType must be a string') + } + if (record.refOp !== 'add' && record.refOp !== 'release') { + throw new Error(`fact log v2: blob.manifest refOp must be 'add' or 'release'`) + } + return [ + T.BLOB_MANIFEST, + V, + hashToBytes(record.hash), + toWireU64(record.size, 'blob size'), + record.mimeType, + record.refOp === 'add' ? 0 : 1 + ] + } + case 'projection.note': + if (!isPlainMap(record.note)) { + throw new Error('fact log v2: projection.note requires a map') + } + return [T.PROJECTION_NOTE, V, record.note] + case 'bootstrap.baseline': { + if (record.kind !== 'noun' && record.kind !== 'verb') { + throw new Error(`fact log v2: bootstrap.baseline kind must be 'noun' or 'verb'`) + } + return [ + T.BOOTSTRAP_BASELINE, + V, + uuidToBytes(record.id), + record.kind === 'noun' ? 0 : 1, + record.metadata ?? null, + encodeVectorLeg(record.vectorLeg, options, `bootstrap.baseline ${record.id}`) + ] + } + case 'log.genesis': { + if (record.idSpaceWidth !== 32 && record.idSpaceWidth !== 64) { + throw new Error( + `fact log v2: log.genesis idSpaceWidth must be 32 or 64; got ${record.idSpaceWidth}` + ) + } + return [ + T.LOG_GENESIS, + V, + record.idSpaceWidth, + uuidToBytes(record.brainId), + toWireU64(record.createdAt, 'createdAt') + ] + } + default: { + // Pads are the sealer's business ({@link sealGroup}); anything else + // here is an unencodable record — refuse instead of writing bytes a + // reader would have to guess about. + const unknown = record as { type?: unknown } + throw new Error(`fact log v2: cannot encode record type ${String(unknown.type)}`) + } + } +} + +/** Exact wire arity per record type (envelope of 2 + type-specific fields). */ +const RECORD_ARITY: Record = { + [LOG_RECORD_TYPES.NOUN_AFTER_IMAGE]: 6, + [LOG_RECORD_TYPES.NOUN_TOMBSTONE]: 3, + [LOG_RECORD_TYPES.VERB_AFTER_IMAGE]: 11, + [LOG_RECORD_TYPES.VERB_TOMBSTONE]: 3, + [LOG_RECORD_TYPES.BATCH_META]: 3, + [LOG_RECORD_TYPES.EMBED_PENDING]: 4, + [LOG_RECORD_TYPES.EMBED_LANDED]: 4, + [LOG_RECORD_TYPES.BLOB_MANIFEST]: 6, + [LOG_RECORD_TYPES.PROJECTION_NOTE]: 3, + [LOG_RECORD_TYPES.BOOTSTRAP_BASELINE]: 6, + [LOG_RECORD_TYPES.LOG_GENESIS]: 5 +} + +/** + * Decode one wire record. Returns `null` for pads (skipped by definition). + * Unknown type / newer version throw {@link UnknownLogRecordError} — never + * skip-and-continue. + */ +function decodeRecord(raw: unknown): LogRecord | null { + if (!Array.isArray(raw) || raw.length < 2) { + throw new Error('fact log v2: malformed record envelope (need [type, version, ...])') + } + const recordType = wireToU8(raw[0], 'recordType') + const recordVersion = wireToU8(raw[1], 'recordVersion') + + if (recordType === LOG_RECORD_TYPES.PAD) { + // Length-only filler: skipped wholesale, filler fields never inspected. + return null + } + const arity = RECORD_ARITY[recordType] + if (arity === undefined) { + throw new UnknownLogRecordError( + recordType, + recordVersion, + `fact log v2: unknown record type ${recordType} (record version ${recordVersion}) — ` + + `a newer reader is required to decode this log` + ) + } + if (recordVersion > LOG_RECORD_VERSION) { + throw new UnknownLogRecordError( + recordType, + recordVersion, + `fact log v2: record type ${recordType} carries record version ${recordVersion}; ` + + `this reader knows version ${LOG_RECORD_VERSION} — a newer reader is required to decode this log` + ) + } + if (recordVersion !== LOG_RECORD_VERSION) { + throw new Error(`fact log v2: record type ${recordType} has invalid record version ${recordVersion}`) + } + if (raw.length !== arity) { + throw new Error( + `fact log v2: record type ${recordType} expects ${arity} wire fields; got ${raw.length}` + ) + } + + switch (recordType) { + case LOG_RECORD_TYPES.NOUN_AFTER_IMAGE: + return { + type: 'noun.afterImage', + id: bytesToUuid(raw[2], 'noun.afterImage id'), + entityInt: wireToBigint(raw[3], 'entityInt'), + metadata: raw[4] ?? null, + vectorLeg: decodeVectorLeg(raw[5], 'noun.afterImage') + } + case LOG_RECORD_TYPES.NOUN_TOMBSTONE: + return { type: 'noun.tombstone', id: bytesToUuid(raw[2], 'noun.tombstone id') } + case LOG_RECORD_TYPES.VERB_AFTER_IMAGE: { + if (typeof raw[6] !== 'string') { + throw new Error('fact log v2: verb.afterImage verb name is not a string') + } + return { + type: 'verb.afterImage', + id: bytesToUuid(raw[2], 'verb.afterImage id'), + verbInt: wireToBigint(raw[3], 'verbInt'), + metadata: raw[4] ?? null, + vectorLeg: decodeVectorLeg(raw[5], 'verb.afterImage'), + verb: raw[6], + sourceId: bytesToUuid(raw[7], 'verb.afterImage sourceId'), + sourceInt: wireToBigint(raw[8], 'sourceInt'), + targetId: bytesToUuid(raw[9], 'verb.afterImage targetId'), + targetInt: wireToBigint(raw[10], 'targetInt') + } + } + case LOG_RECORD_TYPES.VERB_TOMBSTONE: + return { type: 'verb.tombstone', id: bytesToUuid(raw[2], 'verb.tombstone id') } + case LOG_RECORD_TYPES.BATCH_META: { + if (!isPlainMap(raw[2])) throw new Error('fact log v2: batch.meta payload is not a map') + return { type: 'batch.meta', meta: raw[2] } + } + case LOG_RECORD_TYPES.EMBED_PENDING: + return { + type: 'embed.pending', + id: bytesToUuid(raw[2], 'embed.pending id'), + enqueuedAt: wireToNumber(raw[3], 'enqueuedAt') + } + case LOG_RECORD_TYPES.EMBED_LANDED: { + const leg = decodeVectorLeg(raw[3], 'embed.landed') + if (!Array.isArray(leg)) { + throw new Error( + 'fact log v2: embed.landed must carry an INLINE float vector — refs and nil are not allowed here' + ) + } + return { type: 'embed.landed', id: bytesToUuid(raw[2], 'embed.landed id'), vector: leg } + } + case LOG_RECORD_TYPES.BLOB_MANIFEST: { + if (typeof raw[4] !== 'string') { + throw new Error('fact log v2: blob.manifest mimeType is not a string') + } + const refOp = wireToU8(raw[5], 'refOp') + if (refOp !== 0 && refOp !== 1) { + throw new Error(`fact log v2: blob.manifest refOp must be 0 (add) or 1 (release); got ${refOp}`) + } + return { + type: 'blob.manifest', + hash: bytesToHash(raw[2]), + size: wireToNumber(raw[3], 'blob size'), + mimeType: raw[4], + refOp: refOp === 0 ? 'add' : 'release' + } + } + case LOG_RECORD_TYPES.PROJECTION_NOTE: { + if (!isPlainMap(raw[2])) throw new Error('fact log v2: projection.note payload is not a map') + return { type: 'projection.note', note: raw[2] } + } + case LOG_RECORD_TYPES.BOOTSTRAP_BASELINE: { + const kind = wireToU8(raw[3], 'bootstrap.baseline kind') + if (kind !== 0 && kind !== 1) { + throw new Error(`fact log v2: bootstrap.baseline kind must be 0 (noun) or 1 (verb); got ${kind}`) + } + return { + type: 'bootstrap.baseline', + id: bytesToUuid(raw[2], 'bootstrap.baseline id'), + kind: kind === 0 ? 'noun' : 'verb', + metadata: raw[4] ?? null, + vectorLeg: decodeVectorLeg(raw[5], 'bootstrap.baseline') + } + } + case LOG_RECORD_TYPES.LOG_GENESIS: { + const width = wireToU8(raw[2], 'idSpaceWidth') + if (width !== 32 && width !== 64) { + throw new Error(`fact log v2: log.genesis idSpaceWidth must be 32 or 64; got ${width}`) + } + return { + type: 'log.genesis', + idSpaceWidth: width, + brainId: bytesToUuid(raw[3], 'log.genesis brainId'), + createdAt: wireToNumber(raw[4], 'createdAt') + } + } + default: + // Unreachable: every arity-table type is handled above. + throw new Error(`fact log v2: unhandled record type ${recordType}`) + } +} + +// --------------------------------------------------------------------------- +// Fact encode/decode +// --------------------------------------------------------------------------- + +/** + * Encode one committed generation as a complete v2 FRAME (length + crc32c + + * msgpack payload) ready for appending or sealing. + * + * Writer-enforced invariants (refusals, never silent fixes): at least one + * record; no pad records (pads belong to {@link sealGroup}); at most one + * batch.meta; log.genesis only as the first record; vector refs only with a + * passing single-hop validator; embed.landed vectors inline only. + * + * @param fact - The fact to encode (generation ≥ 1; generation 0 marks filler). + * @param options - Single-hop validation for vector refs. + * @returns The complete frame bytes. + */ +export function encodeFactV2(fact: CommitFactV2, options?: EncodeFactV2Options): Uint8Array { + if (!Number.isSafeInteger(fact.generation) || fact.generation < 1) { + throw new Error(`fact log v2: generation must be a positive integer; got ${fact.generation}`) + } + if (!Number.isSafeInteger(fact.timestamp) || fact.timestamp < 0) { + throw new Error(`fact log v2: timestamp must be a non-negative integer; got ${fact.timestamp}`) + } + if (!Array.isArray(fact.records) || fact.records.length === 0) { + throw new Error('fact log v2: a fact must carry at least one record') + } + if (fact.meta !== undefined && !isPlainMap(fact.meta)) { + throw new Error('fact log v2: fact meta must be a map when present') + } + if ( + fact.blobHashes !== undefined && + (!Array.isArray(fact.blobHashes) || fact.blobHashes.some((h) => typeof h !== 'string')) + ) { + throw new Error('fact log v2: blobHashes must be an array of strings when present') + } + + let batchMetaCount = 0 + const wireRecords = fact.records.map((record, index) => { + if (record.type === 'batch.meta' && ++batchMetaCount > 1) { + throw new Error('fact log v2: at most one batch.meta record per fact') + } + if (record.type === 'log.genesis' && index !== 0) { + throw new Error('fact log v2: log.genesis must be the first record of its fact') + } + return encodeRecord(record, options) + }) + + const payload = enc([ + toWireU64(fact.generation, 'generation'), + toWireU64(fact.timestamp, 'timestamp'), + wireRecords, + fact.meta ?? null, + fact.blobHashes && fact.blobHashes.length > 0 ? fact.blobHashes : null + ]) + return buildFrame(payload) +} + +/** + * Decode one fact PAYLOAD (the msgpack bytes inside a frame — see + * {@link framePayload}). The segment's formatVersion, read from its header, + * selects the schema: version 1 decodes the v1 ops shape into a + * {@link CommitFact}; version 2 decodes the record envelope into a + * {@link CommitFactV2}. Any other version is refused. + */ +export function decodeFact(payload: Uint8Array, segmentFormatVersion: 1): CommitFact +export function decodeFact( + payload: Uint8Array, + segmentFormatVersion: 2, + options?: DecodeFactV2Options +): CommitFactV2 +export function decodeFact( + payload: Uint8Array, + segmentFormatVersion: number, + options?: DecodeFactV2Options +): CommitFact | CommitFactV2 +export function decodeFact( + payload: Uint8Array, + segmentFormatVersion: number, + options?: DecodeFactV2Options +): CommitFact | CommitFactV2 { + if (segmentFormatVersion === FACT_LOG_FORMAT_V1) return decodeFactV1(payload) + if (segmentFormatVersion === FACT_LOG_FORMAT_V2) return decodeFactV2(payload, options) + throw new Error( + `fact log: no decoder for segment formatVersion ${segmentFormatVersion} — this build reads 1 and 2` + ) +} + +/** + * The v1 decode path — byte-identical in behavior to the v1 log's own + * decoder (positional ops, bin16 ids, body-less tombstones). Kept here so v1 + * segments stay readable through the same entry point forever. + */ +function decodeFactV1(payload: Uint8Array): CommitFact { + const raw = msgpackDecode(payload) as unknown[] + const [generation, timestamp, ops, meta, blobHashes] = raw as [ + number, + number, + Array<[number, Uint8Array, [unknown, unknown] | null]>, + Record | null, + string[] | null + ] + return { + generation: Number(generation), + timestamp: Number(timestamp), + ops: ops.map(([kind, idBytes, record]) => ({ + kind: kind === 0 ? ('noun' as const) : ('verb' as const), + id: bytesToUuid(idBytes, 'op id'), + record: record === null ? null : { metadata: record[0] ?? null, vector: record[1] ?? null } + })), + ...(meta ? { meta } : {}), + ...(blobHashes && blobHashes.length > 0 ? { blobHashes } : {}) + } +} + +/** The v2 decode path: record envelope, decoder-law enforcement, pad skip. */ +function decodeFactV2(payload: Uint8Array, options?: DecodeFactV2Options): CommitFactV2 { + const raw = dec(payload) + if (!Array.isArray(raw) || raw.length !== 5) { + throw new Error('fact log v2: fact payload must be a positional array of 5') + } + const [genWire, tsWire, recordsWire, metaWire, blobsWire] = raw + if (!Array.isArray(recordsWire)) { + throw new Error('fact log v2: fact records position is not an array') + } + + const records: LogRecord[] = [] + let batchMetaCount = 0 + recordsWire.forEach((rawRecord, index) => { + const record = decodeRecord(rawRecord) + if (record === null) return // pad: length-only filler, skipped by definition + if (record.type === 'log.genesis') { + if (index !== 0) { + throw new Error('fact log v2: log.genesis must be the first record of its fact') + } + const expected = options?.expectedIdSpaceWidth + if (expected !== undefined && record.idSpaceWidth !== expected) { + throw new GenesisWidthMismatchError(expected, record.idSpaceWidth) + } + } + if (record.type === 'batch.meta' && ++batchMetaCount > 1) { + throw new Error('fact log v2: at most one batch.meta record per fact') + } + records.push(record) + }) + + let meta: Record | undefined + if (metaWire !== null && metaWire !== undefined) { + if (!isPlainMap(metaWire)) throw new Error('fact log v2: fact meta position is not a map') + meta = metaWire + } + let blobHashes: string[] | undefined + if (blobsWire !== null && blobsWire !== undefined) { + if (!Array.isArray(blobsWire) || blobsWire.some((h) => typeof h !== 'string')) { + throw new Error('fact log v2: fact blobHashes position is not a string array') + } + blobHashes = blobsWire + } + + return { + generation: wireToNumber(genWire, 'generation'), + timestamp: wireToNumber(tsWire, 'timestamp'), + records, + ...(meta ? { meta } : {}), + ...(blobHashes && blobHashes.length > 0 ? { blobHashes } : {}) + } +} + +// --------------------------------------------------------------------------- +// Sector seals +// --------------------------------------------------------------------------- + +/** Smallest constructible pad frame (envelope + bare pad record), memoized. */ +let minPadFrameBytesMemo: number | null = null +function minPadFrameBytes(): number { + if (minPadFrameBytesMemo === null) { + minPadFrameBytesMemo = + FRAME_PREFIX_BYTES + + enc([0n, 0n, [[LOG_RECORD_TYPES.PAD, LOG_RECORD_VERSION]], null, null]).length + } + return minPadFrameBytesMemo +} + +/** + * Build a pad frame of EXACTLY `totalBytes`: a filler fact + * `[0, 0, [[0, 1, filler?]], nil, nil]` sized via a binary filler field. + * Readers skip pad records by definition, so filler fields are never + * inspected — only their length matters. + */ +function buildPadFrame(totalBytes: number): Uint8Array { + const targetPayload = totalBytes - FRAME_PREFIX_BYTES + const attempt = (record: unknown[]): Uint8Array => enc([0n, 0n, [record], null, null]) + + let payload = attempt([LOG_RECORD_TYPES.PAD, LOG_RECORD_VERSION]) + if (payload.length !== targetPayload) { + // One byte short: a fixint filler adds exactly one byte. + payload = attempt([LOG_RECORD_TYPES.PAD, LOG_RECORD_VERSION, 0]) + } + if (payload.length !== targetPayload) { + // Binary filler: msgpack bin grows byte-for-byte within a size class; + // iterate to absorb the class-header steps (bin8 → bin16 → bin32). + let fillerLength = Math.max(0, targetPayload - payload.length - 1) + let converged = false + for (let i = 0; i < 8; i++) { + const candidate = attempt([ + LOG_RECORD_TYPES.PAD, + LOG_RECORD_VERSION, + new Uint8Array(fillerLength) + ]) + const diff = targetPayload - candidate.length + if (diff === 0) { + payload = candidate + converged = true + break + } + fillerLength += diff + if (fillerLength < 0) break + } + if (!converged) { + throw new Error(`fact log v2: a pad frame of ${totalBytes} bytes is not constructible`) + } + } + return buildFrame(payload) +} + +/** + * Seal a group of frames to a sector boundary: concatenate the frames and pad + * to the next `sealSize` multiple with ONE pad frame. An already-aligned + * group gets no pad. When the gap is smaller than the smallest constructible + * pad frame, the group is padded through to the boundary AFTER next (one + * extra sealSize) — input frames are never rewritten. + * + * @param frames - Complete, well-formed frames (verified; garbage is refused). + * @param sealSize - The sector-seal size (device probing is the caller's + * business; default {@link DEFAULT_SEAL_SIZE}). + * @returns The sector-aligned group (`length % sealSize === 0`). + */ +export function sealGroup(frames: Uint8Array[], sealSize: number = DEFAULT_SEAL_SIZE): Uint8Array { + assertValidSealSize(sealSize) + if (!Array.isArray(frames) || frames.length === 0) { + throw new Error('fact log v2: sealGroup needs at least one frame') + } + frames.forEach((frame, i) => { + try { + framePayload(frame) + } catch (error) { + throw new Error( + `fact log v2: sealGroup frame ${i} is not a well-formed frame: ${(error as Error).message}` + ) + } + }) + + const total = frames.reduce((n, f) => n + f.length, 0) + const remainder = total % sealSize + let padBytes = remainder === 0 ? 0 : sealSize - remainder + if (padBytes !== 0 && padBytes < minPadFrameBytes()) { + padBytes += sealSize // gap too small for any frame — pad through one more sector + } + + const sealed = new Uint8Array(total + padBytes) + let offset = 0 + for (const frame of frames) { + sealed.set(frame, offset) + offset += frame.length + } + if (padBytes > 0) { + sealed.set(buildPadFrame(padBytes), offset) + } + return sealed +} + +/** + * Decode a sequence of v2 frames (a sealed group, or a segment body after its + * 32-byte header) with the torn-tail discipline: a frame whose length overruns + * the buffer or whose CRC fails TERMINATES the walk — everything before it is + * intact and returned; nothing after it is guessed at. Pad frames are dropped + * (invisible). CRC-valid frames with unknown record types still throw + * {@link UnknownLogRecordError} — physical damage truncates, format novelty + * refuses. + */ +export function decodeGroupV2(bytes: Uint8Array, options?: DecodeFactV2Options): DecodedFrameGroup { + const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength) + const facts: CommitFactV2[] = [] + let offset = 0 + while (offset + FRAME_PREFIX_BYTES <= bytes.length) { + const length = view.getUint32(offset, true) + const expectedCrc = view.getUint32(offset + 4, true) + const start = offset + FRAME_PREFIX_BYTES + const end = start + length + if (end > bytes.length) break // torn tail: frame length overruns the buffer + const payload = bytes.subarray(start, end) + if (crc32c(payload) !== expectedCrc) break // torn tail: payload CRC mismatch + const fact = decodeFactV2(payload, options) + if (fact.records.length > 0) facts.push(fact) // zero-record fact = pad filler + offset = end + } + return { facts, validBytes: offset } +} diff --git a/src/db/faultInjectionStorage.ts b/src/db/faultInjectionStorage.ts new file mode 100644 index 00000000..cafd4198 --- /dev/null +++ b/src/db/faultInjectionStorage.ts @@ -0,0 +1,164 @@ +/** + * @module db/faultInjectionStorage + * @description Deterministic fault injection at the fact log's raw-byte + * storage surface — the test harness half of the durability protocol. Wraps + * any adapter exposing the {@link FactLogStorage} primitives (the exact + * surface the fact log appends and syncs through) and injects the three + * crash shapes durability tests must prove against: + * + * - **torn write** ({@link FaultInjectionStorage.tearWriteAtByte}): the next + * append persists only its first N bytes, then reports success — the shape + * of power loss after a partially-flushed page. The caller-side "crash" is + * simulated by abandoning in-memory state and reopening from storage. + * - **dropped sync** ({@link FaultInjectionStorage.dropNextSync}): the next + * sync becomes a silent no-op — an fsync the device acknowledged into a + * volatile cache and lost. + * - **failed append** ({@link FaultInjectionStorage.failNextAppend}): the next + * append throws {@link FaultInjectedError} without writing a byte — EIO or + * a full disk, surfaced to the writer. + * + * Every injected fault is journaled on {@link FaultInjectionStorage.injectedFaults} + * so tests can assert not just the outcome but that the fault actually fired. + * Knobs are one-shot (they disarm on firing) and re-arming overwrites the + * pending shot. All other operations pass through untouched. + */ +import type { FactLogStorage } from './factLog.js' + +/** The error a {@link FaultInjectionStorage.failNextAppend} shot throws. */ +export class FaultInjectedError extends Error { + /** The operation the fault fired on. */ + public readonly operation: 'append' + /** The storage path the operation targeted. */ + public readonly path: string + + constructor(operation: 'append', path: string) { + super(`fault injection: ${operation} to ${path} failed by test design`) + this.name = 'FaultInjectedError' + this.operation = operation + this.path = path + } +} + +/** One journaled fault event — proof the injected fault actually fired. */ +export interface InjectedFault { + kind: 'torn-write' | 'dropped-sync' | 'failed-append' + /** The target path (torn-write / failed-append). */ + path?: string + /** The paths a dropped sync was asked to make durable. */ + paths?: string[] + /** Bytes the caller asked to append (torn-write). */ + requestedBytes?: number + /** Bytes actually persisted (torn-write). */ + writtenBytes?: number +} + +/** + * A {@link FactLogStorage} wrapper that injects deterministic storage faults. + * Construct it around any conforming adapter and hand it wherever a + * FactLogStorage is accepted — unarmed, it is a transparent passthrough. + */ +export class FaultInjectionStorage implements FactLogStorage { + private readonly inner: FactLogStorage + /** Pending torn-write byte count, or null when unarmed. */ + private tearAtByte: number | null = null + /** Pending dropped-sync shot. */ + private dropSyncArmed = false + /** Pending failed-append shot. */ + private failAppendArmed = false + /** Journal of every fault that fired, in firing order. */ + public readonly injectedFaults: InjectedFault[] = [] + + constructor(inner: FactLogStorage) { + this.inner = inner + } + + /** + * Arm a torn write: the NEXT {@link appendRawBytes} persists only the first + * `n` bytes of its buffer (all of it when `n` exceeds the buffer) and then + * reports success. One-shot. + */ + tearWriteAtByte(n: number): void { + if (!Number.isInteger(n) || n < 0) { + throw new Error(`fault injection: tearWriteAtByte needs a non-negative integer; got ${n}`) + } + this.tearAtByte = n + } + + /** Arm a dropped sync: the NEXT {@link syncRawObjects} silently does nothing. One-shot. */ + dropNextSync(): void { + this.dropSyncArmed = true + } + + /** + * Arm a failed append: the NEXT {@link appendRawBytes} throws + * {@link FaultInjectedError} without writing. One-shot; wins over a + * simultaneously-armed torn write (nothing is written at all). + */ + failNextAppend(): void { + this.failAppendArmed = true + } + + /** Append bytes — the injection point for torn writes and failed appends. */ + async appendRawBytes(path: string, bytes: Uint8Array): Promise { + if (this.failAppendArmed) { + this.failAppendArmed = false + this.injectedFaults.push({ kind: 'failed-append', path }) + throw new FaultInjectedError('append', path) + } + if (this.tearAtByte !== null) { + const writtenBytes = Math.min(this.tearAtByte, bytes.length) + this.tearAtByte = null + this.injectedFaults.push({ + kind: 'torn-write', + path, + requestedBytes: bytes.length, + writtenBytes + }) + if (writtenBytes > 0) { + await this.inner.appendRawBytes(path, bytes.subarray(0, writtenBytes)) + } + return + } + return this.inner.appendRawBytes(path, bytes) + } + + /** Make paths durable — the injection point for dropped syncs. */ + async syncRawObjects(paths: string[]): Promise { + if (this.dropSyncArmed) { + this.dropSyncArmed = false + this.injectedFaults.push({ kind: 'dropped-sync', paths: [...paths] }) + return + } + return this.inner.syncRawObjects(paths) + } + + /** Passthrough. */ + async readRawBytes(path: string): Promise { + return this.inner.readRawBytes(path) + } + + /** Passthrough. */ + async writeRawBytes(path: string, bytes: Uint8Array): Promise { + return this.inner.writeRawBytes(path, bytes) + } + + /** Passthrough. */ + async rawByteSize(path: string): Promise { + return this.inner.rawByteSize(path) + } + + /** Passthrough. */ + async readRawObject(path: string): Promise { + return this.inner.readRawObject(path) + } + + /** Passthrough. */ + async writeRawObject(path: string, data: any): Promise { + return this.inner.writeRawObject(path, data) + } + + /** Passthrough. */ + async deleteRawObject(path: string): Promise { + return this.inner.deleteRawObject(path) + } +} diff --git a/tests/unit/db/factLogFormat.test.ts b/tests/unit/db/factLogFormat.test.ts new file mode 100644 index 00000000..ec1aedb2 --- /dev/null +++ b/tests/unit/db/factLogFormat.test.ts @@ -0,0 +1,745 @@ +/** + * @module tests/unit/db/factLogFormat + * @description Fact-log format v2 (record envelope + sector seals) pinned at + * the byte level: every record type round-trips field-exact (bigint ints, + * bin16 uuids, float-exact vectors), headers read v1 AND v2, unknown record + * types/versions refuse loudly with the typed error, genesis width mismatches + * refuse naming both widths, sealed groups align to the sector size with + * invisible pads, vector refs are writer-enforced single-hop, and torn tails + * truncate to the intact prefix at EVERY byte offset. This module is the + * reference implementation of a two-implementation contract — golden byte + * vectors here are frozen; a change that breaks them is a format change. + */ +import { describe, it, expect } from 'vitest' +import { encode } from '@msgpack/msgpack' +import { + encodeFactV2, + decodeFact, + decodeGroupV2, + encodeSegmentHeaderV2, + parseSegmentHeader, + sealGroup, + framePayload, + UnknownLogRecordError, + GenesisWidthMismatchError, + LOG_RECORD_TYPES, + LOG_RECORD_VERSION, + FACT_LOG_FORMAT_V1, + FACT_LOG_FORMAT_V2, + SEGMENT_HEADER_BYTES, + DEFAULT_SEAL_SIZE, + type CommitFactV2, + type LogRecord, + type VectorRef +} from '../../../src/db/factLogFormat.js' + +const UUID = (n: number): string => + `00000000-0000-4000-8000-${String(n).padStart(12, '0')}` +const HASH_A = 'ab'.repeat(32) +const HASH_B = '0123456789abcdef'.repeat(4) + +/** uuid string → bin16 (test-local mirror of the wire helper). */ +const uuidBytes = (id: string): Uint8Array => { + const hex = id.replace(/-/g, '') + const bytes = new Uint8Array(16) + for (let i = 0; i < 16; i++) bytes[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16) + return bytes +} + +const hex = (bytes: Uint8Array): string => Buffer.from(bytes).toString('hex') + +/** Encode → strip frame → decode; the standard round-trip. */ +const roundTrip = ( + fact: CommitFactV2, + encOpts?: Parameters[1], + decOpts?: { expectedIdSpaceWidth?: 32 | 64 } +): CommitFactV2 => decodeFact(framePayload(encodeFactV2(fact, encOpts)), 2, decOpts) + +/** A single-record fact around `record`, canonical shape for strict equality. */ +const factOf = (generation: number, record: LogRecord): CommitFactV2 => ({ + generation, + timestamp: 1_700_000_000_000 + generation, + records: [record] +}) + +/** + * Build a fact frame of EXACTLY `totalBytes` (projection.note binary filler), + * for engineering precise seal-boundary scenarios. + */ +function frameOfExactly(totalBytes: number, generation: number): Uint8Array { + let fillerLength = Math.max(0, totalBytes - 60) + for (let i = 0; i < 12; i++) { + const frame = encodeFactV2({ + generation, + timestamp: 1, + records: [{ type: 'projection.note', note: { fill: new Uint8Array(fillerLength) } }] + }) + const diff = totalBytes - frame.length + if (diff === 0) return frame + fillerLength += diff + if (fillerLength < 0) throw new Error(`no frame of ${totalBytes} bytes is constructible`) + } + throw new Error('frame sizing did not converge') +} + +describe('fact-log format v2 — record round-trips (field-exact)', () => { + it('noun.afterImage: bin16 uuid, u64-as-bigint beyond 2^53, metadata, inline vector', () => { + const fact = factOf(1, { + type: 'noun.afterImage', + id: UUID(1), + entityInt: (1n << 60n) + 3n, // provably beyond Number territory + metadata: { + noun: 'document', + title: 'doc 1', + nested: { tags: ['a', 'b'], score: 0.25 }, + big: Number.MAX_SAFE_INTEGER, + negative: -42, + flag: true, + missing: null + }, + vectorLeg: [0.1, -2.5, 3, 1e-7] + }) + expect(roundTrip(fact)).toStrictEqual(fact) + }) + + it('noun.tombstone: body-less removal', () => { + const fact = factOf(2, { type: 'noun.tombstone', id: UUID(2) }) + expect(roundTrip(fact)).toStrictEqual(fact) + }) + + it('verb.afterImage: both endpoints, three u64 handles, verb name', () => { + const fact = factOf(3, { + type: 'verb.afterImage', + id: UUID(3), + verbInt: 18_446_744_073_709_551_615n, // u64 max + metadata: { verb: 'contains', weight: 0.5 }, + vectorLeg: null, + verb: 'contains', + sourceId: UUID(31), + sourceInt: 7n, + targetId: UUID(32), + targetInt: (1n << 53n) + 1n + }) + expect(roundTrip(fact)).toStrictEqual(fact) + }) + + it('verb.tombstone: body-less removal', () => { + const fact = factOf(4, { type: 'verb.tombstone', id: UUID(4) }) + expect(roundTrip(fact)).toStrictEqual(fact) + }) + + it('batch.meta: one metadata map per fact', () => { + const fact = factOf(5, { type: 'batch.meta', meta: { source: 'import', count: 12 } }) + expect(roundTrip(fact)).toStrictEqual(fact) + }) + + it('embed.pending: id + enqueue time', () => { + const fact = factOf(6, { type: 'embed.pending', id: UUID(6), enqueuedAt: 1_700_000_000_777 }) + expect(roundTrip(fact)).toStrictEqual(fact) + }) + + it('embed.landed: inline vector, float-exact', () => { + const fact = factOf(7, { + type: 'embed.landed', + id: UUID(7), + vector: [0.30000000000000004, -1.5, 2 ** 31 + 0.5] + }) + expect(roundTrip(fact)).toStrictEqual(fact) + }) + + it('blob.manifest: bin32 hash, size, mimeType, both refOps', () => { + const add = factOf(8, { + type: 'blob.manifest', + hash: HASH_A, + size: 1_048_576, + mimeType: 'image/png', + refOp: 'add' + }) + expect(roundTrip(add)).toStrictEqual(add) + const release = factOf(9, { + type: 'blob.manifest', + hash: HASH_B, + size: 0, + mimeType: 'application/octet-stream', + refOp: 'release' + }) + expect(roundTrip(release)).toStrictEqual(release) + }) + + it('projection.note: opaque map rides untouched', () => { + const fact = factOf(10, { + type: 'projection.note', + note: { consumer: 'reserved', payload: { depth: [1, 2, 3] } } + }) + expect(roundTrip(fact)).toStrictEqual(fact) + }) + + it('bootstrap.baseline: kind flag, metadata, vector leg — both kinds', () => { + const noun = factOf(11, { + type: 'bootstrap.baseline', + id: UUID(11), + kind: 'noun', + metadata: { noun: 'person' }, + vectorLeg: [1, 2, 3] + }) + expect(roundTrip(noun)).toStrictEqual(noun) + const verb = factOf(12, { + type: 'bootstrap.baseline', + id: UUID(12), + kind: 'verb', + metadata: null, + vectorLeg: null + }) + expect(roundTrip(verb)).toStrictEqual(verb) + }) + + it('log.genesis: width, brainId, createdAt — both widths', () => { + for (const idSpaceWidth of [32, 64] as const) { + const fact = factOf(1, { + type: 'log.genesis', + idSpaceWidth, + brainId: UUID(999), + createdAt: 1_700_000_000_000 + }) + expect(roundTrip(fact, undefined, { expectedIdSpaceWidth: idSpaceWidth })).toStrictEqual(fact) + } + }) + + it('a combined fact: genesis-first, all record types, fact meta, duplicate blobHashes', () => { + const fact: CommitFactV2 = { + generation: 1, + timestamp: 1_700_000_000_001, + records: [ + { type: 'log.genesis', idSpaceWidth: 64, brainId: UUID(999), createdAt: 1_699_999_999_999 }, + { type: 'noun.afterImage', id: UUID(1), entityInt: 1n, metadata: { a: 1 }, vectorLeg: [0.5] }, + { type: 'noun.tombstone', id: UUID(2) }, + { + type: 'verb.afterImage', + id: UUID(3), + verbInt: 3n, + metadata: null, + vectorLeg: null, + verb: 'relatedTo', + sourceId: UUID(31), + sourceInt: 1n, + targetId: UUID(32), + targetInt: 2n + }, + { type: 'verb.tombstone', id: UUID(4) }, + { type: 'batch.meta', meta: { origin: 'unit' } }, + { type: 'embed.pending', id: UUID(6), enqueuedAt: 5 }, + { type: 'embed.landed', id: UUID(7), vector: [0.1] }, + { type: 'blob.manifest', hash: HASH_A, size: 9, mimeType: 'text/plain', refOp: 'add' }, + { type: 'projection.note', note: {} }, + { type: 'bootstrap.baseline', id: UUID(11), kind: 'noun', metadata: null, vectorLeg: null } + ], + meta: { source: 'unit' }, + blobHashes: [HASH_A, HASH_A] // multiset — duplicates preserved + } + expect(roundTrip(fact, undefined, { expectedIdSpaceWidth: 64 })).toStrictEqual(fact) + }) +}) + +describe('fact-log format v2 — golden byte vectors (frozen contract)', () => { + it('v2 segment header bytes are pinned', () => { + expect(hex(encodeSegmentHeaderV2(7, 4096))).toBe( + '4246414354530000020000000700000000000000001000000000000000000000' + ) + }) + + it('a noun.tombstone frame is pinned byte-for-byte', () => { + const frame = encodeFactV2({ + generation: 3, + timestamp: 1_700_000_000_123, + records: [{ type: 'noun.tombstone', id: '00000000-0000-4000-8000-000000000042' }] + }) + expect(hex(frame)).toBe( + '2b000000c19ad9ff95cf0000000000000003cf0000018bcfe5687b91930201' + + 'c41000000000000040008000000000000042c0c0' + ) + }) + + it('u64 registry fields ride as fixed 8-byte msgpack uint64 (0xcf)', () => { + const payload = framePayload( + encodeFactV2(factOf(1, { type: 'embed.pending', id: UUID(1), enqueuedAt: 2 })) + ) + // positions 0 and 1 (generation, timestamp) and enqueuedAt are all 0xcf + expect(payload[1]).toBe(0xcf) + expect(payload[10]).toBe(0xcf) + }) +}) + +describe('fact-log format v2 — segment headers (v1 AND v2)', () => { + const v1Header = (): Uint8Array => { + const header = new Uint8Array(SEGMENT_HEADER_BYTES) + header.set(new Uint8Array([0x42, 0x46, 0x41, 0x43, 0x54, 0x53, 0x00, 0x00]), 0) + const view = new DataView(header.buffer) + view.setUint32(8, FACT_LOG_FORMAT_V1, true) + view.setBigUint64(12, 42n, true) + return header + } + + it('a v2 header round-trips with its sealSize', () => { + const header = encodeSegmentHeaderV2(123_456, 512) + expect(header.length).toBe(SEGMENT_HEADER_BYTES) + expect(parseSegmentHeader(header)).toStrictEqual({ + formatVersion: FACT_LOG_FORMAT_V2, + firstGeneration: 123_456, + sealSize: 512 + }) + // default sealSize + expect(parseSegmentHeader(encodeSegmentHeaderV2(1)).sealSize).toBe(DEFAULT_SEAL_SIZE) + }) + + it('a v1 header parses: version 1, sealSize absent (undefined)', () => { + const parsed = parseSegmentHeader(v1Header()) + expect(parsed).toStrictEqual({ formatVersion: FACT_LOG_FORMAT_V1, firstGeneration: 42 }) + expect(parsed.sealSize).toBeUndefined() + }) + + it('corrupted magic throws', () => { + const header = encodeSegmentHeaderV2(1) + header[0] = 0x58 + expect(() => parseSegmentHeader(header)).toThrow(/bad magic/) + }) + + it('non-zero reserved bytes throw — v1 (offset 20+) and v2 (offset 22+)', () => { + const v1 = v1Header() + v1[21] = 1 + expect(() => parseSegmentHeader(v1)).toThrow(/non-zero reserved/) + + const v2 = encodeSegmentHeaderV2(1, 4096) + v2[25] = 1 + expect(() => parseSegmentHeader(v2)).toThrow(/non-zero reserved/) + }) + + it('the v2 sealSize bytes are NOT reserved bytes in v2 (but ARE in v1)', () => { + // sealSize 512 puts a non-zero byte at offset 21 — legal in v2 only. + const v2 = encodeSegmentHeaderV2(1, 512) + expect(parseSegmentHeader(v2).sealSize).toBe(512) + const v1 = v1Header() + v1[20] = 0x00 + v1[21] = 0x02 // same bytes a v2 sealSize=512 would carry + expect(() => parseSegmentHeader(v1)).toThrow(/non-zero reserved/) + }) + + it('an unknown header version and a short buffer throw', () => { + const header = encodeSegmentHeaderV2(1) + new DataView(header.buffer).setUint32(8, 3, true) + expect(() => parseSegmentHeader(header)).toThrow(/formatVersion 3/) + expect(() => parseSegmentHeader(header.subarray(0, 31))).toThrow(/32 bytes/) + }) + + it('header writer refuses out-of-range inputs', () => { + expect(() => encodeSegmentHeaderV2(-1)).toThrow(/non-negative/) + expect(() => encodeSegmentHeaderV2(1, 32)).toThrow(/sealSize/) + expect(() => encodeSegmentHeaderV2(1, 65_536)).toThrow(/sealSize/) + }) +}) + +describe('fact-log format v2 — decoder law (typed refusals, never skip)', () => { + it('unknown record type 12 throws UnknownLogRecordError naming type 12', () => { + const payload = encode([1, 1, [[12, 1]], null, null]) + expect(() => decodeFact(payload, 2)).toThrow(UnknownLogRecordError) + try { + decodeFact(payload, 2) + expect.unreachable('decode must throw') + } catch (error) { + const typed = error as UnknownLogRecordError + expect(typed).toBeInstanceOf(UnknownLogRecordError) + expect(typed.recordType).toBe(12) + expect(typed.recordVersion).toBe(1) + expect(typed.message).toMatch(/type 12/) + expect(typed.message).toMatch(/newer reader/) + } + }) + + it('recordVersion 2 on a known type throws the same class naming the version', () => { + const payload = encode([1, 1, [[LOG_RECORD_TYPES.NOUN_TOMBSTONE, 2, new Uint8Array(16)]], null, null]) + try { + decodeFact(payload, 2) + expect.unreachable('decode must throw') + } catch (error) { + const typed = error as UnknownLogRecordError + expect(typed).toBeInstanceOf(UnknownLogRecordError) + expect(typed.recordType).toBe(LOG_RECORD_TYPES.NOUN_TOMBSTONE) + expect(typed.recordVersion).toBe(2) + expect(typed.message).toMatch(/version 2/) + expect(typed.message).toMatch(/newer reader/) + } + }) + + it('a fact mixing known and unknown records still refuses (no partial reads)', () => { + const known = [LOG_RECORD_TYPES.NOUN_TOMBSTONE, 1, uuidBytes(UUID(1))] + const payload = encode([1, 1, [known, [200, 1]], null, null]) + expect(() => decodeFact(payload, 2)).toThrow(UnknownLogRecordError) + }) + + it('an unknown segment format version has no decode path', () => { + const payload = framePayload(encodeFactV2(factOf(1, { type: 'noun.tombstone', id: UUID(1) }))) + expect(() => decodeFact(payload, 3)).toThrow(/reads 1 and 2/) + }) +}) + +describe('fact-log format v2 — log.genesis width law', () => { + const genesisFact = (width: 32 | 64): CommitFactV2 => + factOf(1, { type: 'log.genesis', idSpaceWidth: width, brainId: UUID(9), createdAt: 1 }) + + it('expectedWidth 32 vs a 64-width genesis refuses, naming both widths', () => { + const payload = framePayload(encodeFactV2(genesisFact(64))) + expect(() => decodeFact(payload, 2, { expectedIdSpaceWidth: 32 })).toThrow( + GenesisWidthMismatchError + ) + try { + decodeFact(payload, 2, { expectedIdSpaceWidth: 32 }) + expect.unreachable('decode must throw') + } catch (error) { + const typed = error as GenesisWidthMismatchError + expect(typed.expectedWidth).toBe(32) + expect(typed.actualWidth).toBe(64) + expect(typed.message).toMatch(/32-bit/) + expect(typed.message).toMatch(/64-bit/) + } + }) + + it('a matching width (and no expectation at all) decodes cleanly', () => { + const payload = framePayload(encodeFactV2(genesisFact(64))) + expect(decodeFact(payload, 2, { expectedIdSpaceWidth: 64 }).records[0]).toMatchObject({ + idSpaceWidth: 64 + }) + expect(decodeFact(payload, 2).records[0]).toMatchObject({ idSpaceWidth: 64 }) + }) + + it('genesis anywhere but record 0 refuses — encode AND decode', () => { + const late: CommitFactV2 = { + generation: 1, + timestamp: 1, + records: [ + { type: 'noun.tombstone', id: UUID(1) }, + { type: 'log.genesis', idSpaceWidth: 64, brainId: UUID(9), createdAt: 1 } + ] + } + expect(() => encodeFactV2(late)).toThrow(/first record/) + const crafted = encode([ + 1, + 1, + [ + [LOG_RECORD_TYPES.NOUN_TOMBSTONE, 1, uuidBytes(UUID(1))], + [LOG_RECORD_TYPES.LOG_GENESIS, 1, 64, uuidBytes(UUID(9)), 1] + ], + null, + null + ]) + expect(() => decodeFact(crafted, 2)).toThrow(/first record/) + }) + + it('an invalid genesis width on the wire is malformed, not a mismatch', () => { + const crafted = encode([1, 1, [[LOG_RECORD_TYPES.LOG_GENESIS, 1, 48, uuidBytes(UUID(9)), 1]], null, null]) + expect(() => decodeFact(crafted, 2)).toThrow(/32 or 64/) + }) +}) + +describe('fact-log format v2 — vector legs (single-hop law)', () => { + it('inline vectors round-trip float-exact', () => { + const vector = [0.1 + 0.2, -0.0000001, 3.141592653589793, 2 ** 40 + 0.25] + const fact = factOf(1, { + type: 'noun.afterImage', + id: UUID(1), + entityInt: 1n, + metadata: null, + vectorLeg: vector + }) + const decoded = roundTrip(fact) + expect((decoded.records[0] as { vectorLeg: number[] }).vectorLeg).toStrictEqual(vector) + }) + + it('a ref round-trips when the validator vouches for the target generation', () => { + const fact = factOf(6, { + type: 'noun.afterImage', + id: UUID(1), + entityInt: 1n, + metadata: null, + vectorLeg: { sameAsGeneration: 5 } + }) + const viaSet = roundTrip(fact, { inlineVectorGenerations: new Set([5]) }) + expect((viaSet.records[0] as { vectorLeg: VectorRef }).vectorLeg).toStrictEqual({ + sameAsGeneration: 5 + }) + const viaCallback = roundTrip(fact, { inlineVectorGenerations: (g) => g === 5 }) + expect(viaCallback).toStrictEqual(fact) + }) + + it('the encoder REFUSES a ref the validator rejects', () => { + const fact = factOf(6, { + type: 'noun.afterImage', + id: UUID(1), + entityInt: 1n, + metadata: null, + vectorLeg: { sameAsGeneration: 5 } + }) + expect(() => encodeFactV2(fact, { inlineVectorGenerations: new Set([4]) })).toThrow( + /single-hop/ + ) + expect(() => encodeFactV2(fact, { inlineVectorGenerations: () => false })).toThrow( + /generation 5/ + ) + }) + + it('the encoder REFUSES a ref when no validator was provided at all', () => { + const fact = factOf(6, { + type: 'noun.afterImage', + id: UUID(1), + entityInt: 1n, + metadata: null, + vectorLeg: { sameAsGeneration: 5 } + }) + expect(() => encodeFactV2(fact)).toThrow(/unverifiable ref/) + }) + + it('embed.landed is inline-only: encode refuses non-arrays, decode refuses wire refs', () => { + const bad = factOf(7, { + type: 'embed.landed', + id: UUID(7), + vector: null as unknown as number[] + }) + expect(() => encodeFactV2(bad)).toThrow(/INLINE/) + const craftedRef = encode( + [1, 1, [[LOG_RECORD_TYPES.EMBED_LANDED, 1, uuidBytes(UUID(7)), ['ref', 5]]], null, null] + ) + expect(() => decodeFact(craftedRef, 2)).toThrow(/INLINE/) + }) +}) + +describe('fact-log format v2 — sector seals', () => { + const facts = [1, 2, 3].map((g) => + factOf(g, { + type: 'noun.afterImage', + id: UUID(g), + entityInt: BigInt(g), + metadata: { title: `doc ${g}` }, + vectorLeg: [g + 0.5] + }) + ) + const frames = facts.map((f) => encodeFactV2(f)) + + it('sealGroup output is sector-aligned and decodes to exactly the input facts', () => { + const sealed = sealGroup(frames, 4096) + expect(sealed.length % 4096).toBe(0) + const { facts: decoded, validBytes } = decodeGroupV2(sealed) + expect(decoded).toStrictEqual(facts) // pads invisible + expect(validBytes).toBe(sealed.length) + }) + + it('an already-aligned group gets NO pad (byte-identical passthrough)', () => { + const exact = frameOfExactly(4096, 1) + const sealed = sealGroup([exact], 4096) + expect(sealed.length).toBe(4096) + expect(Buffer.compare(Buffer.from(sealed), Buffer.from(exact))).toBe(0) + expect(decodeGroupV2(sealed).facts).toHaveLength(1) + }) + + it('a normal gap gets ONE exact-fit pad frame', () => { + const sealed = sealGroup([frameOfExactly(2000, 1), frameOfExactly(1996, 2)], 4096) // gap 100 + expect(sealed.length).toBe(4096) + expect(decodeGroupV2(sealed).facts.map((f) => f.generation)).toEqual([1, 2]) + }) + + it('a gap too small for any frame (the <12-byte remainder and friends) pads through one extra sector', () => { + for (const gap of [1, 8, 11, 16, 32]) { + const sealed = sealGroup([frameOfExactly(4096 - gap, 1)], 4096) + expect(sealed.length % 4096).toBe(0) + expect(sealed.length).toBe(8192) // gap + one full sector, still aligned + const { facts: decoded, validBytes } = decodeGroupV2(sealed) + expect(decoded.map((f) => f.generation)).toEqual([1]) + expect(validBytes).toBe(8192) + } + // the smallest constructible pad frame fits exactly — no overshoot at 33 + const sealed33 = sealGroup([frameOfExactly(4096 - 33, 1)], 4096) + expect(sealed33.length).toBe(4096) + expect(decodeGroupV2(sealed33).facts.map((f) => f.generation)).toEqual([1]) + }) + + it('seals honor a custom sealSize (device-probed sizes are the caller business)', () => { + const sealed = sealGroup(frames, 512) + expect(sealed.length % 512).toBe(0) + expect(decodeGroupV2(sealed).facts).toStrictEqual(facts) + }) + + it('pad frame bytes are pinned (golden vector, sealSize 64)', () => { + const tomb = encodeFactV2({ + generation: 3, + timestamp: 1_700_000_000_123, + records: [{ type: 'noun.tombstone', id: '00000000-0000-4000-8000-000000000042' }] + }) + const sealed = sealGroup([tomb], 64) // 51 bytes → gap 13 → overshoot → 77-byte pad + expect(sealed.length).toBe(128) + expect(hex(sealed.subarray(tomb.length))).toBe( + // frame prefix + [0, 0, [[0, 1, bin8(42 zero bytes)]], nil, nil] + '450000009463044d95cf0000000000000000cf000000000000000091930001c42a' + + '0'.repeat(84) + + 'c0c0' + ) + }) + + it('sealGroup refuses garbage: empty groups, malformed frames, bad seal sizes', () => { + expect(() => sealGroup([], 4096)).toThrow(/at least one frame/) + expect(() => sealGroup([new Uint8Array([1, 2, 3])], 4096)).toThrow(/not a well-formed frame/) + const corrupted = encodeFactV2(facts[0]) + corrupted[corrupted.length - 1] ^= 0xff + expect(() => sealGroup([corrupted], 4096)).toThrow(/not a well-formed frame/) + expect(() => sealGroup(frames, 32)).toThrow(/sealSize/) + }) +}) + +describe('fact-log format v2 — torn-tail discipline', () => { + it('truncating a sealed group at EVERY byte offset of the tail yields the intact prefix, never an uncontrolled throw', () => { + const frames = [frameOfExactly(600, 1), frameOfExactly(700, 2), frameOfExactly(800, 3)] + const sealed = sealGroup(frames, 4096) + expect(sealed.length).toBe(4096) + const f3End = 600 + 700 + 800 + + for (let cut = 600 + 700; cut < sealed.length; cut++) { + const { facts: decoded, validBytes } = decodeGroupV2(sealed.subarray(0, cut)) + const expected = cut < f3End ? [1, 2] : [1, 2, 3] + expect(decoded.map((f) => f.generation)).toEqual(expected) + expect(validBytes).toBe(cut < f3End ? 600 + 700 : f3End) + } + }) + + it('a flipped payload byte (not just truncation) also terminates the walk at the damage', () => { + const frames = [frameOfExactly(600, 1), frameOfExactly(700, 2)] + const sealed = sealGroup(frames, 4096) + const damaged = sealed.slice() + damaged[600 + 100] ^= 0xff // inside frame 2's payload + const { facts: decoded, validBytes } = decodeGroupV2(damaged) + expect(decoded.map((f) => f.generation)).toEqual([1]) + expect(validBytes).toBe(600) + }) +}) + +describe('fact-log format v2 — writer refusals (loud, never silent)', () => { + const tombstone = (g: number): CommitFactV2 => factOf(g, { type: 'noun.tombstone', id: UUID(g) }) + + it('refuses empty records, generation 0, and a second batch.meta', () => { + expect(() => encodeFactV2({ generation: 1, timestamp: 1, records: [] })).toThrow( + /at least one record/ + ) + expect(() => encodeFactV2({ ...tombstone(1), generation: 0 })).toThrow(/positive integer/) + expect(() => + encodeFactV2({ + generation: 1, + timestamp: 1, + records: [ + { type: 'batch.meta', meta: { a: 1 } }, + { type: 'batch.meta', meta: { b: 2 } } + ] + }) + ).toThrow(/at most one batch.meta/) + }) + + it('refuses pad records — filler belongs to sealGroup, not to writers', () => { + const fact = { + generation: 1, + timestamp: 1, + records: [{ type: 'pad' } as unknown as LogRecord] + } + expect(() => encodeFactV2(fact)).toThrow(/cannot encode record type pad/) + }) + + it('refuses malformed field values: non-uuid ids, bad hashes, out-of-range u64s', () => { + expect(() => + encodeFactV2(factOf(1, { type: 'noun.tombstone', id: 'not-a-uuid' })) + ).toThrow(/not a uuid/) + expect(() => + encodeFactV2( + factOf(1, { type: 'blob.manifest', hash: 'abc', size: 1, mimeType: 'x', refOp: 'add' }) + ) + ).toThrow(/64 hex chars/) + expect(() => + encodeFactV2( + factOf(1, { + type: 'noun.afterImage', + id: UUID(1), + entityInt: -1n, + metadata: null, + vectorLeg: null + }) + ) + ).toThrow(/u64 range/) + expect(() => + encodeFactV2( + factOf(1, { + type: 'noun.afterImage', + id: UUID(1), + entityInt: 1n << 64n, + metadata: null, + vectorLeg: null + }) + ) + ).toThrow(/u64 range/) + }) +}) + +describe('fact-log format — the v1 decode path stays readable forever', () => { + it('decodeFact(payload, 1) reads the v1 ops shape (positional, bin16, tombstones)', () => { + // Crafted exactly as the v1 writer frames facts: default msgpack, ops at + // position 2 as [kind u8, id bin16, [metadata, vector] | nil]. + const payload = encode([ + 4, + 1_700_000_000_004, + [ + [0, uuidBytes(UUID(41)), [{ noun: 'document', title: 'doc 41' }, { v: [1, 2] }]], + [1, uuidBytes(UUID(42)), null] // verb tombstone + ], + { source: 'v1' }, + ['abc123'] + ]) + const fact = decodeFact(payload, 1) + expect(fact).toStrictEqual({ + generation: 4, + timestamp: 1_700_000_000_004, + ops: [ + { + kind: 'noun', + id: UUID(41), + record: { metadata: { noun: 'document', title: 'doc 41' }, vector: { v: [1, 2] } } + }, + { kind: 'verb', id: UUID(42), record: null } + ], + meta: { source: 'v1' }, + blobHashes: ['abc123'] + }) + }) +}) + +describe('fact-log format v2 — frame envelope helper', () => { + it('framePayload verifies exact length and crc32c', () => { + const frame = encodeFactV2(factOf(1, { type: 'noun.tombstone', id: UUID(1) })) + expect(() => framePayload(frame)).not.toThrow() + + const shortFrame = frame.subarray(0, frame.length - 1) + expect(() => framePayload(shortFrame)).toThrow(/declares/) + + const corrupted = frame.slice() + corrupted[corrupted.length - 1] ^= 0xff + expect(() => framePayload(corrupted)).toThrow(/crc32c/) + }) + + it('the record-type registry and version constants are the frozen wire codes', () => { + expect(LOG_RECORD_TYPES).toStrictEqual({ + PAD: 0, + NOUN_AFTER_IMAGE: 1, + NOUN_TOMBSTONE: 2, + VERB_AFTER_IMAGE: 3, + VERB_TOMBSTONE: 4, + BATCH_META: 5, + EMBED_PENDING: 6, + EMBED_LANDED: 7, + BLOB_MANIFEST: 8, + PROJECTION_NOTE: 9, + BOOTSTRAP_BASELINE: 10, + LOG_GENESIS: 11 + }) + expect(LOG_RECORD_VERSION).toBe(1) + }) +}) diff --git a/tests/unit/db/fault-injection-shim.test.ts b/tests/unit/db/fault-injection-shim.test.ts new file mode 100644 index 00000000..a6d4109e --- /dev/null +++ b/tests/unit/db/fault-injection-shim.test.ts @@ -0,0 +1,231 @@ +/** + * @module tests/unit/db/fault-injection-shim + * @description The fault-injection storage wrapper proven in isolation: a + * torn write persists a decodable prefix (the crash shape durability tests + * replay), a dropped sync is observable (armed → the inner adapter never sees + * it; journaled), a failed append throws without writing a byte, knobs are + * one-shot, and unarmed operation is a transparent passthrough. The full + * commit-path fault matrix lives with the log's ack work — this file proves + * the SHIM itself. + */ +import { describe, it, expect, beforeEach } from 'vitest' +import { MemoryStorage } from '../../../src/storage/adapters/memoryStorage.js' +import { + FactLog, + storageSupportsFactLog, + type CommitFact, + type FactLogStorage +} from '../../../src/db/factLog.js' +import { + FaultInjectionStorage, + FaultInjectedError +} from '../../../src/db/faultInjectionStorage.js' +import { + encodeFactV2, + encodeSegmentHeaderV2, + decodeGroupV2, + parseSegmentHeader, + SEGMENT_HEADER_BYTES, + type CommitFactV2 +} from '../../../src/db/factLogFormat.js' + +const UUID = (n: number): string => + `00000000-0000-4000-8000-${String(n).padStart(12, '0')}` + +const factV2 = (generation: number): CommitFactV2 => ({ + generation, + timestamp: 1_700_000_000_000 + generation, + records: [{ type: 'noun.tombstone', id: UUID(generation) }] +}) + +const factV1 = (generation: number): CommitFact => ({ + generation, + timestamp: 1_700_000_000_000 + generation, + ops: [ + { + kind: 'noun', + id: UUID(generation), + record: { metadata: { noun: 'document' }, vector: null } + } + ] +}) + +describe('fault-injection storage wrapper', () => { + let inner: FactLogStorage & { syncRawObjects: (paths: string[]) => Promise } + let shim: FaultInjectionStorage + let innerSyncCalls: string[][] + + beforeEach(async () => { + const mem: any = new MemoryStorage() + await mem.init() + innerSyncCalls = [] + const realSync = mem.syncRawObjects.bind(mem) + mem.syncRawObjects = async (paths: string[]) => { + innerSyncCalls.push([...paths]) + return realSync(paths) + } + inner = mem + shim = new FaultInjectionStorage(inner) + }) + + it('satisfies the fact-log storage surface (drop-in wrapper)', () => { + expect(storageSupportsFactLog(shim)).toBe(true) + }) + + it('unarmed, every operation is a transparent passthrough', async () => { + await shim.writeRawBytes('seg', new Uint8Array([1, 2, 3])) + await shim.appendRawBytes('seg', new Uint8Array([4, 5])) + expect(Array.from((await shim.readRawBytes('seg'))!)).toEqual([1, 2, 3, 4, 5]) + expect(await shim.rawByteSize('seg')).toBe(5) + expect(Array.from((await inner.readRawBytes('seg'))!)).toEqual([1, 2, 3, 4, 5]) + + await shim.writeRawObject('obj.json', { a: 1 }) + expect(await shim.readRawObject('obj.json')).toEqual({ a: 1 }) + await shim.deleteRawObject('obj.json') + expect(await shim.readRawObject('obj.json')).toBeNull() + + await shim.syncRawObjects(['seg']) + expect(innerSyncCalls).toEqual([['seg']]) + expect(shim.injectedFaults).toEqual([]) + }) + + describe('tearWriteAtByte — a torn write produces a decodable-prefix segment', () => { + it('persists only the first N bytes of the next append; the prefix decodes intact', async () => { + const path = 'facts/seg-test.bfl' + const frame1 = encodeFactV2(factV2(1)) + const frame2 = encodeFactV2(factV2(2)) + + await shim.appendRawBytes(path, encodeSegmentHeaderV2(1, 4096)) + await shim.appendRawBytes(path, frame1) + shim.tearWriteAtByte(frame2.length - 5) // crash 5 bytes before the frame lands + await shim.appendRawBytes(path, frame2) // reports success — the tear is silent + + const bytes = (await inner.readRawBytes(path))! + expect(bytes.length).toBe(SEGMENT_HEADER_BYTES + frame1.length + frame2.length - 5) + + // The "crash": reopen from storage and read what actually survived. + const header = parseSegmentHeader(bytes) + expect(header).toStrictEqual({ formatVersion: 2, firstGeneration: 1, sealSize: 4096 }) + const { facts, validBytes } = decodeGroupV2(bytes.subarray(SEGMENT_HEADER_BYTES)) + expect(facts.map((f) => f.generation)).toEqual([1]) // fact 2's torn frame is invisible + expect(validBytes).toBe(frame1.length) + + expect(shim.injectedFaults).toEqual([ + { + kind: 'torn-write', + path, + requestedBytes: frame2.length, + writtenBytes: frame2.length - 5 + } + ]) + }) + + it('a tear inside the frame prefix (first bytes) leaves the earlier facts intact too', async () => { + const path = 'facts/seg-prefix.bfl' + const frame1 = encodeFactV2(factV2(1)) + await shim.appendRawBytes(path, encodeSegmentHeaderV2(1, 4096)) + await shim.appendRawBytes(path, frame1) + shim.tearWriteAtByte(3) + await shim.appendRawBytes(path, encodeFactV2(factV2(2))) + + const bytes = (await inner.readRawBytes(path))! + const { facts } = decodeGroupV2(bytes.subarray(SEGMENT_HEADER_BYTES)) + expect(facts.map((f) => f.generation)).toEqual([1]) + }) + + it('a tear at byte 0 writes nothing at all', async () => { + shim.tearWriteAtByte(0) + await shim.appendRawBytes('empty.bfl', new Uint8Array([1, 2, 3])) + expect(await inner.readRawBytes('empty.bfl')).toBeNull() + expect(shim.injectedFaults[0]).toMatchObject({ kind: 'torn-write', writtenBytes: 0 }) + }) + + it('is one-shot: the append after the torn one lands whole', async () => { + shim.tearWriteAtByte(1) + await shim.appendRawBytes('seg', new Uint8Array([1, 2, 3, 4])) + await shim.appendRawBytes('seg', new Uint8Array([5, 6])) + expect(Array.from((await inner.readRawBytes('seg'))!)).toEqual([1, 5, 6]) + }) + + it('refuses a negative tear offset', () => { + expect(() => shim.tearWriteAtByte(-1)).toThrow(/non-negative/) + }) + }) + + describe('dropNextSync — a dropped sync is observable', () => { + it('the armed sync never reaches the inner adapter and is journaled', async () => { + shim.dropNextSync() + await shim.syncRawObjects(['a.bfl', 'b.bfl']) + expect(innerSyncCalls).toEqual([]) // the device never saw it + expect(shim.injectedFaults).toEqual([{ kind: 'dropped-sync', paths: ['a.bfl', 'b.bfl'] }]) + }) + + it('is one-shot: the following sync passes through', async () => { + shim.dropNextSync() + await shim.syncRawObjects(['x']) + await shim.syncRawObjects(['y']) + expect(innerSyncCalls).toEqual([['y']]) + }) + }) + + describe('failNextAppend — a failed append throws without writing a byte', () => { + it('throws the typed error, writes nothing, and journals the fault', async () => { + await shim.appendRawBytes('seg', new Uint8Array([1])) + shim.failNextAppend() + await expect(shim.appendRawBytes('seg', new Uint8Array([2, 3]))).rejects.toThrow( + FaultInjectedError + ) + expect(Array.from((await inner.readRawBytes('seg'))!)).toEqual([1]) // untouched + expect(shim.injectedFaults).toEqual([{ kind: 'failed-append', path: 'seg' }]) + // one-shot: the next append succeeds + await shim.appendRawBytes('seg', new Uint8Array([4])) + expect(Array.from((await inner.readRawBytes('seg'))!)).toEqual([1, 4]) + }) + + it('carries the operation and path for programmatic assertions', async () => { + shim.failNextAppend() + try { + await shim.appendRawBytes('some/path.bfl', new Uint8Array([1])) + expect.unreachable('append must throw') + } catch (error) { + const typed = error as FaultInjectedError + expect(typed).toBeInstanceOf(FaultInjectedError) + expect(typed.operation).toBe('append') + expect(typed.path).toBe('some/path.bfl') + } + }) + + it('wins over a simultaneously-armed tear; the tear stays pending for the next append', async () => { + shim.failNextAppend() + shim.tearWriteAtByte(2) + await expect(shim.appendRawBytes('seg', new Uint8Array([1, 2, 3]))).rejects.toThrow( + FaultInjectedError + ) + expect(await inner.readRawBytes('seg')).toBeNull() + await shim.appendRawBytes('seg', new Uint8Array([9, 8, 7])) + expect(Array.from((await inner.readRawBytes('seg'))!)).toEqual([9, 8]) // torn at 2 + expect(shim.injectedFaults.map((f) => f.kind)).toEqual(['failed-append', 'torn-write']) + }) + }) + + describe('composed with the real fact log (v1 surface)', () => { + it('a torn append is truncated away on reopen — the log heals to the intact prefix', async () => { + const log = new FactLog(shim) + await log.open(0) + await log.append(factV1(1)) + await log.sync() + + shim.tearWriteAtByte(10) // fact 2's frame lands 10 bytes long — torn + await log.append(factV1(2)) + await log.sync() + + // The crash: abandon the instance, reopen from what storage actually holds. + const reopened = new FactLog(inner) + await reopened.open(2) // generation 2 committed elsewhere — but its fact is torn + expect(reopened.headGeneration()).toBe(1) + const all: CommitFact[] = [] + for await (const batch of reopened.scanFacts().batches()) all.push(...batch.facts) + expect(all.map((f) => f.generation)).toEqual([1]) + }) + }) +})