@omgbase/core 0.11.1 → 0.19.0

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

package/dist/src/sync/freshness.js

@@ -1,6 +1,10 @@
 import { sha256 } from "../core/hash.js";
 import { processCheckpoint } from "./checkpoint.js";
 import { nodeFs } from "./fs-util.js";
+import { recordStat } from "./stat-cache.js";
+import { materializePending } from "../mutate/materialize.js";
+import { FsDocStore } from "../mutate/doc-store.js";
+export { recordStat, recordFileStat } from "./stat-cache.js";
 /** Step 1 of §4.3 alone: the stat-mismatched or new paths, without hashing anything. */
 export function sweepCandidates(cache, snapshot) {
     const out = [];
@@ -56,30 +60,23 @@ export function snapshotOf(fs, rootPath) {
     }
     return out;
 }
-/** 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 function recordStat(store, repoId, path, st, hash) {
-    if (!st) {
-        store.db.prepare("DELETE FROM file_stats WHERE repo_id = ? AND path = ?").run(repoId, path);
-        return;
-    }
-    store.db
-        .prepare(`INSERT INTO file_stats (repo_id, path, mtime_ns, size, hash) VALUES (?, ?, ?, ?, ?)
-       ON CONFLICT(repo_id, path) DO UPDATE SET mtime_ns = excluded.mtime_ns, size = excluded.size, hash = excluded.hash`)
-        .run(repoId, path, st.mtimeNs, st.size, hash);
-}
-/** Record/refresh a file's stat cache row from its absolute path. Call after any ingest of the file. */
-export function recordFileStat(store, repoId, path, abs, hash) {
-    recordStat(store, repoId, path, nodeFs.stat(abs, ""), hash);
-}
 /**
  * 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 function freshnessSweep(store, repoId, rootPath, opts = {}) {
     const fs = opts.fs ?? nodeFs;
+    // Step 0 (2.2; spec/store §5.7): replay the api path's recorded file intent
+    // before looking at the disk, so a file a crashed or refused write left
+    // behind the database is brought forward instead of being read back as a
+    // human edit. The production recovery point (priming sweep at `omg mcp`
+    // start, the pre-verb sweep of every CLI write).
+    const materialized = materializePending(store, repoId, opts.docStore ?? new FsDocStore(rootPath));
     const cache = loadStatCache(store, repoId);
     const snapshot = snapshotOf(fs, rootPath);
     const plan = sweepPlan(cache, snapshot);
@@ -100,6 +97,7 @@ export function freshnessSweep(store, repoId, rootPath, opts = {}) {
         scanned: snapshot.length,
         candidates: plan.candidates.length,
         changed: result.ingested.length > 0 || result.deleted.length > 0 || result.conflicted.length > 0,
+        materialized,
     };
 }
 /**

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

@@ -46,7 +46,10 @@ export type BatchOutcome = ({
  * The batch reconcile primitive — one checkpoint's worth of members, in order.
  * Two passes with the cross-document phase between them (reconciliation-spec §8):
  *
- *   1. every member is echo-gated and, when it differs from the stored revision,
+ *   1. every member is gated against a pending materialization row at its path
+ *      (spec/store §5.7: the bytes the api path owes confirm the row, an absent
+ *      file is not a deletion, anything else lets the file win), echo-gated and,
+ *      when it differs from the stored revision,
  *      parsed + reconciled against its own prior tree WITHOUT committing
  *      (`prepareReconcile`; members gone from the source contribute their whole
  *      live tree as deleted). All members see one resurrection-pool snapshot with

package/dist/src/sync/observe.js

@@ -6,11 +6,15 @@ import { tombstoneObservedDeletion } from "./tombstone.js";
 import { sweepResurrectionPool } from "../core/store/gc.js";
 import { crossDocMatch, applyCrossDocMatches } from "../reconcile/crossdoc.js";
 import { DEFAULT_CONFIG } from "../reconcile/types.js";
+import { deletePending, readPending } from "../mutate/materialize.js";
 /**
  * The batch reconcile primitive — one checkpoint's worth of members, in order.
  * Two passes with the cross-document phase between them (reconciliation-spec §8):
  *
- *   1. every member is echo-gated and, when it differs from the stored revision,
+ *   1. every member is gated against a pending materialization row at its path
+ *      (spec/store §5.7: the bytes the api path owes confirm the row, an absent
+ *      file is not a deletion, anything else lets the file win), echo-gated and,
+ *      when it differs from the stored revision,
  *      parsed + reconciled against its own prior tree WITHOUT committing
  *      (`prepareReconcile`; members gone from the source contribute their whole
  *      live tree as deleted). All members see one resurrection-pool snapshot with
@@ -42,6 +46,31 @@ export function observeBatch(store, repoId, items, ts, opts = {}) {
     for (const it of items) {
         const existing = liveDoc.get(repoId, it.path);
         const oldHashHex = existing?.file_hash?.toString("hex") ?? null;
+        // The materialization gate (spec/store §5.7): an api commit still owes this
+        // path a file. The observation decides what the row meant for the disk —
+        // the bytes it named confirm it (echo; a `remove` row stays until the file
+        // is gone), an absent file is NOT a deletion (the materializer still owes
+        // it; `remove` rows are confirmed by the absence), anything else is a later
+        // human edit and the file wins: the normal reconciling ingest below, the
+        // row dropped with it.
+        const owed = readPending(db, repoId, it.path);
+        if (owed && it.content === null) {
+            if (owed.kind === "remove")
+                deletePending(db, repoId, it.path);
+            else {
+                pending.push({ kind: "echo", outcome: { kind: "deleted", path: it.path, docId: null, oldHashHex } });
+                continue;
+            }
+        }
+        else if (owed && sha256(it.content).equals(owed.renderedHash)) {
+            if (owed.kind !== "remove")
+                deletePending(db, repoId, it.path);
+            pending.push({
+                kind: "echo",
+                outcome: { kind: "observed", docId: owed.docId, path: it.path, rev: null, commitId: null, converged: true, echo: true, conflicted: false, dispositions: [], oldHashHex, newHashHex: sha256(it.content).toString("hex") },
+            });
+            continue;
+        }
         if (it.content === null) {
             const oldBlocks = existing ? loadOldMatchBlocks(db, existing.doc_id) : [];
             const result = existing
@@ -56,6 +85,10 @@ export function observeBatch(store, repoId, items, ts, opts = {}) {
         // loop-breaker the coordinator relies on (§6): re-observing what the engine
         // already holds is a no-op.
         if (existing && existing.file_hash && existing.file_hash.equals(diskHash)) {
+            // (A row that names other bytes than the file the database already
+            // agrees with is stale either way; the observation settles it.)
+            if (owed)
+                deletePending(db, repoId, it.path);
             pending.push({
                 kind: "echo",
                 outcome: { kind: "observed", docId: existing.doc_id, path: it.path, rev: null, commitId: null, converged: true, echo: true, conflicted: false, dispositions: [], oldHashHex, newHashHex },
@@ -63,7 +96,7 @@ export function observeBatch(store, repoId, items, ts, opts = {}) {
             continue;
         }
         const prepared = prepareReconcile(store, repoId, it.path, it.content, { ts, config, pool, consumed });
-        pending.push({ kind: "ingest", prepared, oldHashHex, newHashHex });
+        pending.push({ kind: "ingest", prepared, oldHashHex, newHashHex, clearPending: owed !== null });
     }
     // ---- cross-document phase (spec/reconcile §7) --------------------------------
     if (pending.length > 1)
@@ -79,6 +112,15 @@ export function observeBatch(store, repoId, items, ts, opts = {}) {
                 tombstoneObservedDeletion(store, repoId, p.docId, ts);
             out.push({ kind: "deleted", path: p.path, docId: p.docId, oldHashHex: p.oldHashHex });
         }
+        else if (p.clearPending) {
+            // File wins (spec/store §5.7): the pending row and the observed commit
+            // that supersedes it go together.
+            out.push(store.write((db) => {
+                const r = commitPrepared(store, repoId, p.prepared, ts, p.oldHashHex, p.newHashHex);
+                deletePending(db, repoId, p.prepared.path);
+                return { kind: "observed", ...r };
+            }));
+        }
         else {
             out.push({ kind: "observed", ...commitPrepared(store, repoId, p.prepared, ts, p.oldHashHex, p.newHashHex) });
         }
@@ -140,13 +182,13 @@ function crossDocPhase(pending, config) {
         prepared.get(m.toDoc)?.crossDocIds.push(m.carriedId);
 }
 // Pass 2 for one reconciled member: commit the finished result as an observed
-// revision (one transaction), flag conflict markers, summarize dispositions.
+// revision — ONE transaction, the conflict-marker flag written inside it with
+// the revision pointers (spec/store §5.4 step 14) — then summarize dispositions.
 function commitPrepared(store, repoId, prepared, ts, oldHashHex, newHashHex) {
     const { path, content } = prepared;
     const conflicted = hasConflictMarkers(content);
     const resolveIds = makeReconcilingResolver(store, repoId, { ts, path, prepared });
-    const res = ingestFile(store, repoId, path, content, { ts, origin: "observed", resolveIds, parsed: prepared.tree });
-    store.db.prepare("UPDATE docs SET conflicted = ? WHERE repo_id = ? AND path = ?").run(conflicted ? 1 : 0, repoId, path);
+    const res = ingestFile(store, repoId, path, content, { ts, origin: "observed", resolveIds, parsed: prepared.tree, conflicted });
     const rows = store.db
         .prepare("SELECT kind, count(*) n FROM dispositions WHERE commit_id = ? GROUP BY kind ORDER BY kind")
         .all(res.commitId);
@@ -213,6 +255,15 @@ export function observeMany(store, repoId, items, opts = {}) {
  */
 export function observeDelete(store, repoId, path, opts = {}) {
     const ts = opts.ts ?? new Date().toISOString();
+    // The §5.7 gate for a gone member: a path the api path still owes a `write`
+    // or `rename` is not tombstoned (the materializer owes the file); a `remove`
+    // row is confirmed by the absence.
+    const owed = readPending(store.db, repoId, path);
+    if (owed) {
+        if (owed.kind !== "remove")
+            return { docId: null, path, deleted: false };
+        deletePending(store.db, repoId, path);
+    }
     const existing = store.db
         .prepare("SELECT doc_id FROM docs WHERE repo_id = ? AND path = ? AND deleted_commit IS NULL")
         .get(repoId, path);

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

@@ -1,10 +1,14 @@
 import type { Store } from "../core/store/store.js";
 import { type SyncFs } from "./fs-util.js";
+import { type DocStore } from "../mutate/doc-store.js";
 export interface RecoveryResult {
+    /** step 0: paths whose pending materialization rows were replayed */
+    materialized: string[];
     healed: string[];
     missing: string[];
 }
 export declare function recoverRepo(store: Store, repoId: string, rootPath: string, opts?: {
     ts?: string;
     fs?: SyncFs;
+    docStore?: DocStore;
 }): RecoveryResult;

package/dist/src/sync/recovery.js

@@ -2,8 +2,11 @@ import { sha256 } from "../core/hash.js";
 import { ingestFile } from "../core/ingest.js";
 import { makeReconcilingResolver } from "./reconciling-ingest.js";
 import { nodeFs } from "./fs-util.js";
+import { materializePending } from "../mutate/materialize.js";
+import { FsDocStore } from "../mutate/doc-store.js";
 export function recoverRepo(store, repoId, rootPath, opts = {}) {
     const fs = opts.fs ?? nodeFs;
+    const materialized = materializePending(store, repoId, opts.docStore ?? new FsDocStore(rootPath));
     const docs = store.db
         .prepare(`SELECT d.doc_id, d.path, d.file_hash, r.rendered_hash
        FROM docs d LEFT JOIN revisions r ON r.rev_id = d.current_rev
@@ -29,6 +32,6 @@ export function recoverRepo(store, repoId, rootPath, opts = {}) {
             healed.push(doc.path);
         }
     }
-    return { healed, missing };
+    return { materialized, healed, missing };
 }
 //# sourceMappingURL=recovery.js.map

package/dist/src/sync/stat-cache.d.ts

@@ -0,0 +1,7 @@
+import type { Store } from "../core/store/store.js";
+import { type FileStat } from "./fs-util.js";
+/** 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;

package/dist/src/sync/stat-cache.js

@@ -0,0 +1,22 @@
+import { nodeFs } from "./fs-util.js";
+// The `file_stats` writers (spec/sync §4.3 step 4), split out of freshness.ts
+// so the mutation write target (`mutate/doc-store.ts`, which refreshes a row
+// after each file it materializes) and the sweep (which imports the doc store
+// for its step 0) do not import each other. freshness.ts re-exports both.
+/** 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 function recordStat(store, repoId, path, st, hash) {
+    if (!st) {
+        store.db.prepare("DELETE FROM file_stats WHERE repo_id = ? AND path = ?").run(repoId, path);
+        return;
+    }
+    store.db
+        .prepare(`INSERT INTO file_stats (repo_id, path, mtime_ns, size, hash) VALUES (?, ?, ?, ?, ?)
+       ON CONFLICT(repo_id, path) DO UPDATE SET mtime_ns = excluded.mtime_ns, size = excluded.size, hash = excluded.hash`)
+        .run(repoId, path, st.mtimeNs, st.size, hash);
+}
+/** Record/refresh a file's stat cache row from its absolute path. Call after any ingest of the file. */
+export function recordFileStat(store, repoId, path, abs, hash) {
+    recordStat(store, repoId, path, nodeFs.stat(abs, ""), hash);
+}
+//# sourceMappingURL=stat-cache.js.map

package/dist/src/sync/tombstone.js

@@ -23,10 +23,13 @@ import { ftsDeleteDoc } from "../core/store/fts.js";
 //      consumes the pool to resurrect ids when the file reappears). Pooling with the
 //      standard ~30-day expiry keeps sweepResurrectionPool semantics intact.
 //
-// Convention: like processCheckpoint/reconcileChanges, this runs bare db.prepare
-// statements on store.db (each auto-commits) rather than opening its own
-// store.write transaction, so it composes with either caller's loop. The unlink of
-// the on-disk file that docsDelete performs is intentionally absent here — the file
+// Transaction: the commit row, the pool snapshot, the FTS deletes and the two
+// tombstone UPDATEs are ONE `store.write` transaction (spec/store §5.6) — a
+// failure midway leaves the doc live with no commit minted, never a doc whose
+// blocks are pooled but still indexed, or tombstoned under a commit that is
+// not there. better-sqlite3 nests an inner `transaction` as a savepoint, so this
+// still composes inside a caller that already holds one. The unlink of the
+// on-disk file that docsDelete performs is intentionally absent here — the file
 // is ALREADY gone (that is what triggered the tombstone).
 /**
  * Tombstone a doc the engine observed as gone from its source (deleted on disk /
@@ -36,20 +39,21 @@ import { ftsDeleteDoc } from "../core/store/fts.js";
  * UPDATEs simply affect zero rows.
  */
 export function tombstoneObservedDeletion(store, repoId, docId, ts) {
-    const db = store.db;
-    const commit = newCommit(db, { repoId, ts, origin: "observed", reason: "observed deletion" });
-    // Snapshot the doc's live blocks into the resurrection pool BEFORE tombstoning,
-    // mirroring core/ingest.ts's reconciling-delete snapshot (~30-day expiry) so a
-    // recreate of the same file can resurrect these block identities.
-    const expires = new Date(Date.parse(ts) + 30 * 24 * 3600 * 1000).toISOString();
-    db.prepare(`INSERT OR REPLACE INTO resurrection_pool (block_id, repo_id, doc_id, raw_hash, norm_hash, type, deleted_commit, expires_ts)
-     SELECT block_id, repo_id, doc_id, raw_hash, norm_hash, type, ?, ?
-       FROM blocks WHERE doc_id = ? AND deleted_commit IS NULL`).run(commit.commitId, expires, docId);
-    // Drop FTS index rows (external-content: delete with the original text before the
-    // blocks change), then tombstone the live blocks and the doc row.
-    ftsDeleteDoc(db, docId);
-    db.prepare("UPDATE blocks SET deleted_commit = ? WHERE doc_id = ? AND deleted_commit IS NULL").run(commit.commitId, docId);
-    db.prepare("UPDATE docs SET deleted_commit = ? WHERE doc_id = ?").run(commit.commitId, docId);
-    return commit.commitId;
+    return store.write((db) => {
+        const commit = newCommit(db, { repoId, ts, origin: "observed", reason: "observed deletion" });
+        // Snapshot the doc's live blocks into the resurrection pool BEFORE tombstoning,
+        // mirroring core/ingest.ts's reconciling-delete snapshot (~30-day expiry) so a
+        // recreate of the same file can resurrect these block identities.
+        const expires = new Date(Date.parse(ts) + 30 * 24 * 3600 * 1000).toISOString();
+        db.prepare(`INSERT OR REPLACE INTO resurrection_pool (block_id, repo_id, doc_id, raw_hash, norm_hash, type, deleted_commit, expires_ts)
+       SELECT block_id, repo_id, doc_id, raw_hash, norm_hash, type, ?, ?
+         FROM blocks WHERE doc_id = ? AND deleted_commit IS NULL`).run(commit.commitId, expires, docId);
+        // Drop FTS index rows (external-content: delete with the original text before the
+        // blocks change), then tombstone the live blocks and the doc row.
+        ftsDeleteDoc(db, docId);
+        db.prepare("UPDATE blocks SET deleted_commit = ? WHERE doc_id = ? AND deleted_commit IS NULL").run(commit.commitId, docId);
+        db.prepare("UPDATE docs SET deleted_commit = ? WHERE doc_id = ?").run(commit.commitId, docId);
+        return commit.commitId;
+    });
 }
 //# sourceMappingURL=tombstone.js.map

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

@@ -5,6 +5,8 @@ export interface WatcherOptions {
     onCheckpoint?: (result: CheckpointResult) => void;
     /** Surface a reconcile error from a background batch (the watch stays live). */
     onError?: (err: unknown) => void;
+    /** The workspace `.omgbase/` dir: when set, every checkpoint runs under the writer lock. */
+    omgbaseDir?: string;
 }
 export declare class Watcher {
     private store;

package/dist/src/sync/watcher.js

@@ -1,4 +1,5 @@
 import { reconcileChanges } from "./driver.js";
+import { withWriterLockAsync } from "./writer-lock.js";
 export class Watcher {
     store;
     repoId;
@@ -30,7 +31,9 @@ export class Watcher {
     async ingest(paths) {
         if (paths.length === 0)
             return null;
-        const result = await reconcileChanges(this.store, this.repoId, this.source, paths.map((path) => ({ path })));
+        const reconcile = () => reconcileChanges(this.store, this.repoId, this.source, paths.map((path) => ({ path })));
+        const dir = this.opts.omgbaseDir;
+        const result = dir !== undefined ? await withWriterLockAsync(dir, reconcile) : await reconcile();
         this.opts.onCheckpoint?.(result);
         return result;
     }

package/dist/src/sync/writer-lock.d.ts

@@ -7,10 +7,25 @@ export interface WriterLockOptions {
 export declare class WriterLockTimeout extends Error {
     constructor(lockPath: string, holderPid: number | null);
 }
+/** Override the process-wide wait defaults (a test seam; the poll never outlasts the timeout). */
+export declare function setWriterLockDefaults(opts: WriterLockOptions): void;
+/** The process-wide wait defaults in force. */
+export declare function writerLockDefaults(): Required<WriterLockOptions>;
 /**
  * Run fn while holding the workspace writer lock. Blocks (polling) until the
  * lock is free or the timeout elapses, then releases the lock even if fn throws.
+ * Re-entrant within the process: a nested call on the same directory runs fn
+ * directly and the outermost exit releases.
  */
 export declare function withWriterLock<T>(omgbaseDir: string, fn: () => T, opts?: WriterLockOptions): T;
+/**
+ * The async form: the lock is held until the promise `fn` returns settles (a
+ * sync `withWriterLock` around an async fn would release at the first await).
+ * Acquisition still polls synchronously — the wait is the same bounded
+ * contention window as the sync form's. Same re-entrancy.
+ */
+export declare function withWriterLockAsync<T>(omgbaseDir: string, fn: () => Promise<T>, opts?: WriterLockOptions): Promise<T>;
+/** True while THIS process holds the lock (at any depth) — a test seam for "ran under the lock". */
+export declare function writerLockHeld(omgbaseDir: string): boolean;
 /** True if no live writer holds the lock (probe without acquiring). */
 export declare function writerLockFree(omgbaseDir: string): boolean;