@omgbase/core 0.3.0 → 0.4.1

package/dist/src/core/ids.d.ts

@@ -2,17 +2,48 @@ export type IdPrefix = "d" | "b" | "c" | "r" | "x" | "col" | "cp" | "e" | "rp" |
 export declare function randomSuffix(len?: number): string;
 /** A replacement id generator (spec/store §2.2): given a prefix, return the whole id. */
 export type IdMinter = (prefix: IdPrefix) => string;
-/** Install a replacement minter (null restores the CSPRNG default). */
+/**
+ * An in-use oracle (spec/store §2.1): does `id` name a row of the prefix's
+ * table(s)? A `Store` registers one when it opens and unregisters it on close.
+ * `col`/`v` have no table; an oracle answers false for them.
+ */
+export type IdOracle = (prefix: IdPrefix, id: string) => boolean;
+/**
+ * Consecutive rejections after which a mint gives up. The CSPRNG cannot hit
+ * this (32⁷ candidates against at most millions in use); only a minter that
+ * can never produce a fresh id — a broken fixture minter — does, and it must
+ * fail loudly rather than spin forever.
+ */
+export declare const MINT_GIVE_UP_AFTER = 1000;
+/** Install a replacement minter (null restores the CSPRNG default). Starts a fresh issued set. */
 export declare function setIdMinter(minter: IdMinter | null): void;
-/** Run `body` with `minter` installed, restoring the previous minter afterwards (also on throw). */
+/** Run `body` with `minter` installed, restoring the previous minter (and its issued set) afterwards (also on throw). */
 export declare function withIdMinter<T>(minter: IdMinter, body: () => T): T;
+/**
+ * Register an in-use oracle (spec/store §2.1); returns the unregister handle.
+ * Every open `Store` holds one, so a mint is checked against every database
+ * this process has open — a false "in use" from another store costs one redraw.
+ */
+export declare function registerIdOracle(oracle: IdOracle): () => void;
 /**
  * The fixture minter (spec/store §2.2): a sequential per-prefix counter —
  * `d_0, d_1, …`, `b_0, …`, each prefix counting from 0 independently. A fresh
  * instance per case resets every counter.
  */
 export declare function sequentialMinter(): IdMinter;
-/** Mint an ID with the given prefix. Collision checking is the store's job. */
+/**
+ * The repeating fixture minter (spec/store §9.4, `"minter": "repeat"`): the
+ * sequential counter whose every id is offered twice — `rp_0, rp_0, b_0, b_0,
+ * b_1, b_1, …`. The store rejects the second offering as in use and asks
+ * again, so a case run under it projects exactly as under `sequentialMinter`.
+ */
+export declare function repeatingMinter(): IdMinter;
+/**
+ * Mint an id with the given prefix (spec/store §2.1 "Uniqueness at mint"):
+ * draw a candidate — from the installed minter, else the CSPRNG — and redraw
+ * while it is in use (issued in this process, or present in a registered
+ * store). Gives up after `MINT_GIVE_UP_AFTER` consecutive rejections.
+ */
 export declare function mintId(prefix: IdPrefix): string;
 export declare function isValidId(id: string, prefix?: IdPrefix): boolean;
 export declare function prefixOf(id: string): string | null;

package/dist/src/core/ids.js

@@ -8,6 +8,13 @@ export function randomSuffix(len = ID_LEN) {
         s += ALPHABET[randomInt(ALPHABET.length)];
     return s;
 }
+/**
+ * Consecutive rejections after which a mint gives up. The CSPRNG cannot hit
+ * this (32⁷ candidates against at most millions in use); only a minter that
+ * can never produce a fresh id — a broken fixture minter — does, and it must
+ * fail loudly rather than spin forever.
+ */
+export const MINT_GIVE_UP_AFTER = 1_000;
 // The installed minter, or null for production (CSPRNG). spec/store §2.2: the
 // store's tree hashes contain block ids, so a fixture runner installs a
 // deterministic per-prefix counter here to make ids comparable across
@@ -15,21 +22,47 @@ export function randomSuffix(len = ID_LEN) {
 // the reconcile module's phase 7 mints), commits, revisions, repos, sources —
 // goes through `mintId`, so one seam covers them all.
 let installed = null;
-/** Install a replacement minter (null restores the CSPRNG default). */
+// Ids issued by the production minter in this process: a candidate already
+// here is redrawn without asking any oracle. Bounded by the number of ids the
+// process mints (a 360k-block ingest is a few tens of MB at most).
+const productionIssued = new Set();
+// Ids issued while a replacement minter is installed. A *fresh* set per
+// install: a fixture case runs on a fresh database, so what the previous case
+// minted must not reject this one's `d_0` — sequential ids stay byte-identical
+// across cases. The repeating minter's second offering of an id is caught
+// here (the row may not be written yet, so the oracle alone would miss it).
+let installedIssued = new Set();
+const oracles = new Set();
+/** Install a replacement minter (null restores the CSPRNG default). Starts a fresh issued set. */
 export function setIdMinter(minter) {
     installed = minter;
+    installedIssued = new Set();
 }
-/** Run `body` with `minter` installed, restoring the previous minter afterwards (also on throw). */
+/** Run `body` with `minter` installed, restoring the previous minter (and its issued set) afterwards (also on throw). */
 export function withIdMinter(minter, body) {
     const previous = installed;
+    const previousIssued = installedIssued;
     installed = minter;
+    installedIssued = new Set();
     try {
         return body();
     }
     finally {
         installed = previous;
+        installedIssued = previousIssued;
     }
 }
+/**
+ * Register an in-use oracle (spec/store §2.1); returns the unregister handle.
+ * Every open `Store` holds one, so a mint is checked against every database
+ * this process has open — a false "in use" from another store costs one redraw.
+ */
+export function registerIdOracle(oracle) {
+    oracles.add(oracle);
+    return () => {
+        oracles.delete(oracle);
+    };
+}
 /**
  * The fixture minter (spec/store §2.2): a sequential per-prefix counter —
  * `d_0, d_1, …`, `b_0, …`, each prefix counting from 0 independently. A fresh
@@ -43,11 +76,51 @@ export function sequentialMinter() {
         return `${prefix}_${n}`;
     };
 }
-/** Mint an ID with the given prefix. Collision checking is the store's job. */
+/**
+ * The repeating fixture minter (spec/store §9.4, `"minter": "repeat"`): the
+ * sequential counter whose every id is offered twice — `rp_0, rp_0, b_0, b_0,
+ * b_1, b_1, …`. The store rejects the second offering as in use and asks
+ * again, so a case run under it projects exactly as under `sequentialMinter`.
+ */
+export function repeatingMinter() {
+    const next = sequentialMinter();
+    const pending = new Map();
+    return (prefix) => {
+        const again = pending.get(prefix);
+        if (again !== undefined) {
+            pending.delete(prefix);
+            return again;
+        }
+        const id = next(prefix);
+        pending.set(prefix, id);
+        return id;
+    };
+}
+function inUse(prefix, id, issued) {
+    if (issued.has(id))
+        return true;
+    for (const oracle of oracles)
+        if (oracle(prefix, id))
+            return true;
+    return false;
+}
+/**
+ * Mint an id with the given prefix (spec/store §2.1 "Uniqueness at mint"):
+ * draw a candidate — from the installed minter, else the CSPRNG — and redraw
+ * while it is in use (issued in this process, or present in a registered
+ * store). Gives up after `MINT_GIVE_UP_AFTER` consecutive rejections.
+ */
 export function mintId(prefix) {
-    if (installed)
-        return installed(prefix);
-    return `${prefix}_${randomSuffix()}`;
+    const minter = installed;
+    const issued = minter ? installedIssued : productionIssued;
+    for (let rejected = 0; rejected < MINT_GIVE_UP_AFTER; rejected++) {
+        const candidate = minter ? minter(prefix) : `${prefix}_${randomSuffix()}`;
+        if (inUse(prefix, candidate, issued))
+            continue;
+        issued.add(candidate);
+        return candidate;
+    }
+    throw new Error(`mintId(${prefix}): ${MINT_GIVE_UP_AFTER} consecutive candidates were already in use — the ${minter ? "installed" : "production"} minter cannot produce a fresh id`);
 }
 // Production ids carry exactly ID_LEN suffix characters; the fixture minter
 // (spec/store §2.2) mints `d_0`, `b_12`, … — one to seven alphabet characters.

package/dist/src/core/ingest.js

@@ -6,7 +6,7 @@ import { assignIds, writeBlockTree, putBlob, newCommit, writeRevision } from "./
 import { sha256, childQuoteDepth, visibleText } from "./hash.js";
 import { mintId } from "./ids.js";
 import { keyBetween } from "./order-key.js";
-import { ftsDeleteDoc, ftsIndexDoc } from "./store/fts.js";
+import { ftsBeforeEvictRows, ftsDeleteDoc, ftsIndexDoc } from "./store/fts.js";
 import { rebuildSections } from "./store/sections.js";
 import { writeDocNodes, projectSectionNodes, toByteSpans } from "./store/nodes.js";
 import { flattenFrontmatter, flattenComputed, writeDocProperties } from "./store/properties.js";
@@ -288,25 +288,28 @@ export function ingestFile(store, repoId, path, content, opts = {}) {
     });
 }
 // Remove another document's `blocks` row for each id in `ids` (a cross-doc move
-// or a resurrection re-homes the id into `docId`). A live foreign row still has
-// an FTS entry (external-content index: delete with the original text); a
-// tombstoned one does not. The source document, if it commits later in the same
+// or a resurrection re-homes the id into `docId`). A live foreign LEAF row still
+// has an FTS entry (external-content index: delete with the original text); a
+// tombstoned row or a container does not (spec/search §1.1) — ftsBeforeEvictRows
+// decides leaf-ness over the table before any row goes and re-indexes a parent
+// left childless. The source document, if it commits later in the same
 // checkpoint, rewrites its rows wholesale and never lists a carried id as
 // deleted, so nothing there depends on the evicted row.
 function evictForeignBlockRows(db, docId, ids) {
-    const sel = db.prepare("SELECT rowid, text, deleted_commit FROM blocks WHERE block_id = ? AND doc_id != ?");
-    const ftsDel = db.prepare("INSERT INTO blocks_fts(blocks_fts, rowid, text) VALUES('delete', ?, ?)");
+    const sel = db.prepare("SELECT rowid, block_id, doc_id, parent_block, text, deleted_commit FROM blocks WHERE block_id = ? AND doc_id != ?");
     const del = db.prepare("DELETE FROM blocks WHERE block_id = ? AND doc_id != ?");
     const unpool = db.prepare("DELETE FROM resurrection_pool WHERE block_id = ?");
+    const rows = [];
     for (const id of ids) {
         const row = sel.get(id, docId);
-        if (row) {
-            if (row.deleted_commit === null)
-                ftsDel.run(row.rowid, row.text);
-            del.run(id, docId);
-        }
-        unpool.run(id);
+        if (row)
+            rows.push(row);
     }
+    ftsBeforeEvictRows(db, rows);
+    for (const r of rows)
+        del.run(r.block_id, docId);
+    for (const id of ids)
+        unpool.run(id);
 }
 // Zip assigned block ids onto the parsed RawBlocks for node projection. The
 // parsed `rest` and `assigned` trees are the same blocks in the same order and

package/dist/src/core/read/document.js

@@ -116,8 +116,13 @@ export function docsReadMany(store, repoId, refs, opts = {}) {
             errors.push({ ref, error: "doc_not_found" });
             continue;
         }
+        // The budget is checked before the SECOND item onward (spec/surface §2, 1.2):
+        // the first item is always emitted even when it alone exceeds the budget —
+        // the same "at least one row" contract docs_list/docs_tree keep, so a
+        // budgeted client always makes progress. `truncated` stays honest: it is
+        // set only when the budget stopped an item that would otherwise have shipped.
         const cost = Math.ceil(JSON.stringify(read).length / 4);
-        if (tokens + cost > budget) {
+        if (items.length > 0 && tokens + cost > budget) {
             truncated = true;
             break;
         }

package/dist/src/core/read/nodes.js

@@ -89,8 +89,12 @@ export function nodesGetMany(store, docId, blockIds, opts = {}) {
             continue;
         }
         const projected = project(store, node, resolution, false);
+        // At least one resolved node is always returned (spec/surface §2, 1.2): the
+        // budget is checked before the second node onward, as docsReadMany does, so
+        // a first node that alone exceeds it still ships and `truncated` only says
+        // that more remained.
         const cost = Math.ceil(JSON.stringify(projected).length / 4);
-        if (tokens + cost > budget) {
+        if (nodes.length > 0 && tokens + cost > budget) {
             truncated = true;
             break;
         }

package/dist/src/core/store/fts.d.ts

@@ -1,10 +1,50 @@
 import type { Database } from "better-sqlite3";
-/** Remove a document's live block rows from the FTS index (call before deleting
- * or tombstoning blocks). Only live blocks are indexed (see ftsIndexDoc), so the
- * delete must target the SAME set: an already-tombstoned block has no FTS row, and
- * re-issuing a 'delete' for it corrupts the external-content index. Keeping this
- * symmetric with ftsIndexDoc (deleted_commit IS NULL) makes a tombstone followed by
- * a later re-ingest of the same doc id (observed delete → recreate) idempotent. */
+/**
+ * SQL predicate: the `blocks` row aliased `b` is a live leaf. `c.doc_id =
+ * b.doc_id` lets the NOT EXISTS use `idx_blocks_doc` (block ids are unique, so
+ * it never changes the answer).
+ */
+export declare const LIVE_LEAF_SQL = "b.deleted_commit IS NULL AND NOT EXISTS (SELECT 1 FROM blocks c WHERE c.doc_id = b.doc_id AND c.parent_block = b.block_id AND c.deleted_commit IS NULL)";
+/**
+ * How many rows the FTS index actually holds. `SELECT count(*) FROM blocks_fts`
+ * is answered from the external-content table (`blocks`, tombstones included),
+ * so the count comes from the index's own `_docsize` shadow table — one row per
+ * indexed row. `doctor` compares it to the live leaf count (spec/search §1.1).
+ */
+export declare function ftsIndexedRowCount(db: Database): number;
+/** The number of live leaf blocks — the rows the FTS index must hold (spec/search §1.1). */
+export declare function liveLeafCount(db: Database): number;
+/** Remove a document's live leaf rows from the FTS index (call before deleting
+ * or tombstoning blocks). Only live leaves are indexed (see ftsIndexDoc), so the
+ * delete must target the SAME set: an already-tombstoned block or a container has
+ * no FTS row, and re-issuing a 'delete' for it corrupts the external-content
+ * index's statistics. Keeping this symmetric with ftsIndexDoc makes a tombstone
+ * followed by a later re-ingest of the same doc id (observed delete → recreate)
+ * idempotent. */
 export declare function ftsDeleteDoc(db: Database, docId: string): void;
-/** Index a document's current block rows (call after inserting blocks). */
+/** Index a document's current live leaf rows (call after inserting blocks). */
 export declare function ftsIndexDoc(db: Database, docId: string): void;
+/**
+ * Rebuild the whole index: `'delete-all'`, then every live leaf of every live
+ * document. (FTS5's own `'rebuild'` command reads the content table wholesale,
+ * containers included, so it is not used.)
+ */
+export declare function ftsRebuild(db: Database): void;
+/**
+ * Remove single `blocks` rows (by id) that are about to be deleted out of
+ * another document's row set — the cross-document eviction of spec/store §5.4
+ * step 8 — keeping the index equal to the table's live leaves. Every row's
+ * leaf-ness is decided over the table BEFORE any of them goes (so a list moving
+ * with its items is order-independent: the items are leaves and lose their
+ * entries, the list never had one), and a live parent that keeps its row but
+ * loses its last live child becomes a leaf and gains an entry. The caller owns
+ * the DELETE of the rows, which must follow this call.
+ */
+export declare function ftsBeforeEvictRows(db: Database, rows: {
+    rowid: number;
+    block_id: string;
+    doc_id: string;
+    parent_block: string | null;
+    text: string;
+    deleted_commit: string | null;
+}[]): void;

package/dist/src/core/store/fts.js

@@ -1,22 +1,86 @@
-/** Remove a document's live block rows from the FTS index (call before deleting
- * or tombstoning blocks). Only live blocks are indexed (see ftsIndexDoc), so the
- * delete must target the SAME set: an already-tombstoned block has no FTS row, and
- * re-issuing a 'delete' for it corrupts the external-content index. Keeping this
- * symmetric with ftsIndexDoc (deleted_commit IS NULL) makes a tombstone followed by
- * a later re-ingest of the same doc id (observed delete → recreate) idempotent. */
+/**
+ * SQL predicate: the `blocks` row aliased `b` is a live leaf. `c.doc_id =
+ * b.doc_id` lets the NOT EXISTS use `idx_blocks_doc` (block ids are unique, so
+ * it never changes the answer).
+ */
+export const LIVE_LEAF_SQL = "b.deleted_commit IS NULL AND NOT EXISTS (SELECT 1 FROM blocks c WHERE c.doc_id = b.doc_id AND c.parent_block = b.block_id AND c.deleted_commit IS NULL)";
+/**
+ * How many rows the FTS index actually holds. `SELECT count(*) FROM blocks_fts`
+ * is answered from the external-content table (`blocks`, tombstones included),
+ * so the count comes from the index's own `_docsize` shadow table — one row per
+ * indexed row. `doctor` compares it to the live leaf count (spec/search §1.1).
+ */
+export function ftsIndexedRowCount(db) {
+    return db.prepare("SELECT count(*) c FROM blocks_fts_docsize").get().c;
+}
+/** The number of live leaf blocks — the rows the FTS index must hold (spec/search §1.1). */
+export function liveLeafCount(db) {
+    return db.prepare(`SELECT count(*) c FROM blocks b WHERE ${LIVE_LEAF_SQL}`).get().c;
+}
+/** Remove a document's live leaf rows from the FTS index (call before deleting
+ * or tombstoning blocks). Only live leaves are indexed (see ftsIndexDoc), so the
+ * delete must target the SAME set: an already-tombstoned block or a container has
+ * no FTS row, and re-issuing a 'delete' for it corrupts the external-content
+ * index's statistics. Keeping this symmetric with ftsIndexDoc makes a tombstone
+ * followed by a later re-ingest of the same doc id (observed delete → recreate)
+ * idempotent. */
 export function ftsDeleteDoc(db, docId) {
-    const rows = db.prepare("SELECT rowid, text FROM blocks WHERE doc_id = ? AND deleted_commit IS NULL").all(docId);
+    const rows = db.prepare(`SELECT b.rowid AS rowid, b.text AS text FROM blocks b WHERE b.doc_id = ? AND ${LIVE_LEAF_SQL}`).all(docId);
     const del = db.prepare("INSERT INTO blocks_fts(blocks_fts, rowid, text) VALUES('delete', ?, ?)");
     for (const r of rows)
         del.run(r.rowid, r.text);
 }
-/** Index a document's current block rows (call after inserting blocks). */
+/** Index a document's current live leaf rows (call after inserting blocks). */
 export function ftsIndexDoc(db, docId) {
     const rows = db
-        .prepare("SELECT rowid, text FROM blocks WHERE doc_id = ? AND deleted_commit IS NULL")
+        .prepare(`SELECT b.rowid AS rowid, b.text AS text FROM blocks b WHERE b.doc_id = ? AND ${LIVE_LEAF_SQL}`)
         .all(docId);
     const ins = db.prepare("INSERT INTO blocks_fts(rowid, text) VALUES(?, ?)");
     for (const r of rows)
         ins.run(r.rowid, r.text);
 }
+/**
+ * Rebuild the whole index: `'delete-all'`, then every live leaf of every live
+ * document. (FTS5's own `'rebuild'` command reads the content table wholesale,
+ * containers included, so it is not used.)
+ */
+export function ftsRebuild(db) {
+    db.exec("INSERT INTO blocks_fts(blocks_fts) VALUES('delete-all')");
+    const docIds = db.prepare("SELECT doc_id FROM docs WHERE deleted_commit IS NULL").all().map((r) => r.doc_id);
+    for (const docId of docIds)
+        ftsIndexDoc(db, docId);
+}
+/**
+ * Remove single `blocks` rows (by id) that are about to be deleted out of
+ * another document's row set — the cross-document eviction of spec/store §5.4
+ * step 8 — keeping the index equal to the table's live leaves. Every row's
+ * leaf-ness is decided over the table BEFORE any of them goes (so a list moving
+ * with its items is order-independent: the items are leaves and lose their
+ * entries, the list never had one), and a live parent that keeps its row but
+ * loses its last live child becomes a leaf and gains an entry. The caller owns
+ * the DELETE of the rows, which must follow this call.
+ */
+export function ftsBeforeEvictRows(db, rows) {
+    if (rows.length === 0)
+        return;
+    const evicted = new Set(rows.map((r) => r.block_id));
+    const hasLiveChild = db.prepare("SELECT 1 FROM blocks c WHERE c.doc_id = ? AND c.parent_block = ? AND c.deleted_commit IS NULL LIMIT 1");
+    const del = db.prepare("INSERT INTO blocks_fts(blocks_fts, rowid, text) VALUES('delete', ?, ?)");
+    const leaves = rows.filter((r) => r.deleted_commit === null && !hasLiveChild.get(r.doc_id, r.block_id));
+    for (const r of leaves)
+        del.run(r.rowid, r.text);
+    // Parents that stay live but are left childless are leaves from now on.
+    const parentRow = db.prepare(`SELECT b.rowid AS rowid, b.text AS text FROM blocks b WHERE b.block_id = ? AND b.doc_id = ? AND b.deleted_commit IS NULL
+       AND NOT EXISTS (SELECT 1 FROM blocks c WHERE c.doc_id = b.doc_id AND c.parent_block = b.block_id AND c.deleted_commit IS NULL AND c.block_id NOT IN (${rows.map(() => "?").join(",")}))`);
+    const ins = db.prepare("INSERT INTO blocks_fts(rowid, text) VALUES(?, ?)");
+    const seen = new Set();
+    for (const r of rows) {
+        if (r.deleted_commit !== null || !r.parent_block || evicted.has(r.parent_block) || seen.has(r.parent_block))
+            continue;
+        seen.add(r.parent_block);
+        const p = parentRow.get(r.parent_block, r.doc_id, ...rows.map((x) => x.block_id));
+        if (p)
+            ins.run(p.rowid, p.text);
+    }
+}
 //# sourceMappingURL=fts.js.map

package/dist/src/core/store/rebuild.js

@@ -1,6 +1,6 @@
 import { rebuildSections } from "./sections.js";
 import { rebuildDocEdges } from "./edges.js";
-import { ftsIndexDoc } from "./fts.js";
+import { ftsRebuild } from "./fts.js";
 export function rebuildIndex(store, target = "all") {
     store.write((db) => {
         const docIds = db.prepare("SELECT doc_id FROM docs WHERE deleted_commit IS NULL").all().map((r) => r.doc_id);
@@ -14,8 +14,10 @@ export function rebuildIndex(store, target = "all") {
                 rebuildDocEdges(db, docId);
         }
         if (target === "fts" || target === "all") {
-            // Rebuild the external-content FTS index from current block text.
-            db.exec("INSERT INTO blocks_fts(blocks_fts) VALUES('rebuild')");
+            // spec/search §1.1: 'delete-all', then every live leaf of every live doc
+            // (FTS5's 'rebuild' would index the content table wholesale, containers
+            // included).
+            ftsRebuild(db);
         }
         if (target === "block_changes" || target === "all") {
             // block_changes is a projection of dispositions across commits: rebuild
@@ -24,6 +26,5 @@ export function rebuildIndex(store, target = "all") {
             db.exec("INSERT OR IGNORE INTO block_changes (block_id, commit_id, kind) SELECT block_id, commit_id, kind FROM dispositions");
         }
     });
-    void ftsIndexDoc; // fts rebuild uses the FTS5 'rebuild' command directly
 }
 //# sourceMappingURL=rebuild.js.map

package/dist/src/core/store/store.d.ts

@@ -5,7 +5,11 @@ export interface StoreOptions {
 }
 export declare class Store {
     readonly db: Database.Database;
+    private readonly unregisterOracle;
+    private readonly inUseStmts;
     constructor(opts: StoreOptions);
+    /** spec/store §2.1: does `id` name a row of the prefix's table(s)? */
+    private idInUse;
     private migrate;
     private migrateV3;
     private migrateV4;

package/dist/src/core/store/store.js

@@ -3,9 +3,28 @@ import { mkdirSync } from "node:fs";
 import { dirname } from "node:path";
 import { DDL, SCHEMA_VERSION, MIGRATIONS, SYNC_DDL } from "./schema.js";
 import { cosineBytes } from "../vec.js";
-import { mintId } from "../ids.js";
+import { mintId, registerIdOracle } from "../ids.js";
+// spec/store §2.1 "Uniqueness at mint": the table(s) and id column a minted
+// id of each prefix must not already name a row of. A block id lives on in
+// history after its `blocks` row is gone, hence `block_changes` and
+// `resurrection_pool`. `col` and `v` have no table and no check.
+const ID_TABLES = {
+    d: [["docs", "doc_id"]],
+    b: [["blocks", "block_id"], ["block_changes", "block_id"], ["resurrection_pool", "block_id"]],
+    c: [["commits", "commit_id"]],
+    r: [["revisions", "rev_id"]],
+    x: [["external_nodes", "node_id"]],
+    e: [["edges", "edge_id"]],
+    cp: [["checkpoints", "id"]],
+    rp: [["repos", "repo_id"]],
+    src: [["sources", "source_id"]],
+};
 export class Store {
     db;
+    // The in-use oracle this store registered with `mintId` (spec/store §2.1);
+    // `close()` calls it to unregister. Prepared statements cached per prefix.
+    unregisterOracle;
+    inUseStmts = new Map();
     constructor(opts) {
         if (opts.path !== ":memory:")
             mkdirSync(dirname(opts.path), { recursive: true });
@@ -17,6 +36,24 @@ export class Store {
         // scalar. Deterministic (same inputs → same score) so SQLite may cache it.
         this.db.function("cosine", { deterministic: true }, (a, b) => cosineBytes(a, b));
         this.migrate();
+        // Registered after the migration so every table the oracle reads exists.
+        // (A migration's own mints — v13's `src_` per repo — are checked only
+        // against the process's issued set; they land in tables that were empty.)
+        this.unregisterOracle = registerIdOracle((prefix, id) => this.idInUse(prefix, id));
+    }
+    /** spec/store §2.1: does `id` name a row of the prefix's table(s)? */
+    idInUse(prefix, id) {
+        if (!this.db.open)
+            return false;
+        let stmts = this.inUseStmts.get(prefix);
+        if (!stmts) {
+            stmts = (ID_TABLES[prefix] ?? []).map(([table, column]) => this.db.prepare(`SELECT 1 FROM ${table} WHERE ${column} = ? LIMIT 1`));
+            this.inUseStmts.set(prefix, stmts);
+        }
+        for (const stmt of stmts)
+            if (stmt.get(id) !== undefined)
+                return true;
+        return false;
     }
     migrate() {
         const current = this.db.pragma("user_version", { simple: true });
@@ -158,6 +195,8 @@ export class Store {
         return this.db.pragma(name, { simple: true });
     }
     close() {
+        this.unregisterOracle();
+        this.inUseStmts.clear();
         this.db.close();
     }
 }

package/dist/src/format/index.d.ts

@@ -1,6 +1,17 @@
 export type { FormatAdapter, AdapterEdge, ProjectedNode, EmbeddingChunk, ReconcileHints, } from "./adapter.js";
 export { AdapterCapability } from "./adapter.js";
 export { registerAdapter, adapterForFormat, adapterForPath, registeredFormats, detectFormat, } from "./registry.js";
-export { markdownAdapter, MARKDOWN_FORMAT } from "./markdown.js";
+export { markdownAdapter, MARKDOWN_FORMAT, MARKDOWN_CONTAINER_KINDS } from "./markdown.js";
 export { yamlAdapter, YAML_FORMAT } from "./yaml.js";
 export { jsonAdapter, JSON_FORMAT } from "./json.js";
+/**
+ * May this block take children (spec/mutate §1.1)? Markdown decides by kind —
+ * the parser only ever nests under `list`, `list_item`, `task`, `blockquote`
+ * and `table`, so an empty `children` on a heading or paragraph is structural,
+ * not "an empty container". The other formats have no kind table for this yet:
+ * a block that has children is a container, a childless one a leaf.
+ */
+export declare function isContainerBlock(format: string, block: {
+    type: string;
+    children: readonly unknown[];
+}): boolean;

package/dist/src/format/index.js

@@ -1,9 +1,22 @@
 // Format adapter system. Importing this module registers the built-in adapters.
 export { AdapterCapability } from "./adapter.js";
 export { registerAdapter, adapterForFormat, adapterForPath, registeredFormats, detectFormat, } from "./registry.js";
-export { markdownAdapter, MARKDOWN_FORMAT } from "./markdown.js";
+export { markdownAdapter, MARKDOWN_FORMAT, MARKDOWN_CONTAINER_KINDS } from "./markdown.js";
 export { yamlAdapter, YAML_FORMAT } from "./yaml.js";
 export { jsonAdapter, JSON_FORMAT } from "./json.js";
+import { MARKDOWN_FORMAT, MARKDOWN_CONTAINER_KINDS } from "./markdown.js";
+/**
+ * May this block take children (spec/mutate §1.1)? Markdown decides by kind —
+ * the parser only ever nests under `list`, `list_item`, `task`, `blockquote`
+ * and `table`, so an empty `children` on a heading or paragraph is structural,
+ * not "an empty container". The other formats have no kind table for this yet:
+ * a block that has children is a container, a childless one a leaf.
+ */
+export function isContainerBlock(format, block) {
+    if (format === MARKDOWN_FORMAT)
+        return MARKDOWN_CONTAINER_KINDS.has(block.type);
+    return block.children.length > 0;
+}
 // Register built-in adapters.
 import { registerAdapter } from "./registry.js";
 import { markdownAdapter } from "./markdown.js";

package/dist/src/format/markdown.d.ts

@@ -1,5 +1,12 @@
 import { type FormatAdapter } from "./adapter.js";
 import { assertFullCoverage } from "../core/parse/tree.js";
 export declare const MARKDOWN_FORMAT = "markdown";
+/**
+ * The Markdown block kinds whose `children` the parser produces (spec/format;
+ * `core/parse/parse.ts` CONTAINER_TYPES on the mdast side: list → list_item /
+ * task, blockquote, table → table_row). Every other kind is a leaf: its raw IS
+ * its whole content, so nothing may be placed inside it (spec/mutate §1.1).
+ */
+export declare const MARKDOWN_CONTAINER_KINDS: ReadonlySet<string>;
 export declare const markdownAdapter: FormatAdapter;
 export { assertFullCoverage };

package/dist/src/format/markdown.js

@@ -4,6 +4,13 @@ import { parseTree, assertFullCoverage } from "../core/parse/tree.js";
 import { render } from "../core/parse/render.js";
 import { extractFromBlock, extractFromFrontmatter, ownText, scanText, INLINE_FIELD_BRACKETED, INLINE_FIELD_LINE } from "../graph/extract.js";
 export const MARKDOWN_FORMAT = "markdown";
+/**
+ * The Markdown block kinds whose `children` the parser produces (spec/format;
+ * `core/parse/parse.ts` CONTAINER_TYPES on the mdast side: list → list_item /
+ * task, blockquote, table → table_row). Every other kind is a leaf: its raw IS
+ * its whole content, so nothing may be placed inside it (spec/mutate §1.1).
+ */
+export const MARKDOWN_CONTAINER_KINDS = new Set(["list", "list_item", "task", "blockquote", "table"]);
 function toAdapterEdge(e) {
     return {
         srcBlock: e.srcBlock,

package/dist/src/graph/history.d.ts

@@ -28,6 +28,27 @@ export declare function diffBlocks(store: Store, docId: string, fromRev: string,
 /** `diff_unified` (spec/surface §3): a unified diff of two revisions' rendered
  * texts — each revision's live raws joined by `\n` — via {@link unifiedDiff}. */
 export declare function diffUnified(store: Store, docId: string, fromRev: string, toRev: string): string;
+/** The `diff_unified` tool's result (spec/surface §3): the resolved revision pair and the diff. */
+export interface DocDiffUnified {
+    doc: string;
+    path: string;
+    from: string;
+    to: string;
+    diff: string;
+}
+/**
+ * `diff_unified` over a resolved document: `to` defaults to the current revision,
+ * `from` to the one before it (or the current one again when there is only one:
+ * an empty diff). Shared by the MCP tool and `omg diff` so the shape cannot
+ * drift. `label` is how the caller named the document, for the error message.
+ * A document with no revision at all is `target_missing`; an unknown `rev` is
+ * `RevisionNotFound` (→ `target_missing` through `errorBody`).
+ */
+export declare function docDiffUnified(store: Store, docId: string, opts?: {
+    fromRev?: string;
+    toRev?: string;
+    label?: string;
+}): DocDiffUnified;
 /** How each text becomes lines: `split("\n")` exactly — no trimming, no
  * dropping of a trailing empty element (a raw ending in `\n` yields one) — with
  * a single special case: the empty text has *no* lines (an empty file is zero