@omgbase/core 0.1.0

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

@@ -0,0 +1,54 @@
+/** How a source's identity relates to omgbase block/doc identity (13 §5.2). */
+export type SourceIdentity = 
+/** Anonymous bytes; block continuity must be inferred by the reconciler. */
+"inferred"
+/** Stable per-member ids from upstream; the matcher is skipped (v1: unused). */
+ | "borne";
+export interface SourceCapabilities {
+    identity: SourceIdentity;
+    /** Can engine-authored mutations be pushed back to the source? */
+    writeThrough: boolean;
+    /** Can the source stream a change feed, or is it poll-only (engine re-enumerates)? */
+    watch: boolean;
+}
+/** A member of the source scope: its storage key + cheap change-token (13 §4.2). */
+export interface SourceEntry {
+    /** Storage key — repo-relative canonical path (docs.path). */
+    path: string;
+    /** The source's cheap change-token; equal ⇒ unchanged ⇒ engine no-op. */
+    revision: string;
+    /** Source locator when it differs from `path`. Defaults to `path` (13 §5.2). */
+    sourceId?: string;
+}
+/** A hydrated member: its entry plus the bytes handed to ingestFile. */
+export interface SourceItem extends SourceEntry {
+    /** The engine hashes this itself for the authoritative echo/convergence gate. */
+    content: string;
+}
+/** A batch of changed storage-keys delivered by a live watch (13 §4.3). */
+export type WatchListener = (paths: string[]) => void;
+/** A live subscription created by SyncSource.watch. */
+export interface SourceWatch {
+    /** Stop delivering batches and release resources. */
+    stop(): Promise<void>;
+}
+/**
+ * The in-engine handle to an external source process. Only capabilities/
+ * enumerate/fetch are always meaningful; watch exists when capabilities().watch,
+ * write/remove when capabilities().writeThrough. close() terminates the process.
+ */
+export interface SyncSource {
+    capabilities(): SourceCapabilities;
+    /** The full current scope as (path, revision) pairs. */
+    enumerate(): Promise<SourceEntry[]>;
+    /** Current state of one member, or null if it left the scope (a delete). */
+    fetch(path: string): Promise<SourceItem | null>;
+    /** Subscribe to debounced change batches (push sources). */
+    watch?(onBatch: WatchListener): Promise<SourceWatch>;
+    /** Persist engine-authored bytes back to the source (writeThrough only). */
+    write?(path: string, content: string): Promise<void>;
+    /** Remove a member from the source (writeThrough only). */
+    remove?(path: string): Promise<void>;
+    /** Terminate the underlying process / release resources. */
+    close(): Promise<void>;
+}

package/dist/src/sync/plugin.js

@@ -0,0 +1,12 @@
+// Sync source contract (sync-plugins). A SyncSource abstracts an external
+// source scope (filesystem, git, GitHub, Linear, …) behind enumerate/fetch/watch
+// keyed on a cheap `revision` change-token. Sources are EXTERNAL PROCESSES spoken
+// to over stdio (see external-source.ts); this interface is the in-engine view of
+// one. Because every call crosses a pipe, the contract is async.
+//
+// The engine owns everything below the bytes — content-hash echo suppression,
+// reconciliation, commits, convergence, and durable revision/cursor state — so a
+// source only reports membership and transports bytes; it can never write a
+// commit, mint identity, or bypass the convergence check.
+export {};
+//# sourceMappingURL=plugin.js.map

package/dist/src/sync/reconciling-ingest.d.ts

@@ -0,0 +1,12 @@
+import type { Database } from "better-sqlite3";
+import type { Store } from "../core/store/store.js";
+import type { IdResolver } from "../core/ingest.js";
+import { type MatchBlock, type ReconcileConfig } from "../reconcile/types.js";
+export declare function loadOldMatchBlocks(db: Database, docId: string): MatchBlock[];
+/** Build an IdResolver bound to this store + repo, reconciling against the
+ * document's current revision. */
+export declare function makeReconcilingResolver(store: Store, repoId: string, opts?: {
+    ts?: string;
+    config?: ReconcileConfig;
+    path?: string;
+}): IdResolver;

package/dist/src/sync/reconciling-ingest.js

@@ -0,0 +1,209 @@
+import { mintId } from "../core/ids.js";
+import { extractFromBlock, extractFromFrontmatter, resolveRelativePath } from "../graph/extract.js";
+import { resolveExternal, resolveDocPath } from "../core/store/edges.js";
+import { sha256, normalizeVisibleText } from "../core/hash.js";
+import { reconcileDocument } from "../reconcile/reconcile.js";
+import { flatten } from "../reconcile/flatten.js";
+import { DEFAULT_CONFIG } from "../reconcile/types.js";
+import { adapterForPath } from "../format/index.js";
+// Rebuild the old tree as positional MatchBlocks straight from stored blocks +
+// blob bytes (so text/hashes match what reconcile expects). Exported so the
+// whole-document update planner (mutate/plan-update.ts) reconciles against the
+// same old-tree representation the observation path uses.
+export function loadOldMatchBlocks(db, docId) {
+    const rows = db
+        .prepare(`SELECT block_id, parent_block, ordinal, type, raw_hash
+       FROM blocks WHERE doc_id = ? AND deleted_commit IS NULL
+       ORDER BY parent_block, ordinal`)
+        .all(docId);
+    // Build positional keys mirroring the flatten() convention. We need parent's
+    // key, so process in a way that resolves parents first (top-level then down).
+    const byId = new Map();
+    for (const r of rows)
+        byId.set(r.block_id, r);
+    // Compute a positional key per block: parentKey + '/' + ordinal.
+    const keyOf = new Map();
+    const parentKeyOf = new Map();
+    const resolveKey = (r) => {
+        if (keyOf.has(r.block_id))
+            return keyOf.get(r.block_id);
+        let parentKey = null;
+        if (r.parent_block && byId.has(r.parent_block))
+            parentKey = resolveKey(byId.get(r.parent_block));
+        const key = `${parentKey ?? ""}/${r.ordinal}`;
+        keyOf.set(r.block_id, key);
+        parentKeyOf.set(r.block_id, parentKey);
+        return key;
+    };
+    const blobBytes = db.prepare("SELECT bytes FROM blobs WHERE hash = ?");
+    return rows.map((r) => {
+        const key = resolveKey(r);
+        const raw = blobBytes.get(r.raw_hash)?.bytes.toString("utf8") ?? "";
+        const text = normalizeVisibleText(raw, r.type);
+        return {
+            blockId: r.block_id,
+            type: r.type,
+            rawHashHex: r.raw_hash.toString("hex"),
+            normHashHex: sha256(text).toString("hex"),
+            text,
+            anchors: [],
+            parentKey: parentKeyOf.get(r.block_id) ?? null,
+            index: r.ordinal,
+            key,
+        };
+    });
+}
+function loadPool(db, repoId, ts) {
+    const rows = db
+        .prepare("SELECT block_id, raw_hash, norm_hash, type FROM resurrection_pool WHERE repo_id = ? AND expires_ts > ?")
+        .all(repoId, ts);
+    return rows.map((r) => ({
+        blockId: r.block_id,
+        rawHashHex: r.raw_hash.toString("hex"),
+        normHashHex: r.norm_hash.toString("hex"),
+        type: r.type,
+    }));
+}
+// Assign ids from a reconcile assignment (new key → id) onto a fresh
+// TreeInputBlock tree, minting for keys the assignment missed.
+function assignFromMap(blocks, assignment) {
+    const walk = (list, parentKey) => list.map((b, index) => {
+        const key = `${parentKey ?? ""}/${index}`;
+        const blockId = assignment.get(key) ?? mintId("b");
+        return { blockId, type: b.type, raw: b.raw, trivia: b.trivia, attrs: b.attrs, children: walk(b.children, key) };
+    });
+    return walk(blocks, null);
+}
+/** Build an IdResolver bound to this store + repo, reconciling against the
+ * document's current revision. */
+export function makeReconcilingResolver(store, repoId, opts = {}) {
+    const ts = opts.ts ?? new Date().toISOString();
+    const config = opts.config ?? DEFAULT_CONFIG;
+    const adapter = opts.path ? adapterForPath(opts.path) : undefined;
+    const docDir = opts.path ? opts.path.replace(/[^/]*$/, "") : "";
+    return (rest, docId) => {
+        const db = store.db;
+        const oldBlocks = docId ? loadOldMatchBlocks(db, docId) : [];
+        const newBlocks = flatten(rest.map(toFlatSource));
+        const pool = docId ? loadPool(db, repoId, ts) : [];
+        const result = reconcileDocument(oldBlocks, newBlocks, { config, pool });
+        const assigned = assignFromMap(rest, result.assignment);
+        const dispositions = result.dispositions.map((d) => ({
+            blockId: d.blockId,
+            kind: d.kind,
+            confidence: d.confidence,
+            reason: d.reason,
+            matcherV: d.matcherV,
+            detail: d.detail,
+        }));
+        // Edge extraction: adapter-aware. For formats with extractEdges(), use the
+        // adapter; otherwise fall back to markdown's per-block link scanner.
+        const extractEdges = (thisDocId, metadata) => {
+            const out = [];
+            if (adapter?.extractEdges) {
+                const rawBlocks = collectRawBlocks(assigned);
+                const adapterEdges = adapter.extractEdges(rawBlocks, metadata);
+                for (const e of adapterEdges) {
+                    out.push(resolveAdapterEdge(db, repoId, thisDocId, e, docDir));
+                }
+            }
+            else {
+                // Markdown fallback: per-block link scanning + frontmatter relations.
+                const walk = (blocks) => {
+                    for (const b of blocks) {
+                        for (const e of extractFromBlock(b.blockId, b.type, b.raw)) {
+                            out.push(resolveEdge(db, repoId, thisDocId, e));
+                        }
+                        if (b.children.length > 0)
+                            walk(b.children);
+                    }
+                };
+                walk(assigned);
+                for (const e of extractFromFrontmatter(metadata))
+                    out.push(resolveEdge(db, repoId, thisDocId, e));
+            }
+            return out;
+        };
+        return { assigned, dispositions, deleted: result.deleted, consumedPool: result.consumedPool, extractEdges };
+    };
+}
+// Resolve an extracted edge's target to a node id (external mint, doc path or
+// phantom). Block-anchor targets resolve to a document node in v1 (block-ref
+// resolution requires the anchor index; the anchor is preserved on the edge).
+function resolveEdge(db, repoId, srcDoc, e) {
+    let dstNode;
+    let dstKind = e.dstKind;
+    if (e.dstKind === "external") {
+        dstNode = resolveExternal(db, repoId, e.target);
+    }
+    else if (e.target === "") {
+        // pure fragment (#H / ^ref) → self document
+        dstNode = srcDoc;
+        dstKind = "document";
+    }
+    else {
+        const resolved = resolveDocPath(db, repoId, e.target);
+        dstNode = resolved.id;
+        dstKind = "document";
+    }
+    return {
+        srcDoc,
+        srcBlock: e.srcBlock,
+        srcField: e.srcField,
+        predicate: e.predicate,
+        dstKind,
+        dstNode,
+        anchor: e.anchor,
+        provenance: e.provenance,
+    };
+}
+// resolveRelativePath (./foo, ../bar against the source doc's directory) lives
+// in graph/extract.ts so docs_move's inbound-link scan resolves identically.
+// Resolve an adapter-produced edge to a ResolvedEdgeRow. Same resolution
+// logic as resolveEdge but accepts the AdapterEdge shape, with relative path
+// resolution against the source document's directory.
+function resolveAdapterEdge(db, repoId, srcDoc, e, docDir) {
+    let dstNode;
+    let dstKind = e.dstKind;
+    if (e.dstKind === "external") {
+        dstNode = resolveExternal(db, repoId, e.target);
+    }
+    else if (e.target === "") {
+        dstNode = srcDoc;
+        dstKind = "document";
+    }
+    else {
+        const resolved = resolveDocPath(db, repoId, resolveRelativePath(e.target, docDir));
+        dstNode = resolved.id;
+        dstKind = "document";
+    }
+    return {
+        srcDoc,
+        srcBlock: e.srcBlock,
+        srcField: e.srcField,
+        predicate: e.predicate,
+        dstKind,
+        dstNode,
+        anchor: e.anchor,
+        provenance: e.provenance,
+    };
+}
+// Collect RawBlock-shaped objects from the id-assigned tree for adapter edge extraction.
+function collectRawBlocks(blocks) {
+    return blocks.map((b) => ({
+        type: b.type,
+        span: { start: 0, end: 0 },
+        raw: b.raw,
+        text: "",
+        attrs: b.attrs,
+        children: collectRawBlocks(b.children),
+        trivia: b.trivia,
+        anchors: [],
+        outLinks: [],
+        blockId: b.blockId, // thread the assigned id so extractEdges can set src_block
+    }));
+}
+function toFlatSource(b) {
+    return { type: b.type, raw: b.raw, children: b.children.map(toFlatSource) };
+}
+//# sourceMappingURL=reconciling-ingest.js.map

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

@@ -0,0 +1,6 @@
+import type { Store } from "../core/store/store.js";
+export interface RecoveryResult {
+    healed: string[];
+    missing: string[];
+}
+export declare function recoverRepo(store: Store, repoId: string, rootPath: string): RecoveryResult;

package/dist/src/sync/recovery.js

@@ -0,0 +1,34 @@
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { sha256 } from "../core/hash.js";
+import { ingestFile } from "../core/ingest.js";
+import { makeReconcilingResolver } from "./reconciling-ingest.js";
+export function recoverRepo(store, repoId, 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
+       WHERE d.repo_id = ? AND d.deleted_commit IS NULL`)
+        .all(repoId);
+    const healed = [];
+    const missing = [];
+    const ts = new Date().toISOString();
+    for (const doc of docs) {
+        const abs = join(rootPath, doc.path);
+        if (!existsSync(abs)) {
+            missing.push(doc.path);
+            continue;
+        }
+        const onDisk = sha256(readFileSync(abs, "utf8"));
+        const recorded = doc.rendered_hash ?? doc.file_hash;
+        if (!recorded || !onDisk.equals(recorded)) {
+            // Divergence: the file moved ahead of (or behind) the store. Re-ingest.
+            ingestFile(store, repoId, doc.path, readFileSync(abs, "utf8"), {
+                ts,
+                resolveIds: makeReconcilingResolver(store, repoId, { ts, path: doc.path }),
+            });
+            healed.push(doc.path);
+        }
+    }
+    return { healed, missing };
+}
+//# sourceMappingURL=recovery.js.map

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

@@ -0,0 +1,18 @@
+import type { Store } from "../core/store/store.js";
+export type Settings = Record<string, unknown>;
+/** The workspace default settings blob (the layer repos inherit from). */
+export declare function workspaceSettings(store: Store): Settings;
+/** A single repo's own (override) settings blob — NOT merged with defaults. */
+export declare function repoOwnSettings(store: Store, repoId: string): Settings;
+export declare function writeWorkspaceSettings(store: Store, settings: Settings): void;
+export declare function writeRepoSettings(store: Store, repoId: string, settings: Settings): void;
+/** Deep-merge: `over` wins at the leaf; nested plain objects merge recursively,
+ *  everything else (scalars, arrays) replaces wholesale. */
+export declare function deepMerge(base: Settings, over: Settings): Settings;
+/**
+ * The effective settings a repo sees: workspace defaults with the repo's own
+ * settings deep-merged on top. Every settings consumer should read through this
+ * so the workspace-default/repo-override rule holds uniformly. Pass repoId=null
+ * (e.g. a sourceless workspace-scoped read) to get the defaults alone.
+ */
+export declare function resolveSettings(store: Store, repoId: string | null): Settings;

package/dist/src/sync/settings.js

@@ -0,0 +1,58 @@
+function parse(json) {
+    if (!json)
+        return {};
+    try {
+        const v = JSON.parse(json);
+        return v && typeof v === "object" ? v : {};
+    }
+    catch {
+        return {};
+    }
+}
+/** The workspace default settings blob (the layer repos inherit from). */
+export function workspaceSettings(store) {
+    const row = store.db.prepare("SELECT settings FROM workspace_settings WHERE id = 0").get();
+    return parse(row?.settings);
+}
+/** A single repo's own (override) settings blob — NOT merged with defaults. */
+export function repoOwnSettings(store, repoId) {
+    const row = store.db.prepare("SELECT settings FROM repos WHERE repo_id = ?").get(repoId);
+    return parse(row?.settings);
+}
+export function writeWorkspaceSettings(store, settings) {
+    store.db
+        .prepare("INSERT INTO workspace_settings (id, settings) VALUES (0, ?) ON CONFLICT(id) DO UPDATE SET settings = excluded.settings")
+        .run(JSON.stringify(settings));
+}
+export function writeRepoSettings(store, repoId, settings) {
+    store.db.prepare("UPDATE repos SET settings = ? WHERE repo_id = ?").run(JSON.stringify(settings), repoId);
+}
+/** Deep-merge: `over` wins at the leaf; nested plain objects merge recursively,
+ *  everything else (scalars, arrays) replaces wholesale. */
+export function deepMerge(base, over) {
+    const out = { ...base };
+    for (const [k, v] of Object.entries(over)) {
+        const b = out[k];
+        if (isPlainObject(b) && isPlainObject(v))
+            out[k] = deepMerge(b, v);
+        else
+            out[k] = v;
+    }
+    return out;
+}
+function isPlainObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/**
+ * The effective settings a repo sees: workspace defaults with the repo's own
+ * settings deep-merged on top. Every settings consumer should read through this
+ * so the workspace-default/repo-override rule holds uniformly. Pass repoId=null
+ * (e.g. a sourceless workspace-scoped read) to get the defaults alone.
+ */
+export function resolveSettings(store, repoId) {
+    const defaults = workspaceSettings(store);
+    if (!repoId)
+        return defaults;
+    return deepMerge(defaults, repoOwnSettings(store, repoId));
+}
+//# sourceMappingURL=settings.js.map

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

@@ -0,0 +1,37 @@
+import type { Store } from "../core/store/store.js";
+export interface AdapterRow {
+    name: string;
+    command: string;
+    args: string[];
+}
+export interface SourceRow {
+    sourceId: string;
+    name: string;
+    adapter: string;
+    config: Record<string, unknown>;
+    env: Record<string, string>;
+}
+/** Register (or update) a named adapter → external command. Idempotent. */
+export declare function ensureAdapter(store: Store, name: string, command: string, args?: string[]): void;
+export declare function listAdapters(store: Store): AdapterRow[];
+/** Create a named source over an adapter. Throws if `name` is taken or the
+ *  adapter does not exist (FK enforced). Returns the minted source id. */
+export declare function createSource(store: Store, spec: {
+    name: string;
+    adapter: string;
+    config?: Record<string, unknown>;
+    env?: Record<string, string>;
+}): string;
+export declare function deleteSource(store: Store, sourceId: string): void;
+export declare function listSources(store: Store): SourceRow[];
+export declare function getSourceByName(store: Store, name: string): SourceRow | null;
+/** Attach a source to a repo (m:n). Idempotent. */
+export declare function attachSourceToRepo(store: Store, repoId: string, sourceId: string): void;
+export declare function detachSourceFromRepo(store: Store, repoId: string, sourceId: string): void;
+/** The sources attached to a repo (ordered by source name). */
+export declare function sourcesForRepo(store: Store, repoId: string): SourceRow[];
+/** Render a source's structured config into adapter argv flags: each own key
+ *  becomes `--key value` (booleans render as a bare `--key` when true, omitted
+ *  when false). The declarative config→argv mapping reserved in sync-plugins
+ *  §3.1; the fs adapter consumes `{ root }` → `--root <root>`. */
+export declare function renderConfigFlags(config: Record<string, unknown>): string[];

package/dist/src/sync/sources.js

@@ -0,0 +1,75 @@
+import { mintId } from "../core/ids.js";
+/** Register (or update) a named adapter → external command. Idempotent. */
+export function ensureAdapter(store, name, command, args = []) {
+    store.db
+        .prepare(`INSERT INTO adapters (name, command, args) VALUES (?, ?, ?)
+       ON CONFLICT(name) DO UPDATE SET command = excluded.command, args = excluded.args`)
+        .run(name, command, JSON.stringify(args));
+}
+export function listAdapters(store) {
+    return store.db.prepare("SELECT name, command, args FROM adapters ORDER BY name").all().map((r) => ({ name: r.name, command: r.command, args: JSON.parse(r.args) }));
+}
+/** Create a named source over an adapter. Throws if `name` is taken or the
+ *  adapter does not exist (FK enforced). Returns the minted source id. */
+export function createSource(store, spec) {
+    const sourceId = mintId("src");
+    store.db
+        .prepare("INSERT INTO sources (source_id, name, adapter, config, env) VALUES (?, ?, ?, ?, ?)")
+        .run(sourceId, spec.name, spec.adapter, JSON.stringify(spec.config ?? {}), JSON.stringify(spec.env ?? {}));
+    return sourceId;
+}
+export function deleteSource(store, sourceId) {
+    store.db.prepare("DELETE FROM attachments WHERE source_id = ?").run(sourceId);
+    store.db.prepare("DELETE FROM sync_state WHERE source_id = ?").run(sourceId);
+    store.db.prepare("DELETE FROM sources WHERE source_id = ?").run(sourceId);
+}
+function rowToSource(r) {
+    return {
+        sourceId: r.source_id,
+        name: r.name,
+        adapter: r.adapter,
+        config: JSON.parse(r.config),
+        env: JSON.parse(r.env),
+    };
+}
+export function listSources(store) {
+    return store.db.prepare("SELECT source_id, name, adapter, config, env FROM sources ORDER BY name").all().map(rowToSource);
+}
+export function getSourceByName(store, name) {
+    const r = store.db.prepare("SELECT source_id, name, adapter, config, env FROM sources WHERE name = ?").get(name);
+    return r ? rowToSource(r) : null;
+}
+/** Attach a source to a repo (m:n). Idempotent. */
+export function attachSourceToRepo(store, repoId, sourceId) {
+    store.db.prepare("INSERT OR IGNORE INTO attachments (repo_id, source_id) VALUES (?, ?)").run(repoId, sourceId);
+}
+export function detachSourceFromRepo(store, repoId, sourceId) {
+    store.db.prepare("DELETE FROM attachments WHERE repo_id = ? AND source_id = ?").run(repoId, sourceId);
+}
+/** The sources attached to a repo (ordered by source name). */
+export function sourcesForRepo(store, repoId) {
+    return store.db
+        .prepare(`SELECT s.source_id, s.name, s.adapter, s.config, s.env
+         FROM sources s JOIN attachments a ON a.source_id = s.source_id
+         WHERE a.repo_id = ? ORDER BY s.name`)
+        .all(repoId).map(rowToSource);
+}
+/** Render a source's structured config into adapter argv flags: each own key
+ *  becomes `--key value` (booleans render as a bare `--key` when true, omitted
+ *  when false). The declarative config→argv mapping reserved in sync-plugins
+ *  §3.1; the fs adapter consumes `{ root }` → `--root <root>`. */
+export function renderConfigFlags(config) {
+    const out = [];
+    for (const [key, value] of Object.entries(config)) {
+        if (value === undefined || value === null)
+            continue;
+        if (typeof value === "boolean") {
+            if (value)
+                out.push(`--${key}`);
+            continue;
+        }
+        out.push(`--${key}`, String(value));
+    }
+    return out;
+}
+//# sourceMappingURL=sources.js.map

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

@@ -0,0 +1,9 @@
+import type { Store } from "../core/store/store.js";
+/**
+ * Tombstone a doc the engine observed as gone from its source (deleted on disk /
+ * left the scope). Pools the doc's live blocks for later resurrection, then drops
+ * FTS rows and tombstones the blocks + the doc with an "observed"-origin commit.
+ * Returns the minted commit id. Idempotent-safe: if the doc has no live blocks the
+ * UPDATEs simply affect zero rows.
+ */
+export declare function tombstoneObservedDeletion(store: Store, repoId: string, docId: string, ts: string): string;

package/dist/src/sync/tombstone.js

@@ -0,0 +1,55 @@
+import { newCommit } from "../core/store/writers.js";
+import { ftsDeleteDoc } from "../core/store/fts.js";
+// Observed-deletion tombstone (01 §6, 02 §3/§7). Shared by BOTH observed-change
+// paths — the synchronous filesystem fast-path (checkpoint.ts::processCheckpoint,
+// used by the freshness sweep / one-shot / recovery) and the async SyncSource
+// path (driver.ts::reconcileChanges, used by the live watcher). Factored into ONE
+// helper so the two loops cannot drift apart: a file that leaves the source scope
+// (existsSync false / source.fetch → null) MUST tombstone the doc, not linger as a
+// live, queryable, FTS-indexed ghost.
+//
+// This mirrors the DB effects of the API delete path (mutate/docs.ts::docsDelete)
+// — mint a commit, drop FTS rows, tombstone the doc's live blocks + the doc row —
+// with two deliberate differences:
+//   1. origin is "observed", not "api": the engine witnessed the disk change; it
+//      did not author it (writers.ts NewCommitInput.origin; ingestFile defaults to
+//      "observed"). No actor.
+//   2. the live blocks are snapshotted into the resurrection_pool BEFORE they are
+//      tombstoned. An API delete is an intentional, permanent removal, so
+//      docsDelete pools nothing. An observed disk deletion is the opposite: a file
+//      vanishing is overwhelmingly a move/rename/transient (editor swap, git
+//      checkout), which is exactly the delete→recreate case the pool exists for
+//      (core/ingest.ts snapshots deleted blocks the same way; makeReconcilingResolver
+//      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
+// is ALREADY gone (that is what triggered the tombstone).
+/**
+ * Tombstone a doc the engine observed as gone from its source (deleted on disk /
+ * left the scope). Pools the doc's live blocks for later resurrection, then drops
+ * FTS rows and tombstones the blocks + the doc with an "observed"-origin commit.
+ * Returns the minted commit id. Idempotent-safe: if the doc has no live blocks the
+ * 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;
+}
+//# sourceMappingURL=tombstone.js.map

package/dist/src/sync/watch-lease.d.ts

@@ -0,0 +1,14 @@
+/** True if a live watcher currently holds the lease. */
+export declare function watchLeaseLive(omgbaseDir: string): boolean;
+export declare class WatchLease {
+    private held;
+    private readonly leasePath;
+    private constructor();
+    /**
+     * Try to take the lease. Returns a held lease, or null if a live watcher
+     * already holds it. A lease whose holder pid is dead is stolen.
+     */
+    static tryAcquire(omgbaseDir: string): WatchLease | null;
+    private take;
+    release(): void;
+}