@omgbase/core 0.1.0

package/dist/src/mutate/lower.js

@@ -0,0 +1,232 @@
+import { rawHashHex } from "./tree.js";
+function collectMutIds(list, out = new Set()) {
+    for (const b of list) {
+        out.add(b.id);
+        collectMutIds(b.children, out);
+    }
+    return out;
+}
+function collectTargetIds(list, out = new Set()) {
+    for (const b of list) {
+        out.add(b.id);
+        collectTargetIds(b.children, out);
+    }
+    return out;
+}
+// Build the proposed tree annotated with assigned ids + carry flags, keying
+// exactly as flatten()/assignFromMut() do (parentKey + '/' + index).
+function buildTarget(blocks, assignment, oldIds, parentKey) {
+    return blocks.map((b, index) => {
+        const key = `${parentKey ?? ""}/${index}`;
+        const id = assignment.get(key) ?? key; // key fallback should not happen
+        return {
+            id,
+            key,
+            type: b.type,
+            raw: b.raw,
+            trivia: b.trivia,
+            children: buildTarget(b.children, assignment, oldIds, key),
+            carried: oldIds.has(id),
+        };
+    });
+}
+// Longest common subsequence of two id lists (indices into a). Standard DP;
+// used to leave already-ordered survivors in place and move only the rest.
+function lcs(a, b) {
+    const n = a.length, m = b.length;
+    const dp = Array.from({ length: n + 1 }, () => new Array(m + 1).fill(0));
+    for (let i = n - 1; i >= 0; i--) {
+        for (let j = m - 1; j >= 0; j--) {
+            dp[i][j] = a[i] === b[j] ? dp[i + 1][j + 1] + 1 : Math.max(dp[i + 1][j], dp[i][j + 1]);
+        }
+    }
+    const keep = new Set();
+    let i = 0, j = 0;
+    while (i < n && j < m) {
+        if (a[i] === b[j]) {
+            keep.add(a[i]);
+            i++;
+            j++;
+        }
+        else if (dp[i + 1][j] >= dp[i][j + 1])
+            i++;
+        else
+            j++;
+    }
+    return keep;
+}
+/**
+ * Lower a reconciled whole-document update to a kernel opset (top-level
+ * granularity). Preserves identity for every top-level block carried unchanged
+ * and correctly realizes add / remove / reorder / content-edit at the top
+ * level. A carried container whose content changed is updated as a whole (its
+ * children re-minted); recursion to preserve nested identity is a later
+ * refinement (verification keeps this honest either way).
+ */
+export function lowerTopLevel(oldDoc, rest, assignment, dispositions) {
+    const docId = oldDoc.docId;
+    const oldIds = collectMutIds(oldDoc.children);
+    const target = buildTarget(rest, assignment, oldIds, null);
+    const targetIdSet = collectTargetIds(target);
+    const dispBy = new Map(dispositions.map((d) => [d.blockId, d]));
+    const oldById = new Map();
+    {
+        const walk = (l) => { for (const b of l) {
+            oldById.set(b.id, b);
+            walk(b.children);
+        } };
+        walk(oldDoc.children);
+    }
+    const oldTopIds = oldDoc.children.map((b) => b.id);
+    const oldTopSet = new Set(oldTopIds);
+    const ops = [];
+    let preserved = 0;
+    let ambiguous = 0;
+    for (const d of dispositions)
+        if (d.detail && Array.isArray(d.detail.nearMisses))
+            ambiguous++;
+    const meta = (id) => {
+        const d = dispBy.get(id);
+        return { confidence: d?.confidence ?? null, reason: d?.reason ?? null, ...(d?.detail ? { detail: d.detail } : {}) };
+    };
+    // 1. Removes: current top-level blocks gone from the proposed TOP LEVEL. An id
+    // the reconciler carried into a nested position (a paragraph that became a
+    // blockquote's child) is still removed here: the container it now lives in is
+    // inserted fresh below, and an insert cannot carry ids, so leaving the old
+    // top-level block in place would duplicate its bytes.
+    const targetTopIds = new Set(target.map((t) => t.id));
+    for (const ob of oldDoc.children) {
+        if (!targetTopIds.has(ob.id)) {
+            ops.push({
+                op: { op: "remove", blocks: [ob.id], expect: { [ob.id]: { content_hash: rawHashHex(ob.raw) } } },
+                disposition: "deleted", blocks: [ob.id], confidence: null, reason: "tombstone",
+            });
+        }
+    }
+    // 2. Content updates: a carried top-level block whose raw changed. A carried
+    // container (list/blockquote) is updated as a whole — its raw carries the
+    // children — but `childIds` threads the reconcile-carried identity of the
+    // items onto the re-parsed subtree, so a within-container edit/reorder/insert
+    // preserves the identity of every item that was NOT itself changed (only
+    // genuinely new items mint). Nested identity, at no convergence cost.
+    for (const t of target) {
+        if (!t.carried)
+            continue;
+        const ob = oldById.get(t.id);
+        if (!ob)
+            continue; // carried an id that lives nested in old — handled by move below
+        if (rawHashHex(ob.raw) !== rawHashHex(t.raw)) {
+            const m = meta(t.id);
+            const childIds = t.children.length > 0 ? carriedChildIdMap(t, oldIds) : {};
+            ops.push({
+                op: { op: "update", block: t.id, markdown: t.raw, expect: { content_hash: rawHashHex(ob.raw) }, ...(Object.keys(childIds).length > 0 ? { childIds } : {}) },
+                disposition: "edited", blocks: [t.id], confidence: m.confidence, reason: m.reason, ...(m.detail ? { detail: m.detail } : {}),
+            });
+        }
+    }
+    // 3. Placement: realize the proposed top-level order. Leave the LCS of
+    // survivors in place; move the rest and insert new blocks, each anchored after
+    // the preceding proposed block (a minted-id placeholder for a fresh insert).
+    const keptTop = target.filter((t) => t.carried && oldTopSet.has(t.id)).map((t) => t.id);
+    const survivorsInOldOrder = oldTopIds.filter((id) => targetIdSet.has(id) && keptTop.includes(id));
+    const stable = lcs(survivorsInOldOrder, keptTop);
+    let prevRef = null; // null = document start
+    const refOf = []; // parallel to target, the id/placeholder to anchor after
+    const placed = []; // parallel to target: realized by insert/move (seam-healing ops)
+    target.forEach((t, i) => {
+        const anchorAt = prevRef === null ? "start" : { after: prevRef };
+        placed[i] = !t.carried || !oldTopSet.has(t.id) || !stable.has(t.id);
+        if (!t.carried || !oldTopSet.has(t.id)) {
+            // Insert new (or a block not previously top-level) at this position.
+            const opIndex = ops.length;
+            ops.push({
+                op: { op: "insert", doc: docId, to: { parent: { doc: true }, at: anchorAt }, markdown: t.raw },
+                disposition: dispositionForNew(dispBy.get(t.id)?.kind), blocks: [], confidence: dispBy.get(t.id)?.confidence ?? null, reason: dispBy.get(t.id)?.reason ?? null,
+            });
+            prevRef = `$${opIndex}.ids[0]`;
+        }
+        else {
+            if (!stable.has(t.id)) {
+                const m = meta(t.id);
+                ops.push({
+                    op: { op: "move", blocks: [t.id], to: { parent: { doc: true }, at: anchorAt } },
+                    disposition: "moved", blocks: [t.id], confidence: m.confidence, reason: m.reason, ...(m.detail ? { detail: m.detail } : {}),
+                });
+            }
+            prevRef = t.id;
+        }
+        refOf[i] = { ref: prevRef };
+    });
+    // 4. Trivia: set exact trailing trivia for proposed top-level blocks that are
+    // inserted, moved, or whose trivia differs from the current block's — so the
+    // committed bytes equal the proposed content exactly. A block ANCHORING an
+    // insert/move is retiled too: those ops heal the seam (bump a lone "\n" to a
+    // blank line) so hand-authored ops never jam blocks, but the proposed content
+    // may legitimately want the tight seam (a blockquote directly under a heading).
+    target.forEach((t, i) => {
+        const ob = t.carried ? oldById.get(t.id) : undefined;
+        const wasTop = ob && oldTopSet.has(t.id);
+        const moved = wasTop && !stable.has(t.id);
+        const anchorsPlacement = placed[i + 1] === true;
+        const needs = !wasTop || moved || anchorsPlacement || (ob && ob.trivia !== t.trivia);
+        if (!needs)
+            return;
+        ops.push({
+            op: { op: "update", block: refOf[i].ref, trivia: t.trivia },
+            disposition: "retiled", blocks: wasTop ? [t.id] : [], confidence: null, reason: null,
+        });
+    });
+    // preserved = carried top-level blocks with unchanged content AND position.
+    for (const t of target) {
+        if (t.carried && oldById.get(t.id) && rawHashHex(oldById.get(t.id).raw) === rawHashHex(t.raw) && stable.has(t.id))
+            preserved++;
+    }
+    return { ops, preserved, ambiguous };
+}
+// Positional-key → id map for a container's carried descendants (keys relative
+// to the container's own children, e.g. "/0", "/1", "/0/0"). Only carried ids
+// (present in the current tree) are threaded; genuinely-new positions are
+// omitted so the op stays deterministic and opUpdate mints those fresh.
+function carriedChildIdMap(container, oldIds) {
+    const out = {};
+    const walk = (children, parentKey) => {
+        children.forEach((c, i) => {
+            const key = `${parentKey}/${i}`;
+            if (oldIds.has(c.id))
+                out[key] = c.id;
+            if (c.children.length > 0)
+                walk(c.children, key);
+        });
+    };
+    walk(container.children, "");
+    return out;
+}
+function dispositionForNew(kind) {
+    if (kind === "copied_from")
+        return "copied_from";
+    if (kind === "resurrected")
+        return "resurrected";
+    if (kind === "split_from")
+        return "split_from";
+    return "inserted";
+}
+/**
+ * Guaranteed fallback: replace the whole body. Remove every current top-level
+ * block, then insert the entire proposed body as one op. Loses all block
+ * identity but always reproduces the exact bytes (verification still checks).
+ * Used only when no identity-preserving lowering converges.
+ */
+export function lowerReplace(oldDoc, content) {
+    const ops = [];
+    for (const ob of oldDoc.children) {
+        ops.push({ op: { op: "remove", blocks: [ob.id] }, disposition: "deleted", blocks: [ob.id], confidence: null, reason: "tombstone" });
+    }
+    ops.push({ op: { op: "insert", doc: oldDoc.docId, to: { parent: { doc: true }, at: "end" }, markdown: bodyOf(content) }, disposition: "bulk_rewrite", blocks: [], confidence: null, reason: null });
+    return { ops, preserved: 0, ambiguous: 0 };
+}
+// Strip a leading YAML frontmatter block from raw content for a body-only insert.
+function bodyOf(content) {
+    const m = /^---\r?\n[\s\S]*?\r?\n---\r?\n?/.exec(content);
+    return m ? content.slice(m[0].length).replace(/^\s*\n/, "") : content;
+}
+//# sourceMappingURL=lower.js.map

package/dist/src/mutate/macros.d.ts

@@ -0,0 +1,91 @@
+import type { Store } from "../core/store/store.js";
+import type { Op } from "./apply.js";
+import type { To } from "./ops.js";
+/** tasks_complete: update(attrs:{checked:true}) per block. */
+export declare function tasksComplete(store: Store, blocks: string[]): Op[];
+/** sections_append: insert markdown at the end of a heading's section. */
+export declare function sectionsAppend(heading: string, markdown: string): Op[];
+/**
+ * docs_append: insert markdown at the END of a whole document — the
+ * document-root peer of sections_append (which appends within a heading's
+ * section). ADDITIVE, not a whole-body replace: it parses `markdown` into new
+ * blocks and inserts them as fresh top-level blocks after the document's
+ * existing ones, so every existing block keeps its stable `b_` id. Expands to a
+ * single insert op targeting the document top level (`{ doc: true }`, `at:
+ * "end"`) with an explicit `doc` — the kernel then threads the new blocks in
+ * without touching any prior block. The doc must already exist; resolving the
+ * ref is the caller's job (a missing doc is doc_missing — creation belongs to
+ * docs_create, never here).
+ */
+export declare function docsAppend(docId: string, markdown: string): Op[];
+/** sections_rename: update the heading block's markdown to a new title. */
+export declare function sectionsRename(store: Store, heading: string, title: string): Op[];
+/** sections_move: move a heading's whole section range to a new location. */
+export declare function sectionsMove(store: Store, heading: string, to: To): Op[];
+/** lists_insert_item: insert a list item at a position relative to a list/item. */
+export declare function listsInsertItem(anchor: string, at: "start" | "end" | {
+    before: string;
+} | {
+    after: string;
+}, markdown: string): Op[];
+export interface RetargetHit {
+    block: string;
+    /** repo-relative path of the block's document */
+    path: string;
+    oldRaw: string;
+    newRaw: string;
+}
+/** node_set: surgically set one editable property of a node (node-editability).
+ * Resolves the node → its block + owning doc's format adapter, runs the adapter's
+ * registered editor for (kind, prop) against the block's current raw + the node's
+ * span, and returns a single kernel `update` op (markdown or attrs) with a CAS
+ * pin. The node stays a read-only projection; the write goes through the block.
+ * Throws node_not_editable when no editor is registered for (kind, prop). */
+export declare function nodeSet(store: Store, nodeId: string, prop: string, value: string): Op[];
+/** The editable property names registered for a (format, kind), for discovery. */
+export declare function editablePropsFor(format: string, kind: string): string[];
+/** links_retarget: the single-pair form of linksRepair (delegates). */
+export declare function linksRetarget(store: Store, repoId: string, fromTarget: string, toTarget: string, opts?: LinkRepairOptions): LinkRepairPlan;
+/** A single from→to link-destination rewrite. */
+export interface LinkRepair {
+    from: string;
+    to: string;
+}
+export interface LinkRepairOptions {
+    /** scope the SOURCE docs by a path glob (`journal/*`), mirroring linksStale. */
+    pathGlob?: string;
+}
+/** Per-pair tally: how many link destinations `from` matched (across all hits). */
+export interface LinkRepairCount extends LinkRepair {
+    hits: number;
+}
+export interface LinkRepairPlan {
+    /** kernel update ops, one per rewritten TOP-MOST block */
+    ops: Op[];
+    /** the rewritten blocks (dry-run preview) */
+    hits: RetargetHit[];
+    /** each input pair with its destination-match count (0 = nothing to fix) */
+    pairs: LinkRepairCount[];
+}
+/**
+ * links_repair: bulk stale-link repair. Given a batch of {from,to} destination
+ * rewrites, produce the kernel update ops plus the hits for dry-run preview.
+ * Repairs compose within ONE changeset so an agent can fix many dangling
+ * targets (surfaced by linksStale) at once.
+ *
+ * Scope: this rewrites LINK DESTINATIONS, not substrings. A destination is
+ * rewritten only when `from` is the WHOLE destination of a Markdown link /
+ * image, a wikilink, or a bare-path inline field (`key:: /path`) — ignoring the
+ * leading `/`, and allowing a trailing `#heading`/`^ref` fragment which is
+ * re-appended. Prose mentions, inline code, and `code_fence` blocks are never
+ * touched, and a `from` that is merely a suffix/prefix of a longer path does
+ * not match it. Each destination takes the FIRST matching pair (no chaining).
+ * Frontmatter links are not blocks and are out of reach here (use docs_set_meta).
+ *
+ * Coalescing: a block hit by several pairs gets a single update op (one CAS pin
+ * per block). Hits collapse to their TOP-MOST block: a list and its list items
+ * both carry the same bytes, and updating the container re-parses (re-mints)
+ * its children, so a second op on the child would fail block_missing and sink
+ * the whole changeset. Mirrors opRemove's top-most collapse. No FS/network I/O.
+ */
+export declare function linksRepair(store: Store, repoId: string, repairs: LinkRepair[], opts?: LinkRepairOptions): LinkRepairPlan;

package/dist/src/mutate/macros.js

@@ -0,0 +1,230 @@
+import { adapterForFormat } from "../format/registry.js";
+import { MutationError } from "./tree.js";
+import { globClause } from "../graph/link-health.js";
+import { rewriteLinkDestinations, splitDestination } from "../graph/link-destinations.js";
+// Server-side macros (04 §3). Each expands deterministically to kernel ops —
+// no policy judgment (that belongs in the agent). The expansion is returned so
+// callers see the kernel ops that ran. Macros compose within one changeset.
+function rawHashOfBlock(store, blockId) {
+    const row = store.db.prepare("SELECT lower(hex(raw_hash)) h FROM blocks WHERE block_id = ? AND deleted_commit IS NULL").get(blockId);
+    return row?.h ?? null;
+}
+function rawOfBlock(store, blockId) {
+    const row = store.db.prepare("SELECT b.bytes FROM blocks bl JOIN blobs b ON b.hash = bl.raw_hash WHERE bl.block_id = ? AND bl.deleted_commit IS NULL").get(blockId);
+    return row?.bytes.toString("utf8") ?? null;
+}
+/** tasks_complete: update(attrs:{checked:true}) per block. */
+export function tasksComplete(store, blocks) {
+    return blocks.map((block) => {
+        const hash = rawHashOfBlock(store, block);
+        return { op: "update", block, attrs: { checked: true }, ...(hash ? { expect: { content_hash: hash } } : {}) };
+    });
+}
+/** sections_append: insert markdown at the end of a heading's section. */
+export function sectionsAppend(heading, markdown) {
+    const to = { parent: { heading, scope: "section" }, at: "end" };
+    return [{ op: "insert", to, markdown }];
+}
+/**
+ * docs_append: insert markdown at the END of a whole document — the
+ * document-root peer of sections_append (which appends within a heading's
+ * section). ADDITIVE, not a whole-body replace: it parses `markdown` into new
+ * blocks and inserts them as fresh top-level blocks after the document's
+ * existing ones, so every existing block keeps its stable `b_` id. Expands to a
+ * single insert op targeting the document top level (`{ doc: true }`, `at:
+ * "end"`) with an explicit `doc` — the kernel then threads the new blocks in
+ * without touching any prior block. The doc must already exist; resolving the
+ * ref is the caller's job (a missing doc is doc_missing — creation belongs to
+ * docs_create, never here).
+ */
+export function docsAppend(docId, markdown) {
+    const to = { parent: { doc: true }, at: "end" };
+    return [{ op: "insert", doc: docId, to, markdown }];
+}
+/** sections_rename: update the heading block's markdown to a new title. */
+export function sectionsRename(store, heading, title) {
+    const raw = rawOfBlock(store, heading) ?? "";
+    const level = (/^(#{1,6})\s/.exec(raw)?.[1] ?? "#").length;
+    const hash = rawHashOfBlock(store, heading);
+    const markdown = `${"#".repeat(level)} ${title}`;
+    return [{ op: "update", block: heading, markdown, ...(hash ? { expect: { content_hash: hash } } : {}) }];
+}
+/** sections_move: move a heading's whole section range to a new location. */
+export function sectionsMove(store, heading, to) {
+    // The section range is the heading + blocks until the next peer/higher
+    // heading. We resolve the contiguous top-level run of ids from the store.
+    const docRow = store.db.prepare("SELECT doc_id, ordinal, json_extract(attrs,'$.level') level FROM blocks WHERE block_id = ?").get(heading);
+    if (!docRow)
+        return [];
+    const level = docRow.level ?? 1;
+    const tops = store.db.prepare("SELECT block_id, ordinal, type, json_extract(attrs,'$.level') level FROM blocks WHERE doc_id = ? AND parent_block IS NULL AND deleted_commit IS NULL ORDER BY ordinal").all(docRow.doc_id);
+    const startIdx = tops.findIndex((t) => t.block_id === heading);
+    let end = tops.length;
+    for (let i = startIdx + 1; i < tops.length; i++) {
+        if (tops[i].type === "heading" && (tops[i].level ?? 1) <= level) {
+            end = i;
+            break;
+        }
+    }
+    const run = tops.slice(startIdx, end).map((t) => t.block_id);
+    return [{ op: "move", blocks: run, to }];
+}
+/** lists_insert_item: insert a list item at a position relative to a list/item. */
+export function listsInsertItem(anchor, at, markdown) {
+    const item = markdown.trimStart().startsWith("- ") ? markdown : `- ${markdown}`;
+    return [{ op: "insert", to: { parent: anchor, at }, markdown: item }];
+}
+/** node_set: surgically set one editable property of a node (node-editability).
+ * Resolves the node → its block + owning doc's format adapter, runs the adapter's
+ * registered editor for (kind, prop) against the block's current raw + the node's
+ * span, and returns a single kernel `update` op (markdown or attrs) with a CAS
+ * pin. The node stays a read-only projection; the write goes through the block.
+ * Throws node_not_editable when no editor is registered for (kind, prop). */
+export function nodeSet(store, nodeId, prop, value) {
+    const node = store.db.prepare(`SELECT n.kind, n.name, n.value, n.attrs, n.span_start, n.span_end, n.block_id,
+            d.format AS format
+     FROM nodes n JOIN docs d ON d.doc_id = n.doc_id
+     WHERE n.node_id = ?`).get(nodeId);
+    if (!node)
+        throw new MutationError("block_missing", `node ${nodeId} not found`, {});
+    if (!node.block_id)
+        throw new MutationError("node_not_editable", `node ${nodeId} is not anchored to a block`, {});
+    const adapter = adapterForFormat(node.format);
+    const editor = adapter?.nodeEditors?.[node.kind]?.[prop];
+    if (!editor) {
+        throw new MutationError("node_not_editable", `no editor for ${node.kind}.${prop}`, {
+            kind: node.kind, prop, editable: editablePropsFor(node.format, node.kind),
+        });
+    }
+    const blockRaw = rawOfBlock(store, node.block_id);
+    if (blockRaw === null)
+        throw new MutationError("block_missing", `block ${node.block_id} not found`, {});
+    const hash = rawHashOfBlock(store, node.block_id);
+    const result = editor({
+        blockRaw,
+        span: node.span_start !== null && node.span_end !== null ? { start: node.span_start, end: node.span_end } : null,
+        node: {
+            kind: node.kind,
+            ...(node.name !== null ? { name: node.name } : {}),
+            ...(node.value !== null ? { value: node.value } : {}),
+            attrs: JSON.parse(node.attrs || "{}"),
+        },
+    }, value);
+    const expect = hash ? { expect: { content_hash: hash } } : {};
+    if ("markdown" in result) {
+        return [{ op: "update", block: node.block_id, markdown: result.markdown, ...expect }];
+    }
+    return [{ op: "update", block: node.block_id, attrs: result.attrs, ...expect }];
+}
+/** The editable property names registered for a (format, kind), for discovery. */
+export function editablePropsFor(format, kind) {
+    const editors = adapterForFormat(format)?.nodeEditors?.[kind];
+    return editors ? Object.keys(editors) : [];
+}
+/** links_retarget: the single-pair form of linksRepair (delegates). */
+export function linksRetarget(store, repoId, fromTarget, toTarget, opts = {}) {
+    return linksRepair(store, repoId, [{ from: fromTarget, to: toTarget }], opts);
+}
+const stripSlash = (s) => s.replace(/^\//, "");
+// Does destination `dest` (as authored) name the same link target as `from`?
+// Whole-destination match first (lets `from` carry its own #fragment), then the
+// path part alone (the fragment rides along). Both sides compare with the
+// leading `/` dropped, so `from` may be given either as authored (`/b.md`) or as
+// links_stale reports `target` (`b.md`). Returns the fragment to re-append.
+function destinationMatch(dest, from) {
+    if (stripSlash(dest) === stripSlash(from))
+        return { fragment: "" };
+    const { path, fragment } = splitDestination(dest);
+    if (fragment !== "" && stripSlash(path) === stripSlash(from))
+        return { fragment };
+    return null;
+}
+/**
+ * links_repair: bulk stale-link repair. Given a batch of {from,to} destination
+ * rewrites, produce the kernel update ops plus the hits for dry-run preview.
+ * Repairs compose within ONE changeset so an agent can fix many dangling
+ * targets (surfaced by linksStale) at once.
+ *
+ * Scope: this rewrites LINK DESTINATIONS, not substrings. A destination is
+ * rewritten only when `from` is the WHOLE destination of a Markdown link /
+ * image, a wikilink, or a bare-path inline field (`key:: /path`) — ignoring the
+ * leading `/`, and allowing a trailing `#heading`/`^ref` fragment which is
+ * re-appended. Prose mentions, inline code, and `code_fence` blocks are never
+ * touched, and a `from` that is merely a suffix/prefix of a longer path does
+ * not match it. Each destination takes the FIRST matching pair (no chaining).
+ * Frontmatter links are not blocks and are out of reach here (use docs_set_meta).
+ *
+ * Coalescing: a block hit by several pairs gets a single update op (one CAS pin
+ * per block). Hits collapse to their TOP-MOST block: a list and its list items
+ * both carry the same bytes, and updating the container re-parses (re-mints)
+ * its children, so a second op on the child would fail block_missing and sink
+ * the whole changeset. Mirrors opRemove's top-most collapse. No FS/network I/O.
+ */
+export function linksRepair(store, repoId, repairs, opts = {}) {
+    const pairs = repairs.map((r) => ({ from: r.from, to: r.to, hits: 0 }));
+    const effective = pairs.filter((r) => stripSlash(r.from) !== "" && r.from !== r.to);
+    if (effective.length === 0)
+        return { ops: [], hits: [], pairs };
+    // Candidate blocks: live, not a code fence, whose bytes contain the slash-less
+    // form of some `from` (a cheap prefilter; the destination scan below decides).
+    const params = [];
+    let globSql = "";
+    if (opts.pathGlob) {
+        const { clause, param } = globClause("d.path", opts.pathGlob);
+        globSql = `AND ${clause}`;
+        params.push(param);
+    }
+    const stmt = store.db.prepare(`SELECT bl.block_id, bl.parent_block, d.path, b.bytes
+     FROM blocks bl
+     JOIN blobs b ON b.hash = bl.raw_hash
+     JOIN docs d ON d.doc_id = bl.doc_id
+     WHERE bl.repo_id = ? AND bl.deleted_commit IS NULL AND d.deleted_commit IS NULL
+       AND bl.type != 'code_fence' AND instr(b.bytes, ?) > 0 ${globSql}`);
+    const candidates = new Map();
+    for (const key of new Set(effective.map((r) => stripSlash(r.from)))) {
+        const rows = stmt.all(repoId, key, ...params);
+        for (const row of rows) {
+            if (!candidates.has(row.block_id))
+                candidates.set(row.block_id, { parent: row.parent_block, path: row.path, raw: row.bytes.toString("utf8") });
+        }
+    }
+    // Rewrite each candidate's destinations; keep the blocks that changed.
+    const changed = new Map();
+    for (const [blockId, c] of candidates) {
+        const tally = effective.map(() => 0);
+        const newRaw = rewriteLinkDestinations(c.raw, (dest) => {
+            for (let i = 0; i < effective.length; i++) {
+                const m = destinationMatch(dest, effective[i].from);
+                if (m) {
+                    tally[i]++;
+                    return effective[i].to + m.fragment;
+                }
+            }
+            return null;
+        });
+        if (newRaw !== c.raw)
+            changed.set(blockId, { parent: c.parent, path: c.path, oldRaw: c.raw, newRaw, tally });
+    }
+    // Collapse to top-most blocks: drop a hit whose ancestor is also a hit.
+    const parentOf = store.db.prepare("SELECT parent_block FROM blocks WHERE block_id = ? AND deleted_commit IS NULL");
+    const hasChangedAncestor = (parent) => {
+        for (let p = parent; p !== null;) {
+            if (changed.has(p))
+                return true;
+            p = parentOf.get(p)?.parent_block ?? null;
+        }
+        return false;
+    };
+    const ops = [];
+    const hits = [];
+    for (const [blockId, c] of changed) {
+        if (hasChangedAncestor(c.parent))
+            continue;
+        c.tally.forEach((n, i) => { effective[i].hits += n; });
+        const hash = rawHashOfBlock(store, blockId);
+        ops.push({ op: "update", block: blockId, markdown: c.newRaw, ...(hash ? { expect: { content_hash: hash } } : {}) });
+        hits.push({ block: blockId, path: c.path, oldRaw: c.oldRaw, newRaw: c.newRaw });
+    }
+    return { ops, hits, pairs };
+}
+//# sourceMappingURL=macros.js.map

package/dist/src/mutate/ops.d.ts

@@ -0,0 +1,40 @@
+import { type MutDoc } from "./tree.js";
+export type At = "start" | "end" | {
+    before: string;
+} | {
+    after: string;
+};
+export interface To {
+    parent: string | {
+        doc: true;
+    } | {
+        heading: string;
+        scope: "section";
+    };
+    at: At;
+}
+export interface Expect {
+    content_hash?: string;
+    parent_children_hash?: string;
+}
+export declare function opInsert(doc: MutDoc, to: To, markdown: string): {
+    ids: string[];
+};
+export declare function opUpdate(doc: MutDoc, blockId: string, opIndex: number, markdown?: string, attrs?: Record<string, unknown>, expect?: Expect, trivia?: string, childIds?: Record<string, string>): {
+    ids: string[];
+};
+export declare function opMove(doc: MutDoc, blockIds: string[], to: To, opIndex: number): {
+    ids: string[];
+};
+export declare function opRemove(doc: MutDoc, blockIds: string[], opIndex: number, expectPer?: Record<string, Expect>): {
+    ids: string[];
+    removed: string[];
+};
+export declare function opSplit(doc: MutDoc, blockId: string, at: number[], opIndex: number, expect?: Expect): {
+    ids: string[];
+};
+export declare function opMerge(doc: MutDoc, blockIds: string[], opIndex: number, separator?: string, expectPer?: Record<string, Expect>): {
+    ids: string[];
+    mergedInto: string[];
+};
+export declare function checkParentChildrenHash(doc: MutDoc, parentId: string | null, expected: string, opIndex: number): void;