@omgbase/core 0.4.0 → 0.5.0

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/store/fts.d.ts

@@ -5,6 +5,15 @@ import type { Database } from "better-sqlite3";
  * 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

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

@@ -4,6 +4,19 @@
  * 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

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

package/dist/src/graph/history.js

@@ -1,5 +1,6 @@
 import { findDocByRef } from "../core/read/reader.js";
 import { isValidId } from "../core/ids.js";
+import { EngineError } from "../mcp/errors.js";
 /** history_node: a block's biography from block_changes + commits (06 §3). */
 export function historyNode(store, blockId, opts = {}) {
     const limit = opts.limit ?? 100;
@@ -78,6 +79,25 @@ export function diffUnified(store, docId, fromRev, toRev) {
     const rendered = (rev) => [...blocksAtRevision(store, docId, rev).values()].join("\n");
     return unifiedDiff(rendered(fromRev), rendered(toRev));
 }
+/**
+ * `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 function docDiffUnified(store, docId, opts = {}) {
+    const revs = store.db
+        .prepare("SELECT rev_id FROM revisions WHERE doc_id = ? ORDER BY seq DESC LIMIT 2")
+        .all(docId);
+    const to = opts.toRev ?? revs[0]?.rev_id;
+    const from = opts.fromRev ?? revs[1]?.rev_id ?? revs[0]?.rev_id;
+    if (!to || !from)
+        throw new EngineError("target_missing", `no revisions to diff for ${opts.label ?? docId}`);
+    const path = store.db.prepare("SELECT path FROM docs WHERE doc_id = ?").get(docId)?.path ?? "";
+    return { doc: docId, path, from, to, diff: diffUnified(store, docId, from, to) };
+}
 // ---- unified diff (spec/surface §3) ------------------------------------------
 // A line-grain unified diff with a deterministic Myers script, so both engines
 // (this reference and crates/omgbase-surface/src/history.rs) produce the same
@@ -232,14 +252,19 @@ export function changesSince(store, repoId, opts = {}) {
         params.push(opts.origin);
     params.push(limit + 1);
     const commits = store.db
-        .prepare(`SELECT commit_id, seq, ts, origin, actor FROM commits WHERE repo_id = ? AND seq > ? ${originClause} ORDER BY seq LIMIT ?`)
+        .prepare(`SELECT commit_id, seq, ts, origin, actor, reason FROM commits WHERE repo_id = ? AND seq > ? ${originClause} ORDER BY seq LIMIT ?`)
         .all(...params);
     const truncated = commits.length > limit;
     const page = commits.slice(0, limit);
     const digests = page.map((c) => {
         const revs = store.db.prepare("SELECT r.doc_id AS doc, r.path AS path, r.rendered_hash AS rendered_hash FROM revisions r WHERE r.commit_id = ?").all(c.commit_id).map((r) => ({ doc: r.doc, path: r.path, contentHash: r.rendered_hash.toString("hex") }));
         const dispCounts = store.db.prepare("SELECT kind, count(*) n FROM dispositions WHERE commit_id = ? GROUP BY kind").all(c.commit_id);
-        const summary = renderSummary(c.origin, c.actor, revs, dispCounts);
+        // A deletion or a move writes no revision: the tombstone names the commit
+        // (`docs.deleted_commit`), a move only its reason (`move <from> -> <to>`).
+        const deleted = revs.length === 0
+            ? store.db.prepare("SELECT path FROM docs WHERE deleted_commit = ? ORDER BY path").all(c.commit_id).map((r) => r.path)
+            : [];
+        const summary = renderSummary(c.origin, c.actor, revs, dispCounts, { deleted, moved: revs.length === 0 ? parseMove(c.reason) : null });
         return { commit: c.commit_id, seq: c.seq, ts: c.ts, origin: c.origin, actor: c.actor, summary, revisions: revs };
     });
     const nextCursor = page.length > 0 ? page[page.length - 1].seq : cursor;
@@ -333,12 +358,29 @@ function resolveDocRow(store, repoId, ref, includeDeleted) {
         : store.db.prepare("SELECT doc_id, path, current_rev, deleted_commit FROM docs WHERE repo_id = ? AND path = ?");
     return (asId ? stmt.get(ref) : stmt.get(repoId, ref));
 }
-function renderSummary(origin, actor, revs, disp) {
-    const paths = revs.map((r) => r.path).join(", ");
+/** The `reason` a document move records (`mutate/docs.ts`): `move <from> -> <to>`. */
+function parseMove(reason) {
+    const m = reason === null ? null : /^move (.+) -> (.+)$/.exec(reason);
+    return m ? { from: m[1], to: m[2] } : null;
+}
+/**
+ * One line per commit: `<origin>[(<actor>)]: <paths> — <n> <kind>, …`. A
+ * commit that touched no revision — a document deletion (observed or api) or a
+ * move — says so instead: `deleted <path>` / `moved <from> → <to>`
+ * (spec/cli §6 `log`; the summary is unpinned by spec/surface).
+ */
+function renderSummary(origin, actor, revs, disp, extra = { deleted: [], moved: null }) {
+    let subject = revs.map((r) => r.path).join(", ");
+    if (revs.length === 0) {
+        if (extra.deleted.length > 0)
+            subject = `deleted ${extra.deleted.join(", ")}`;
+        else if (extra.moved)
+            subject = `moved ${extra.moved.from} → ${extra.moved.to}`;
+    }
     const parts = disp.filter((d) => d.kind !== "same").map((d) => `${d.n} ${d.kind}`);
     const detail = parts.length > 0 ? ` — ${parts.join(", ")}` : "";
     if (origin === "api" || origin === "import")
-        return `${origin}(${actor ?? "?"}): ${paths}${detail}`;
-    return `observed: ${paths}${detail}`;
+        return `${origin}(${actor ?? "?"}): ${subject}${detail}`;
+    return `observed: ${subject}${detail}`;
 }
 //# sourceMappingURL=history.js.map

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

@@ -8,6 +8,8 @@ export interface LinkEdge {
     count: number;
     /** sample source block ids (out-edges only) */
     samples?: string[];
+    /** block-grain (`blocks: true`): the source block of this edge (null for a frontmatter edge) */
+    block?: string | null;
 }
 export interface LinksResult {
     out: LinkEdge[];

package/dist/src/graph/links.js

@@ -8,12 +8,12 @@ export function docLinks(store, docId, opts = {}) {
     if (dir === "out" || dir === "both") {
         if (opts.blocks) {
             const rows = store.db
-                .prepare(`SELECT predicate, dst_node, dst_kind FROM edges
-           WHERE src_doc = ? AND to_commit IS NULL ORDER BY predicate, dst_node`)
+                .prepare(`SELECT predicate, dst_node, dst_kind, src_block FROM edges
+           WHERE src_doc = ? AND to_commit IS NULL ORDER BY predicate, dst_node, src_block`)
                 .all(docId);
             for (const r of rows)
                 if (inPred(r.predicate))
-                    out.push({ predicate: r.predicate, node: r.dst_node, kind: r.dst_kind, count: 1 });
+                    out.push({ predicate: r.predicate, node: r.dst_node, kind: r.dst_kind, count: 1, block: r.src_block });
         }
         else {
             const rows = store.db
@@ -28,14 +28,25 @@ export function docLinks(store, docId, opts = {}) {
         }
     }
     if (dir === "in" || dir === "both") {
-        const rows = store.db
-            .prepare(`SELECT predicate, src_doc, count(*) AS cnt FROM edges
-         WHERE dst_node = ? AND to_commit IS NULL
-         GROUP BY predicate, src_doc ORDER BY predicate, src_doc`)
-            .all(docId);
-        for (const r of rows)
-            if (inPred(r.predicate))
-                inbound.push({ predicate: r.predicate, node: r.src_doc, kind: "document", count: r.cnt });
+        if (opts.blocks) {
+            const rows = store.db
+                .prepare(`SELECT predicate, src_doc, src_block FROM edges
+           WHERE dst_node = ? AND to_commit IS NULL ORDER BY predicate, src_doc, src_block`)
+                .all(docId);
+            for (const r of rows)
+                if (inPred(r.predicate))
+                    inbound.push({ predicate: r.predicate, node: r.src_doc, kind: "document", count: 1, block: r.src_block });
+        }
+        else {
+            const rows = store.db
+                .prepare(`SELECT predicate, src_doc, count(*) AS cnt FROM edges
+           WHERE dst_node = ? AND to_commit IS NULL
+           GROUP BY predicate, src_doc ORDER BY predicate, src_doc`)
+                .all(docId);
+            for (const r of rows)
+                if (inPred(r.predicate))
+                    inbound.push({ predicate: r.predicate, node: r.src_doc, kind: "document", count: r.cnt });
+        }
     }
     return { out, in: inbound };
 }

package/dist/src/index.d.ts

@@ -1,4 +1,6 @@
 export { VERSION } from "./core/index.js";
+export { versionInfo, coreVersion, nearestPackageVersion, COMPONENT_PACKAGES, type VersionInfo, type HostInfo } from "./version.js";
+export { SPEC_VERSIONS, type SpecName } from "./spec-versions.js";
 export type { FormatAdapter, AdapterEdge, ProjectedNode, EmbeddingChunk, ReconcileHints } from "./format/adapter.js";
 export { AdapterCapability } from "./format/adapter.js";
 export { registerAdapter, adapterForFormat, adapterForPath, registeredFormats, detectFormat } from "./format/registry.js";
@@ -28,7 +30,7 @@ export { observeFile, observeMany, observeOne, observeDelete, observeBatch, type
 export { buildServer, type ServerContext } from "./mcp/server.js";
 export { serveStdio, type ServeStdioHandle } from "./mcp/stdio.js";
 export { processCheckpoint, type CheckpointResult } from "./sync/checkpoint.js";
-export { reposStatus, syncStatus, type RepoStatus, type SyncStatus, type DiskStatus } from "./sync/admin.js";
+export { reposStatus, syncStatus, reposList, type RepoStatus, type SyncStatus, type DiskStatus, type ReposList } from "./sync/admin.js";
 export { docsOutline, type OutlineResult, type OutlineOptions } from "./core/read/outline.js";
 export { docsRead, reconstructContent, type DocsReadResult, type DocsReadOptions } from "./core/read/document.js";
 export { nodesGet, nodesGetMany, type GetNode, type Resolution } from "./core/read/nodes.js";
@@ -38,18 +40,18 @@ export { resolveRef, type ResolvedRef } from "./core/read/refs.js";
 export { resolve, type ResolveHit, type ResolveInput } from "./search/resolve.js";
 export { oqxRun, oqxRunAsync, collectSemanticPhrases, parseOqx, type OqxResult, type OqxHit, type OqxOptions, type EmbedQuery } from "./oqx/run.js";
 export { EmbeddingWorker, SemanticUnavailable, contextPrefix, shouldEmbed, estimateTokens, type EmbeddingProvider, type EmbedTask, type DocEmbedTask, type DocEmbedBlockRef, type DocEmbedMethod, type DocVectorRow, } from "./search/embeddings.js";
-export { buildEmbedTasks, buildDocEmbedTasks } from "./search/tasks.js";
+export { buildEmbedTasks, buildDocEmbedTasks, staleEmbedCount } from "./search/tasks.js";
 export { EmbedDrainer, type DrainerOptions } from "./search/drain.js";
 export { embeddingSettings, type EmbeddingSettings } from "./search/provider.js";
 export { createExternalProvider, type ExternalProvider } from "./search/external.js";
 export { hybridSearch, type HybridHit, type HybridInput } from "./search/rrf.js";
 export { vectorSearch, docVectorSearch, type VectorHit, type DocVectorHit } from "./search/vector.js";
-export { historyNode, diffUnified, unifiedDiff, changesSince, type NodeChange, type CommitDigest } from "./graph/history.js";
+export { historyNode, diffUnified, docDiffUnified, diffBlocks, unifiedDiff, changesSince, RevisionNotFound, type NodeChange, type CommitDigest, type DocDiffUnified, type DiffEntry } from "./graph/history.js";
 export { docLinks, type LinksResult, type LinkEdge, type LinksOptions } from "./graph/links.js";
 export { FilterInvalid } from "./search/cel/parser.js";
-export { EngineError, type ErrorCode } from "./mcp/errors.js";
+export { EngineError, errorBody, type ErrorCode, type ErrorBody } from "./mcp/errors.js";
 export { MutationError } from "./mutate/tree.js";
-export { isValidId, prefixOf, mintId, setIdMinter, withIdMinter, sequentialMinter, type IdMinter, type IdPrefix } from "./core/ids.js";
+export { isValidId, prefixOf, mintId, setIdMinter, withIdMinter, sequentialMinter, repeatingMinter, registerIdOracle, type IdMinter, type IdOracle, type IdPrefix } from "./core/ids.js";
 export { pinClock, withClock } from "./core/clock.js";
 export { sha256 } from "./core/hash.js";
 export { ingestFile, type IngestResult } from "./core/ingest.js";
@@ -63,3 +65,4 @@ export { planUpdate, applyOpset, docsUpdate, type PlanUpdateOptions, type ApplyO
 export { opsetKernelOps, renderOpsetPlan, serializeOpset, parseOpset, type Opset, type PlanOp, type OpsetSummary, type OpsetPrecondition, type PlanDisposition, } from "./mutate/opset.js";
 export { rebuildIndex, type RebuildTarget } from "./core/store/rebuild.js";
 export { runGc, type GcResult } from "./core/store/gc.js";
+export { LIVE_LEAF_SQL, ftsIndexedRowCount, liveLeafCount } from "./core/store/fts.js";

package/dist/src/index.js

@@ -1,4 +1,6 @@
 export { VERSION } from "./core/index.js";
+export { versionInfo, coreVersion, nearestPackageVersion, COMPONENT_PACKAGES } from "./version.js";
+export { SPEC_VERSIONS } from "./spec-versions.js";
 export { AdapterCapability } from "./format/adapter.js";
 export { registerAdapter, adapterForFormat, adapterForPath, registeredFormats, detectFormat } from "./format/registry.js";
 export { markdownAdapter, MARKDOWN_FORMAT } from "./format/markdown.js";
@@ -28,7 +30,7 @@ export { observeFile, observeMany, observeOne, observeDelete, observeBatch } fro
 export { buildServer } from "./mcp/server.js";
 export { serveStdio } from "./mcp/stdio.js";
 export { processCheckpoint } from "./sync/checkpoint.js";
-export { reposStatus, syncStatus } from "./sync/admin.js";
+export { reposStatus, syncStatus, reposList } from "./sync/admin.js";
 // Read surface consumed by CLI read commands (11 §5.2–5.5).
 export { docsOutline } from "./core/read/outline.js";
 export { docsRead, reconstructContent } from "./core/read/document.js";
@@ -43,18 +45,18 @@ export { oqxRun, oqxRunAsync, collectSemanticPhrases, parseOqx } from "./oqx/run
 // Embeddings + semantic retrieval (05 §5–6). The provider is a plugin loaded by
 // package name; core carries no ML dependency.
 export { EmbeddingWorker, SemanticUnavailable, contextPrefix, shouldEmbed, estimateTokens, } from "./search/embeddings.js";
-export { buildEmbedTasks, buildDocEmbedTasks } from "./search/tasks.js";
+export { buildEmbedTasks, buildDocEmbedTasks, staleEmbedCount } from "./search/tasks.js";
 export { EmbedDrainer } from "./search/drain.js";
 export { embeddingSettings } from "./search/provider.js";
 export { createExternalProvider } from "./search/external.js";
 export { hybridSearch } from "./search/rrf.js";
 export { vectorSearch, docVectorSearch } from "./search/vector.js";
-export { historyNode, diffUnified, unifiedDiff, changesSince } from "./graph/history.js";
+export { historyNode, diffUnified, docDiffUnified, diffBlocks, unifiedDiff, changesSince, RevisionNotFound } from "./graph/history.js";
 export { docLinks } from "./graph/links.js";
 export { FilterInvalid } from "./search/cel/parser.js";
-export { EngineError } from "./mcp/errors.js";
+export { EngineError, errorBody } from "./mcp/errors.js";
 export { MutationError } from "./mutate/tree.js";
-export { isValidId, prefixOf, mintId, setIdMinter, withIdMinter, sequentialMinter } from "./core/ids.js";
+export { isValidId, prefixOf, mintId, setIdMinter, withIdMinter, sequentialMinter, repeatingMinter, registerIdOracle } from "./core/ids.js";
 // The clock seam (spec/surface §7.1): `omg mcp` pins the process clock under OMGBASE_SPEC_CLOCK.
 export { pinClock, withClock } from "./core/clock.js";
 export { sha256 } from "./core/hash.js";
@@ -73,4 +75,5 @@ export { planUpdate, applyOpset, docsUpdate, } from "./mutate/plan-update.js";
 export { opsetKernelOps, renderOpsetPlan, serializeOpset, parseOpset, } from "./mutate/opset.js";
 export { rebuildIndex } from "./core/store/rebuild.js";
 export { runGc } from "./core/store/gc.js";
+export { LIVE_LEAF_SQL, ftsIndexedRowCount, liveLeafCount } from "./core/store/fts.js";
 //# sourceMappingURL=index.js.map

package/dist/src/mcp/errors.d.ts

@@ -15,3 +15,11 @@ export declare class EngineError extends Error {
     });
     body(): EngineErrorBody;
 }
+/** The rendered body of any thrown error (`error` is the code). */
+export interface ErrorBody {
+    error: string;
+    message: string;
+    data?: unknown;
+    retriable: boolean;
+}
+export declare function errorBody(err: unknown): ErrorBody;