@superbee/core 0.2.0-pre.17 → 0.2.0-pre.19

package/dist/file-journaled-backend.js

@@ -1,5 +1,8 @@
 /**
- * Experimental (`0.2.0-pre`): the API and the on-disk format may change before a stable release.
+ * The API is experimental (`0.2.0-pre`) and may change before a stable release. The on-disk
+ * format is a supported compatibility promise, because the hosted client's durable journal
+ * (`openHostedClientJournal`) keeps app state in it: a format bump ships a reader for the older
+ * layout, or a migration.
  *
  * A Node {@link JournaledBackend}: the private store behind a CLI working copy, proven by the
  * same contract kit as the IndexedDB adapter. It is an append-only, checksummed transaction log
@@ -35,24 +38,30 @@
  * entry of every file the store created. On macOS `fsync` does not force the drive's own cache
  * (Node exposes no `F_FULLFSYNC`), which is the same promise every Node program gets there.
  */
+var _a;
 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 { BLOB_JOURNAL_BOUNDS, captureBlobAdmission, captureBlobForget, captureBlobIntentRecord, captureBlobMetaWrite, captureBlobRetirement, captureBlobUpdate, decideBlobAdmission, decideBlobForget, decideBlobMetaWrite, decideBlobRetirement, decideBlobUpdate, readBlobJournal, } from "./blob-journal.js";
 import { resolveContentType } from "./content-type.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, equalJournalValue, captureIntentUpdate, captureJournalDeleteOptions, captureJournalGuardOption, captureJournalValue, captureJournalWriteOptions, captureMetaWrite, captureRetireAcknowledged, deletionIntentRecord, IntentHoldConflict, IntentStateConflict, JournalGuardConflict, JournalSnapshotConflict, } from "./journaled-backend.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 { mutationActorFromFrontmatter } from "./mutation-attribution.js";
 import { assertSafeBlobKey, assertSafeConceptId, assertSafeReservedDir, assertSafeReservedFilename, compareStorageKeys, pathFromConceptId } from "./paths.js";
 import { parseLeadingFrontmatter } from "./portable-frontmatter.js";
 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 = 2;
+/**
+ * The newest layout this adapter writes and reads; it reads every earlier one too. A store stays
+ * at format 1 until it holds a blob intent (format 2), and at 2 until a blob intent carries
+ * not-dispatched evidence (format 3); the store keeps the highest format it has written. Bumping
+ * this requires a reader for the older layouts; open refuses any newer format.
+ */
+export const FILE_JOURNAL_FORMAT_VERSION = 3;
 export const FILE_JOURNAL_LOG = "store.log";
 export const FILE_JOURNAL_SNAPSHOT = "store.snapshot";
 const SNAPSHOT_TEMP = "store.snapshot.tmp";
@@ -128,7 +137,7 @@ export class FileJournalFormatError extends FileJournalCorruptError {
     name = "FileJournalFormatError";
     format;
     constructor(file, format, offset) {
-        super(file, `written in store format ${format}; this adapter reads formats 1 and ${FILE_JOURNAL_FORMAT_VERSION}`, offset);
+        super(file, `written in store format ${format}; this adapter reads formats 1 to ${FILE_JOURNAL_FORMAT_VERSION}`, offset);
         this.format = format;
     }
 }
@@ -355,7 +364,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 !== 1 && found.format !== 2)
+        if (!readableFormat(found.format))
             throw new FileJournalFormatError(file, found.format, at);
         let record;
         try {
@@ -366,7 +375,7 @@ 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))
+        if ((found.format >= 2 ? record.format !== found.format : 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;
@@ -381,7 +390,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 !== 1 && found.format !== 2)
+    if (!readableFormat(found.format))
         throw new FileJournalFormatError(file, found.format);
     let decoded;
     try {
@@ -397,14 +406,19 @@ function decodeSnapshot(bytes, file) {
     validateIntentChanges(decoded.intents.map(([key, value]) => ({ family: "intent", key, value })), found.format, file);
     return decoded;
 }
+const readableFormat = (format) => Number.isSafeInteger(format) && format >= 1 && format <= FILE_JOURNAL_FORMAT_VERSION;
+/** The layout a blob intent needs: not-dispatched evidence first appeared in format 3. */
+const blobIntentFormat = (row) => ("notDispatched" in row ? 3 : 2);
 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)
+            if (row.recordFamily !== "blob" || format < 2)
                 throw new FileJournalCorruptError(file, "blob intent is not allowed in this format");
+            if (blobIntentFormat(row) > format)
+                throw new FileJournalCorruptError(file, "blob not-dispatched evidence is not allowed in this format");
             try {
                 captureBlobIntentRecord(row);
                 assertReceiptBound(row);
@@ -440,7 +454,7 @@ function settlementReserve(state, txn) {
         // 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 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 }), ...(row.notDispatched === undefined ? {} : { notDispatched: row.notDispatched }) }).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");
@@ -579,6 +593,9 @@ export class FileJournaledBackend {
     #maximumBytes = MAXIMUM_RECORD_BYTES;
     #logBytes;
     #queue = Promise.resolve();
+    /** Blob claims this handle made, by request id, at their attempt count. The exclusive lock means
+     * any `in_flight` row found at open was claimed by a process that has since died. */
+    #claims = new Map();
     #unavailable = null;
     #closing = null;
     #readOnly = false;
@@ -597,11 +614,11 @@ export class FileJournaledBackend {
      * file. Compacts when the log is larger than `compactAfterBytes`.
      */
     static open(options) {
-        return FileJournaledBackend.#open(options, (file) => fs.open(file, "r+"));
+        return _a.#open(options, (file) => fs.open(file, "r+"));
     }
     /** @internal The test seam: open with a substitute log handle. Reachable only through {@link OPEN_LOG}. */
     static [OPEN_LOG](options, openLog) {
-        return FileJournaledBackend.#open(options, openLog);
+        return _a.#open(options, openLog);
     }
     static async #open(options, openLog) {
         if (typeof options.directory !== "string" || options.directory.trim() === "")
@@ -664,7 +681,7 @@ export class FileJournaledBackend {
                 txn = record.txn;
             }
             if (options.readOnly) {
-                const backend = new FileJournaledBackend(directory, state, READ_ONLY_LOG, release, txn, scanned.validBytes, policy);
+                const backend = new _a(directory, state, READ_ONLY_LOG, release, txn, scanned.validBytes, policy);
                 backend.#maximumBytes = maximumBytes;
                 backend.#readOnly = true;
                 return backend;
@@ -679,7 +696,7 @@ export class FileJournaledBackend {
                 await log.truncate(scanned.validBytes);
                 await log.sync();
             }
-            const backend = new FileJournaledBackend(directory, state, log, release, txn, scanned.validBytes, policy);
+            const backend = new _a(directory, state, log, release, txn, scanned.validBytes, policy);
             backend.#maximumBytes = maximumBytes;
             if (scanned.validBytes > compactAfter)
                 await backend.compact();
@@ -769,18 +786,20 @@ export class FileJournaledBackend {
      */
     #mutate(decide) {
         return this.#serial(async () => {
-            const { changes, result, format } = decide(this.#state);
-            if (changes.length === 0)
+            const { changes, result, format, afterCommit } = decide(this.#state);
+            if (changes.length === 0) {
+                afterCommit?.();
                 return result;
+            }
             const nextFormat = Math.max(this.#state.format, format ?? 1);
-            const record = { ...(nextFormat === 2 ? { format: 2 } : {}), txn: this.#txn + 1, changes };
+            const record = { ...(nextFormat >= 2 ? { format: nextFormat } : {}), txn: this.#txn + 1, changes };
             const payload = encodePayload(record);
             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) {
+            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`);
@@ -805,6 +824,7 @@ export class FileJournaledBackend {
             this.#txn = record.txn;
             this.#state.format = nextFormat;
             applyChanges(this.#state, changes);
+            afterCommit?.();
             return result;
         });
     }
@@ -1006,7 +1026,7 @@ export class FileJournaledBackend {
             if (resolveIntents)
                 assertJournalSnapshot(id, resolveIntents.expected, documentIntents(state), intent?.requestId);
             if (requireSettled) {
-                const holder = FileJournaledBackend.#holder(state, id);
+                const holder = _a.#holder(state, id);
                 if (holder)
                     throw new IntentHoldConflict(id, holder.requestId, holder.state);
             }
@@ -1029,7 +1049,7 @@ export class FileJournaledBackend {
                 record = { ...intent, local: version, content: raw, sequence, attempts: 0, state: "pending", updatedAt: now };
                 changes.push({ family: "sequence", value: sequence }, { family: "intent", key: record.requestId, value: structuredClone(record) });
             }
-            changes.push(...FileJournaledBackend.#metaChanges(meta, removeMeta));
+            changes.push(..._a.#metaChanges(meta, removeMeta));
             return { changes, result: { version, raw, intent: record } };
         });
     }
@@ -1051,11 +1071,11 @@ export class FileJournaledBackend {
             if (captured.intent && state.intents.has(captured.intent.requestId))
                 throw new JournalSnapshotConflict(id);
             if (requireSettled) {
-                const holder = FileJournaledBackend.#holder(state, id);
+                const holder = _a.#holder(state, id);
                 if (holder) {
                     if (!captured.onHeld)
                         throw new IntentHoldConflict(id, holder.requestId, holder.state);
-                    return { changes: FileJournaledBackend.#metaChanges(captured.onHeld.meta), result: { outcome: "held", requestId: holder.requestId, state: holder.state } };
+                    return { changes: _a.#metaChanges(captured.onHeld.meta), result: { outcome: "held", requestId: holder.requestId, state: holder.state } };
                 }
             }
             const current = state.documents.get(id)?.version ?? null;
@@ -1080,7 +1100,7 @@ export class FileJournaledBackend {
                 record = deletionIntentRecord(captured.intent, sequence, now);
                 changes.push({ family: "sequence", value: sequence }, { family: "intent", key: record.requestId, value: structuredClone(record) });
             }
-            changes.push(...FileJournaledBackend.#metaChanges(captured.meta, captured.removeMeta));
+            changes.push(..._a.#metaChanges(captured.meta, captured.removeMeta));
             return { changes, result: { outcome: current !== null ? "deleted" : "absent", ...(record ? { intent: record } : {}) } };
         });
     }
@@ -1164,7 +1184,7 @@ export class FileJournaledBackend {
             const changes = [];
             if (replacement)
                 changes.push({ family: "document", key: replacement.id, value: replacement.record });
-            changes.push({ family: "intent", key: requestId, value: structuredClone(next) }, ...FileJournaledBackend.#metaChanges(meta));
+            changes.push({ family: "intent", key: requestId, value: structuredClone(next) }, ..._a.#metaChanges(meta));
             return { changes, result: next };
         });
     }
@@ -1174,64 +1194,63 @@ export class FileJournaledBackend {
         await this.#mutate((state) => {
             this.#checkGuard(state, guard);
             const changes = requestIds.map((key) => ({ family: "intent", key, value: null }));
-            return { changes: [...changes, ...FileJournaledBackend.#metaChanges([], removeMeta ?? [])], result: undefined };
+            return { changes: [...changes, ..._a.#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 } })),
-        });
+    /** The committed index as the pure blob transition owner reads it. */
+    #blobView(state) {
+        return {
+            blobIntentsFor: key => [...state.intents.values()].filter((row) => !isDocumentIntent(row) && row.target === key),
+            blobIntent: id => { const row = state.intents.get(id); return row && !isDocumentIntent(row) ? row : undefined; },
+            intentState: id => state.intents.get(id)?.state ?? null,
+            meta: key => state.meta.has(key) ? { present: true, value: state.meta.get(key) } : { present: false },
+            sequence: state.sequence,
+            claimedInThisSession: (id, attempts) => this.#claims.get(id) === attempts,
+        };
+    }
+    /** A decided blob verb as one mutation: its changes, the format they need, and the session claims. */
+    #blobDecision(decision) {
+        const formats = decision.intents.flatMap(({ value }) => (value === null ? [] : [blobIntentFormat(value)]));
+        const format = formats.length === 0 ? undefined : Math.max(...formats);
+        return {
+            changes: _a.#blobChanges(decision),
+            result: decision.result,
+            ...(format === undefined ? {} : { format }),
+            afterCommit: () => {
+                if (decision.session) {
+                    if (decision.session.claimed === null)
+                        this.#claims.delete(decision.session.requestId);
+                    else
+                        this.#claims.set(decision.session.requestId, decision.session.claimed);
+                }
+                for (const { requestId, value } of decision.intents)
+                    if (value === null)
+                        this.#claims.delete(requestId);
+            },
+        };
+    }
+    /** A decided blob verb as one log record's changes. */
+    static #blobChanges(decision) {
+        return [
+            ...(decision.sequence === undefined ? [] : [{ family: "sequence", value: decision.sequence }]),
+            ...decision.intents.map(({ requestId, value }) => ({ family: "intent", key: requestId, value: value === null ? null : structuredClone(value) })),
+            ..._a.#metaChanges(decision.meta, decision.removeMeta),
+        ];
     }
     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 } };
+        return readBlobJournal(this.#blobView(this.#state), key, options);
     }
     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 };
-        });
+        const captured = captureBlobMetaWrite(key, changes, options);
+        await this.#mutate(state => this.#blobDecision(decideBlobMetaWrite(this.#blobView(state), captured)));
     }
     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 captured = captureBlobAdmission(prepared, options);
         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 };
-        });
+        return this.#mutate(state => this.#blobDecision(decideBlobAdmission(this.#blobView(state), captured, now)));
     }
     async listBlobIntents(state) {
         this.#assertOpen();
@@ -1244,56 +1263,17 @@ export class FileJournaledBackend {
         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 captured = captureBlobUpdate(requestId, expectedState, patch, 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 };
-        });
+        return this.#mutate(state => this.#blobDecision(decideBlobUpdate(this.#blobView(state), captured, now, assertReceiptBound)));
     }
     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 };
-        });
+        const captured = captureBlobRetirement(key, requestIds, options);
+        await this.#mutate(state => this.#blobDecision(decideBlobRetirement(this.#blobView(state), captured)));
+    }
+    async forgetBlobIntent(requestId, options) {
+        const captured = captureBlobForget(requestId, options);
+        await this.#mutate(state => this.#blobDecision(decideBlobForget(this.#blobView(state), captured)));
     }
     async readMeta(key) {
         this.#assertOpen();
@@ -1317,5 +1297,38 @@ export class FileJournaledBackend {
             return { changes: [{ family: "meta", key, present: true, value: captured }], result: undefined };
         });
     }
+    /**
+     * Every meta row whose key starts with `prefix` (all rows when it is empty), in code-unit key
+     * order, read in one synchronous pass over the last committed transaction. Values are copies.
+     */
+    async listMeta(prefix = "") {
+        if (typeof prefix !== "string")
+            throw new TypeError("a meta prefix is a string");
+        this.#assertOpen();
+        const meta = this.#state.meta;
+        const keys = [...meta.keys()].filter((key) => key.startsWith(prefix)).sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+        return keys.map((key) => ({ key, value: structuredClone(meta.get(key)) }));
+    }
+    /**
+     * Remove one meta row, compare-and-swap: `expected` is the row's presence and value as the
+     * caller last read it, compared in the same transaction as the removal. A mismatch is
+     * `JournalGuardConflict` and writes nothing. It resolves true when it removed the row and false
+     * when the row was absent as expected, which writes nothing either.
+     */
+    async removeMeta(key, options) {
+        if (typeof key !== "string")
+            throw new TypeError("a meta key is a string");
+        if (!options || typeof options !== "object" || options.expected === undefined)
+            throw new JournalGuardConflict(key);
+        const { expected } = captureMetaWrite({ expected: options.expected });
+        return this.#mutate((state) => {
+            const actual = state.meta.has(key) ? { present: true, value: state.meta.get(key) } : { present: false };
+            assertMetaWrite(key, { expected }, actual, []);
+            if (!actual.present)
+                return { changes: [], result: false };
+            return { changes: [{ family: "meta", key, present: false }], result: true };
+        });
+    }
 }
+_a = FileJournaledBackend;
 //# sourceMappingURL=file-journaled-backend.js.map