@omgbase/core 0.1.0

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

@@ -0,0 +1,13 @@
+import { type ServerContext } from "./server.js";
+export interface ServeStdioHandle {
+    /** Resolves when the transport closes. */
+    closed: Promise<void>;
+    /** Close the server + transport (idempotent). */
+    close(): Promise<void>;
+}
+/**
+ * Build the MCP server for `ctx` and connect it to stdio. Returns a handle
+ * whose `closed` promise settles when the client disconnects. stdout is the
+ * protocol channel — callers MUST NOT write anything else to it.
+ */
+export declare function serveStdio(ctx: ServerContext): Promise<ServeStdioHandle>;

package/dist/src/mcp/stdio.js

@@ -0,0 +1,24 @@
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { buildServer } from "./server.js";
+/**
+ * Build the MCP server for `ctx` and connect it to stdio. Returns a handle
+ * whose `closed` promise settles when the client disconnects. stdout is the
+ * protocol channel — callers MUST NOT write anything else to it.
+ */
+export async function serveStdio(ctx) {
+    const server = buildServer(ctx);
+    const transport = new StdioServerTransport();
+    let resolveClosed;
+    const closed = new Promise((res) => {
+        resolveClosed = res;
+    });
+    transport.onclose = () => resolveClosed();
+    await server.connect(transport);
+    return {
+        closed,
+        async close() {
+            await server.close();
+        },
+    };
+}
+//# sourceMappingURL=stdio.js.map

package/dist/src/migrate/mrplex.d.ts

@@ -0,0 +1,27 @@
+import type { Store } from "../core/store/store.js";
+export interface MrplexDoc {
+    /** repo-relative path (no leading slash) */
+    path: string;
+    /** full markdown body including any frontmatter fence */
+    markdown: string;
+}
+export interface ImportPlan {
+    repoId: string;
+    docCount: number;
+    totalBytes: number;
+    paths: string[];
+}
+export interface ImportResult {
+    repoId: string;
+    imported: {
+        path: string;
+        docId: string;
+        blockCount: number;
+        converged: boolean;
+    }[];
+    allConverged: boolean;
+}
+/** Dry-run: report what would be imported without writing anything. */
+export declare function planImport(repoId: string, docs: MrplexDoc[]): ImportPlan;
+/** Import the documents as `import`-origin commits with freshly minted ids. */
+export declare function importDocs(store: Store, repoId: string, docs: MrplexDoc[]): ImportResult;

package/dist/src/migrate/mrplex.js

@@ -0,0 +1,29 @@
+import { ingestFile } from "../core/ingest.js";
+import { makeReconcilingResolver } from "../sync/reconciling-ingest.js";
+/** Dry-run: report what would be imported without writing anything. */
+export function planImport(repoId, docs) {
+    return {
+        repoId,
+        docCount: docs.length,
+        totalBytes: docs.reduce((n, d) => n + Buffer.byteLength(d.markdown, "utf8"), 0),
+        paths: docs.map((d) => d.path).sort(),
+    };
+}
+/** Import the documents as `import`-origin commits with freshly minted ids. */
+export function importDocs(store, repoId, docs) {
+    const ts = new Date().toISOString();
+    const imported = [];
+    let allConverged = true;
+    for (const doc of docs) {
+        const res = ingestFile(store, repoId, doc.path, doc.markdown, {
+            ts,
+            origin: "import",
+            resolveIds: makeReconcilingResolver(store, repoId, { ts, path: doc.path }),
+        });
+        imported.push({ path: doc.path, docId: res.docId, blockCount: res.blockCount, converged: res.converged });
+        if (!res.converged)
+            allConverged = false;
+    }
+    return { repoId, imported, allConverged };
+}
+//# sourceMappingURL=mrplex.js.map

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

@@ -0,0 +1,83 @@
+import type { Store } from "../core/store/store.js";
+import { type To, type Expect } from "./ops.js";
+import { type DocStore } from "./doc-store.js";
+export type Op = {
+    op: "insert";
+    doc?: string;
+    to: To;
+    markdown: string;
+} | {
+    op: "update";
+    block: string;
+    markdown?: string;
+    attrs?: Record<string, unknown>;
+    expect?: Expect;
+    trivia?: string;
+    childIds?: Record<string, string>;
+} | {
+    op: "move";
+    blocks: string[];
+    to: To;
+} | {
+    op: "remove";
+    blocks: string[];
+    expect?: Record<string, Expect>;
+} | {
+    op: "split";
+    block: string;
+    at: number[];
+    expect?: Expect;
+} | {
+    op: "merge";
+    blocks: string[];
+    separator?: string;
+    expect?: Record<string, Expect>;
+};
+export interface ApplyRequest {
+    repoId: string;
+    /** Working-tree root for the default filesystem write target. Omit only when
+     *  supplying an explicit `docStore` (e.g. a headless NullDocStore). */
+    rootPath?: string;
+    /** Write target (ADR-014 §5); defaults to a filesystem store at `rootPath`. */
+    docStore?: DocStore;
+    ops: Op[];
+    origin: {
+        actor: string;
+        reason?: string;
+    };
+    dryRun?: boolean;
+    /**
+     * Workspace .omgbase/ dir. When set, the file-write + commit phase runs under
+     * the cross-process writer lock (11 §3.2). Omitted in single-process/in-memory
+     * contexts (tests) where the in-process serialization of Store.write suffices.
+     */
+    omgbaseDir?: string;
+    /**
+     * Document-level frontmatter overrides (doc id → new frontmatter raw incl.
+     * fences + trailing separator, or null to drop it). Frontmatter is a
+     * document-level materialization unit (rendered before the block tree), not a
+     * block the six ops address; the whole-document update planner sets it here
+     * when the proposed content changes the frontmatter. The doc is force-loaded
+     * so a frontmatter-only change still commits.
+     */
+    setFrontmatter?: {
+        doc: string;
+        raw: string | null;
+    }[];
+}
+export interface OpResult {
+    ids: string[];
+}
+export interface ApplyResult {
+    results: OpResult[];
+    revisions: {
+        doc: string;
+        path: string;
+    }[];
+    diffs?: Record<string, {
+        before: string;
+        after: string;
+    }>;
+    committed: boolean;
+}
+export declare function apply(store: Store, req: ApplyRequest): ApplyResult;

package/dist/src/mutate/apply.js

@@ -0,0 +1,302 @@
+import { sha256 } from "../core/hash.js";
+import { isValidId } from "../core/ids.js";
+import { findDocByRef } from "../core/read/reader.js";
+import { ingestFile } from "../core/ingest.js";
+import { makeReconcilingResolver } from "../sync/reconciling-ingest.js";
+import { makeKnownIdResolver } from "./known-ids.js";
+import { loadMutDoc } from "./load.js";
+import { renderDoc, MutationError } from "./tree.js";
+import { opInsert, opUpdate, opMove, opRemove, opSplit, opMerge } from "./ops.js";
+import { withWriterLock } from "../sync/writer-lock.js";
+import { resolveDocStore } from "./doc-store.js";
+// Resolve "$n.ids[i]" placeholders in a string against prior op results.
+function resolvePlaceholder(value, results) {
+    const m = /^\$(\d+)\.ids\[(\d+)\]$/.exec(value);
+    if (!m)
+        return value;
+    const opIdx = Number(m[1]);
+    const idIdx = Number(m[2]);
+    const id = results[opIdx]?.ids[idIdx];
+    if (!id)
+        throw new MutationError("target_missing", `placeholder ${value} did not resolve`);
+    return id;
+}
+function resolveTo(to, results) {
+    const parent = typeof to.parent === "string" ? resolvePlaceholder(to.parent, results) : to.parent;
+    let at = to.at;
+    if (typeof at === "object") {
+        if ("before" in at)
+            at = { before: resolvePlaceholder(at.before, results) };
+        else if ("after" in at)
+            at = { after: resolvePlaceholder(at.after, results) };
+    }
+    return { parent, at };
+}
+// Resolve an insert op's `doc` field, which may be a minted doc id (d_...) or a
+// document path — the same id-or-path symmetry the read/graph surfaces expose
+// (shared via findDocByRef; see core/read/reader.ts). A valid d_ id passes
+// through WITHOUT a store lookup so a doc minted by an earlier op in the SAME
+// changeset (not yet committed) still resolves; ensureDoc validates existence.
+// A path is resolved via the shared helper; an unresolvable path throws
+// doc_missing naming it.
+function resolveDocRef(store, repoId, ref) {
+    if (isValidId(ref, "d"))
+        return ref;
+    const info = findDocByRef(store, repoId, ref);
+    if (!info)
+        throw new MutationError("doc_missing", `doc ${ref} not found`, { doc: ref });
+    return info.docId;
+}
+// Which doc a given block id lives in (searches loaded docs; falls back to store).
+function docIdForBlock(store, repoId, blockId) {
+    const row = store.db.prepare("SELECT doc_id FROM blocks WHERE block_id = ? AND deleted_commit IS NULL").get(blockId);
+    return row?.doc_id ?? null;
+}
+export function apply(store, req) {
+    const { store: _s } = { store };
+    void _s;
+    // Load all docs that ops touch into memory; apply ops in order.
+    const loaded = new Map();
+    const before = new Map();
+    // Block ids present in each doc BEFORE any op — used to label intent
+    // dispositions (edited vs inserted) on the known-id commit path.
+    const priorIds = new Map();
+    const results = [];
+    const ensureDoc = (docId) => {
+        let d = loaded.get(docId);
+        if (!d) {
+            const md = loadMutDoc(store.db, docId);
+            if (!md)
+                throw new MutationError("doc_missing", `doc ${docId} not found`);
+            d = md;
+            loaded.set(docId, d);
+            before.set(docId, renderDoc(d));
+            const ids = store.db.prepare("SELECT block_id FROM blocks WHERE doc_id = ? AND deleted_commit IS NULL").all(docId);
+            priorIds.set(docId, new Set(ids.map((r) => r.block_id)));
+        }
+        return d;
+    };
+    // Document-level frontmatter overrides, before the op loop (so a change with
+    // no body ops still loads + commits the doc). Applied to the loaded MutDoc;
+    // renderDoc emits frontmatterRaw verbatim and the commit re-ingest re-derives
+    // properties/edges from the rendered bytes.
+    for (const fm of req.setFrontmatter ?? []) {
+        // ensureDoc captures `before` (pre-mutation render) at load time.
+        ensureDoc(fm.doc).frontmatterRaw = fm.raw;
+    }
+    req.ops.forEach((rawOp, i) => {
+        switch (rawOp.op) {
+            case "insert": {
+                const to = resolveTo(rawOp.to, results);
+                const docId = rawOp.doc !== undefined
+                    ? resolveDocRef(store, req.repoId, rawOp.doc)
+                    : parentDoc(store, req.repoId, to, loaded);
+                const d = ensureDoc(docId);
+                results.push(opInsert(d, to, rawOp.markdown));
+                break;
+            }
+            case "update": {
+                const block = resolvePlaceholder(rawOp.block, results);
+                const docId = docIdForBlockLoaded(loaded, block) ?? docIdForBlock(store, req.repoId, block);
+                if (!docId)
+                    throw new MutationError("block_missing", `block ${block} not found`, { op_index: i });
+                results.push(opUpdate(ensureDoc(docId), block, i, rawOp.markdown, rawOp.attrs, rawOp.expect, rawOp.trivia, rawOp.childIds));
+                break;
+            }
+            case "move": {
+                const blocks = rawOp.blocks.map((b) => resolvePlaceholder(b, results));
+                const to = resolveTo(rawOp.to, results);
+                const srcDocId = docIdForBlockLoaded(loaded, blocks[0]) ?? docIdForBlock(store, req.repoId, blocks[0]);
+                if (!srcDocId)
+                    throw new MutationError("block_missing", `block ${blocks[0]} not found`, { op_index: i });
+                // {doc:true} with a non-anchor `at` (start/end) means the source doc's
+                // top level; otherwise infer the destination doc from the target.
+                const topLevelSameDoc = typeof to.parent === "object" && "doc" in to.parent && typeof to.at === "string";
+                const dstDocId = topLevelSameDoc ? srcDocId : parentDoc(store, req.repoId, to, loaded);
+                if (dstDocId === srcDocId) {
+                    results.push(opMove(ensureDoc(srcDocId), blocks, to, i));
+                }
+                else {
+                    // Cross-document move (04 §1): extract from source, insert into target.
+                    results.push(crossDocMove(ensureDoc(srcDocId), ensureDoc(dstDocId), blocks, to, i));
+                }
+                break;
+            }
+            case "remove": {
+                const blocks = rawOp.blocks.map((b) => resolvePlaceholder(b, results));
+                const docId = docIdForBlockLoaded(loaded, blocks[0]) ?? docIdForBlock(store, req.repoId, blocks[0]);
+                if (!docId)
+                    throw new MutationError("block_missing", `block ${blocks[0]} not found`, { op_index: i });
+                results.push(opRemove(ensureDoc(docId), blocks, i, rawOp.expect));
+                break;
+            }
+            case "split": {
+                const block = resolvePlaceholder(rawOp.block, results);
+                const docId = docIdForBlockLoaded(loaded, block) ?? docIdForBlock(store, req.repoId, block);
+                if (!docId)
+                    throw new MutationError("block_missing", `block ${block} not found`, { op_index: i });
+                results.push(opSplit(ensureDoc(docId), block, rawOp.at, i, rawOp.expect));
+                break;
+            }
+            case "merge": {
+                const blocks = rawOp.blocks.map((b) => resolvePlaceholder(b, results));
+                const docId = docIdForBlockLoaded(loaded, blocks[0]) ?? docIdForBlock(store, req.repoId, blocks[0]);
+                if (!docId)
+                    throw new MutationError("block_missing", `block ${blocks[0]} not found`, { op_index: i });
+                results.push(opMerge(ensureDoc(docId), blocks, i, rawOp.separator, rawOp.expect));
+                break;
+            }
+        }
+    });
+    const revisions = [];
+    const diffs = {};
+    for (const [docId, d] of loaded) {
+        diffs[d.path] = { before: before.get(docId) ?? "", after: renderDoc(d) };
+        revisions.push({ doc: docId, path: d.path });
+    }
+    if (req.dryRun) {
+        return { results, revisions, diffs, committed: false };
+    }
+    // Write each touched file with the file-CAS + atomic-write protocol (04 §6),
+    // then re-ingest the rendered bytes as an api-origin commit so identity
+    // threads (the ops already assigned ids; reconciliation confirms carries).
+    // Steps 2–7 run under the cross-process writer lock when a workspace dir is
+    // supplied (11 §3.2); otherwise the Store's in-process serialization suffices.
+    const docStore = resolveDocStore(req);
+    const commitPhase = () => {
+        const ts = new Date().toISOString();
+        for (const [docId, d] of loaded) {
+            const rendered = renderDoc(d);
+            // File-CAS: on-disk bytes must equal the revision we computed against.
+            const current = store.db.prepare("SELECT file_hash FROM docs WHERE doc_id = ?").get(docId);
+            const onDiskContent = docStore.read(d.path);
+            if (onDiskContent !== null && current?.file_hash) {
+                const onDisk = sha256(onDiskContent);
+                if (!onDisk.equals(current.file_hash)) {
+                    // A human edit landed first: ingest it, then the caller must retry.
+                    ingestFile(store, req.repoId, d.path, onDiskContent, { ts, resolveIds: makeReconcilingResolver(store, req.repoId, { ts, path: d.path }) });
+                    if (req.omgbaseDir)
+                        docStore.recordStat(store, req.repoId, d.path, onDiskContent);
+                    throw new MutationError("sync_conflict", `file ${d.path} changed on disk; re-ingested — retry`, { retriable: true });
+                }
+            }
+            // Atomic write through the DocStore (no-op for a headless NullDocStore).
+            docStore.write(d.path, rendered);
+            // Commit (INTENT path): persist the ops' tree with its KNOWN block ids —
+            // never re-derive identity from the rendered bytes. The mutated MutDoc `d`
+            // already carries deterministic ids (opUpdate keeps a block's id in place,
+            // untouched blocks keep theirs, new blocks carry the op-minted id), so the
+            // known-id resolver threads them onto the re-parsed tree and records intent
+            // dispositions (confidence 1.0). Re-reconciling here would gamble block —
+            // and thus node — identity on the probabilistic matcher (node-editability).
+            ingestFile(store, req.repoId, d.path, rendered, {
+                ts,
+                origin: "import",
+                resolveIds: makeKnownIdResolver(store, req.repoId, d, priorIds.get(docId) ?? new Set(), { path: d.path }),
+            });
+            // Keep the freshness cache warm so this engine write isn't re-hashed by a
+            // later sweep (echo suppression already covers correctness; this avoids work).
+            if (req.omgbaseDir)
+                docStore.recordStat(store, req.repoId, d.path, rendered);
+        }
+    };
+    if (req.omgbaseDir)
+        withWriterLock(req.omgbaseDir, commitPhase);
+    else
+        commitPhase();
+    return { results, revisions, committed: true };
+}
+function docIdForBlockLoaded(loaded, blockId) {
+    for (const [docId, d] of loaded) {
+        if (findInDoc(d, blockId))
+            return docId;
+    }
+    return null;
+}
+function findInDoc(d, blockId) {
+    const walk = (list) => list.some((b) => b.id === blockId || walk(b.children));
+    return walk(d.children);
+}
+// Determine the doc for a placement whose target is a block/heading/doc. When
+// parent is {doc:true}, infer the doc from the anchor block in `at`.
+function parentDoc(store, repoId, to, loaded) {
+    if (typeof to.parent === "string") {
+        return docIdForBlockLoaded(loaded, to.parent) ?? docIdForBlock(store, repoId, to.parent) ?? throwMissing(to.parent);
+    }
+    if (typeof to.parent === "object" && "heading" in to.parent) {
+        return docIdForBlockLoaded(loaded, to.parent.heading) ?? docIdForBlock(store, repoId, to.parent.heading) ?? throwMissing(to.parent.heading);
+    }
+    // parent: {doc:true} — infer from the anchor block in `at`.
+    if (typeof to.at === "object") {
+        const anchor = "before" in to.at ? to.at.before : to.at.after;
+        return docIdForBlockLoaded(loaded, anchor) ?? docIdForBlock(store, repoId, anchor) ?? throwMissing(anchor);
+    }
+    throw new MutationError("target_missing", "insert at top-level start/end requires an explicit doc");
+}
+function throwMissing(id) {
+    throw new MutationError("parent_missing", `parent ${id} not found`);
+}
+// Cross-document move: extract the contiguous run from src, insert into dst.
+function crossDocMove(src, dst, blockIds, to, opIndex) {
+    // Extract from src (must be a contiguous top-level or same-parent run).
+    const moving = [];
+    for (const id of blockIds) {
+        const found = locateMut(src, id);
+        if (!found)
+            throw new MutationError("block_missing", `block ${id} not found in source doc`, { op_index: opIndex });
+        moving.push(found.block);
+    }
+    // remove from their source lists
+    for (const id of blockIds) {
+        const f = locateMut(src, id);
+        if (f)
+            f.siblings.splice(f.index, 1);
+    }
+    // Insert into dst at the resolved target.
+    const target = resolveDstTarget(dst, to);
+    target.siblings.splice(target.index, 0, ...moving);
+    return { ids: blockIds };
+}
+function locateMut(doc, blockId) {
+    const search = (list) => {
+        for (let i = 0; i < list.length; i++) {
+            if (list[i].id === blockId)
+                return { block: list[i], siblings: list, index: i };
+            const f = search(list[i].children);
+            if (f)
+                return f;
+        }
+        return null;
+    };
+    return search(doc.children);
+}
+function resolveDstTarget(dst, to) {
+    if (typeof to.parent === "object" && "doc" in to.parent) {
+        return { siblings: dst.children, index: resolveAt(dst.children, to.at) };
+    }
+    if (typeof to.parent === "string") {
+        const f = locateMut(dst, to.parent);
+        if (!f)
+            throw new MutationError("parent_missing", `parent ${to.parent} not found in dest`);
+        return { siblings: f.block.children, index: resolveAt(f.block.children, to.at) };
+    }
+    // heading/section: insert into top-level list at the anchor.
+    return { siblings: dst.children, index: resolveAt(dst.children, to.at) };
+}
+function resolveAt(siblings, at) {
+    if (at === "start")
+        return 0;
+    if (at === "end")
+        return siblings.length;
+    if ("before" in at) {
+        const i = siblings.findIndex((b) => b.id === at.before);
+        if (i < 0)
+            throw new MutationError("target_missing", `anchor ${at.before} not found`);
+        return i;
+    }
+    const i = siblings.findIndex((b) => b.id === at.after);
+    if (i < 0)
+        throw new MutationError("target_missing", `anchor ${at.after} not found`);
+    return i + 1;
+}
+//# sourceMappingURL=apply.js.map

package/dist/src/mutate/doc-store.d.ts

@@ -0,0 +1,49 @@
+import type { Store } from "../core/store/store.js";
+export interface DocStore {
+    /** Does a file exist at repo-relative `path`? */
+    exists(path: string): boolean;
+    /** Current bytes at `path`, or null if absent. */
+    read(path: string): string | null;
+    /** Atomically write `bytes` to `path` (mkdir -p parents; temp file + rename). */
+    write(path: string, bytes: string): void;
+    /** Rename `from` → `to` (mkdir -p the destination's parents). */
+    rename(from: string, to: string): void;
+    /** Remove `path` if present. */
+    remove(path: string): void;
+    /** Refresh the freshness stat-cache row for `path` after writing `bytes`. */
+    recordStat(store: Store, repoId: string, path: string, bytes: string): void;
+    /** Drop the freshness stat-cache row for `path`. */
+    clearStat(store: Store, repoId: string, path: string): void;
+}
+/** Filesystem-backed DocStore rooted at a working-tree directory (v1 default). */
+export declare class FsDocStore implements DocStore {
+    private readonly root;
+    constructor(root: string);
+    private abs;
+    exists(path: string): boolean;
+    read(path: string): string | null;
+    write(path: string, bytes: string): void;
+    rename(from: string, to: string): void;
+    remove(path: string): void;
+    recordStat(store: Store, repoId: string, path: string, bytes: string): void;
+    clearStat(store: Store, repoId: string, path: string): void;
+}
+/** Headless DocStore: no working tree. The DB is the canonical artifact, so the
+ *  file write is a no-op and there is no on-disk state to CAS against or stat. */
+export declare class NullDocStore implements DocStore {
+    exists(): boolean;
+    read(): string | null;
+    write(): void;
+    rename(): void;
+    remove(): void;
+    recordStat(): void;
+    clearStat(): void;
+}
+/** The write target for a mutation: an explicit DocStore, else a filesystem
+ *  store rooted at `rootPath`. Throws if neither is supplied (a caller must name
+ *  one or the other — a filesystem repo passes rootPath; a headless repo passes
+ *  a NullDocStore). */
+export declare function resolveDocStore(req: {
+    docStore?: DocStore;
+    rootPath?: string;
+}): DocStore;

package/dist/src/mutate/doc-store.js

@@ -0,0 +1,71 @@
+import { writeFileSync, readFileSync, existsSync, renameSync, unlinkSync, mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { sha256 } from "../core/hash.js";
+import { recordFileStat } from "../sync/freshness.js";
+/** Filesystem-backed DocStore rooted at a working-tree directory (v1 default). */
+export class FsDocStore {
+    root;
+    constructor(root) {
+        this.root = root;
+    }
+    abs(path) {
+        return join(this.root, path);
+    }
+    exists(path) {
+        return existsSync(this.abs(path));
+    }
+    read(path) {
+        const abs = this.abs(path);
+        return existsSync(abs) ? readFileSync(abs, "utf8") : null;
+    }
+    write(path, bytes) {
+        const abs = this.abs(path);
+        mkdirSync(dirname(abs), { recursive: true });
+        const tmp = `${abs}.omgtmp`;
+        writeFileSync(tmp, bytes);
+        renameSync(tmp, abs);
+    }
+    rename(from, to) {
+        const toAbs = this.abs(to);
+        mkdirSync(dirname(toAbs), { recursive: true });
+        renameSync(this.abs(from), toAbs);
+    }
+    remove(path) {
+        const abs = this.abs(path);
+        if (existsSync(abs))
+            unlinkSync(abs);
+    }
+    recordStat(store, repoId, path, bytes) {
+        recordFileStat(store, repoId, path, this.abs(path), sha256(bytes));
+    }
+    clearStat(store, repoId, path) {
+        store.db.prepare("DELETE FROM file_stats WHERE repo_id = ? AND path = ?").run(repoId, path);
+    }
+}
+/** Headless DocStore: no working tree. The DB is the canonical artifact, so the
+ *  file write is a no-op and there is no on-disk state to CAS against or stat. */
+export class NullDocStore {
+    exists() {
+        return false;
+    }
+    read() {
+        return null;
+    }
+    write() { }
+    rename() { }
+    remove() { }
+    recordStat() { }
+    clearStat() { }
+}
+/** The write target for a mutation: an explicit DocStore, else a filesystem
+ *  store rooted at `rootPath`. Throws if neither is supplied (a caller must name
+ *  one or the other — a filesystem repo passes rootPath; a headless repo passes
+ *  a NullDocStore). */
+export function resolveDocStore(req) {
+    if (req.docStore)
+        return req.docStore;
+    if (req.rootPath != null)
+        return new FsDocStore(req.rootPath);
+    throw new Error("mutation requires a rootPath or an explicit docStore");
+}
+//# sourceMappingURL=doc-store.js.map

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

@@ -0,0 +1,60 @@
+import type { Store } from "../core/store/store.js";
+import { type InboundLink } from "../graph/inbound-links.js";
+import { type DocStore } from "./doc-store.js";
+export interface DocOpContext {
+    repoId: string;
+    /** Working-tree root for the default filesystem write target. Omit only when
+     *  supplying an explicit `docStore` (e.g. a headless NullDocStore). */
+    rootPath?: string;
+    /** Write target (ADR-014 §5); defaults to a filesystem store at `rootPath`. */
+    docStore?: DocStore;
+    /** workspace .omgbase/ dir; when set, the write runs under the writer flock. */
+    omgbaseDir?: string;
+    actor?: string;
+}
+export interface DocOpResult {
+    docId: string;
+    path: string;
+    committed: boolean;
+}
+export interface DocMoveOptions {
+    /**
+     * Also rewrite the inbound links that named the OLD path so they point at the
+     * new one — a destination-aware rewrite (anchors, link text, titles, and code
+     * spans preserved; absolute/relative style kept) applied as a CAS-checked
+     * `update` per source block in one follow-up api changeset. Frontmatter-level
+     * relations are not rewritten (reported in `dangling`).
+     */
+    retargetInbound?: boolean;
+}
+export interface DocMoveResult extends DocOpResult {
+    /**
+     * Inbound links still pointing at the OLD path after this call — the source
+     * blocks `links_stale` will now report (empty when `retargetInbound` rewrote
+     * them all). Computed from the open edge index before the move.
+     */
+    dangling: InboundLink[];
+    /** With `retargetInbound`: the source blocks rewritten and the docs re-ingested. */
+    retargeted: {
+        blocks: string[];
+        docs: string[];
+    } | null;
+}
+/** docs_create: create a new document from complete file bytes (frontmatter incl.). */
+export declare function docsCreate(store: Store, ctx: DocOpContext, path: string, markdown: string, frontmatter?: Record<string, unknown>): DocOpResult;
+/**
+ * docs_move: rename a document to a new path (identity preserved). The edge
+ * index follows the path, not the identity: links written against the OLD path
+ * now dangle (their open edges are re-pointed at `phantom:<old>`, exactly what
+ * re-extracting the source would produce, so `links_stale` sees them), and
+ * phantom edges already written against the NEW path are adopted. The result
+ * lists the dangling inbound links; `retargetInbound` rewrites them.
+ */
+export declare function docsMove(store: Store, ctx: DocOpContext, docRef: string, toPath: string, opts?: DocMoveOptions): DocMoveResult;
+/** docs_delete: mark a document deleted and remove its file (resurrection-poolable). */
+export declare function docsDelete(store: Store, ctx: DocOpContext, docRef: string): DocOpResult;
+/** docs_set_meta: surgical frontmatter patch (set/unset keys), re-ingested. */
+export declare function docsSetMeta(store: Store, ctx: DocOpContext, docRef: string, patch: {
+    set?: Record<string, unknown>;
+    unset?: string[];
+}): DocOpResult;