@omgbase/core 0.1.0

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

@@ -0,0 +1,102 @@
+import { loadDocBlocks, blockRaw } from "./reader.js";
+function firstWords(text, n) {
+    const w = text.split(/\s+/).filter(Boolean);
+    return w.length <= n ? w.join(" ") : w.slice(0, n).join(" ") + "…";
+}
+function project(store, node, resolution, includeChildren) {
+    const out = { id: node.blockId, type: node.type };
+    switch (resolution) {
+        case "skeleton":
+            out.label = node.type === "heading" ? node.text : node.type;
+            break;
+        case "outline":
+            out.label = firstWords(node.text, 10);
+            break;
+        case "text":
+            out.text = node.text;
+            break;
+        case "raw":
+            out.raw = blockRaw(store, node.rawHashHex);
+            out.content_hash = node.rawHashHex;
+            break;
+        case "full":
+            out.raw = blockRaw(store, node.rawHashHex);
+            out.content_hash = node.rawHashHex;
+            out.text = node.text;
+            out.attrs = node.attrs;
+            out.placement = { parent: node.parentBlock, ordinal: node.ordinal, depth: node.depth };
+            break;
+    }
+    if (includeChildren && node.children.length > 0) {
+        out.children = node.children.map((c) => project(store, c, resolution, true));
+    }
+    return out;
+}
+function findBlock(roots, blockId) {
+    for (const n of roots) {
+        if (n.blockId === blockId)
+            return n;
+        const found = findBlock(n.children, blockId);
+        if (found)
+            return found;
+    }
+    return null;
+}
+/** Fetch a single block subtree at a resolution. Returns null if missing. */
+export function nodesGet(store, docId, blockId, opts = {}) {
+    const roots = loadDocBlocks(store, docId);
+    const node = findBlock(roots, blockId);
+    if (!node)
+        return null;
+    const includeChildren = opts.include?.includes("children") ?? true;
+    return project(store, node, opts.resolution ?? "full", includeChildren);
+}
+/**
+ * Fetch up to 100 blocks by id, with budget truncation (06 §3). Block ids are
+ * globally unique, so `docId` is an optional SCOPE, not a requirement: with
+ * `null` each id is resolved to its owning document (`blocks.doc_id`), the ids
+ * are grouped by doc, each doc's forest is loaded once, and the nodes come back
+ * in request order. With a `docId`, ids from other documents count as
+ * `unresolved` (the caller asked for that doc's blocks).
+ */
+export function nodesGetMany(store, docId, blockIds, opts = {}) {
+    const capped = blockIds.slice(0, 100);
+    const budget = opts.budgetTokens ?? Infinity;
+    const resolution = opts.resolution ?? "text";
+    // id → owning doc for every requested id that is a live block (one query).
+    const owner = new Map();
+    if (capped.length > 0) {
+        const rows = store.db
+            .prepare(`SELECT block_id, doc_id FROM blocks WHERE deleted_commit IS NULL AND block_id IN (${capped.map(() => "?").join(",")})`)
+            .all(...capped);
+        for (const r of rows)
+            if (docId === null || r.doc_id === docId)
+                owner.set(r.block_id, r.doc_id);
+    }
+    // Load each involved document's forest once.
+    const forests = new Map();
+    for (const d of new Set(owner.values()))
+        forests.set(d, loadDocBlocks(store, d));
+    const nodes = [];
+    const unresolved = [];
+    let tokens = 0;
+    let truncated = blockIds.length > 100;
+    for (const id of capped) {
+        const d = owner.get(id);
+        const node = d ? findBlock(forests.get(d), id) : null;
+        if (!node) {
+            unresolved.push(id);
+            continue;
+        }
+        const projected = project(store, node, resolution, false);
+        const cost = Math.ceil(JSON.stringify(projected).length / 4);
+        if (tokens + cost > budget) {
+            truncated = true;
+            break;
+        }
+        tokens += cost;
+        nodes.push(projected);
+    }
+    return { nodes, truncated, unresolved };
+}
+//# sourceMappingURL=nodes.js.map

package/dist/src/core/read/outline.d.ts

@@ -0,0 +1,12 @@
+import type { Store } from "../store/store.js";
+export interface OutlineResult {
+    text: string;
+    truncated: boolean;
+}
+export interface OutlineOptions {
+    resolution?: "skeleton" | "outline";
+    depth?: number;
+    budgetTokens?: number;
+}
+/** Render a document outline in the frozen wire format. */
+export declare function docsOutline(store: Store, docId: string, opts?: OutlineOptions): OutlineResult;

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

@@ -0,0 +1,76 @@
+import { loadDocBlocks } from "./reader.js";
+// Outline wire format (06 §6). Each line:
+//   <block-id> <type-abbr> <label>         [§ for section-owning headings]
+// The full block id (b_…) is emitted inline so it can be used directly in
+// follow-up ops without a separate alias→id lookup table.
+const TYPE_ABBR = {
+    heading: "h",
+    paragraph: "p",
+    list: "ul",
+    list_item: "li",
+    task: "li",
+    blockquote: "bq",
+    code_fence: "code",
+    table: "tbl",
+    table_row: "tr",
+    thematic_break: "hr",
+    html_block: "html",
+    opaque: "raw",
+};
+function typeLabel(node) {
+    if (node.type === "heading")
+        return `h${node.attrs.level ?? ""}`;
+    return TYPE_ABBR[node.type] ?? node.type;
+}
+// Structural containers carry no label of their own; their content is in
+// children (matches the frozen format example, 06 §6: `b03 ul` has no label).
+const CONTAINER_TYPES = new Set(["list", "blockquote", "table"]);
+function labelFor(node) {
+    if (CONTAINER_TYPES.has(node.type))
+        return "";
+    if (node.type === "task") {
+        const glyph = node.attrs.checked ? "☑" : "☐";
+        return `${glyph} ${truncateWords(node.text, 10)}`;
+    }
+    return truncateWords(node.text, 10);
+}
+function truncateWords(text, n) {
+    const words = text.split(/\s+/).filter(Boolean);
+    if (words.length <= n)
+        return words.join(" ");
+    return words.slice(0, n).join(" ") + "…";
+}
+/** Render a document outline in the frozen wire format. */
+export function docsOutline(store, docId, opts = {}) {
+    const roots = loadDocBlocks(store, docId);
+    const resolution = opts.resolution ?? "outline";
+    const maxDepth = opts.depth ?? Infinity;
+    const budget = opts.budgetTokens ?? Infinity;
+    const lines = [];
+    let tokens = 0;
+    let truncated = false;
+    const walk = (nodes, indent) => {
+        for (const node of nodes) {
+            if (truncated)
+                return;
+            if (indent > maxDepth)
+                continue;
+            const pad = "  ".repeat(indent);
+            const sectionMark = node.type === "heading" ? "  §" : "";
+            const label = resolution === "skeleton" ? "" : labelFor(node);
+            const line = `${pad}${node.blockId} ${typeLabel(node).padEnd(4)} ${label}${sectionMark}`.trimEnd();
+            const lineTokens = Math.ceil(line.length / 4);
+            if (tokens + lineTokens > budget) {
+                truncated = true;
+                return;
+            }
+            tokens += lineTokens;
+            lines.push(line);
+            if (node.children.length > 0)
+                walk(node.children, indent + 1);
+        }
+    };
+    walk(roots, 0);
+    return { text: lines.join("\n"), truncated };
+}
+//# sourceMappingURL=outline.js.map

package/dist/src/core/read/reader.d.ts

@@ -0,0 +1,125 @@
+import type { Store } from "../store/store.js";
+/** One row of the `ls` / docs_list surface: a live document with its block
+ *  count and last-commit timestamp. */
+export interface DocListRow {
+    path: string;
+    blocks: number;
+    ts: string | null;
+}
+/** A page of the docs_list surface. Honors the uniform list contract (mcp-api
+ *  §1): `truncated` is honest, and when true `cursor` resumes after the last
+ *  item returned. */
+export interface DocListPage {
+    items: DocListRow[];
+    truncated: boolean;
+    cursor: string | null;
+}
+export interface DocListOptions {
+    /** Simple LIKE match on the path (`*` → any run, ACROSS `/`). */
+    pathGlob?: string;
+    /** Max rows per page (default DOCS_LIST_DEFAULT_LIMIT). */
+    limit?: number;
+    /** Resume after a previous page's `cursor`. */
+    cursor?: string | null;
+    /** Cap the page's estimated size (~4 chars/token); at least one row is always
+     *  returned so a paging client makes progress. */
+    budgetTokens?: number;
+}
+export declare const DOCS_LIST_DEFAULT_LIMIT = 200;
+/** List a repo's live documents (path, block count, last-commit ts), ordered by
+ *  path, as a page: `{ items, truncated, cursor }`. `pathGlob` is a simple LIKE
+ *  match (`*` → `%`). Backs `omg ls` and the `docs_list` MCP tool (one
+ *  implementation for both surfaces). For a directory-aware summary use
+ *  `docsTree`. */
+export declare function docsList(store: Store, repoId: string, opts?: DocListOptions): DocListPage;
+/** One entry of the docs_tree surface: a live document (`kind: "doc"`) or a
+ *  collapsed directory (`kind: "dir"`, path ends in `/`) at the requested
+ *  depth. `docs`/`blocks` are totals under the entry (a doc counts 1 doc);
+ *  `ts` is the latest last-commit timestamp under it. */
+export interface DocTreeEntry {
+    path: string;
+    kind: "dir" | "doc";
+    docs: number;
+    blocks: number;
+    ts: string | null;
+}
+export interface DocTreePage {
+    /** The normalized directory prefix the tree was taken under (`""` = root;
+     *  otherwise ends in `/`). */
+    prefix: string;
+    depth: number;
+    /** Totals over EVERYTHING under `prefix`, regardless of paging. */
+    total: {
+        docs: number;
+        blocks: number;
+    };
+    entries: DocTreeEntry[];
+    truncated: boolean;
+    cursor: string | null;
+}
+export interface DocTreeOptions {
+    /** Directory to take the tree under (`projects` or `projects/`; leading `/`
+     *  tolerated). Omit for the repo root. */
+    path?: string;
+    /** How many path segments below `prefix` to expand before collapsing
+     *  (default 1 = immediate children, like `tree -L 1`). */
+    depth?: number;
+    limit?: number;
+    cursor?: string | null;
+    budgetTokens?: number;
+}
+export declare const DOCS_TREE_DEFAULT_LIMIT = 200;
+/** Normalize a tree prefix: no leading `/`, and either empty or ending in `/`. */
+export declare function normalizeTreePrefix(path: string | undefined): string;
+/** The path-separator-aware orientation read (`tree -L depth` + `du`): every
+ *  live doc under `path` is collapsed at `depth` segments into one entry per
+ *  directory (with doc/block totals + latest ts) or listed as a doc when it is
+ *  shallow enough. Entries are ordered by path; dirs carry a trailing `/`. The
+ *  result is paged under the same limit/cursor/budget contract as docsList,
+ *  and always carries `total` for the whole prefix so an agent sees the size of
+ *  what it is looking at even when the page is cut. Backs the `docs_tree` MCP
+ *  tool. */
+export declare function docsTree(store: Store, repoId: string, opts?: DocTreeOptions): DocTreePage;
+export interface BlockNode {
+    blockId: string;
+    docId: string;
+    parentBlock: string | null;
+    ordinal: number;
+    depth: number;
+    type: string;
+    attrs: Record<string, unknown>;
+    text: string;
+    rawHashHex: string;
+    children: BlockNode[];
+}
+/** Load a document's live blocks as a containment forest, ordered. */
+export declare function loadDocBlocks(store: Store, docId: string): BlockNode[];
+/** Retrieve the raw source bytes for a block by its raw_hash. */
+export declare function blockRaw(store: Store, rawHashHex: string): string;
+export interface DocInfo {
+    docId: string;
+    repoId: string;
+    path: string;
+    format: string;
+    currentRev: string | null;
+}
+export declare function findDoc(store: Store, ref: {
+    docId?: string;
+    repoId?: string;
+    path?: string;
+}): DocInfo | null;
+/**
+ * Resolve a single `doc` ref that may be EITHER a minted document id (`d_…`) OR
+ * a repo-relative path — the id-or-path symmetry every doc-ref surface expects
+ * (docs_read/outline/read_at, diff, apply's insert.doc, graph seeds, docHistory).
+ * This is the ONE dispatch those call sites route through so the "path in the
+ * doc field" trap can't recur per-tool.
+ *
+ * A `d_`-shaped id is looked up by id ONLY — if it doesn't exist we return null
+ * (the caller fails loud) rather than falling through to a path lookup that
+ * would also miss and confusingly report a path-not-found for a d_ value.
+ * Anything else is treated as a path. Returns null when unresolvable; callers
+ * throw a clear doc_missing/target_missing so an unresolvable ref is never a
+ * silent empty result.
+ */
+export declare function findDocByRef(store: Store, repoId: string, ref: string): DocInfo | null;

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

@@ -0,0 +1,206 @@
+import { isValidId } from "../ids.js";
+import { encodeCursor, decodeCursor } from "../cursor.js";
+export const DOCS_LIST_DEFAULT_LIMIT = 200;
+/** Escape a user glob into a LIKE pattern (`*` → `%`; literal `%`/`_` escaped). */
+function globToLike(glob) {
+    return glob.replace(/[%_\\]/g, "\\$&").replace(/\*/g, "%");
+}
+/** Live docs of a repo (path, live block count, last-commit ts) whose path
+ *  matches `like`, ordered by path, optionally resuming strictly after `after`
+ *  and capped at `limit`. The one query behind docs_list and docs_tree. */
+function liveDocRows(store, repoId, like, after, limit) {
+    const params = [repoId, like];
+    let where = "";
+    if (after !== null) {
+        where += " AND d.path > ?";
+        params.push(after);
+    }
+    let tail = "";
+    if (limit !== null) {
+        tail = " LIMIT ?";
+        params.push(limit);
+    }
+    return store.db
+        .prepare(`SELECT d.path AS path,
+              (SELECT count(*) FROM blocks b WHERE b.doc_id = d.doc_id AND b.deleted_commit IS NULL) AS blocks,
+              (SELECT c.ts FROM revisions r JOIN commits c ON c.commit_id = r.commit_id WHERE r.rev_id = d.current_rev) AS ts
+       FROM docs d
+       WHERE d.repo_id = ? AND d.deleted_commit IS NULL AND d.path LIKE ? ESCAPE '\\'${where}
+       ORDER BY d.path${tail}`)
+        .all(...params);
+}
+// Path-keyset cursors for the path-ordered list surfaces: the shared kernel
+// encoding (core/cursor.ts) with a one-part tuple.
+function encodePathCursor(path) {
+    return encodeCursor([path]);
+}
+function decodePathCursor(cursor) {
+    return decodeCursor(cursor, "docs_list/docs_tree", 1)[0];
+}
+/** Page an already path-ordered row set under a limit + token budget, issuing
+ *  a keyset cursor when it stops early. Shared by docs_list and docs_tree. */
+function pagePathOrdered(rows, limit, budgetTokens, moreBeyond) {
+    const budget = budgetTokens ?? Infinity;
+    const items = [];
+    let tokens = 0;
+    let truncated = moreBeyond;
+    for (const row of rows) {
+        if (items.length >= limit) {
+            truncated = true;
+            break;
+        }
+        const cost = Math.ceil(JSON.stringify(row).length / 4);
+        if (items.length > 0 && tokens + cost > budget) {
+            truncated = true;
+            break;
+        }
+        tokens += cost;
+        items.push(row);
+    }
+    const last = items[items.length - 1];
+    return { items, truncated, cursor: truncated && last ? encodePathCursor(last.path) : null };
+}
+/** List a repo's live documents (path, block count, last-commit ts), ordered by
+ *  path, as a page: `{ items, truncated, cursor }`. `pathGlob` is a simple LIKE
+ *  match (`*` → `%`). Backs `omg ls` and the `docs_list` MCP tool (one
+ *  implementation for both surfaces). For a directory-aware summary use
+ *  `docsTree`. */
+export function docsList(store, repoId, opts = {}) {
+    const like = opts.pathGlob ? globToLike(opts.pathGlob) : "%";
+    const limit = Math.max(1, Math.floor(opts.limit ?? DOCS_LIST_DEFAULT_LIMIT));
+    const after = opts.cursor ? decodePathCursor(opts.cursor) : null;
+    // Fetch one past the limit so `truncated` is a fact, not a guess.
+    const rows = liveDocRows(store, repoId, like, after, limit + 1);
+    const moreBeyond = rows.length > limit;
+    return pagePathOrdered(rows.slice(0, limit), limit, opts.budgetTokens, moreBeyond);
+}
+export const DOCS_TREE_DEFAULT_LIMIT = 200;
+/** Normalize a tree prefix: no leading `/`, and either empty or ending in `/`. */
+export function normalizeTreePrefix(path) {
+    const trimmed = (path ?? "").replace(/^\/+/, "").replace(/\/+$/, "");
+    return trimmed === "" ? "" : trimmed + "/";
+}
+/** The path-separator-aware orientation read (`tree -L depth` + `du`): every
+ *  live doc under `path` is collapsed at `depth` segments into one entry per
+ *  directory (with doc/block totals + latest ts) or listed as a doc when it is
+ *  shallow enough. Entries are ordered by path; dirs carry a trailing `/`. The
+ *  result is paged under the same limit/cursor/budget contract as docsList,
+ *  and always carries `total` for the whole prefix so an agent sees the size of
+ *  what it is looking at even when the page is cut. Backs the `docs_tree` MCP
+ *  tool. */
+export function docsTree(store, repoId, opts = {}) {
+    const prefix = normalizeTreePrefix(opts.path);
+    const depth = Math.max(1, Math.floor(opts.depth ?? 1));
+    const limit = Math.max(1, Math.floor(opts.limit ?? DOCS_TREE_DEFAULT_LIMIT));
+    const like = prefix === "" ? "%" : globToLike(prefix) + "%";
+    const rows = liveDocRows(store, repoId, like, null, null);
+    const byPath = new Map();
+    const total = { docs: 0, blocks: 0 };
+    for (const row of rows) {
+        total.docs += 1;
+        total.blocks += row.blocks;
+        const segs = row.path.slice(prefix.length).split("/");
+        if (segs.length <= depth) {
+            byPath.set(row.path, { path: row.path, kind: "doc", docs: 1, blocks: row.blocks, ts: row.ts });
+            continue;
+        }
+        const dir = prefix + segs.slice(0, depth).join("/") + "/";
+        const cur = byPath.get(dir);
+        if (cur) {
+            cur.docs += 1;
+            cur.blocks += row.blocks;
+            if (row.ts !== null && (cur.ts === null || row.ts > cur.ts))
+                cur.ts = row.ts;
+        }
+        else {
+            byPath.set(dir, { path: dir, kind: "dir", docs: 1, blocks: row.blocks, ts: row.ts });
+        }
+    }
+    let entries = [...byPath.values()].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    if (opts.cursor) {
+        const after = decodePathCursor(opts.cursor);
+        entries = entries.filter((e) => e.path > after);
+    }
+    const { items, truncated, cursor } = pagePathOrdered(entries, limit, opts.budgetTokens, false);
+    return { prefix, depth, total, entries: items, truncated, cursor };
+}
+function toNode(r) {
+    return {
+        blockId: r.block_id,
+        docId: r.doc_id,
+        parentBlock: r.parent_block,
+        ordinal: r.ordinal,
+        depth: r.depth,
+        type: r.type,
+        attrs: JSON.parse(r.attrs),
+        text: r.text,
+        rawHashHex: r.raw_hash.toString("hex"),
+        children: [],
+    };
+}
+/** Load a document's live blocks as a containment forest, ordered. */
+export function loadDocBlocks(store, docId) {
+    const rows = store.db
+        .prepare(`SELECT block_id, doc_id, parent_block, order_key, ordinal, depth, type, attrs, text, raw_hash
+       FROM blocks WHERE doc_id = ? AND deleted_commit IS NULL
+       ORDER BY parent_block, order_key`)
+        .all(docId);
+    const byId = new Map();
+    for (const r of rows)
+        byId.set(r.block_id, toNode(r));
+    const roots = [];
+    // Preserve order_key ordering by iterating rows (already sorted).
+    for (const r of rows) {
+        const node = byId.get(r.block_id);
+        if (r.parent_block && byId.has(r.parent_block)) {
+            byId.get(r.parent_block).children.push(node);
+        }
+        else {
+            roots.push(node);
+        }
+    }
+    return roots;
+}
+/** Retrieve the raw source bytes for a block by its raw_hash. */
+export function blockRaw(store, rawHashHex) {
+    const row = store.db.prepare("SELECT bytes FROM blobs WHERE hash = ?").get(Buffer.from(rawHashHex, "hex"));
+    return row ? row.bytes.toString("utf8") : "";
+}
+export function findDoc(store, ref) {
+    let row;
+    if (ref.docId) {
+        row = store.db.prepare("SELECT doc_id, repo_id, path, format, current_rev FROM docs WHERE doc_id = ? AND deleted_commit IS NULL").get(ref.docId);
+    }
+    else if (ref.repoId && ref.path) {
+        row = store.db.prepare("SELECT doc_id, repo_id, path, format, current_rev FROM docs WHERE repo_id = ? AND path = ? AND deleted_commit IS NULL").get(ref.repoId, ref.path);
+    }
+    if (!row)
+        return null;
+    return {
+        docId: row.doc_id,
+        repoId: row.repo_id,
+        path: row.path,
+        format: row.format ?? "markdown",
+        currentRev: row.current_rev ?? null,
+    };
+}
+/**
+ * Resolve a single `doc` ref that may be EITHER a minted document id (`d_…`) OR
+ * a repo-relative path — the id-or-path symmetry every doc-ref surface expects
+ * (docs_read/outline/read_at, diff, apply's insert.doc, graph seeds, docHistory).
+ * This is the ONE dispatch those call sites route through so the "path in the
+ * doc field" trap can't recur per-tool.
+ *
+ * A `d_`-shaped id is looked up by id ONLY — if it doesn't exist we return null
+ * (the caller fails loud) rather than falling through to a path lookup that
+ * would also miss and confusingly report a path-not-found for a d_ value.
+ * Anything else is treated as a path. Returns null when unresolvable; callers
+ * throw a clear doc_missing/target_missing so an unresolvable ref is never a
+ * silent empty result.
+ */
+export function findDocByRef(store, repoId, ref) {
+    if (isValidId(ref, "d"))
+        return findDoc(store, { docId: ref });
+    return findDoc(store, { repoId, path: ref });
+}
+//# sourceMappingURL=reader.js.map

package/dist/src/core/read/refs.d.ts

@@ -0,0 +1,15 @@
+import type { Store } from "../store/store.js";
+export interface ResolvedRef {
+    kind: "block" | "document";
+    docId: string;
+    blockId?: string;
+}
+/**
+ * Resolve a node reference within a repo. Accepts:
+ *   - a block id (prefix "b")        → { block, docId, blockId }
+ *   - a document id (prefix "d")     → { document, docId }
+ *   - a projected node id ("n_…")    → its block, or its doc when block-less
+ *   - a repo-relative document path  → { document, docId }
+ * Returns null when nothing matches.
+ */
+export declare function resolveRef(store: Store, repoId: string, ref: string): ResolvedRef | null;

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

@@ -0,0 +1,51 @@
+import { prefixOf } from "../ids.js";
+import { findDoc } from "./reader.js";
+// Node ids are content-hash derived (`n_` + 12 hex chars, see core/store/nodes),
+// not the 7-char minted scheme prefixOf recognizes — match them explicitly.
+const NODE_ID_RE = /^n_[0-9a-f]{12}$/;
+/**
+ * Resolve a node reference within a repo. Accepts:
+ *   - a block id (prefix "b")        → { block, docId, blockId }
+ *   - a document id (prefix "d")     → { document, docId }
+ *   - a projected node id ("n_…")    → its block, or its doc when block-less
+ *   - a repo-relative document path  → { document, docId }
+ * Returns null when nothing matches.
+ */
+export function resolveRef(store, repoId, ref) {
+    // A projected-node id (e.g. an OQX `from nodes` hit) dereferences to the block
+    // it was projected from — so a node hit is a first-class argument to the same
+    // read/write commands a block id is. Block-less nodes (or nodes whose block is
+    // no longer live) fall back to their document.
+    if (NODE_ID_RE.test(ref)) {
+        const node = store.db
+            .prepare("SELECT doc_id, block_id FROM nodes WHERE node_id = ?")
+            .get(ref);
+        if (!node)
+            return null;
+        if (node.block_id) {
+            const live = store.db
+                .prepare("SELECT 1 FROM blocks WHERE block_id = ? AND deleted_commit IS NULL")
+                .get(node.block_id);
+            if (live)
+                return { kind: "block", docId: node.doc_id, blockId: node.block_id };
+        }
+        return { kind: "document", docId: node.doc_id };
+    }
+    const prefix = prefixOf(ref);
+    if (prefix === "b") {
+        const row = store.db
+            .prepare("SELECT doc_id FROM blocks WHERE block_id = ? AND deleted_commit IS NULL")
+            .get(ref);
+        if (!row)
+            return null;
+        return { kind: "block", docId: row.doc_id, blockId: ref };
+    }
+    if (prefix === "d") {
+        const info = findDoc(store, { docId: ref });
+        return info ? { kind: "document", docId: info.docId } : null;
+    }
+    // Otherwise treat it as a document path.
+    const info = findDoc(store, { repoId, path: ref });
+    return info ? { kind: "document", docId: info.docId } : null;
+}
+//# sourceMappingURL=refs.js.map

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

@@ -0,0 +1,26 @@
+import type { Database } from "better-sqlite3";
+export interface ResolvedEdge {
+    srcDoc: string;
+    srcBlock: string | null;
+    srcField: string | null;
+    predicate: string;
+    dstKind: "document" | "block" | "external" | "collection";
+    dstNode: string;
+    anchor: string | null;
+    provenance: string;
+}
+/**
+ * Reconcile the extracted edge set for a document against its currently-open
+ * rows: close rows no longer present (to_commit = this), open rows that are new
+ * (from_commit = this), leave unchanged rows untouched. Then recompute the
+ * doc_edges rollup for the doc. All within the caller's transaction.
+ */
+export declare function maintainEdges(db: Database, repoId: string, srcDoc: string, commitId: string, edges: ResolvedEdge[]): void;
+export declare function adoptPhantoms(db: Database, path: string, realDocId: string): void;
+/** Recompute the doc_edges rollup for one document from its open edges. */
+export declare function rebuildDocEdges(db: Database, srcDoc: string): void;
+export declare function resolveExternal(db: Database, repoId: string, uri: string): string;
+export declare function resolveDocPath(db: Database, repoId: string, path: string): {
+    id: string;
+    phantom: boolean;
+};