@omgbase/core 0.11.1 → 0.15.0

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

@@ -0,0 +1,135 @@
+import type { Store } from "../core/store/store.js";
+import { type InboundLink } from "../graph/inbound-links.js";
+import { type DocStore } from "./doc-store.js";
+import type { Effect, EffectAt, EffectExpect, EffectTarget } from "./effects.js";
+import { type ExecuteRequest, type Plan, type Receipt } from "./plan.js";
+/** What a builder returns: the ordered effects and the commit reason they carry (absent → the caller's `reason` argument). */
+export interface Sugar {
+    effects: Effect[];
+    reason?: string;
+}
+/** A live document as the builders address it: its id and its storage-form path (the reasons spell the path). */
+export interface SugarDoc {
+    id: string;
+    path: string;
+}
+/** A caller's guard as an effect guard: absent stays absent, an empty object stays an empty guard (the planner then pins what it needs). */
+export declare function guardOf(e: {
+    content_hash?: string | undefined;
+    parent_children_hash?: string | undefined;
+} | undefined): {
+    expect?: EffectExpect;
+};
+/**
+ * The pre-check a `create` / `move document` caller runs before planning
+ * (spec/surface §4 "The document operations", §9): `path_taken` exactly as the
+ * 2.x library operations raised it — the caller's message (`document already
+ * exists at <rel>` for a create, `a document already exists at <rel>` for a
+ * move), then `file already exists on disk at <rel>` — with NO `data`, so the
+ * planner's own `path_taken { path }` never fires. Shared by the MCP tools and
+ * the `omg` verbs (the Rust port mirrors it).
+ */
+export declare function requireAbsentPath(store: Store, repoId: string, where: {
+    rootPath?: string;
+    docStore?: DocStore;
+}, rel: string, takenMessage: string): void;
+/** `docs_create` / `omg new`: one `create` at the canonical path; reason `create <rel>`. */
+export declare function createEffects(path: string, markdown: string, frontmatter?: Record<string, unknown>): Sugar;
+/** `docs_move` / `omg mv`: one `move { target: document, to, retarget_inbound }`; reason `move <from> -> <to>`. */
+export declare function moveDocEffects(doc: SugarDoc, toPath: string, retargetInbound?: boolean): Sugar;
+/** `docs_delete` / `omg rm --doc`: one `remove { target: document }`; reason `delete <path>`. */
+export declare function deleteDocEffects(doc: SugarDoc): Sugar;
+/**
+ * `docs_set_meta` / `omg meta`: one `set`/`unset frontmatter.<k>` per key, `unset`
+ * winning a key named in both (the legacy merge spread `set` then deleted `unset`);
+ * reason `set_meta <path>`. An empty patch yields no effect — the caller refuses
+ * it (`filter_invalid` "pass `set` and/or `unset`", spec/surface §9).
+ */
+export declare function setMetaEffects(doc: SugarDoc, set: Record<string, unknown> | undefined, unset: readonly string[] | undefined): Sugar;
+/** `docs_update` / `omg update <doc>`: one `set { document, content }`; the reason is the caller's. */
+export declare function updateContentEffects(doc: Pick<SugarDoc, "id">, content: string, reason?: string): Sugar;
+/** `blocks_insert` / `omg insert`: `insert into <document|block> at …`; the caller's `expect` is the destination-parent CAS. */
+export declare function insertEffects(into: EffectTarget, at: EffectAt, markdown: string, expect?: {
+    parent_children_hash?: string | undefined;
+}): Sugar;
+/**
+ * `blocks_update` / `omg update <block>` / `omg edit`: `set markdown` and/or `set
+ * attrs.checked`. The caller's `expect` guards the FIRST effect (the content CAS
+ * is checked once, against the bytes the caller saw); a second effect is pinned
+ * by the planner to the block as the first left it. Nothing to set → no effect
+ * (the caller refuses it).
+ */
+export declare function updateBlockEffects(id: string, patch: {
+    markdown?: string | undefined;
+    checked?: boolean | undefined;
+    expect?: {
+        content_hash?: string | undefined;
+        parent_children_hash?: string | undefined;
+    } | undefined;
+}): Sugar;
+/** `blocks_move` / `omg move`: one `move { targets, into, at, expect }`. */
+export declare function moveBlocksEffects(ids: readonly string[], into: EffectTarget, at: EffectAt, expect?: {
+    parent_children_hash?: string | undefined;
+}): Sugar;
+/** `blocks_remove` / `omg rm`: one `remove { targets }` (the planner pins each block). */
+export declare function removeBlocksEffects(ids: readonly string[]): Sugar;
+/** `blocks_split` / `omg split`: one `split { target, at }` (the planner pins the content CAS). */
+export declare function splitEffects(id: string, at: readonly number[]): Sugar;
+/** `blocks_merge` / `omg merge`: one `merge { targets, separator? }`. */
+export declare function mergeEffects(ids: readonly string[], separator?: string): Sugar;
+/** `blocks_check` / `omg done`: N × `set attrs.checked` (a block named twice is one write — the planner drops the duplicate). */
+export declare function checkEffects(ids: readonly string[], checked: boolean): Sugar;
+/** `nodes_set` / `omg node set`: one `set { node, field: prop, value }`. */
+export declare function nodeSetEffects(nodeId: string, prop: string, value: string): Sugar;
+/** `blocks_append` / `omg append`: `insert at end` into a heading's section or a container block (the caller decided which by the block's kind). */
+export declare function appendEffects(into: EffectTarget, text: string): Sugar;
+/** `docs_append`: `insert at end` into the document's top level or a resolved section. */
+export declare function docsAppendEffects(into: EffectTarget, text: string): Sugar;
+/** `links_retarget` / `links_repair` / `omg retarget --apply`: one `retarget { repairs, path_glob? }` under the calling tool's name. */
+export declare function retargetEffects(repairs: readonly {
+    from: string;
+    to: string;
+}[], pathGlob: string | undefined, reason: "links_retarget" | "links_repair"): Sugar;
+/** The request half a caller supplies: where to write and under whom (`ExecuteRequest` minus the origin's reason, which the sugar carries). */
+export type SugarRequest = Omit<ExecuteRequest, "origin"> & {
+    actor: string | null;
+    reason?: string;
+};
+/**
+ * Plan + execute a builder's effects as one request (`applyEffectsDetailed`: one
+ * lock, one transaction) under `actor` and the sugar's reason — `request.reason`
+ * wins when given (a `--reason`, a `docs_update` argument) — and report any
+ * planner failure without its `effect_index`. `dryRun` plans only (the CLI's
+ * `--dry-run`, spec/cli §3.6: every dry run is a plan and burns no id).
+ */
+export declare function applySugar(store: Store, request: SugarRequest & {
+    dryRun?: boolean;
+}, sugar: Sugar): {
+    plan: Plan;
+    receipt?: Receipt;
+};
+/** The document-operation result the `omg` document verbs and the fixture `docs` step record (`spec/mutate` §9): `{ id, path, committed }`, the path in the storage form. */
+export interface DocOpOutcome {
+    id: string;
+    path: string;
+    committed: true;
+}
+/** `docs_create`'s document is the receipt's first revision (`new_ids["$new.0"]` is the same id); every other operation's is the one addressed. */
+export declare function createdDoc(receipt: Receipt, path: string): DocOpOutcome;
+export declare function docOutcome(doc: SugarDoc, path?: string): DocOpOutcome;
+/** What a move reports about the inbound links (spec/mutate §6 `docs_move`; the `retargeted`/`dangling` extras of the tool and the verb). */
+export interface MoveLinks {
+    /** inbound links still naming the OLD path after the move — every link when the retarget was opted out, else the frontmatter relations a move never rewrites */
+    dangling: InboundLink[];
+    /** the source blocks rewritten and their documents; `null` when the retarget was opted out or nothing linked in */
+    retargeted: {
+        blocks: string[];
+        docs: string[];
+    } | null;
+}
+/**
+ * Who links to the document BY PATH as written, and what the move's retarget
+ * rewrites — computed BEFORE the move from the current blocks (`planInboundRetarget`
+ * is pure, so it equals what the planner lowers for the same `move` effect).
+ */
+export declare function moveLinks(store: Store, repoId: string, doc: SugarDoc, toPath: string, retargetInbound?: boolean): MoveLinks;

package/dist/src/mutate/sugar.js

@@ -0,0 +1,167 @@
+import { findDoc } from "../core/read/reader.js";
+import { inboundLinksTo } from "../graph/inbound-links.js";
+import { canonicalDocPath, planInboundRetarget } from "./docs.js";
+import { resolveDocStore } from "./doc-store.js";
+import { MutationError } from "./tree.js";
+import { applyEffectsDetailed, stripEffectIndex } from "./plan.js";
+const documentTarget = (id) => ({ kind: "document", id });
+const blockTarget = (id) => ({ kind: "block", id });
+/** A caller's guard as an effect guard: absent stays absent, an empty object stays an empty guard (the planner then pins what it needs). */
+export function guardOf(e) {
+    if (!e)
+        return {};
+    const expect = {};
+    if (e.content_hash !== undefined)
+        expect.content_hash = e.content_hash;
+    if (e.parent_children_hash !== undefined)
+        expect.parent_children_hash = e.parent_children_hash;
+    return { expect };
+}
+// ---- the document operations (spec/mutate §6) ---------------------------------------------
+/**
+ * The pre-check a `create` / `move document` caller runs before planning
+ * (spec/surface §4 "The document operations", §9): `path_taken` exactly as the
+ * 2.x library operations raised it — the caller's message (`document already
+ * exists at <rel>` for a create, `a document already exists at <rel>` for a
+ * move), then `file already exists on disk at <rel>` — with NO `data`, so the
+ * planner's own `path_taken { path }` never fires. Shared by the MCP tools and
+ * the `omg` verbs (the Rust port mirrors it).
+ */
+export function requireAbsentPath(store, repoId, where, rel, takenMessage) {
+    if (findDoc(store, { repoId, path: rel }))
+        throw new MutationError("path_taken", takenMessage);
+    if (resolveDocStore(where).exists(rel))
+        throw new MutationError("path_taken", `file already exists on disk at ${rel}`);
+}
+/** `docs_create` / `omg new`: one `create` at the canonical path; reason `create <rel>`. */
+export function createEffects(path, markdown, frontmatter) {
+    const rel = canonicalDocPath(path);
+    return { effects: [{ op: "create", path: rel, markdown, ...(frontmatter !== undefined ? { frontmatter } : {}) }], reason: `create ${rel}` };
+}
+/** `docs_move` / `omg mv`: one `move { target: document, to, retarget_inbound }`; reason `move <from> -> <to>`. */
+export function moveDocEffects(doc, toPath, retargetInbound = true) {
+    const to = canonicalDocPath(toPath);
+    return { effects: [{ op: "move", target: documentTarget(doc.id), to, ...(retargetInbound ? {} : { retarget_inbound: false }) }], reason: `move ${doc.path} -> ${to}` };
+}
+/** `docs_delete` / `omg rm --doc`: one `remove { target: document }`; reason `delete <path>`. */
+export function deleteDocEffects(doc) {
+    return { effects: [{ op: "remove", target: documentTarget(doc.id) }], reason: `delete ${doc.path}` };
+}
+/**
+ * `docs_set_meta` / `omg meta`: one `set`/`unset frontmatter.<k>` per key, `unset`
+ * winning a key named in both (the legacy merge spread `set` then deleted `unset`);
+ * reason `set_meta <path>`. An empty patch yields no effect — the caller refuses
+ * it (`filter_invalid` "pass `set` and/or `unset`", spec/surface §9).
+ */
+export function setMetaEffects(doc, set, unset) {
+    const gone = unset ?? [];
+    const target = documentTarget(doc.id);
+    const effects = [
+        ...Object.entries(set ?? {}).filter(([k]) => !gone.includes(k)).map(([k, value]) => ({ op: "set", target, field: `frontmatter.${k}`, value })),
+        ...gone.map((k) => ({ op: "unset", target, field: `frontmatter.${k}` })),
+    ];
+    return { effects, reason: `set_meta ${doc.path}` };
+}
+/** `docs_update` / `omg update <doc>`: one `set { document, content }`; the reason is the caller's. */
+export function updateContentEffects(doc, content, reason) {
+    return { effects: [{ op: "set", target: documentTarget(doc.id), field: "content", value: content }], ...(reason !== undefined ? { reason } : {}) };
+}
+// ---- the block-level tools (spec/surface §4) ----------------------------------------------
+/** `blocks_insert` / `omg insert`: `insert into <document|block> at …`; the caller's `expect` is the destination-parent CAS. */
+export function insertEffects(into, at, markdown, expect) {
+    return { effects: [{ op: "insert", into, at, markdown, ...guardOf(expect) }], reason: "blocks_insert" };
+}
+/**
+ * `blocks_update` / `omg update <block>` / `omg edit`: `set markdown` and/or `set
+ * attrs.checked`. The caller's `expect` guards the FIRST effect (the content CAS
+ * is checked once, against the bytes the caller saw); a second effect is pinned
+ * by the planner to the block as the first left it. Nothing to set → no effect
+ * (the caller refuses it).
+ */
+export function updateBlockEffects(id, patch) {
+    const target = blockTarget(id);
+    const expect = guardOf(patch.expect);
+    const effects = [];
+    if (patch.markdown !== undefined)
+        effects.push({ op: "set", target, field: "markdown", value: patch.markdown, ...expect });
+    if (patch.checked !== undefined)
+        effects.push({ op: "set", target, field: "attrs.checked", value: patch.checked, ...(effects.length === 0 ? expect : {}) });
+    return { effects, reason: "blocks_update" };
+}
+/** `blocks_move` / `omg move`: one `move { targets, into, at, expect }`. */
+export function moveBlocksEffects(ids, into, at, expect) {
+    return { effects: [{ op: "move", targets: ids.map(blockTarget), into, at, ...guardOf(expect) }], reason: "blocks_move" };
+}
+/** `blocks_remove` / `omg rm`: one `remove { targets }` (the planner pins each block). */
+export function removeBlocksEffects(ids) {
+    return { effects: [{ op: "remove", targets: ids.map(blockTarget) }], reason: "blocks_remove" };
+}
+/** `blocks_split` / `omg split`: one `split { target, at }` (the planner pins the content CAS). */
+export function splitEffects(id, at) {
+    return { effects: [{ op: "split", target: blockTarget(id), at: [...at] }], reason: "blocks_split" };
+}
+/** `blocks_merge` / `omg merge`: one `merge { targets, separator? }`. */
+export function mergeEffects(ids, separator) {
+    return { effects: [{ op: "merge", targets: ids.map(blockTarget), ...(separator !== undefined ? { separator } : {}) }], reason: "blocks_merge" };
+}
+/** `blocks_check` / `omg done`: N × `set attrs.checked` (a block named twice is one write — the planner drops the duplicate). */
+export function checkEffects(ids, checked) {
+    return { effects: ids.map((id) => ({ op: "set", target: blockTarget(id), field: "attrs.checked", value: checked })), reason: "blocks_check" };
+}
+/** `nodes_set` / `omg node set`: one `set { node, field: prop, value }`. */
+export function nodeSetEffects(nodeId, prop, value) {
+    return { effects: [{ op: "set", target: { kind: "node", id: nodeId }, field: prop, value }], reason: "nodes_set" };
+}
+/** `blocks_append` / `omg append`: `insert at end` into a heading's section or a container block (the caller decided which by the block's kind). */
+export function appendEffects(into, text) {
+    return { effects: [{ op: "insert", into, at: "end", markdown: text }], reason: "blocks_append" };
+}
+/** `docs_append`: `insert at end` into the document's top level or a resolved section. */
+export function docsAppendEffects(into, text) {
+    return { effects: [{ op: "insert", into, at: "end", markdown: text }], reason: "docs_append" };
+}
+/** `links_retarget` / `links_repair` / `omg retarget --apply`: one `retarget { repairs, path_glob? }` under the calling tool's name. */
+export function retargetEffects(repairs, pathGlob, reason) {
+    return { effects: [{ op: "retarget", repairs: repairs.map((r) => ({ from: r.from, to: r.to })), ...(pathGlob !== undefined ? { path_glob: pathGlob } : {}) }], reason };
+}
+/**
+ * Plan + execute a builder's effects as one request (`applyEffectsDetailed`: one
+ * lock, one transaction) under `actor` and the sugar's reason — `request.reason`
+ * wins when given (a `--reason`, a `docs_update` argument) — and report any
+ * planner failure without its `effect_index`. `dryRun` plans only (the CLI's
+ * `--dry-run`, spec/cli §3.6: every dry run is a plan and burns no id).
+ */
+export function applySugar(store, request, sugar) {
+    const { actor, reason, dryRun, ...rest } = request;
+    const chosen = reason ?? sugar.reason;
+    try {
+        return applyEffectsDetailed(store, { ...rest, effects: sugar.effects, origin: { actor, ...(chosen !== undefined ? { reason: chosen } : {}) }, ...(dryRun ? { dryRun: true } : {}) });
+    }
+    catch (e) {
+        throw stripEffectIndex(e);
+    }
+}
+/** `docs_create`'s document is the receipt's first revision (`new_ids["$new.0"]` is the same id); every other operation's is the one addressed. */
+export function createdDoc(receipt, path) {
+    const id = receipt.new_ids["$new.0"] ?? receipt.revisions[0]?.id;
+    if (id === undefined)
+        throw new Error("createdDoc: the receipt names no created document");
+    return { id, path, committed: true };
+}
+export function docOutcome(doc, path = doc.path) {
+    return { id: doc.id, path, committed: true };
+}
+/**
+ * Who links to the document BY PATH as written, and what the move's retarget
+ * rewrites — computed BEFORE the move from the current blocks (`planInboundRetarget`
+ * is pure, so it equals what the planner lowers for the same `move` effect).
+ */
+export function moveLinks(store, repoId, doc, toPath, retargetInbound = true) {
+    const to = canonicalDocPath(toPath);
+    const inbound = inboundLinksTo(store, repoId, doc.id, doc.path);
+    if (!retargetInbound || inbound.length === 0)
+        return { dangling: inbound, retargeted: null };
+    const plan = planInboundRetarget(store, doc.id, doc.path, to, inbound);
+    return { dangling: plan.dangling, retargeted: { blocks: plan.blocks, docs: plan.docs } };
+}
+//# sourceMappingURL=sugar.js.map

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

@@ -16,10 +16,12 @@ export interface MutDoc {
     frontmatterRaw: string | null;
     children: MutBlock[];
 }
+/** The codes spec/mutate §8 lists (2.3 adds `conflicting_effects`, `unsupported_plan_version`, `plan_mismatch`); `filter_invalid` is the planner's shape error, spec/surface §4's envelope. */
+export type MutationErrorCode = "stale_expectation" | "block_missing" | "target_missing" | "parent_missing" | "doc_missing" | "cycle_move" | "not_contiguous" | "type_mismatch" | "path_taken" | "node_not_editable" | "stale_plan" | "plan_not_convergent" | "sync_conflict" | "conflicting_effects" | "unsupported_plan_version" | "plan_mismatch" | "filter_invalid";
 export declare class MutationError extends Error {
-    code: string;
+    code: MutationErrorCode | string;
     data: Record<string, unknown>;
-    constructor(code: string, message: string, data?: Record<string, unknown>);
+    constructor(code: MutationErrorCode | string, message: string, data?: Record<string, unknown>);
 }
 /** Find a block by id anywhere in the doc; returns the block + its parent list. */
 export declare function locate(doc: MutDoc, blockId: string): {

package/dist/src/spec-versions.d.ts

@@ -2,13 +2,13 @@ export declare const SPEC_VERSIONS: {
     readonly oqx: "0.20";
     readonly format: "0.2";
     readonly reconcile: "2.3";
-    readonly store: "13.5";
+    readonly store: "14.0";
     readonly properties: "1.1";
     readonly graph: "1.1";
     readonly search: "2.0";
-    readonly mutate: "2.0";
-    readonly sync: "2.0";
-    readonly surface: "3.0";
-    readonly cli: "3.0";
+    readonly mutate: "3.0";
+    readonly sync: "2.2";
+    readonly surface: "4.0";
+    readonly cli: "4.0";
 };
 export type SpecName = keyof typeof SPEC_VERSIONS;

package/dist/src/spec-versions.js

@@ -13,13 +13,13 @@ export const SPEC_VERSIONS = {
     oqx: LANGUAGE_VERSION,
     format: "0.2",
     reconcile: "2.3",
-    store: "13.5",
+    store: "14.0",
     properties: "1.1",
     graph: "1.1",
     search: "2.0",
-    mutate: "2.0",
-    sync: "2.0",
-    surface: "3.0",
-    cli: "3.0",
+    mutate: "3.0",
+    sync: "2.2",
+    surface: "4.0",
+    cli: "4.0",
 };
 //# sourceMappingURL=spec-versions.js.map

package/dist/src/surface-paths.d.ts

@@ -1,28 +1,16 @@
 import type { ApplyResult } from "./mutate/apply.js";
-import type { DocOpResult, DocMoveResult } from "./mutate/docs.js";
 import type { RetargetHit } from "./mutate/macros.js";
-import type { Opset } from "./mutate/opset.js";
-import type { DocsUpdateResult } from "./mutate/plan-update.js";
+import type { Plan, Receipt } from "./mutate/plan.js";
 import type { InboundLink } from "./graph/inbound-links.js";
 import type { ObserveResult, ObserveDeleteResult } from "./sync/observe.js";
 import type { SweepResult } from "./sync/freshness.js";
 import type { TextSearchResult } from "./search/text.js";
 import type { ResolveHit } from "./search/resolve.js";
-/** `spec/mutate` §4's result: `revisions[].path` and the dry-run `diffs` keys. */
+/** `spec/mutate` §4's kernel result (the library's `apply`; no tool returns it since 4.0): `revisions[].path` and the dry-run `diffs` keys. */
 export declare function surfaceApplyResult<T extends ApplyResult>(res: T): T;
-/** A document operation's result on the wire (spec/surface §4, 3.0): the
- *  library's `{ docId, path, … }` (`spec/mutate` §6, unchanged there) renamed
- *  to the document's row attributes `id`/`path`, the path rooted, the
- *  dry-run `diffs` re-keyed; every other key (`committed`, `deleted`, …) as is. */
-export type SurfaceDocOpResult<T extends DocOpResult> = Omit<T, "docId" | "path"> & {
-    id: string;
-    path: string;
-};
-/** `docs_create` / `docs_delete` / `docs_set_meta`. */
-export declare function surfaceDocOpResult<T extends DocOpResult>(res: T): SurfaceDocOpResult<T>;
-/** An inbound link on the wire (`docs_move.dangling[]`): an edge row under the
- *  `edges` target's names (spec/surface §1.2) — `doc_id`, `path` (rooted),
- *  `block_id`, `target` (as authored), `anchor`, `field?`. */
+/** An inbound link on the wire (`docs_move.dangling[]`, `omg mv`): a link row
+ *  under the `links` target's names (spec/surface §1.2) — `doc_id`, `path`
+ *  (rooted), `block_id`, `target` (as authored), `anchor`, `field?`. */
 export interface SurfaceInboundLink {
     doc_id: string;
     path: string;
@@ -32,11 +20,6 @@ export interface SurfaceInboundLink {
     field?: string;
 }
 export declare function surfaceInboundLink(l: InboundLink): SurfaceInboundLink;
-/** `docs_move`: the document-op fields plus each dangling link (its `target`
- *  stays as authored — that is what the link says). */
-export declare function surfaceDocMoveResult(res: DocMoveResult): Omit<SurfaceDocOpResult<DocMoveResult>, "dangling"> & {
-    dangling: SurfaceInboundLink[];
-};
 /** An observe outcome on the wire (spec/surface §4, 3.0): `spec/store` §5's
  *  `{ docId, path, … }` (unchanged there) renamed to the document's row
  *  attributes `id`/`path`, the path rooted. */
@@ -58,9 +41,17 @@ export declare function surfaceTextSearch(res: TextSearchResult): TextSearchResu
 export declare function surfaceResolveHits(hits: ResolveHit[]): ResolveHit[];
 /** `links_retarget` / `links_repair` hits (`path` is the block's document). */
 export declare function surfaceRetargetHits(hits: RetargetHit[]): RetargetHit[];
-/** A whole-document update plan: `target.path` and `precondition.path`. */
-export declare function surfaceOpset(opset: Opset): Opset;
-/** `docs_update`: the opset and, when committed, the apply result. */
-export declare function surfaceDocsUpdate(res: DocsUpdateResult): DocsUpdateResult;
+/**
+ * A Plan on the wire (spec/surface §4, 3.1): the executable core — `effects`,
+ * `opset`, `preconditions`, `new_ids`, `plan_id` — is returned VERBATIM in the
+ * storage form, because `plan_id` digests exactly those bytes and the client
+ * hands the object back to `execute` (spec/mutate §11.5; the one result the
+ * path rule exempts, like `dangling[].target`). Only the un-digested `preview`
+ * is rooted: its `revisions[].path`, `diffs` keys and `retarget[].hits[].path`
+ * (3.0; `identity` is keyed by document id and carries no path).
+ */
+export declare function surfacePlan(plan: Plan): Plan;
+/** A Receipt on the wire: `revisions[].path` rooted (the same shape as an apply revision). */
+export declare function surfaceReceipt(receipt: Receipt): Receipt;
 /** `omg sync`'s one-shot sweep: the ingested / suppressed / deleted / conflicted paths. */
 export declare function surfaceSweepResult(res: SweepResult): SweepResult;

package/dist/src/surface-paths.js

@@ -11,14 +11,14 @@
 // Row names (spec/surface §1.2, 3.0): a result that renders a document, block
 // or edge row spells it the way the query binding does — `id`, `path`,
 // `hash`, `raw`, `updated_at`, plain `doc_id`/`block_id` foreign keys. The
-// shapes other specs own under their own names — `spec/mutate`'s document
-// operation result `{ docId, path, … }`, `spec/store`'s observe outcome — are
-// re-shaped HERE too (`SurfaceDocOpResult`, `SurfaceObserveResult`, …).
+// shapes other specs own under their own names — `spec/store`'s observe
+// outcome, a move's dangling inbound links — are re-shaped HERE too
+// (`SurfaceObserveResult`, `surfaceInboundLink`, …).
 //
 // Both the MCP server and the `omg` verbs call these, so the two clients
 // cannot drift. Each function returns a new value; the input is not mutated.
 import { referencePath, referenceKeyed } from "./core/paths.js";
-/** `spec/mutate` §4's result: `revisions[].path` and the dry-run `diffs` keys. */
+/** `spec/mutate` §4's kernel result (the library's `apply`; no tool returns it since 4.0): `revisions[].path` and the dry-run `diffs` keys. */
 export function surfaceApplyResult(res) {
     return {
         ...res,
@@ -26,20 +26,10 @@ export function surfaceApplyResult(res) {
         ...(res.diffs ? { diffs: referenceKeyed(res.diffs) } : {}),
     };
 }
-/** `docs_create` / `docs_delete` / `docs_set_meta`. */
-export function surfaceDocOpResult(res) {
-    const { docId, path, ...rest } = res;
-    return { id: docId, path: referencePath(path), ...rest, ...(res.diffs ? { diffs: referenceKeyed(res.diffs) } : {}) };
-}
 export function surfaceInboundLink(l) {
     const { path, ...rest } = l;
     return { doc_id: rest.doc_id, path: referencePath(path), block_id: rest.block_id, target: rest.target, anchor: rest.anchor, ...(rest.field !== undefined ? { field: rest.field } : {}) };
 }
-/** `docs_move`: the document-op fields plus each dangling link (its `target`
- *  stays as authored — that is what the link says). */
-export function surfaceDocMoveResult(res) {
-    return { ...surfaceDocOpResult(res), dangling: res.dangling.map(surfaceInboundLink) };
-}
 /** `observe` / `observe_many` outcomes. */
 export function surfaceObserveResult(res) {
     const { docId, path, ...rest } = res;
@@ -66,17 +56,31 @@ export function surfaceResolveHits(hits) {
 export function surfaceRetargetHits(hits) {
     return hits.map((h) => ({ ...h, path: referencePath(h.path) }));
 }
-/** A whole-document update plan: `target.path` and `precondition.path`. */
-export function surfaceOpset(opset) {
+/**
+ * A Plan on the wire (spec/surface §4, 3.1): the executable core — `effects`,
+ * `opset`, `preconditions`, `new_ids`, `plan_id` — is returned VERBATIM in the
+ * storage form, because `plan_id` digests exactly those bytes and the client
+ * hands the object back to `execute` (spec/mutate §11.5; the one result the
+ * path rule exempts, like `dangling[].target`). Only the un-digested `preview`
+ * is rooted: its `revisions[].path`, `diffs` keys and `retarget[].hits[].path`
+ * (3.0; `identity` is keyed by document id and carries no path).
+ */
+export function surfacePlan(plan) {
+    if (!plan.preview)
+        return plan;
     return {
-        ...opset,
-        target: { ...opset.target, path: referencePath(opset.target.path) },
-        precondition: { ...opset.precondition, path: referencePath(opset.precondition.path) },
+        ...plan,
+        preview: {
+            ...plan.preview,
+            revisions: plan.preview.revisions.map((r) => ({ ...r, path: referencePath(r.path) })),
+            diffs: referenceKeyed(plan.preview.diffs),
+            ...(plan.preview.retarget !== undefined ? { retarget: plan.preview.retarget.map((r) => ({ ...r, hits: surfaceRetargetHits(r.hits) })) } : {}),
+        },
     };
 }
-/** `docs_update`: the opset and, when committed, the apply result. */
-export function surfaceDocsUpdate(res) {
-    return { opset: surfaceOpset(res.opset), result: res.result ? surfaceApplyResult(res.result) : null };
+/** A Receipt on the wire: `revisions[].path` rooted (the same shape as an apply revision). */
+export function surfaceReceipt(receipt) {
+    return { ...receipt, revisions: receipt.revisions.map((r) => ({ ...r, path: referencePath(r.path) })) };
 }
 /** `omg sync`'s one-shot sweep: the ingested / suppressed / deleted / conflicted paths. */
 export function surfaceSweepResult(res) {
@@ -86,6 +90,7 @@ export function surfaceSweepResult(res) {
         suppressed: res.suppressed.map(referencePath),
         deleted: res.deleted.map(referencePath),
         conflicted: res.conflicted.map(referencePath),
+        materialized: res.materialized.map(referencePath),
     };
 }
 //# sourceMappingURL=surface-paths.js.map

package/dist/src/sync/checkpoint.d.ts

@@ -29,8 +29,11 @@ export declare function processCheckpoint(store: Store, repoId: string, rootPath
 }): CheckpointResult;
 /**
  * Turn a batch's outcomes into the checkpoint row + result, then sweep the
- * resurrection pool. Shared with the external-source driver (driver.ts), which
- * obtains its bytes asynchronously but records its checkpoint the same way.
+ * resurrection pool — the row and the sweep in ONE transaction (spec/sync §4.1),
+ * so a checkpoint is never recorded without its sweep or swept without its row
+ * (the member commits before it are one transaction each, as before). Shared
+ * with the external-source driver (driver.ts), which obtains its bytes
+ * asynchronously but records its checkpoint the same way.
  */
 export declare function finishCheckpoint(store: Store, repoId: string, outcomes: BatchOutcome[], opts: {
     ts: string;

package/dist/src/sync/checkpoint.js

@@ -20,8 +20,11 @@ export function processCheckpoint(store, repoId, rootPath, changes, opts = {}) {
 }
 /**
  * Turn a batch's outcomes into the checkpoint row + result, then sweep the
- * resurrection pool. Shared with the external-source driver (driver.ts), which
- * obtains its bytes asynchronously but records its checkpoint the same way.
+ * resurrection pool — the row and the sweep in ONE transaction (spec/sync §4.1),
+ * so a checkpoint is never recorded without its sweep or swept without its row
+ * (the member commits before it are one transaction each, as before). Shared
+ * with the external-source driver (driver.ts), which obtains its bytes
+ * asynchronously but records its checkpoint the same way.
  */
 export function finishCheckpoint(store, repoId, outcomes, opts) {
     const checkpointId = mintId("cp");
@@ -45,10 +48,11 @@ export function finishCheckpoint(store, repoId, outcomes, opts) {
             ingested.push(o.path);
         fileEntries.push([o.path, o.oldHashHex, o.newHashHex]);
     }
-    store.db
-        .prepare("INSERT INTO checkpoints (id, repo_id, ts, files, git_head) VALUES (?, ?, ?, ?, ?)")
-        .run(checkpointId, repoId, opts.ts, JSON.stringify(fileEntries), opts.gitHead);
-    sweepResurrectionPool(store, opts.ts);
+    store.write((db) => {
+        db.prepare("INSERT INTO checkpoints (id, repo_id, ts, files, git_head) VALUES (?, ?, ?, ?, ?)")
+            .run(checkpointId, repoId, opts.ts, JSON.stringify(fileEntries), opts.gitHead);
+        sweepResurrectionPool(store, opts.ts);
+    });
     return { checkpointId, ingested, suppressed, deleted, conflicted };
 }
 //# sourceMappingURL=checkpoint.js.map

package/dist/src/sync/freshness.d.ts

@@ -1,6 +1,8 @@
 import type { Store } from "../core/store/store.js";
 import { type CheckpointResult } from "./checkpoint.js";
-import { type FileStat, type SyncFs } from "./fs-util.js";
+import { type SyncFs } from "./fs-util.js";
+import { type DocStore } from "../mutate/doc-store.js";
+export { recordStat, recordFileStat } from "./stat-cache.js";
 /** One `file_stats` row (spec/sync §4.3 "the repo's cache rows"). */
 export interface StatCacheRow {
     path: string;
@@ -44,22 +46,23 @@ export interface SweepResult extends CheckpointResult {
     scanned: number;
     candidates: number;
     changed: boolean;
+    /** step 0 (spec/sync §4.3, 2.2): the paths whose pending materialization rows were replayed before the walk. */
+    materialized: string[];
 }
-/** Write a file's stat cache row from a stat (`INSERT … ON CONFLICT DO UPDATE`); a null stat (the
- *  file vanished) deletes the row. The DB half of `record_file_stat` (spec/sync §4.3 step 4). */
-export declare function recordStat(store: Store, repoId: string, path: string, st: FileStat | null, hash: Buffer): void;
-/** Record/refresh a file's stat cache row from its absolute path. Call after any ingest of the file. */
-export declare function recordFileStat(store: Store, repoId: string, path: string, abs: string, hash: Buffer): void;
 /**
  * Run the freshness sweep for a repo (spec/sync §4.3). Returns the checkpoint
  * result plus scan counters. Idempotent; safe alongside a live watcher
  * (hash-based echo suppression makes a double ingest a no-op). `opts.ts` pins
- * the batch timestamp (default now); `opts.fs` the filesystem seam.
+ * the batch timestamp (default now); `opts.fs` the filesystem seam;
+ * `opts.docStore` the write target step 0 materializes through (default: the
+ * filesystem store at `rootPath` — the fixtures' in-memory filesystem never
+ * holds a pending row, so the default is never exercised there).
  */
 export declare function freshnessSweep(store: Store, repoId: string, rootPath: string, opts?: {
     ts?: string;
     gitHead?: string | null;
     fs?: SyncFs;
+    docStore?: DocStore;
 }): SweepResult;
 /**
  * Counts of ways the DB disagrees with the current filesystem. All fields are