@omgbase/core 0.11.1 → 0.15.0

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;

package/dist/src/sync/writer-lock.js

@@ -1,5 +1,5 @@
-import { openSync, closeSync, readFileSync, writeFileSync, unlinkSync, existsSync, mkdirSync } from "node:fs";
-import { join } from "node:path";
+import { openSync, closeSync, readFileSync, writeFileSync, unlinkSync, existsSync, mkdirSync, realpathSync } from "node:fs";
+import { join, resolve } from "node:path";
 // Cross-process writer lock (11 §3.2). The write protocol's per-repo writer
 // mutex (04 §6 step 1) generalizes to an advisory lock on
 // <workspace>/.omgbase/writer.lock, held for steps 2–7. All writers — one-shot
@@ -72,33 +72,120 @@ const SLEEP_CELL = new Int32Array(new SharedArrayBuffer(4));
 function sleepSync(ms) {
     Atomics.wait(SLEEP_CELL, 0, 0, ms);
 }
-/**
- * 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.
- */
-export function withWriterLock(omgbaseDir, fn, opts = {}) {
+// Re-entrancy (one acquire per host write, spec/sync §7). The lock is a
+// per-PROCESS claim — the record names a pid and liveness is the pid's — so a
+// second `withWriterLock` on the same directory from the holder must not poll
+// against itself (it would see its own live pid and time out). The process
+// keeps a depth per lock path: the first entry acquires the file, nested
+// entries run their fn directly, and the exit that brings the depth back to
+// zero releases. Nesting happens by design — a tool-boundary lock around a
+// whole MCP call (`mcp/server.ts`) encloses the kernel's own commit-phase lock
+// (`mutate/apply.ts`), and a watcher checkpoint may run while a verb holds the
+// lock — and since the file is one claim per process, the depth also lets an
+// async holder (a checkpoint awaiting the adapter) and a tool call interleave
+// on the event loop without either releasing the other's claim. Cross-process
+// semantics are unchanged: a foreign live holder is waited for, never stolen.
+const held = new Map();
+// The depth is keyed by the directory's real path, so two spellings of one
+// workspace (relative/absolute, a symlinked tree) are one claim; a directory
+// that does not exist yet (a probe before the first write) keys by its resolved path.
+function lockPathOf(omgbaseDir) {
+    let dir;
+    try {
+        dir = realpathSync.native(omgbaseDir);
+    }
+    catch {
+        dir = resolve(omgbaseDir);
+    }
+    return join(dir, LOCK_NAME);
+}
+// Process-wide defaults for the wait (spec/sync §7: 5 s, polled every 25 ms).
+// A host may override them for the whole process — the CLI's
+// `OMGBASE_WRITER_LOCK_TIMEOUT_MS` test seam does, so a verb's kernel-level lock
+// and `omg mcp`'s tool-boundary lock shorten together, like the Rust binary's.
+// Per-call `opts` still win.
+let defaults = { timeoutMs: 5000, pollMs: 25 };
+/** Override the process-wide wait defaults (a test seam; the poll never outlasts the timeout). */
+export function setWriterLockDefaults(opts) {
     const timeoutMs = opts.timeoutMs ?? 5000;
-    const pollMs = opts.pollMs ?? 25;
-    mkdirSync(omgbaseDir, { recursive: true });
-    const lockPath = join(omgbaseDir, LOCK_NAME);
+    defaults = { timeoutMs, pollMs: Math.min(opts.pollMs ?? 25, timeoutMs) };
+}
+/** The process-wide wait defaults in force. */
+export function writerLockDefaults() {
+    return { ...defaults };
+}
+function acquire(lockPath, opts) {
+    const timeoutMs = opts.timeoutMs ?? defaults.timeoutMs;
+    const pollMs = opts.pollMs ?? defaults.pollMs;
     const deadline = Date.now() + timeoutMs;
     while (!tryAcquire(lockPath)) {
         if (Date.now() >= deadline)
             throw new WriterLockTimeout(lockPath, readHolderPid(lockPath));
         sleepSync(pollMs);
     }
+}
+function release(lockPath) {
+    try {
+        if (existsSync(lockPath))
+            unlinkSync(lockPath);
+    }
+    catch {
+        /* best-effort release */
+    }
+}
+/** Enter the lock: acquire the file at depth 0, otherwise just deepen. */
+function enter(omgbaseDir, opts) {
+    mkdirSync(omgbaseDir, { recursive: true });
+    const lockPath = lockPathOf(omgbaseDir);
+    const depth = held.get(lockPath) ?? 0;
+    if (depth === 0)
+        acquire(lockPath, opts);
+    held.set(lockPath, depth + 1);
+    return lockPath;
+}
+/** Leave the lock: shallow, and release the file when the depth reaches 0. */
+function exit(lockPath) {
+    const depth = (held.get(lockPath) ?? 1) - 1;
+    if (depth > 0) {
+        held.set(lockPath, depth);
+        return;
+    }
+    held.delete(lockPath);
+    release(lockPath);
+}
+/**
+ * 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 function withWriterLock(omgbaseDir, fn, opts = {}) {
+    const lockPath = enter(omgbaseDir, opts);
     try {
         return fn();
     }
     finally {
-        try {
-            if (existsSync(lockPath))
-                unlinkSync(lockPath);
-        }
-        catch {
-            /* best-effort release */
-        }
+        exit(lockPath);
+    }
+}
+/**
+ * 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 async function withWriterLockAsync(omgbaseDir, fn, opts = {}) {
+    const lockPath = enter(omgbaseDir, opts);
+    try {
+        return await fn();
     }
+    finally {
+        exit(lockPath);
+    }
+}
+/** True while THIS process holds the lock (at any depth) — a test seam for "ran under the lock". */
+export function writerLockHeld(omgbaseDir) {
+    return (held.get(lockPathOf(omgbaseDir)) ?? 0) > 0;
 }
 /** True if no live writer holds the lock (probe without acquiring). */
 export function writerLockFree(omgbaseDir) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omgbase/core",
-  "version": "0.11.1",
+  "version": "0.15.0",
   "description": "Open Markdown Graph Base — embedded engine",
   "license": "MIT",
   "repository": {