@omgbase/core 0.1.0

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

@@ -0,0 +1,38 @@
+export declare const EXTRACTION_VERSION = "x2";
+export type DstKind = "document" | "block" | "external" | "collection";
+export type Provenance = "link" | "frontmatter" | "inline_field";
+export interface ExtractedEdge {
+    srcBlock: string | null;
+    srcField: string | null;
+    predicate: string;
+    dstKind: DstKind;
+    /** raw target string: a repo path, wikilink name, or URL (store resolves) */
+    target: string;
+    anchor: string | null;
+    provenance: Provenance;
+}
+/**
+ * Resolve a `./foo` / `../bar` destination against the source document's
+ * directory (`docDir` = path with the filename stripped, e.g. "a/b/" or "").
+ * Any other destination is returned as-is (root-relative). The ONE resolution
+ * rule shared by edge extraction (sync/reconciling-ingest.ts) and docs_move's
+ * inbound-link scan (graph/inbound-links.ts) so they agree on what a link
+ * points at.
+ */
+export declare function resolveRelativePath(target: string, docDir: string): string;
+export declare function normalizeUri(uri: string): string;
+/**
+ * Mask code in a block's raw markdown — fenced code (``` / ~~~, incl. the fence
+ * lines, closed by a same-char fence at least as long, or running to the end)
+ * and inline code spans (a backtick run of length n closed by the next run of
+ * EXACTLY n; an unmatched run stays literal, per CommonMark). Length-preserving:
+ * masked characters become spaces, newlines are kept. Container blocks (list,
+ * list_item, blockquote) carry their children's raw, so a fence nested in a
+ * list item is masked here too. Shared by edge extraction and md:* node
+ * projection so nodes and edges agree on what counts as a link.
+ */
+export declare function maskCode(raw: string): string;
+/** Extract edges from a single block's raw markdown. Code is skipped: a
+ *  `code_fence` block yields nothing, and inline code spans are masked. */
+export declare function extractFromBlock(blockId: string, blockType: string, rawInput: string): ExtractedEdge[];
+export declare function extractFromFrontmatter(fm: Record<string, unknown>): ExtractedEdge[];

package/dist/src/graph/extract.js

@@ -0,0 +1,242 @@
+// Edge extraction, extraction_version x2 (05 §2). A pure function of
+// (block content, frontmatter). Produces edge descriptors; the store layer
+// resolves targets to node ids and maintains intervals. No identity is
+// inherited here — extraction is recomputed fresh at every revision.
+//
+// x2: code is not prose. `code_fence` blocks yield no edges, and inline code
+// spans (`` `…` ``, any backtick-run length) are masked before scanning, so a
+// backticked `[[wikilink]]` example, a placeholder `[t](/path)` in a fence, or
+// a regex fragment with square brackets no longer mints a `references` edge
+// (and links_stale no longer reports them as dangling). There is no persisted
+// extraction version — an existing repo re-extracts a document the next time
+// that document is ingested (checkpoint/observe/apply), not via rebuild-index.
+export const EXTRACTION_VERSION = "x2";
+// --- link/inline scanners (operate on a block's raw markdown) ----------------
+const MD_LINK = /(!?)\[[^\]]*\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g; // [t](dest) / ![alt](dest)
+const WIKILINK = /(!?)\[\[([^\]]+)\]\]/g; // [[note]] / [[note#H]] / [[note^ref]]
+const BARE_URL = /(?<![("[])\bhttps?:\/\/[^\s)>\]]+/g;
+const AUTOLINK = /<(https?:\/\/[^>]+)>/g;
+const INLINE_FIELD = /(?:^|\s)([a-z][a-z0-9_]*)::\s*(\[\[[^\]]+\]\]|\/[^\s]+|https?:\/\/[^\s]+)/gi;
+function splitAnchor(target) {
+    const hashIdx = target.indexOf("#");
+    const caretIdx = target.indexOf("^");
+    if (caretIdx >= 0 && (hashIdx < 0 || caretIdx < hashIdx)) {
+        return { path: target.slice(0, caretIdx), anchor: target.slice(caretIdx + 1), anchorKind: "ref" };
+    }
+    if (hashIdx >= 0) {
+        return { path: target.slice(0, hashIdx), anchor: target.slice(hashIdx + 1), anchorKind: "heading" };
+    }
+    return { path: target, anchor: null, anchorKind: null };
+}
+/**
+ * Resolve a `./foo` / `../bar` destination against the source document's
+ * directory (`docDir` = path with the filename stripped, e.g. "a/b/" or "").
+ * Any other destination is returned as-is (root-relative). The ONE resolution
+ * rule shared by edge extraction (sync/reconciling-ingest.ts) and docs_move's
+ * inbound-link scan (graph/inbound-links.ts) so they agree on what a link
+ * points at.
+ */
+export function resolveRelativePath(target, docDir) {
+    if (!target.startsWith("./") && !target.startsWith("../"))
+        return target;
+    const parts = (docDir + target).split("/");
+    const resolved = [];
+    for (const p of parts) {
+        if (p === "." || p === "")
+            continue;
+        if (p === "..") {
+            resolved.pop();
+            continue;
+        }
+        resolved.push(p);
+    }
+    return resolved.join("/");
+}
+function isExternal(dest) {
+    return /^https?:\/\//.test(dest) || /^[a-z][a-z0-9+.-]*:/i.test(dest) === true && !dest.startsWith("/");
+}
+function classifyTarget(dest) {
+    if (/^https?:\/\//.test(dest))
+        return { dstKind: "external", target: normalizeUri(dest), anchor: null };
+    const { path, anchor, anchorKind } = splitAnchor(dest);
+    // A pure fragment link (#H or ^ref) with empty path targets the same doc; we
+    // still emit a document edge with the anchor (store resolves to self).
+    const dstKind = anchorKind === "ref" ? "block" : "document";
+    return { dstKind, target: path, anchor };
+}
+export function normalizeUri(uri) {
+    try {
+        const u = new URL(uri);
+        u.hash = "";
+        u.protocol = u.protocol.toLowerCase();
+        u.hostname = u.hostname.toLowerCase();
+        if ((u.protocol === "http:" && u.port === "80") || (u.protocol === "https:" && u.port === "443"))
+            u.port = "";
+        return u.toString().replace(/\/$/, "");
+    }
+    catch {
+        return uri;
+    }
+}
+// --- code masking -------------------------------------------------------------
+const FENCE_OPEN = /^[ \t]*(`{3,}|~{3,})/;
+const FENCE_CLOSE = /^[ \t]*(`{3,}|~{3,})[ \t]*$/;
+// Blank out every non-newline character of `s` so offsets are preserved (node
+// projection records spans into the ORIGINAL raw; a length-preserving mask keeps
+// those spans valid).
+function blank(s) {
+    return s.replace(/[^\n]/g, " ");
+}
+/**
+ * Mask code in a block's raw markdown — fenced code (``` / ~~~, incl. the fence
+ * lines, closed by a same-char fence at least as long, or running to the end)
+ * and inline code spans (a backtick run of length n closed by the next run of
+ * EXACTLY n; an unmatched run stays literal, per CommonMark). Length-preserving:
+ * masked characters become spaces, newlines are kept. Container blocks (list,
+ * list_item, blockquote) carry their children's raw, so a fence nested in a
+ * list item is masked here too. Shared by edge extraction and md:* node
+ * projection so nodes and edges agree on what counts as a link.
+ */
+export function maskCode(raw) {
+    if (!raw.includes("`") && !raw.includes("~~~"))
+        return raw;
+    // 1. Fenced code blocks, line by line.
+    const lines = raw.split("\n");
+    let open = null;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (open) {
+            const m = FENCE_CLOSE.exec(line);
+            lines[i] = blank(line);
+            if (m && m[1][0] === open.ch && m[1].length >= open.len)
+                open = null;
+            continue;
+        }
+        const m = FENCE_OPEN.exec(line);
+        if (m) {
+            const fence = m[1];
+            // A backtick fence's info string may not contain a backtick.
+            if (fence[0] === "`" && line.slice(m[0].length).includes("`"))
+                continue;
+            open = { ch: fence[0], len: fence.length };
+            lines[i] = blank(line);
+        }
+    }
+    let out = lines.join("\n");
+    // 2. Inline code spans over what remains.
+    let i = 0;
+    while (i < out.length) {
+        if (out[i] !== "`") {
+            i++;
+            continue;
+        }
+        let j = i;
+        while (j < out.length && out[j] === "`")
+            j++;
+        const n = j - i;
+        // Find the next backtick run of exactly n.
+        let k = j;
+        let close = -1;
+        while (k < out.length) {
+            if (out[k] !== "`") {
+                k++;
+                continue;
+            }
+            let e = k;
+            while (e < out.length && out[e] === "`")
+                e++;
+            if (e - k === n) {
+                close = k;
+                break;
+            }
+            k = e;
+        }
+        if (close < 0) {
+            i = j;
+            continue;
+        }
+        out = out.slice(0, i) + blank(out.slice(i, close + n)) + out.slice(close + n);
+        i = close + n;
+    }
+    return out;
+}
+/** Extract edges from a single block's raw markdown. Code is skipped: a
+ *  `code_fence` block yields nothing, and inline code spans are masked. */
+export function extractFromBlock(blockId, blockType, rawInput) {
+    const edges = [];
+    if (blockType === "code_fence")
+        return edges;
+    const raw = maskCode(rawInput);
+    const seen = new Set();
+    const push = (e) => {
+        const k = `${e.predicate}|${e.target}|${e.anchor ?? ""}|${e.srcField ?? ""}`;
+        if (seen.has(k))
+            return;
+        seen.add(k);
+        edges.push(e);
+    };
+    // Inline fields first (so their targets aren't double-counted as plain links).
+    const inlineTargets = new Set();
+    for (const m of raw.matchAll(INLINE_FIELD)) {
+        const key = m[1].toLowerCase();
+        const rawTarget = m[2];
+        inlineTargets.add(rawTarget);
+        const wl = /^\[\[([^\]]+)\]\]$/.exec(rawTarget);
+        const dest = wl ? wl[1] : rawTarget;
+        const c = classifyTarget(dest);
+        push({ srcBlock: blockId, srcField: key, predicate: key, dstKind: c.dstKind, target: c.target, anchor: c.anchor, provenance: "inline_field" });
+    }
+    // Markdown links and images.
+    for (const m of raw.matchAll(MD_LINK)) {
+        const isImg = m[1] === "!";
+        const dest = m[2];
+        if (inlineTargets.has(dest))
+            continue;
+        const c = classifyTarget(dest);
+        push({ srcBlock: blockId, srcField: null, predicate: isImg ? "embeds" : "references", dstKind: c.dstKind, target: c.target, anchor: c.anchor, provenance: "link" });
+    }
+    // Wikilinks.
+    for (const m of raw.matchAll(WIKILINK)) {
+        const isImg = m[1] === "!";
+        const inner = m[2];
+        if (inlineTargets.has(`[[${inner}]]`))
+            continue;
+        const c = classifyTarget(inner);
+        push({ srcBlock: blockId, srcField: null, predicate: isImg ? "embeds" : "references", dstKind: c.dstKind, target: c.target, anchor: c.anchor, provenance: "link" });
+    }
+    // Autolinks + bare URLs → external.
+    for (const m of raw.matchAll(AUTOLINK))
+        push({ srcBlock: blockId, srcField: null, predicate: "references", dstKind: "external", target: normalizeUri(m[1]), anchor: null, provenance: "link" });
+    for (const m of raw.matchAll(BARE_URL))
+        push({ srcBlock: blockId, srcField: null, predicate: "references", dstKind: "external", target: normalizeUri(m[0]), anchor: null, provenance: "link" });
+    void isExternal;
+    return edges;
+}
+// --- frontmatter relation fields --------------------------------------------
+// Repo-path or wikilink values under a frontmatter key → doc-grain edges.
+export function extractFromFrontmatter(fm) {
+    const edges = [];
+    const consider = (key, value) => {
+        if (typeof value !== "string")
+            return;
+        let dest = null;
+        const wl = /^\[\[([^\]]+)\]\]$/.exec(value);
+        if (wl)
+            dest = wl[1];
+        else if (value.startsWith("/"))
+            dest = value;
+        if (!dest)
+            return;
+        const c = classifyTarget(dest);
+        edges.push({ srcBlock: null, srcField: key, predicate: key, dstKind: c.dstKind, target: c.target, anchor: c.anchor, provenance: "frontmatter" });
+    };
+    for (const [key, value] of Object.entries(fm)) {
+        if (Array.isArray(value))
+            for (const v of value)
+                consider(key, v);
+        else
+            consider(key, value);
+    }
+    return edges;
+}
+//# sourceMappingURL=extract.js.map

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

@@ -0,0 +1,103 @@
+import type { Store } from "../core/store/store.js";
+export interface NodeChange {
+    commitId: string;
+    seq: number;
+    ts: string;
+    origin: string;
+    kind: string;
+    confidence: number | null;
+    reason: string | null;
+}
+/** history_node: a block's biography from block_changes + commits (06 §3). */
+export declare function historyNode(store: Store, blockId: string, opts?: {
+    limit?: number;
+}): NodeChange[];
+export interface DiffEntry {
+    kind: "added" | "removed" | "changed" | "unchanged";
+    blockId: string;
+    before?: string;
+    after?: string;
+}
+export declare function diffBlocks(store: Store, docId: string, fromRev: string, toRev: string): DiffEntry[];
+/** Unified textual diff (line-based) between two revisions' rendered files. */
+export declare function diffUnified(store: Store, docId: string, fromRev: string, toRev: string): string;
+export interface CommitDigest {
+    commit: string;
+    seq: number;
+    ts: string;
+    origin: string;
+    actor: string | null;
+    summary: string;
+    /** `contentHash` (hex of the revision's rendered_hash) lets a puller decide
+     *  "changed vs echo" without a follow-up docs_read/docs_history (ADR-014 §4.2). */
+    revisions: {
+        doc: string;
+        path: string;
+        contentHash: string;
+    }[];
+}
+/** changes_since: commit digests after a cursor (repo commit seq) — the change
+ * feed (06 §3). `seq` is a dense per-REPO total order, so a cursor is only
+ * meaningful against the repo it came from; `head` (the repo's current max seq)
+ * lets a caller tell "no new changes" (cursor == head) from "cursor is beyond
+ * this repo's feed" (cursor > head — e.g. a cursor from another repo/server),
+ * which otherwise both look like an empty page. */
+export declare function changesSince(store: Store, repoId: string, opts?: {
+    cursor?: number;
+    limit?: number;
+    origin?: string;
+}): {
+    digests: CommitDigest[];
+    cursor: number;
+    truncated: boolean;
+    head: number;
+};
+/** One stored version (revision) of a document. */
+export interface DocVersion {
+    rev: string;
+    seq: number;
+    commit: string;
+    ts: string;
+    origin: string;
+    actor: string | null;
+    /** hex of the revision's rendered_hash — spot no-op vs real change, feed into docs_read_at/diff. */
+    contentHash: string;
+    /** true when this rev == the doc's current_rev. */
+    isCurrent: boolean;
+}
+/** A matching document with its ordered version history. */
+export interface DocVersions {
+    docId: string;
+    path: string;
+    deleted: boolean;
+    currentRev: string | null;
+    versions: DocVersion[];
+}
+/**
+ * docHistory: the version history of matching documents, grouped by document.
+ *
+ * - `doc` (id OR path): list that single document's versions. Resolves via
+ *   findDoc for non-deleted docs; falls back to a direct docs lookup (by id or
+ *   repo+path) so `includeDeleted` can surface a tombstoned doc's history too.
+ * - `pathGlob`: match docs.path with the SAME LIKE conversion as within()
+ *   (compileWithin): escape %/_ then map `*`→SQL `%`. So `journal/*` and
+ *   `journal/**` both become `journal/%`; `*` matches ACROSS `/` (there is no
+ *   distinct single-segment wildcard in this dialect), consistent with within().
+ * - By default only NON-deleted docs (deleted_commit IS NULL). includeDeleted:
+ *   true also returns tombstoned docs, whose past versions remain valuable for
+ *   audit (a deleted journal file's history is intact).
+ *
+ * Docs are ordered by path (ascending). Versions within a doc are ordered by
+ * seq ASCENDING (chronological — reads as a timeline). `limit` (default 50)
+ * caps the number of DOCUMENTS returned (not revisions); `truncated` is set
+ * when more matching docs existed.
+ */
+export declare function docHistory(store: Store, repoId: string, opts?: {
+    pathGlob?: string;
+    doc?: string;
+    includeDeleted?: boolean;
+    limit?: number;
+}): {
+    docs: DocVersions[];
+    truncated: boolean;
+};

package/dist/src/graph/history.js

@@ -0,0 +1,210 @@
+import { findDocByRef } from "../core/read/reader.js";
+import { isValidId } from "../core/ids.js";
+/** history_node: a block's biography from block_changes + commits (06 §3). */
+export function historyNode(store, blockId, opts = {}) {
+    const limit = opts.limit ?? 100;
+    return store.db
+        .prepare(`SELECT bc.commit_id AS commitId, c.seq AS seq, c.ts AS ts, c.origin AS origin, bc.kind AS kind,
+              d.confidence AS confidence, d.reason AS reason
+       FROM block_changes bc
+       JOIN commits c ON c.commit_id = bc.commit_id
+       LEFT JOIN dispositions d ON d.commit_id = bc.commit_id AND d.block_id = bc.block_id AND d.kind = bc.kind
+       WHERE bc.block_id = ?
+       ORDER BY c.seq DESC
+       LIMIT ?`)
+        .all(blockId, limit);
+}
+// Block-grain diff between two revisions of a document: compare block id → raw.
+export function diffBlocks(store, docId, fromRev, toRev) {
+    const at = (rev) => blocksAtRevision(store, docId, rev);
+    const before = at(fromRev);
+    const after = at(toRev);
+    const entries = [];
+    for (const [id, raw] of before) {
+        if (!after.has(id))
+            entries.push({ kind: "removed", blockId: id, before: raw });
+        else if (after.get(id) !== raw)
+            entries.push({ kind: "changed", blockId: id, before: raw, after: after.get(id) });
+    }
+    for (const [id, raw] of after)
+        if (!before.has(id))
+            entries.push({ kind: "added", blockId: id, after: raw });
+    return entries;
+}
+// Reconstruct the (block id → raw) map for a document at a revision by walking
+// its Merkle tree from the revision's root_tree. Recurses into child subtrees so
+// the map spans every block (roots + nested), which block-grain diff compares.
+// NOTE: the persisted tree-node entry is a six-field canonical tuple (see
+// core/hash.ts serializeTreeEntries): [blockId, rawHashHex, childTreeHashHex,
+// type, attrs, triviaHashHex]. Diff needs only the first three; whole-document
+// byte-faithful reconstruction (which also needs trivia + top-level order) lives
+// in core/read/document.ts readDocumentAtRevision.
+function blocksAtRevision(store, docId, revId) {
+    const rev = store.db.prepare("SELECT root_tree FROM revisions WHERE rev_id = ? AND doc_id = ?").get(revId, docId);
+    const out = new Map();
+    if (!rev)
+        return out;
+    const blob = store.db.prepare("SELECT bytes FROM blobs WHERE hash = ?");
+    const treeNode = store.db.prepare("SELECT entries FROM tree_nodes WHERE hash = ?");
+    const walk = (treeHashHex) => {
+        const node = treeNode.get(Buffer.from(treeHashHex, "hex"));
+        if (!node)
+            return;
+        const entries = JSON.parse(node.entries);
+        for (const [blockId, rawHashHex, childHashHex] of entries) {
+            const raw = blob.get(Buffer.from(rawHashHex, "hex"))?.bytes.toString("utf8") ?? "";
+            out.set(blockId, raw);
+            if (childHashHex)
+                walk(childHashHex);
+        }
+    };
+    walk(rev.root_tree.toString("hex"));
+    return out;
+}
+/** Unified textual diff (line-based) between two revisions' rendered files. */
+export function diffUnified(store, docId, fromRev, toRev) {
+    const rendered = (rev) => {
+        const map = blocksAtRevision(store, docId, rev);
+        return [...map.values()].join("\n");
+    };
+    const a = rendered(fromRev).split("\n");
+    const b = rendered(toRev).split("\n");
+    // Minimal line diff (not a full Myers; sufficient for digests/preview).
+    const out = [];
+    const max = Math.max(a.length, b.length);
+    for (let i = 0; i < max; i++) {
+        if (a[i] === b[i])
+            continue;
+        if (a[i] !== undefined)
+            out.push(`- ${a[i]}`);
+        if (b[i] !== undefined)
+            out.push(`+ ${b[i]}`);
+    }
+    return out.join("\n");
+}
+/** changes_since: commit digests after a cursor (repo commit seq) — the change
+ * feed (06 §3). `seq` is a dense per-REPO total order, so a cursor is only
+ * meaningful against the repo it came from; `head` (the repo's current max seq)
+ * lets a caller tell "no new changes" (cursor == head) from "cursor is beyond
+ * this repo's feed" (cursor > head — e.g. a cursor from another repo/server),
+ * which otherwise both look like an empty page. */
+export function changesSince(store, repoId, opts = {}) {
+    const cursor = opts.cursor ?? 0;
+    const head = store.db.prepare("SELECT COALESCE(MAX(seq), 0) AS head FROM commits WHERE repo_id = ?").get(repoId).head;
+    const limit = opts.limit ?? 50;
+    const originClause = opts.origin ? "AND origin = ?" : "";
+    const params = [repoId, cursor];
+    if (opts.origin)
+        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 ?`)
+        .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);
+        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;
+    return { digests, cursor: nextCursor, truncated, head };
+}
+/**
+ * docHistory: the version history of matching documents, grouped by document.
+ *
+ * - `doc` (id OR path): list that single document's versions. Resolves via
+ *   findDoc for non-deleted docs; falls back to a direct docs lookup (by id or
+ *   repo+path) so `includeDeleted` can surface a tombstoned doc's history too.
+ * - `pathGlob`: match docs.path with the SAME LIKE conversion as within()
+ *   (compileWithin): escape %/_ then map `*`→SQL `%`. So `journal/*` and
+ *   `journal/**` both become `journal/%`; `*` matches ACROSS `/` (there is no
+ *   distinct single-segment wildcard in this dialect), consistent with within().
+ * - By default only NON-deleted docs (deleted_commit IS NULL). includeDeleted:
+ *   true also returns tombstoned docs, whose past versions remain valuable for
+ *   audit (a deleted journal file's history is intact).
+ *
+ * Docs are ordered by path (ascending). Versions within a doc are ordered by
+ * seq ASCENDING (chronological — reads as a timeline). `limit` (default 50)
+ * caps the number of DOCUMENTS returned (not revisions); `truncated` is set
+ * when more matching docs existed.
+ */
+export function docHistory(store, repoId, opts = {}) {
+    const limit = opts.limit ?? 50;
+    const includeDeleted = opts.includeDeleted ?? false;
+    let docRows;
+    if (opts.doc) {
+        const row = resolveDocRow(store, repoId, opts.doc, includeDeleted);
+        docRows = row ? [row] : [];
+    }
+    else if (opts.pathGlob) {
+        const deletedClause = includeDeleted ? "" : "AND deleted_commit IS NULL";
+        const params = [repoId];
+        let pathClause;
+        if (opts.pathGlob.includes("*")) {
+            const like = opts.pathGlob.replace(/[%_]/g, "\\$&").replace(/\*/g, "%");
+            pathClause = "path LIKE ? ESCAPE '\\'";
+            params.push(like);
+        }
+        else {
+            pathClause = "path = ?";
+            params.push(opts.pathGlob);
+        }
+        params.push(limit + 1);
+        docRows = store.db
+            .prepare(`SELECT doc_id, path, current_rev, deleted_commit FROM docs WHERE repo_id = ? AND ${pathClause} ${deletedClause} ORDER BY path LIMIT ?`)
+            .all(...params);
+    }
+    else {
+        throw new Error("docHistory requires one of { doc, pathGlob }");
+    }
+    const truncated = docRows.length > limit;
+    const page = docRows.slice(0, limit);
+    const revStmt = store.db.prepare(`SELECT r.rev_id AS rev, r.seq AS seq, r.commit_id AS commitId, r.rendered_hash AS rendered_hash,
+            c.ts AS ts, c.origin AS origin, c.actor AS actor
+     FROM revisions r JOIN commits c ON c.commit_id = r.commit_id
+     WHERE r.doc_id = ? ORDER BY r.seq ASC`);
+    const docs = page.map((d) => {
+        const rows = revStmt.all(d.doc_id);
+        const versions = rows.map((r) => ({
+            rev: r.rev,
+            seq: r.seq,
+            commit: r.commitId,
+            ts: r.ts,
+            origin: r.origin,
+            actor: r.actor,
+            contentHash: r.rendered_hash.toString("hex"),
+            isCurrent: r.rev === d.current_rev,
+        }));
+        return { docId: d.doc_id, path: d.path, deleted: d.deleted_commit !== null, currentRev: d.current_rev, versions };
+    });
+    return { docs, truncated };
+}
+// Resolve a `doc` ref (id or path) to a docs row. Prefers findDoc (live docs);
+// when includeDeleted is set and findDoc misses (a tombstoned doc), falls back
+// to a direct lookup that ignores the deleted_commit filter.
+function resolveDocRow(store, repoId, ref, includeDeleted) {
+    const info = findDocByRef(store, repoId, ref);
+    if (info) {
+        return store.db.prepare("SELECT doc_id, path, current_rev, deleted_commit FROM docs WHERE doc_id = ?").get(info.docId);
+    }
+    if (!includeDeleted)
+        return undefined;
+    // findDocByRef filters deleted docs; for includeDeleted, look through the
+    // tombstone using the SAME id-or-path dispatch (isValidId, not a "d_" prefix).
+    const asId = isValidId(ref, "d");
+    const stmt = asId
+        ? store.db.prepare("SELECT doc_id, path, current_rev, deleted_commit FROM docs WHERE doc_id = ?")
+        : 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(", ");
+    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}`;
+}
+//# sourceMappingURL=history.js.map

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

@@ -0,0 +1,33 @@
+import type { Store } from "../core/store/store.js";
+export interface InboundLink {
+    /** source document id */
+    doc: string;
+    /** source document repo-relative path */
+    path: string;
+    /** source block id; null for a frontmatter-level edge */
+    block: string | null;
+    /** the link's destination path as written (e.g. "/old.md", "../old.md", "old.md") */
+    target: string;
+    /** #heading / ^ref fragment, if any */
+    anchor: string | null;
+    /** frontmatter key or inline-field key for typed edges */
+    field?: string;
+}
+/**
+ * Every link occurrence in the repo whose destination resolves to `docPath`,
+ * found via the open edges that point at `docId`. Block-level edges are
+ * re-scanned from the block raw so `target`/`anchor` are as written (and so a
+ * self-doc pure-fragment link `#H`, which also has dst_node == docId, is NOT
+ * reported — it does not depend on the path). Frontmatter edges are reported
+ * with `block: null`, `target: docPath`, and their `field`.
+ */
+export declare function inboundLinksTo(store: Store, repoId: string, docId: string, docPath: string): InboundLink[];
+/**
+ * Rewrite every link destination in `raw` that resolves (relative to `matchDir`,
+ * the source doc's directory at extraction time) to `fromPath` so it points at
+ * `toPath`, writing relative forms against `writeDir` (the source doc's current
+ * directory — differs from `matchDir` only for links inside the moved doc
+ * itself). Anchors, link text, titles, and code spans are preserved. Returns
+ * null when nothing changed.
+ */
+export declare function retargetLinksInRaw(raw: string, matchDir: string, writeDir: string, fromPath: string, toPath: string): string | null;