@superbee/core 0.2.0-pre.2 → 0.2.0-pre.20

package/dist/indexeddb-backend.js

@@ -32,7 +32,7 @@
 import { resolveContentType } from "./content-type.js";
 import { MalformedDocumentError, parseMarkdown, stringifyDoc } from "./frontmatter.js";
 import { mutationActorFromFrontmatter } from "./mutation-attribution.js";
-import { IntentHoldConflict, IntentStateConflict, } from "./journaled-backend.js";
+import { assertDeletionIntent, deletionIntentRecord, JournalSnapshotConflict, assertJournalGuard, assertJournalIntentChanges, assertJournalMetaChanges, assertMetaWrite, captureJournalGuardOption, captureJournalDeleteOptions, captureJournalWriteOptions, captureIntentUpdate, captureMetaWrite, captureJournalValue, captureRetireAcknowledged, JournalGuardConflict, assertJournalResolutionOptions, assertJournalSnapshot, IntentHoldConflict, IntentStateConflict, } from "./journaled-backend.js";
 import { assertSafeBlobKey, assertSafeConceptId, assertSafeReservedDir, assertSafeReservedFilename, compareStorageKeys, pathFromConceptId } from "./paths.js";
 import { parseLeadingFrontmatter } from "./portable-frontmatter.js";
 import { blobVersion, defaultActor, VersionConflict, versionOfBytes } from "./versioning.js";
@@ -105,12 +105,31 @@ function editionOf(index) {
         throw error;
     }
 }
+/**
+ * One listing row from a stored record: the frontmatter is what `readWithJournal` parses for
+ * the record under `edition` (the split takes the body as a substring it never parses), or
+ * `null` with the parser's error when the leading block does not parse.
+ */
+function headOf(record, intents, meta, edition) {
+    const head = { id: record.id, version: record.version, updatedBy: record.updatedBy, updatedAt: record.updatedAt, raw: record.raw, intents, meta };
+    let frontmatter;
+    try {
+        frontmatter = parseMarkdown(record.raw, pathFromConceptId(record.id), { okfVersion: edition }).frontmatter;
+    }
+    catch (error) {
+        if (!(error instanceof MalformedDocumentError))
+            throw error;
+        return { ...head, frontmatter: null, malformed: error };
+    }
+    return { ...head, frontmatter };
+}
 /**
  * A persistent browser-local OKF store implementing the {@link JournaledBackend} contract over
  * IndexedDB. One instance per bundle per JavaScript realm; several instances over the same
  * database name are peers whose conditional writes are serialized by the database.
  */
 export class IndexedDbBackend {
+    journalSnapshotCas = true;
     /**
      * What a resolved write promises: the IndexedDB transaction reported `complete`. Whether the
      * committed pages survive power loss is the browser's and the operating system's decision.
@@ -251,9 +270,47 @@ export class IndexedDbBackend {
      * report the transaction's AbortError and the cause would be lost.
      */
     async #transact(stores, mode, body) {
-        const db = await this.#open();
+        // Starting a transaction throws synchronously on a handle closed between the open resolving
+        // and this line, which is what a `close()` issued in the same turn as an in-flight call
+        // produces. `close()` promises that the next operation reopens lazily, and the cold path gets
+        // that for free by joining the next open; this is the warm equivalent. Retrying is safe here
+        // and only here: the throw means no transaction exists, so nothing was attempted and the
+        // retry cannot repeat work. A second failure is the host's own answer and propagates, which
+        // is also what a genuinely bad store name does after one wasted reopen.
+        let db = await this.#open();
+        let transaction;
+        try {
+            transaction = db.transaction(stores, mode);
+        }
+        catch (firstFailure) {
+            if (this.#db === db)
+                this.close();
+            db = await this.#open();
+            try {
+                transaction = db.transaction(stores, mode);
+            }
+            catch (retryFailure) {
+                // The retry's failure is what the caller acts on. When the two differ the first one was
+                // never about a closed handle, so it is the more informative of the pair and is kept as
+                // the cause rather than discarded.
+                const failure = asError(retryFailure);
+                if (failure !== firstFailure && failure.cause == null) {
+                    // Attaching a cause is a convenience and is never worth replacing the host's own error.
+                    // This error belongs to the host, which may hand back a frozen one or one whose `cause`
+                    // is a getter; assigning to either throws in strict mode, and that TypeError would reach
+                    // the caller in place of the real failure.
+                    try {
+                        failure.cause = firstFailure;
+                    }
+                    catch {
+                        // Surface the host's error exactly as it came.
+                    }
+                }
+                throw failure;
+            }
+        }
         return new Promise((resolve, reject) => {
-            const tx = db.transaction(stores, mode);
+            const tx = transaction;
             let result = null;
             let failure = null;
             tx.oncomplete = () => {
@@ -481,6 +538,54 @@ export class IndexedDbBackend {
     // pending-change record and no record exists for an edit that never committed. Settling an
     // intent is a compare-and-swap on the intent's own `state`, so a stale realm cannot settle
     // an intent another realm already settled.
+    /**
+     * Remove acknowledged intents of one target and named meta rows in one transaction, after
+     * comparing the target's full guard in that same transaction.
+     */
+    async retireAcknowledged(target, options) {
+        assertSafeConceptId(target);
+        const { guard: expected, requestIds, removeMeta } = captureRetireAcknowledged(target, options);
+        await this.#transact([DOCUMENTS, INTENTS, META], "readwrite", (tx, done, fail, guard) => {
+            this.#checkJournalGuard(tx, expected, () => {
+                for (const requestId of requestIds) {
+                    const removal = tx.objectStore(INTENTS).delete(requestId);
+                    removal.onerror = () => fail(requestError(removal, `IndexedDB intent retirement failed for '${requestId}'`));
+                }
+                for (const key of removeMeta ?? []) {
+                    const removal = tx.objectStore(META).delete(key);
+                    removal.onerror = () => fail(requestError(removal, `IndexedDB meta delete failed for '${key}'`));
+                }
+                done(undefined);
+            }, fail, guard);
+        });
+    }
+    /** Read and compare a complete guard inside its caller's still-active transaction. */
+    #checkJournalGuard(tx, expected, next, fail, guard) {
+        if (expected === undefined) {
+            next();
+            return;
+        }
+        const current = { target: expected.target, document: null, intents: [], meta: [] };
+        let pending = 2 + expected.meta.length;
+        const finish = () => { if (--pending === 0) {
+            assertJournalGuard(expected, current);
+            next();
+        } };
+        const read = (request, accept) => {
+            request.onerror = () => fail(requestError(request, "IndexedDB journal guard read failed"));
+            request.onsuccess = guard(() => { accept(request.result); finish(); });
+        };
+        read(tx.objectStore(DOCUMENTS).get(expected.target), value => {
+            const row = value;
+            current.document = row ? { version: row.version, raw: row.raw } : null;
+        });
+        read(tx.objectStore(INTENTS).getAll(), value => { current.intents = value.filter(row => row.target === expected.target); });
+        for (const entry of expected.meta)
+            read(tx.objectStore(META).get(entry.key), value => {
+                const row = value;
+                current.meta.push({ key: entry.key, expected: row === undefined ? { present: false } : { present: true, value: row.value } });
+            });
+    }
     /**
      * One transaction over documents, intents, and meta: the document compare-and-swap of
      * {@link write}, plus (optionally) deleting a superseded intent, recording a new intent for
@@ -491,14 +596,25 @@ export class IndexedDbBackend {
      * {@link IntentHoldConflict} before the document is touched.
      */
     async writeJournaled(id, doc, options = {}) {
+        const snapshotGuard = captureJournalGuardOption(options, id);
+        if (snapshotGuard !== undefined) {
+            options = captureJournalWriteOptions(options);
+            doc = captureJournalValue(doc);
+        }
         assertSafeConceptId(id);
+        assertJournalResolutionOptions(id, options);
         const raw = stringifyDoc(doc.frontmatter, doc.body ?? "");
         const version = versionOfBytes(raw);
+        if (snapshotGuard && (doc.id !== id || (options.intent && options.intent.target !== id)))
+            throw new JournalGuardConflict(id);
+        const suppliedMeta = typeof options.meta === "function" ? options.meta({ version, raw }) : options.meta;
+        assertJournalMetaChanges(snapshotGuard, suppliedMeta ?? [], options.removeMeta);
+        options = structuredClone({ ...options, meta: suppliedMeta, ...(snapshotGuard ? { guard: snapshotGuard } : {}) });
         const updatedBy = options.actor?.trim() || defaultActor();
         const now = new Date().toISOString();
         const expected = options.expectedVersion;
         const { intent, supersede, requireSettled } = options;
-        const meta = typeof options.meta === "function" ? options.meta({ version, raw }) : options.meta;
+        const meta = options.meta;
         return this.#transact([DOCUMENTS, INTENTS, META], "readwrite", (tx, done, fail, guard) => {
             const documents = tx.objectStore(DOCUMENTS);
             const intents = tx.objectStore(INTENTS);
@@ -512,6 +628,10 @@ export class IndexedDbBackend {
                     const put = metaStore.put(row);
                     put.onerror = () => fail(requestError(put, `IndexedDB meta write failed for '${row.key}'`));
                 }
+                for (const key of options.removeMeta ?? []) {
+                    const remove = metaStore.delete(key);
+                    remove.onerror = () => fail(requestError(remove, `IndexedDB meta delete failed for '${key}'`));
+                }
             };
             const recordIntent = () => {
                 if (!intent) {
@@ -568,20 +688,55 @@ export class IndexedDbBackend {
                     removeSuperseded();
                 });
             };
-            if (!requireSettled) {
-                writeDocument();
-                return;
-            }
-            // The journal has no index by target, so the hold check scans it; the scan runs inside
-            // this transaction, which is what makes the answer hold for the write that follows.
-            request(intents.getAll(), "intent scan", (rows) => {
-                const holder = rows.find((row) => row.target === id && row.state !== "acknowledged");
-                if (holder) {
-                    fail(new IntentHoldConflict(id, holder.requestId, holder.state));
+            const apply = () => {
+                if (options.resolveIntents) {
+                    request(intents.getAll(), "resolution snapshot", (rows) => {
+                        assertJournalSnapshot(id, options.resolveIntents.expected, rows, intent?.requestId);
+                        for (const row of options.resolveIntents.expected) {
+                            const removal = intents.delete(row.requestId);
+                            removal.onerror = () => fail(requestError(removal, "IndexedDB resolution delete failed"));
+                        }
+                        writeDocument();
+                    });
                     return;
                 }
-                writeDocument();
-            });
+                if (!requireSettled) {
+                    writeDocument();
+                    return;
+                }
+                // The journal has no target index; this scan shares the write's transaction.
+                request(intents.getAll(), "intent scan", (rows) => {
+                    const holder = rows.find((row) => row.target === id && row.state !== "acknowledged");
+                    if (holder) {
+                        fail(new IntentHoldConflict(id, holder.requestId, holder.state));
+                        return;
+                    }
+                    writeDocument();
+                });
+            };
+            const checkIdentities = () => {
+                if (!snapshotGuard) {
+                    apply();
+                    return;
+                }
+                const checkSuperseded = (existingIdentity) => {
+                    if (!supersede) {
+                        assertJournalIntentChanges(snapshotGuard, existingIdentity, undefined);
+                        apply();
+                        return;
+                    }
+                    request(intents.get(supersede.requestId), "superseded identity read", row => {
+                        assertJournalIntentChanges(snapshotGuard, existingIdentity, row);
+                        apply();
+                    });
+                };
+                if (!intent) {
+                    checkSuperseded(undefined);
+                    return;
+                }
+                request(intents.get(intent.requestId), "new identity read", row => checkSuperseded(row));
+            };
+            this.#checkJournalGuard(tx, snapshotGuard, checkIdentities, fail, guard);
         });
     }
     /**
@@ -594,69 +749,138 @@ export class IndexedDbBackend {
      * with `false` even under a compare-and-swap.
      */
     async deleteJournaled(id, options = {}) {
+        options = captureJournalDeleteOptions(id, options);
         assertSafeConceptId(id);
+        assertJournalResolutionOptions(id, options);
+        assertDeletionIntent(id, options);
         const expected = options.expectedVersion;
         const { requireSettled, onHeld } = options;
         const puts = options.meta ?? [];
         const removals = options.removeMeta ?? [];
+        const intent = options.intent ? structuredClone(options.intent) : undefined;
+        const supersede = options.supersede ? { ...options.supersede } : undefined;
+        const now = new Date().toISOString();
         return this.#transact([DOCUMENTS, INTENTS, META], "readwrite", (tx, done, fail, guard) => {
-            const documents = tx.objectStore(DOCUMENTS);
-            const intents = tx.objectStore(INTENTS);
-            const metaStore = tx.objectStore(META);
-            const request = (req, label, next) => {
-                req.onerror = () => fail(requestError(req, `IndexedDB ${label} failed for '${id}'`));
-                req.onsuccess = guard(() => next(req.result));
-            };
-            const putMeta = (rows) => {
-                for (const row of rows) {
-                    const put = metaStore.put(row);
-                    put.onerror = () => fail(requestError(put, `IndexedDB meta write failed for '${row.key}'`));
-                }
-            };
-            const applyMeta = () => {
-                putMeta(puts);
-                for (const key of removals) {
-                    const removal = metaStore.delete(key);
-                    removal.onerror = () => fail(requestError(removal, `IndexedDB meta delete failed for '${key}'`));
-                }
-            };
-            const deleteDocument = () => {
-                request(documents.get(id), "read", (current) => {
-                    const record = current;
-                    if (!record) {
-                        applyMeta();
-                        done({ outcome: "absent" });
-                        return;
+            this.#checkJournalGuard(tx, options.guard, () => {
+                const documents = tx.objectStore(DOCUMENTS);
+                const intents = tx.objectStore(INTENTS);
+                const metaStore = tx.objectStore(META);
+                const request = (req, label, next) => {
+                    req.onerror = () => fail(requestError(req, `IndexedDB ${label} failed for '${id}'`));
+                    req.onsuccess = guard(() => next(req.result));
+                };
+                const putMeta = (rows) => {
+                    for (const row of rows) {
+                        const put = metaStore.put(row);
+                        put.onerror = () => fail(requestError(put, `IndexedDB meta write failed for '${row.key}'`));
                     }
-                    if (expected !== undefined && expected !== record.version) {
-                        fail(new VersionConflict(id, expected, record.version));
-                        return;
+                };
+                const applyMeta = () => {
+                    putMeta(puts);
+                    for (const key of removals) {
+                        const removal = metaStore.delete(key);
+                        removal.onerror = () => fail(requestError(removal, `IndexedDB meta delete failed for '${key}'`));
                     }
-                    const removal = documents.delete(id);
-                    removal.onerror = () => fail(requestError(removal, `IndexedDB delete failed for '${id}'`));
-                    applyMeta();
-                    done({ outcome: "deleted" });
-                });
-            };
-            if (!requireSettled) {
-                deleteDocument();
-                return;
-            }
-            // The same in-transaction hold scan as `writeJournaled`: the answer holds for the deletion
-            // that follows, and for the `onHeld` rows put in its place.
-            request(intents.getAll(), "intent scan", (rows) => {
-                const holder = rows.find((row) => row.target === id && row.state !== "acknowledged");
-                if (holder) {
-                    if (!onHeld) {
-                        fail(new IntentHoldConflict(id, holder.requestId, holder.state));
+                };
+                // The superseded intent and the recorded deletion intent, in the same transaction as the
+                // deletion and its meta rows, as `writeJournaled` records a write's.
+                const journal = (outcome) => {
+                    const record = (sequence) => {
+                        if (!intent) {
+                            applyMeta();
+                            done({ outcome });
+                            return;
+                        }
+                        const row = deletionIntentRecord(intent, sequence, now);
+                        const counter = metaStore.put({ key: INTENT_SEQUENCE_KEY, value: sequence });
+                        counter.onerror = () => fail(requestError(counter, "IndexedDB sequence write failed"));
+                        const put = intents.put(row);
+                        put.onerror = () => fail(requestError(put, `IndexedDB intent write failed for '${row.requestId}'`));
+                        applyMeta();
+                        done({ outcome, intent: row });
+                    };
+                    const next = () => {
+                        if (!intent) {
+                            record(0);
+                            return;
+                        }
+                        request(intents.get(intent.requestId), "intent read", (taken) => {
+                            if (taken !== undefined) {
+                                fail(new JournalSnapshotConflict(id));
+                                return;
+                            }
+                            request(metaStore.get(INTENT_SEQUENCE_KEY), "sequence read", (current) => {
+                                const previous = current?.value;
+                                record((typeof previous === "number" ? previous : 0) + 1);
+                            });
+                        });
+                    };
+                    if (!supersede) {
+                        next();
                         return;
                     }
-                    putMeta(onHeld.meta);
-                    done({ outcome: "held", requestId: holder.requestId, state: holder.state });
+                    request(intents.get(supersede.requestId), "intent read", (current) => {
+                        const existing = current;
+                        if (!existing || existing.target !== id || existing.state !== supersede.expectedState || existing.attempts !== supersede.expectedAttempts) {
+                            fail(new IntentStateConflict(supersede.requestId, supersede.expectedState, existing?.state ?? null));
+                            return;
+                        }
+                        const removal = intents.delete(supersede.requestId);
+                        removal.onerror = () => fail(requestError(removal, `IndexedDB intent delete failed for '${supersede.requestId}'`));
+                        next();
+                    });
+                };
+                const deleteDocument = () => {
+                    request(documents.get(id), "read", (current) => {
+                        const record = current;
+                        if (options.resolveIntents && expected !== (record?.version ?? null)) {
+                            fail(new VersionConflict(id, expected, record?.version ?? null));
+                            return;
+                        }
+                        if (!record) {
+                            journal("absent");
+                            return;
+                        }
+                        if (expected !== undefined && expected !== record.version) {
+                            fail(new VersionConflict(id, expected, record.version));
+                            return;
+                        }
+                        const removal = documents.delete(id);
+                        removal.onerror = () => fail(requestError(removal, `IndexedDB delete failed for '${id}'`));
+                        journal("deleted");
+                    });
+                };
+                if (options.resolveIntents) {
+                    request(intents.getAll(), "resolution snapshot", (rows) => {
+                        assertJournalSnapshot(id, options.resolveIntents.expected, rows, intent?.requestId);
+                        for (const row of options.resolveIntents.expected) {
+                            const removal = intents.delete(row.requestId);
+                            removal.onerror = () => fail(requestError(removal, "IndexedDB resolution delete failed"));
+                        }
+                        deleteDocument();
+                    });
                     return;
                 }
-                deleteDocument();
-            });
+                if (!requireSettled) {
+                    deleteDocument();
+                    return;
+                }
+                // The same in-transaction hold scan as `writeJournaled`: the answer holds for the deletion
+                // that follows, and for the `onHeld` rows put in its place.
+                request(intents.getAll(), "intent scan", (rows) => {
+                    const holder = rows.find((row) => row.target === id && row.state !== "acknowledged");
+                    if (holder) {
+                        if (!onHeld) {
+                            fail(new IntentHoldConflict(id, holder.requestId, holder.state));
+                            return;
+                        }
+                        putMeta(onHeld.meta);
+                        done({ outcome: "held", requestId: holder.requestId, state: holder.state });
+                        return;
+                    }
+                    deleteDocument();
+                });
+            }, fail, guard);
         });
     }
     /**
@@ -712,6 +936,132 @@ export class IndexedDbBackend {
         const { frontmatter, body } = parseMarkdown(record.raw, pathFromConceptId(id), { okfVersion: editionOf(index) });
         return { document: { doc: { id, frontmatter, body }, version: record.version }, raw: record.raw, intents: rows, meta };
     }
+    /**
+     * Every document's head with its intents and the meta rows named for it, from ONE readonly
+     * transaction over documents, reserved, intents, and meta: {@link readWithJournal} over the
+     * whole store. The root index, the journal (grouped by target, since it has no index by
+     * target) and the `shared` keys are read once, then the documents are walked by cursor, each
+     * row's own keys read with it, so a caller's `project` sees one record at a time and the
+     * listing holds only what it keeps plus the journal it read up front, intents' content
+     * included. The frontmatter is the one `readWithJournal` would parse
+     * for the record, under the edition the root index declared at this moment; the body is
+     * never parsed. Rows come back in `list` order.
+     */
+    async readHeads(options = {}) {
+        const keysOf = options.meta ?? (() => []);
+        const sharedKeys = [...new Set(options.shared ?? [])];
+        const project = options.project ?? ((head) => head);
+        const rows = await this.#transact([DOCUMENTS, RESERVED, INTENTS, META], "readonly", (tx, done, fail, guard) => {
+            const out = [];
+            let edition;
+            const byTarget = new Map();
+            const shared = new Map();
+            // Rows still being assembled, plus one for the cursor walk itself; the listing is done
+            // when the walk has ended and every row's meta reads have landed.
+            let outstanding = 1;
+            const finish = () => {
+                if (--outstanding === 0)
+                    done(out);
+            };
+            // A parse or projection failure aborts the transaction through `fail`; after it no
+            // request is placed and no request's own error is reported, so the caller's error is
+            // the rejection, not the aborted transaction's refusal of the requests still in flight.
+            let stopped = false;
+            const stop = (error) => {
+                if (stopped)
+                    return;
+                stopped = true;
+                fail(error);
+            };
+            const metaStore = tx.objectStore(META);
+            const readMeta = (key, into, then) => {
+                const request = metaStore.get(key);
+                request.onerror = () => stop(requestError(request, `IndexedDB meta read failed for '${key}'`));
+                request.onsuccess = guard(() => {
+                    const row = request.result;
+                    if (row !== undefined)
+                        into.set(key, row.value);
+                    then();
+                });
+            };
+            const walk = () => {
+                const cursor = tx.objectStore(DOCUMENTS).openCursor();
+                cursor.onerror = () => stop(requestError(cursor, "IndexedDB document scan failed"));
+                cursor.onsuccess = guard(() => {
+                    const current = cursor.result;
+                    if (!current) {
+                        finish();
+                        return;
+                    }
+                    const record = current.value;
+                    const intents = byTarget.get(record.id) ?? [];
+                    const keys = [...new Set(keysOf(record.id, intents))].filter((key) => !shared.has(key) && !sharedKeys.includes(key));
+                    const meta = new Map(shared);
+                    let pending = keys.length;
+                    outstanding += 1;
+                    const complete = () => {
+                        try {
+                            out.push({ id: record.id, row: project(headOf(record, intents, meta, edition)) });
+                        }
+                        catch (error) {
+                            stop(asError(error));
+                            return;
+                        }
+                        finish();
+                    };
+                    if (pending === 0)
+                        complete();
+                    else {
+                        for (const key of keys) {
+                            readMeta(key, meta, () => {
+                                if (--pending === 0)
+                                    complete();
+                            });
+                        }
+                    }
+                    if (!stopped)
+                        current.continue();
+                });
+            };
+            const readShared = () => {
+                let pending = sharedKeys.length;
+                if (pending === 0) {
+                    walk();
+                    return;
+                }
+                for (const key of sharedKeys) {
+                    readMeta(key, shared, () => {
+                        if (--pending === 0)
+                            walk();
+                    });
+                }
+            };
+            // The index, the journal and the shared rows land before the walk starts, so every row
+            // is built under one edition and sees its whole journal, whatever order the host
+            // answers requests in.
+            const rootIndex = tx.objectStore(RESERVED).get(reservedKey("", "index.md"));
+            rootIndex.onerror = () => stop(requestError(rootIndex, "IndexedDB root index read failed"));
+            rootIndex.onsuccess = guard(() => {
+                edition = editionOf(rootIndex.result);
+                const scan = tx.objectStore(INTENTS).getAll();
+                scan.onerror = () => stop(requestError(scan, "IndexedDB journal scan failed"));
+                scan.onsuccess = guard(() => {
+                    for (const row of scan.result) {
+                        const list = byTarget.get(row.target);
+                        if (list)
+                            list.push(row);
+                        else
+                            byTarget.set(row.target, [row]);
+                    }
+                    for (const list of byTarget.values())
+                        list.sort((a, b) => a.sequence - b.sequence);
+                    readShared();
+                });
+            });
+        });
+        rows.sort((a, b) => compareStorageKeys(a.id, b.id));
+        return rows.map((entry) => entry.row);
+    }
     /** Intents in local commit order, optionally restricted to one or more states. */
     async listIntents(state) {
         const wanted = state === undefined ? null : new Set(typeof state === "string" ? [state] : state);
@@ -732,38 +1082,67 @@ export class IndexedDbBackend {
      * missing record rejects with {@link IntentStateConflict} and writes nothing.
      */
     async updateIntent(requestId, expectedState, patch, options = {}) {
+        ({ patch, options } = captureIntentUpdate(patch, options));
         const now = new Date().toISOString();
-        return this.#transact([INTENTS, META], "readwrite", (tx, done, fail, guard) => {
-            const intents = tx.objectStore(INTENTS);
-            const read = intents.get(requestId);
-            read.onerror = () => fail(requestError(read, `IndexedDB intent read failed for '${requestId}'`));
-            read.onsuccess = guard(() => {
-                const current = read.result;
-                if (!current || current.state !== expectedState) {
-                    fail(new IntentStateConflict(requestId, expectedState, current?.state ?? null));
-                    return;
-                }
-                const next = { ...current, ...patch, requestId, sequence: current.sequence, updatedAt: now };
-                const put = intents.put(next);
-                put.onerror = () => fail(requestError(put, `IndexedDB intent write failed for '${requestId}'`));
-                const metaStore = tx.objectStore(META);
-                for (const row of options.meta ?? []) {
-                    const metaPut = metaStore.put(row);
-                    metaPut.onerror = () => fail(requestError(metaPut, `IndexedDB meta write failed for '${row.key}'`));
-                }
-                done(next);
-            });
+        const raw = options.document ? stringifyDoc(options.document.frontmatter, options.document.body ?? "") : undefined;
+        const replacement = raw === undefined ? undefined : { id: options.document.id, raw, version: versionOfBytes(raw), updatedBy: defaultActor(), updatedAt: now };
+        return this.#transact([DOCUMENTS, INTENTS, META], "readwrite", (tx, done, fail, guard) => {
+            this.#checkJournalGuard(tx, options.guard, () => {
+                const intents = tx.objectStore(INTENTS);
+                const read = intents.get(requestId);
+                read.onerror = () => fail(requestError(read, `IndexedDB intent read failed for '${requestId}'`));
+                read.onsuccess = guard(() => {
+                    const current = read.result;
+                    if (!current || current.state !== expectedState) {
+                        fail(new IntentStateConflict(requestId, expectedState, current?.state ?? null));
+                        return;
+                    }
+                    if (options.guard && current.target !== options.guard.target)
+                        throw new JournalGuardConflict(current.target);
+                    const next = { ...current, ...patch, requestId, sequence: current.sequence, updatedAt: now };
+                    if (replacement) {
+                        const write = tx.objectStore(DOCUMENTS).put(replacement);
+                        write.onerror = () => fail(requestError(write, "IndexedDB replacement write failed"));
+                    }
+                    const put = intents.put(next);
+                    put.onerror = () => fail(requestError(put, `IndexedDB intent write failed for '${requestId}'`));
+                    const metaStore = tx.objectStore(META);
+                    for (const row of options.meta ?? []) {
+                        const metaPut = metaStore.put(row);
+                        metaPut.onerror = () => fail(requestError(metaPut, `IndexedDB meta write failed for '${row.key}'`));
+                    }
+                    done(next);
+                });
+            }, fail, guard);
         });
     }
     async readMeta(key) {
         const row = await this.#getOne(META, key);
         return row === undefined ? undefined : row.value;
     }
-    async writeMeta(key, value) {
-        await this.#transact(META, "readwrite", (tx, done, fail) => {
-            const put = tx.objectStore(META).put({ key, value });
-            put.onerror = () => fail(requestError(put, `IndexedDB meta write failed for '${key}'`));
-            done(undefined);
+    async writeMeta(key, value, options = {}) {
+        options = captureMetaWrite(options);
+        value = options.expected !== undefined || options.requireEmptyJournal ? captureJournalValue(value) : structuredClone(value);
+        await this.#transact([INTENTS, META], "readwrite", (tx, done, fail, guard) => {
+            const meta = tx.objectStore(META);
+            const read = meta.get(key);
+            read.onerror = () => fail(requestError(read, "IndexedDB admission read failed"));
+            read.onsuccess = guard(() => {
+                const row = read.result;
+                const finish = (intents) => {
+                    assertMetaWrite(key, options, row === undefined ? { present: false } : { present: true, value: row.value }, intents);
+                    const put = meta.put({ key, value });
+                    put.onerror = () => fail(requestError(put, `IndexedDB meta write failed for '${key}'`));
+                    done(undefined);
+                };
+                if (!options.requireEmptyJournal) {
+                    finish([]);
+                    return;
+                }
+                const scan = tx.objectStore(INTENTS).getAll();
+                scan.onerror = () => fail(requestError(scan, "IndexedDB admission journal scan failed"));
+                scan.onsuccess = guard(() => finish(scan.result));
+            });
         });
     }
     // ── blobs ──────────────────────────────────────────────────────────────────────────────