@superbee/core 0.2.0-pre.15 → 0.2.0-pre.16

package/dist/file-journaled-backend.js

@@ -37,12 +37,14 @@
  */
 import { promises as fs } from "node:fs";
 import path from "node:path";
+import { assertBlobKey } from "./blob-contract.js";
+import { BLOB_JOURNAL_BOUNDS, assertBlobJournalGuard, captureBlobIntentRecord, captureBlobMutationOptions, decodePreparedBlobIntent } from "./blob-journal.js";
 import { resolveContentType } from "./content-type.js";
-import { OPEN_LOG, STORE_RAW } from "./file-journaled-backend-internal.js";
+import { OPEN_LOG, STORE_RAW, STORE_BYTE_LIMIT } from "./file-journaled-backend-internal.js";
 import { captureFilesystemHostPolicy } from "./filesystem-host.js";
 import { acquireFilesystemMutationLock } from "./filesystem-lock.js";
 import { MalformedDocumentError, parseMarkdown, stringifyDoc } from "./frontmatter.js";
-import { assertDeletionIntent, assertJournalGuard, assertJournalIntentChanges, assertJournalMetaChanges, assertJournalResolutionOptions, assertJournalSnapshot, assertMetaWrite, captureIntentUpdate, captureJournalDeleteOptions, captureJournalGuardOption, captureJournalValue, captureJournalWriteOptions, captureMetaWrite, captureRetireAcknowledged, deletionIntentRecord, IntentHoldConflict, IntentStateConflict, JournalGuardConflict, JournalSnapshotConflict, } from "./journaled-backend.js";
+import { assertDeletionIntent, assertJournalGuard, assertJournalIntentChanges, assertJournalMetaChanges, assertJournalResolutionOptions, assertJournalSnapshot, assertMetaWrite, equalJournalValue, captureIntentUpdate, captureJournalDeleteOptions, captureJournalGuardOption, captureJournalValue, captureJournalWriteOptions, captureMetaWrite, captureRetireAcknowledged, deletionIntentRecord, IntentHoldConflict, IntentStateConflict, JournalGuardConflict, JournalSnapshotConflict, } from "./journaled-backend.js";
 import { mutationActorFromFrontmatter } from "./mutation-attribution.js";
 import { assertSafeBlobKey, assertSafeConceptId, assertSafeReservedDir, assertSafeReservedFilename, compareStorageKeys, pathFromConceptId } from "./paths.js";
 import { parseLeadingFrontmatter } from "./portable-frontmatter.js";
@@ -50,7 +52,7 @@ import { sha256HexOfBytes } from "./sha256.js";
 import { blobVersion, defaultActor, VersionConflict, versionOfBytes } from "./versioning.js";
 // ── on-disk format ─────────────────────────────────────────────────────────────────────────
 /** Bumping this requires a reader for the older layout; open refuses any other format. */
-export const FILE_JOURNAL_FORMAT_VERSION = 1;
+export const FILE_JOURNAL_FORMAT_VERSION = 2;
 export const FILE_JOURNAL_LOG = "store.log";
 export const FILE_JOURNAL_SNAPSHOT = "store.snapshot";
 const SNAPSHOT_TEMP = "store.snapshot.tmp";
@@ -62,8 +64,14 @@ const HEADER = 44;
 /** A record larger than this is refused at write and read as corruption at open. */
 const MAXIMUM_RECORD_BYTES = 256 * 1024 * 1024;
 const DEFAULT_COMPACT_AFTER_BYTES = 8 * 1024 * 1024;
+const isDocumentIntent = (row) => !("recordFamily" in row);
+const documentIntents = (state) => [...state.intents.values()].filter(isDocumentIntent);
+const documentIntent = (state, id) => {
+    const row = state.intents.get(id);
+    return row && isDocumentIntent(row) ? row : undefined;
+};
 function emptyState() {
-    return { documents: new Map(), reserved: new Map(), blobs: new Map(), intents: new Map(), meta: new Map(), sequence: 0 };
+    return { format: 1, documents: new Map(), reserved: new Map(), blobs: new Map(), intents: new Map(), meta: new Map(), sequence: 0 };
 }
 function applyChanges(state, changes) {
     for (const change of changes) {
@@ -120,7 +128,7 @@ export class FileJournalFormatError extends FileJournalCorruptError {
     name = "FileJournalFormatError";
     format;
     constructor(file, format, offset) {
-        super(file, `written in store format ${format}; this adapter reads only format ${FILE_JOURNAL_FORMAT_VERSION}`, offset);
+        super(file, `written in store format ${format}; this adapter reads formats 1 and ${FILE_JOURNAL_FORMAT_VERSION}`, offset);
         this.format = format;
     }
 }
@@ -297,10 +305,10 @@ const encodePayload = (value) => utf8.encode(JSON.stringify(encodeValue(value, n
 const decodePayload = (bytes) => decodeValue(JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes)));
 // ── framing ────────────────────────────────────────────────────────────────────────────────
 /** magic (4) + format version (4) + payload length (4) + SHA-256 of the payload (32), then the payload. */
-function frame(magic, payload) {
+function frame(magic, payload, format) {
     const out = Buffer.alloc(HEADER + payload.byteLength);
     out.writeUInt32BE(magic, 0);
-    out.writeUInt32BE(FILE_JOURNAL_FORMAT_VERSION, 4);
+    out.writeUInt32BE(format, 4);
     out.writeUInt32BE(payload.byteLength, 8);
     Buffer.from(sha256HexOfBytes(payload), "hex").copy(out, 12);
     Buffer.from(payload.buffer, payload.byteOffset, payload.byteLength).copy(out, HEADER);
@@ -347,7 +355,7 @@ function scanLog(bytes, file) {
                 throw new FileJournalCorruptError(file, "a damaged record is followed by a whole one", at);
             return { records, validBytes: at, totalBytes: bytes.byteLength };
         }
-        if (found.format !== FILE_JOURNAL_FORMAT_VERSION)
+        if (found.format !== 1 && found.format !== 2)
             throw new FileJournalFormatError(file, found.format, at);
         let record;
         try {
@@ -358,6 +366,10 @@ function scanLog(bytes, file) {
         }
         if (!record || !Number.isSafeInteger(record.txn) || !Array.isArray(record.changes))
             throw new FileJournalCorruptError(file, "record has no transaction number or changes", at);
+        if ((found.format === 2 ? record.format !== 2 : record.format !== undefined && record.format !== 1))
+            throw new FileJournalCorruptError(file, "record format does not match its frame", at);
+        validateIntentChanges(record.changes, found.format, file);
+        record.format = found.format;
         records.push(record);
         at = found.end;
     }
@@ -369,7 +381,7 @@ function decodeSnapshot(bytes, file) {
     const found = frameAt(bytes, 0, SNAPSHOT_MAGIC);
     if (!found || found.end !== bytes.byteLength)
         throw new FileJournalCorruptError(file, "snapshot checksum or length does not match");
-    if (found.format !== FILE_JOURNAL_FORMAT_VERSION)
+    if (found.format !== 1 && found.format !== 2)
         throw new FileJournalFormatError(file, found.format);
     let decoded;
     try {
@@ -378,10 +390,68 @@ function decodeSnapshot(bytes, file) {
     catch {
         throw new FileJournalCorruptError(file, "snapshot checksum matches but its payload does not decode");
     }
-    if (!decoded || decoded.format !== FILE_JOURNAL_FORMAT_VERSION || !Number.isSafeInteger(decoded.txn) || !Number.isSafeInteger(decoded.sequence))
+    if (!decoded || decoded.format !== found.format || !Number.isSafeInteger(decoded.txn) || !Number.isSafeInteger(decoded.sequence))
         throw new FileJournalCorruptError(file, "snapshot has no transaction number");
+    if (!Array.isArray(decoded.intents))
+        throw new FileJournalCorruptError(file, "snapshot has no intent records");
+    validateIntentChanges(decoded.intents.map(([key, value]) => ({ family: "intent", key, value })), found.format, file);
     return decoded;
 }
+function validateIntentChanges(changes, format, file) {
+    for (const change of changes) {
+        if (change.family !== "intent" || change.value === null)
+            continue;
+        const row = change.value;
+        if ("recordFamily" in row) {
+            if (row.recordFamily !== "blob" || format !== 2)
+                throw new FileJournalCorruptError(file, "blob intent is not allowed in this format");
+            try {
+                captureBlobIntentRecord(row);
+                assertReceiptBound(row);
+            }
+            catch {
+                throw new FileJournalCorruptError(file, "invalid blob intent payload");
+            }
+            if (row.requestId !== change.key)
+                throw new FileJournalCorruptError(file, "blob identity index mismatch");
+        }
+    }
+}
+function snapshotPayload(state, txn) {
+    return { format: state.format, txn, sequence: state.sequence, documents: [...state.documents], reserved: [...state.reserved], blobs: [...state.blobs], intents: [...state.intents], meta: [...state.meta] };
+}
+/** Terminal evidence must fit the space protected when its pending record was admitted. */
+function assertReceiptBound(row) {
+    if (row.receipt !== undefined)
+        assertByteBound(encodePayload(row.receipt), BLOB_JOURNAL_BOUNDS.terminalReceiptBytes, "blob terminal receipt");
+}
+/** Derived from existing records only: no persisted reservation map or quota ledger. The
+ * mutable projection (including transaction-number width) is subtracted so claiming an
+ * attempt/state cannot consume its own reserve.
+ * The 4 KiB structural allowance covers the terminal record envelope/tagging and counter/time
+ * changes; the additional 16 KiB is aggregate encoded growth of ordinary baseline metadata.
+ * Arbitrary extra metadata growth still requires unreserved store capacity. */
+function settlementReserve(state, txn) {
+    let reserved = 0;
+    for (const row of state.intents.values()) {
+        if (isDocumentIntent(row))
+            continue;
+        // All stored blob rows passed captureBlobIntentRecord and assertReceiptBound, including
+        // replay. Unknown/nonterminal evidence can never release this allocation.
+        if (row.receipt !== undefined && ["acknowledged", "refused", "conflict"].includes(row.state))
+            continue;
+        const mutableBytes = encodePayload({ state: row.state, attempts: row.attempts, updatedAt: row.updatedAt, transaction: txn, ...(row.notAppliedThrough === undefined ? {} : { notAppliedThrough: row.notAppliedThrough }), ...(row.deletionHold === undefined ? {} : { deletionHold: row.deletionHold }) }).byteLength;
+        const remaining = BLOB_JOURNAL_BOUNDS.terminalReceiptBytes + BLOB_JOURNAL_BOUNDS.settlementStructureBytes + BLOB_JOURNAL_BOUNDS.baselineBytes - mutableBytes;
+        if (!Number.isSafeInteger(remaining) || remaining < 0 || !Number.isSafeInteger(reserved + remaining))
+            throw new RangeError("blob settlement reserve is not representable");
+        reserved += remaining;
+    }
+    return reserved;
+}
+function assertByteBound(payload, maximum, family) {
+    if (payload.byteLength > maximum)
+        throw new RangeError(`a ${family} of ${payload.byteLength} bytes exceeds the store's ${maximum} byte bound`);
+}
 // ── helpers shared with the other adapters' record handling ────────────────────────────────
 function notFound(id) {
     const err = new Error(`no concept document '${id}'`);
@@ -506,6 +576,7 @@ export class FileJournaledBackend {
     #release;
     #policy;
     #txn;
+    #maximumBytes = MAXIMUM_RECORD_BYTES;
     #logBytes;
     #queue = Promise.resolve();
     #unavailable = null;
@@ -565,9 +636,13 @@ export class FileJournaledBackend {
             const logRead = await readIfPresent(logFile);
             const logBytes = logRead ?? Buffer.alloc(0);
             const scanned = scanLog(logBytes, logFile);
+            const maximumBytes = options[STORE_BYTE_LIMIT] ?? MAXIMUM_RECORD_BYTES;
+            if (!Number.isSafeInteger(maximumBytes) || maximumBytes < 1 || maximumBytes > MAXIMUM_RECORD_BYTES)
+                throw new TypeError("invalid store byte bound");
             const state = emptyState();
             let txn = 0;
             if (snapshot) {
+                state.format = snapshot.format;
                 state.documents = new Map(snapshot.documents);
                 state.reserved = new Map(snapshot.reserved);
                 state.blobs = new Map(snapshot.blobs);
@@ -582,11 +657,15 @@ export class FileJournaledBackend {
                     continue;
                 if (record.txn !== txn + 1)
                     throw new FileJournalCorruptError(logFile, `transaction ${record.txn} follows ${txn}`);
+                if (record.format < state.format)
+                    throw new FileJournalCorruptError(logFile, "store format regressed");
+                state.format = record.format;
                 applyChanges(state, record.changes);
                 txn = record.txn;
             }
             if (options.readOnly) {
                 const backend = new FileJournaledBackend(directory, state, READ_ONLY_LOG, release, txn, scanned.validBytes, policy);
+                backend.#maximumBytes = maximumBytes;
                 backend.#readOnly = true;
                 return backend;
             }
@@ -601,6 +680,7 @@ export class FileJournaledBackend {
                 await log.sync();
             }
             const backend = new FileJournaledBackend(directory, state, log, release, txn, scanned.validBytes, policy);
+            backend.#maximumBytes = maximumBytes;
             if (scanned.validBytes > compactAfter)
                 await backend.compact();
             return backend;
@@ -639,17 +719,9 @@ export class FileJournaledBackend {
     compact() {
         return this.#serial(async () => {
             const state = this.#state;
-            const payload = {
-                format: FILE_JOURNAL_FORMAT_VERSION,
-                txn: this.#txn,
-                sequence: state.sequence,
-                documents: [...state.documents],
-                reserved: [...state.reserved],
-                blobs: [...state.blobs],
-                intents: [...state.intents],
-                meta: [...state.meta],
-            };
-            const bytes = frame(SNAPSHOT_MAGIC, encodePayload(payload));
+            const encoded = encodePayload(snapshotPayload(state, this.#txn));
+            assertByteBound(encoded, this.#maximumBytes, "snapshot");
+            const bytes = frame(SNAPSHOT_MAGIC, encoded, state.format);
             const temp = path.join(this.directory, SNAPSHOT_TEMP);
             const handle = await fs.open(temp, "w", 0o600);
             try {
@@ -697,14 +769,23 @@ export class FileJournaledBackend {
      */
     #mutate(decide) {
         return this.#serial(async () => {
-            const { changes, result } = decide(this.#state);
+            const { changes, result, format } = decide(this.#state);
             if (changes.length === 0)
                 return result;
-            const record = { txn: this.#txn + 1, changes };
+            const nextFormat = Math.max(this.#state.format, format ?? 1);
+            const record = { ...(nextFormat === 2 ? { format: 2 } : {}), txn: this.#txn + 1, changes };
             const payload = encodePayload(record);
-            if (payload.byteLength > MAXIMUM_RECORD_BYTES)
-                throw new RangeError(`a transaction of ${payload.byteLength} bytes exceeds the log's record bound`);
-            const bytes = frame(RECORD_MAGIC, payload);
+            assertByteBound(payload, this.#maximumBytes, "transaction");
+            const projected = { ...this.#state, format: nextFormat, documents: new Map(this.#state.documents), reserved: new Map(this.#state.reserved), blobs: new Map(this.#state.blobs), intents: new Map(this.#state.intents), meta: new Map(this.#state.meta) };
+            applyChanges(projected, changes);
+            const snapshotBytes = encodePayload(snapshotPayload(projected, record.txn));
+            assertByteBound(snapshotBytes, this.#maximumBytes, "projected snapshot");
+            if (nextFormat === 2) {
+                const reserved = settlementReserve(projected, record.txn);
+                if (snapshotBytes.byteLength + reserved > this.#maximumBytes)
+                    throw new RangeError(`a projected snapshot of ${snapshotBytes.byteLength} bytes plus ${reserved} bytes of blob settlement reserve exceeds the store's ${this.#maximumBytes} byte bound`);
+            }
+            const bytes = frame(RECORD_MAGIC, payload, nextFormat);
             const at = this.#logBytes;
             try {
                 await writeAll(this.#log, bytes, at);
@@ -722,6 +803,7 @@ export class FileJournaledBackend {
             }
             this.#logBytes = at + bytes.byteLength;
             this.#txn = record.txn;
+            this.#state.format = nextFormat;
             applyChanges(this.#state, changes);
             return result;
         });
@@ -876,12 +958,12 @@ export class FileJournaledBackend {
         assertJournalGuard(guard, {
             target: guard.target,
             document: document ? { version: document.version, raw: document.raw } : null,
-            intents: [...state.intents.values()].filter((row) => row.target === guard.target),
+            intents: documentIntents(state).filter((row) => row.target === guard.target),
             meta: guard.meta.map((row) => ({ key: row.key, expected: state.meta.has(row.key) ? { present: true, value: state.meta.get(row.key) } : { present: false } })),
         });
     }
     static #holder(state, id) {
-        return [...state.intents.values()].sort(bySequence).find((row) => row.target === id && row.state !== "acknowledged");
+        return documentIntents(state).sort(bySequence).find((row) => row.target === id && row.state !== "acknowledged");
     }
     static #metaChanges(puts, removals = []) {
         return [
@@ -908,6 +990,8 @@ export class FileJournaledBackend {
         const meta = structuredClone(producedMeta);
         const removeMeta = options.removeMeta ? [...options.removeMeta] : [];
         const intent = options.intent ? structuredClone(options.intent) : undefined;
+        if (intent && "recordFamily" in intent)
+            throw new JournalGuardConflict(id);
         const supersede = options.supersede ? { ...options.supersede } : undefined;
         const resolveIntents = options.resolveIntents ? structuredClone(options.resolveIntents) : undefined;
         const { requireSettled } = options;
@@ -917,8 +1001,10 @@ export class FileJournaledBackend {
         return this.#mutate((state) => {
             this.#checkGuard(state, snapshotGuard);
             assertJournalIntentChanges(snapshotGuard, intent ? state.intents.get(intent.requestId) : undefined, supersede ? state.intents.get(supersede.requestId) : undefined);
+            if (intent && state.intents.has(intent.requestId))
+                throw new JournalSnapshotConflict(id);
             if (resolveIntents)
-                assertJournalSnapshot(id, resolveIntents.expected, [...state.intents.values()], intent?.requestId);
+                assertJournalSnapshot(id, resolveIntents.expected, documentIntents(state), intent?.requestId);
             if (requireSettled) {
                 const holder = FileJournaledBackend.#holder(state, id);
                 if (holder)
@@ -928,7 +1014,7 @@ export class FileJournaledBackend {
             if (expected !== undefined && expected !== current)
                 throw new VersionConflict(id, expected, current);
             if (supersede) {
-                const existing = state.intents.get(supersede.requestId);
+                const existing = documentIntent(state, supersede.requestId);
                 if (!existing || existing.state !== supersede.expectedState || existing.attempts !== supersede.expectedAttempts)
                     throw new IntentStateConflict(supersede.requestId, supersede.expectedState, existing?.state ?? null);
             }
@@ -954,12 +1040,14 @@ export class FileJournaledBackend {
         assertDeletionIntent(id, options);
         const captured = structuredClone({ meta: options.meta ?? [], removeMeta: [...(options.removeMeta ?? [])], onHeld: options.onHeld, resolveIntents: options.resolveIntents, intent: options.intent, supersede: options.supersede });
         const { guard, requireSettled } = options;
+        if (captured.intent && "recordFamily" in captured.intent)
+            throw new JournalGuardConflict(id);
         const expected = options.expectedVersion;
         const now = new Date().toISOString();
         return this.#mutate((state) => {
             this.#checkGuard(state, guard);
             if (captured.resolveIntents)
-                assertJournalSnapshot(id, captured.resolveIntents.expected, [...state.intents.values()], captured.intent?.requestId);
+                assertJournalSnapshot(id, captured.resolveIntents.expected, documentIntents(state), captured.intent?.requestId);
             if (captured.intent && state.intents.has(captured.intent.requestId))
                 throw new JournalSnapshotConflict(id);
             if (requireSettled) {
@@ -975,7 +1063,7 @@ export class FileJournaledBackend {
                 throw new VersionConflict(id, expected, current);
             const { supersede } = captured;
             if (supersede) {
-                const existing = state.intents.get(supersede.requestId);
+                const existing = documentIntent(state, supersede.requestId);
                 if (!existing || existing.target !== id || existing.state !== supersede.expectedState || existing.attempts !== supersede.expectedAttempts)
                     throw new IntentStateConflict(supersede.requestId, supersede.expectedState, existing?.state ?? null);
             }
@@ -1001,7 +1089,7 @@ export class FileJournaledBackend {
         this.#assertOpen();
         const state = this.#state;
         const record = state.documents.get(id);
-        const intents = [...state.intents.values()].filter((row) => row.target === id).sort(bySequence).map((row) => structuredClone(row));
+        const intents = documentIntents(state).filter((row) => row.target === id).sort(bySequence).map((row) => structuredClone(row));
         const meta = new Map();
         for (const key of options.meta ?? []) {
             if (state.meta.has(key))
@@ -1021,7 +1109,7 @@ export class FileJournaledBackend {
         // One synchronous pass: no mutation can apply between the first row and the last.
         const edition = editionOf(state.reserved.get(reservedKey("", "index.md")));
         const byTarget = new Map();
-        for (const row of state.intents.values()) {
+        for (const row of documentIntents(state)) {
             const list = byTarget.get(row.target);
             if (list)
                 list.push(row);
@@ -1049,15 +1137,17 @@ export class FileJournaledBackend {
     async listIntents(state) {
         this.#assertOpen();
         const wanted = state === undefined ? null : new Set(typeof state === "string" ? [state] : state);
-        return [...this.#state.intents.values()].filter((row) => !wanted || wanted.has(row.state)).sort(bySequence).map((row) => structuredClone(row));
+        return documentIntents(this.#state).filter((row) => !wanted || wanted.has(row.state)).sort(bySequence).map((row) => structuredClone(row));
     }
     async readIntent(requestId) {
         this.#assertOpen();
-        const row = this.#state.intents.get(requestId);
+        const row = documentIntent(this.#state, requestId);
         return row ? structuredClone(row) : undefined;
     }
     async updateIntent(requestId, expectedState, patch, options = {}) {
         ({ patch, options } = captureIntentUpdate(patch, options));
+        if ("recordFamily" in patch)
+            throw new JournalGuardConflict(requestId);
         const now = new Date().toISOString();
         const raw = options.document ? stringifyDoc(options.document.frontmatter, options.document.body ?? "") : undefined;
         const replacement = raw === undefined ? undefined : { id: options.document.id, record: { raw, version: versionOfBytes(raw), updatedBy: defaultActor(), updatedAt: now } };
@@ -1065,7 +1155,7 @@ export class FileJournaledBackend {
         const meta = options.meta ?? [];
         return this.#mutate((state) => {
             this.#checkGuard(state, guard);
-            const current = state.intents.get(requestId);
+            const current = documentIntent(state, requestId);
             if (!current || current.state !== expectedState)
                 throw new IntentStateConflict(requestId, expectedState, current?.state ?? null);
             if (guard && current.target !== guard.target)
@@ -1087,6 +1177,124 @@ export class FileJournaledBackend {
             return { changes: [...changes, ...FileJournaledBackend.#metaChanges([], removeMeta ?? [])], result: undefined };
         });
     }
+    // ── optional ordinary-file journal (no filesystem/body mirror) ─────────────────────────
+    #blobGuard(state, guard) {
+        assertBlobJournalGuard(guard, {
+            key: guard.key,
+            intents: [...state.intents.values()].filter((row) => !isDocumentIntent(row) && row.target === guard.key),
+            meta: guard.meta.map(row => ({ key: row.key, expected: state.meta.has(row.key) ? { present: true, value: state.meta.get(row.key) } : { present: false } })),
+        });
+    }
+    async readBlobWithJournal(key, options = {}) {
+        assertBlobKey(key);
+        this.#assertOpen();
+        const state = this.#state;
+        const intents = [...state.intents.values()].filter((row) => !isDocumentIntent(row) && row.target === key).sort(bySequence).map(row => structuredClone(row));
+        const meta = new Map();
+        const premises = [];
+        for (const name of new Set(options.meta ?? [])) {
+            if (typeof name !== "string")
+                throw new JournalGuardConflict(key);
+            if (state.meta.has(name)) {
+                const value = structuredClone(state.meta.get(name));
+                meta.set(name, value);
+                premises.push({ key: name, expected: { present: true, value: structuredClone(value) } });
+            }
+            else
+                premises.push({ key: name, expected: { present: false } });
+        }
+        return { key, intents, meta, guard: { key, intents: structuredClone(intents), meta: premises } };
+    }
+    async writeBlobMeta(key, changes, options) {
+        assertBlobKey(key);
+        const captured = captureBlobMutationOptions({ ...captureJournalValue(changes), guard: options.guard });
+        if (captured.guard.key !== key)
+            throw new JournalGuardConflict(key);
+        await this.#mutate(state => {
+            this.#blobGuard(state, captured.guard);
+            return { changes: FileJournaledBackend.#metaChanges(captured.meta ?? [], captured.removeMeta ?? []), result: undefined };
+        });
+    }
+    async admitPreparedBlob(prepared, options) {
+        const captured = decodePreparedBlobIntent(prepared);
+        options = captureBlobMutationOptions(options);
+        const { guard, meta = [], removeMeta = [] } = options;
+        if (guard.key !== captured.intent.key)
+            throw new JournalGuardConflict(captured.intent.key);
+        const now = new Date().toISOString();
+        return this.#mutate(state => {
+            this.#blobGuard(state, guard);
+            if (state.intents.has(captured.identity.requestId))
+                throw new JournalSnapshotConflict(guard.key);
+            const sequence = state.sequence + 1;
+            if (!Number.isSafeInteger(sequence))
+                throw new RangeError("journal sequence exhausted");
+            const record = captureBlobIntentRecord({ recordFamily: "blob", requestId: captured.identity.requestId, target: captured.intent.key, prepared, sequence, attempts: 0, state: "pending", updatedAt: now });
+            return { format: 2, changes: [{ family: "sequence", value: sequence }, { family: "intent", key: record.requestId, value: structuredClone(record) }, ...FileJournaledBackend.#metaChanges(meta, removeMeta)], result: record };
+        });
+    }
+    async listBlobIntents(state) {
+        this.#assertOpen();
+        const wanted = state === undefined ? null : new Set(typeof state === "string" ? [state] : state);
+        return [...this.#state.intents.values()].filter((row) => !isDocumentIntent(row) && (!wanted || wanted.has(row.state))).sort(bySequence).map(row => structuredClone(row));
+    }
+    async readBlobIntent(requestId) {
+        this.#assertOpen();
+        const row = this.#state.intents.get(requestId);
+        return row && !isDocumentIntent(row) ? structuredClone(row) : undefined;
+    }
+    async updateBlobIntent(requestId, expectedState, patch, options) {
+        patch = captureJournalValue(patch);
+        options = captureBlobMutationOptions(options);
+        if (!patch || typeof patch !== "object" || Array.isArray(patch) || Object.keys(patch).some(key => !["state", "attempts", "receipt", "notAppliedThrough", "deletionHold"].includes(key)))
+            throw new JournalGuardConflict(options.guard.key);
+        const { guard, meta = [], removeMeta = [] } = options;
+        const now = new Date().toISOString();
+        return this.#mutate(state => {
+            this.#blobGuard(state, guard);
+            const current = state.intents.get(requestId);
+            if (!current || isDocumentIntent(current) || current.state !== expectedState)
+                throw new IntentStateConflict(requestId, expectedState, current?.state ?? null);
+            if (current.target !== guard.key)
+                throw new JournalGuardConflict(guard.key);
+            const next = captureBlobIntentRecord({ ...current, ...patch, updatedAt: now });
+            assertReceiptBound(next);
+            const beforePrefix = current.notAppliedThrough ?? 0, afterPrefix = next.notAppliedThrough ?? 0;
+            const sameHold = equalJournalValue(current.deletionHold, next.deletionHold);
+            if (current.receipt && (next.attempts !== current.attempts || next.state !== current.state || !equalJournalValue(current.receipt, next.receipt) || afterPrefix !== beforePrefix || !sameHold))
+                throw new JournalGuardConflict(guard.key);
+            if (next.attempts !== current.attempts) {
+                // The durable claim consumes exactly one eligibility before any wire operation.
+                if (current.receipt || !["pending", "unknown"].includes(current.state) || next.state !== "in_flight" || next.attempts !== current.attempts + 1 || beforePrefix !== current.attempts || afterPrefix !== beforePrefix || !sameHold)
+                    throw new JournalGuardConflict(guard.key);
+            }
+            else if (afterPrefix !== beforePrefix) {
+                // Typed evidence belongs to this exact claimed count and must extend the complete prefix.
+                if (current.receipt || !["in_flight", "unknown"].includes(current.state) || next.state !== "pending" || patch.attempts !== current.attempts || beforePrefix !== current.attempts - 1 || afterPrefix !== current.attempts || patch.deletionHold === undefined || next.receipt !== undefined)
+                    throw new JournalGuardConflict(guard.key);
+            }
+            else if (!sameHold || patch.state === "in_flight")
+                throw new JournalGuardConflict(guard.key);
+            return { changes: [{ family: "intent", key: requestId, value: structuredClone(next) }, ...FileJournaledBackend.#metaChanges(meta, removeMeta)], result: next };
+        });
+    }
+    async retireBlobIntents(key, requestIds, options) {
+        assertBlobKey(key);
+        const ids = captureJournalValue([...requestIds]);
+        options = captureBlobMutationOptions(options);
+        const { guard, meta = [], removeMeta = [] } = options;
+        if (guard.key !== key || ids.length === 0 || ids.some(id => typeof id !== "string") || new Set(ids).size !== ids.length)
+            throw new JournalGuardConflict(key);
+        await this.#mutate(state => {
+            this.#blobGuard(state, guard);
+            for (const id of ids) {
+                const row = state.intents.get(id);
+                if (!row || isDocumentIntent(row) || row.target !== key || !row.receipt || !["acknowledged", "refused", "conflict"].includes(row.state))
+                    throw new JournalGuardConflict(key);
+            }
+            return { changes: [...ids.map((id) => ({ family: "intent", key: id, value: null })), ...FileJournaledBackend.#metaChanges(meta, removeMeta)], result: undefined };
+        });
+    }
     async readMeta(key) {
         this.#assertOpen();
         return this.#state.meta.has(key) ? structuredClone(this.#state.meta.get(key)) : undefined;