@omgbase/core 0.1.0

package/dist/src/sync/driver.js

@@ -0,0 +1,80 @@
+import { mintId } from "../core/ids.js";
+import { ingestFile } from "../core/ingest.js";
+import { ensureRepo } from "../core/attach.js";
+import { makeReconcilingResolver } from "./reconciling-ingest.js";
+import { observeOne } from "./observe.js";
+import { sweepResurrectionPool } from "../core/store/gc.js";
+import { tombstoneObservedDeletion } from "./tombstone.js";
+/**
+ * Reconcile a batch of changed members against a repo as one checkpoint.
+ * `source.fetch(path)` supplies current bytes (or null = left the scope). The
+ * engine hashes the bytes itself: a hash equal to the stored file_hash is an
+ * echo (no commit); otherwise the member is ingested as an observed commit.
+ */
+export async function reconcileChanges(store, repoId, source, changes, opts = {}) {
+    const ts = opts.ts ?? new Date().toISOString();
+    const checkpointId = mintId("cp");
+    const ingested = [];
+    const suppressed = [];
+    const deleted = [];
+    const conflicted = [];
+    const fileEntries = [];
+    for (const change of changes) {
+        const item = await source.fetch(change.path);
+        if (item === null) {
+            // Member left the source scope (deleted/moved out): tombstone the live doc
+            // (drop FTS, tombstone blocks + doc, pool blocks) so it stops being served.
+            const existing = store.db
+                .prepare("SELECT doc_id, file_hash FROM docs WHERE repo_id = ? AND path = ? AND deleted_commit IS NULL")
+                .get(repoId, change.path);
+            if (existing) {
+                tombstoneObservedDeletion(store, repoId, existing.doc_id, ts);
+                deleted.push(change.path);
+            }
+            fileEntries.push([change.path, existing?.file_hash?.toString("hex") ?? null, null]);
+            continue;
+        }
+        // Reconcile the fetched bytes through the shared observe primitive — the one
+        // implementation of echo gate + identity threading + conflict flagging (D2).
+        // (v1 sources are identity-inferred; borne identity is deferred, ADR-010/D4.)
+        const r = observeOne(store, repoId, change.path, item.content, ts);
+        if (r.echo)
+            suppressed.push(change.path);
+        else if (r.conflicted)
+            conflicted.push(change.path);
+        else
+            ingested.push(change.path);
+        fileEntries.push([change.path, r.oldHashHex, r.newHashHex]);
+    }
+    store.db
+        .prepare("INSERT INTO checkpoints (id, repo_id, ts, files, git_head) VALUES (?, ?, ?, ?, ?)")
+        .run(checkpointId, repoId, ts, JSON.stringify(fileEntries), opts.gitHead ?? null);
+    sweepResurrectionPool(store, ts);
+    return { checkpointId, ingested, suppressed, deleted, conflicted };
+}
+/**
+ * Attach a source scope as a repo: create/reuse the repo row, then ingest every
+ * member the source enumerates (identity-inferred sources thread the reconciling
+ * resolver so edges + identity are established on the initial walk).
+ */
+export async function attachSource(store, slug, rootPath, source) {
+    const repoId = ensureRepo(store, slug, rootPath);
+    const inferred = source.capabilities().identity === "inferred";
+    const ts = new Date().toISOString();
+    let fileCount = 0;
+    let allConverged = true;
+    for (const entry of await source.enumerate()) {
+        const item = await source.fetch(entry.path);
+        if (!item)
+            continue;
+        const res = ingestFile(store, repoId, entry.path, item.content, {
+            ts,
+            ...(inferred ? { resolveIds: makeReconcilingResolver(store, repoId, { ts, path: entry.path }) } : {}),
+        });
+        fileCount++;
+        if (!res.converged)
+            allConverged = false;
+    }
+    return { repoId, fileCount, allConverged };
+}
+//# sourceMappingURL=driver.js.map

package/dist/src/sync/external-source.d.ts

@@ -0,0 +1,14 @@
+import type { SyncSource } from "./plugin.js";
+export interface ExternalSourceSpec {
+    /** Adapter command (argv[0]). */
+    command: string;
+    /** Rendered flags from the source config (13 §3.1). */
+    args: string[];
+    /** Extra environment (secrets; 13 §3.2). Merged over process.env. */
+    env?: Record<string, string>;
+}
+/**
+ * Spawn an adapter and connect it as a SyncSource. Throws on spawn/handshake
+ * failure. Callers MUST call close() to terminate the process.
+ */
+export declare function createExternalSource(spec: ExternalSourceSpec): Promise<SyncSource>;

package/dist/src/sync/external-source.js

@@ -0,0 +1,137 @@
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+/**
+ * Spawn an adapter and connect it as a SyncSource. Throws on spawn/handshake
+ * failure. Callers MUST call close() to terminate the process.
+ */
+export async function createExternalSource(spec) {
+    let child;
+    try {
+        child = spawn(spec.command, spec.args, {
+            stdio: ["pipe", "pipe", "inherit"],
+            env: { ...process.env, ...(spec.env ?? {}) },
+        });
+    }
+    catch (err) {
+        throw new Error(`sync adapter '${spec.command}' failed to spawn: ${err.message}`);
+    }
+    const rl = createInterface({ input: child.stdout });
+    let watchListener = null;
+    const router = messageRouter(rl, (paths) => watchListener?.(paths));
+    const died = new Promise((_, reject) => {
+        child.once("error", (err) => reject(new Error(`sync adapter '${spec.command}' failed to spawn: ${err.message}`)));
+        child.once("exit", (code) => reject(new Error(`sync adapter '${spec.command}' exited early (code ${code ?? "?"})`)));
+    });
+    // Handshake: the first line declares protocol + capabilities.
+    const handshakeRaw = await Promise.race([router.nextResponse(), died]);
+    let caps;
+    try {
+        const hs = JSON.parse(handshakeRaw);
+        const c = hs.capabilities ?? {};
+        caps = {
+            identity: c.identity === "borne" ? "borne" : "inferred",
+            writeThrough: Boolean(c.writeThrough),
+            watch: Boolean(c.watch),
+        };
+    }
+    catch {
+        throw new Error(`sync adapter '${spec.command}' sent an invalid handshake: ${handshakeRaw.slice(0, 120)}`);
+    }
+    let nextId = 1;
+    const call = async (method, params = {}) => {
+        const id = nextId++;
+        child.stdin.write(JSON.stringify({ id, method, params }) + "\n");
+        for (;;) {
+            const raw = await Promise.race([router.nextResponse(), died]);
+            const msg = JSON.parse(raw);
+            if (msg.id !== id)
+                continue; // response to another in-flight call
+            if (msg.error)
+                throw new Error(`sync adapter error (${method}): ${msg.error}`);
+            return msg.result;
+        }
+    };
+    const source = {
+        capabilities: () => caps,
+        async enumerate() {
+            const r = (await call("enumerate"));
+            return r.entries ?? [];
+        },
+        async fetch(path) {
+            const r = (await call("fetch", { path }));
+            return r.item ?? null;
+        },
+        ...(caps.watch
+            ? {
+                async watch(onBatch) {
+                    watchListener = onBatch;
+                    await call("watch");
+                    return {
+                        async stop() {
+                            watchListener = null;
+                            try {
+                                await call("unwatch");
+                            }
+                            catch {
+                                // process may already be exiting; ignore.
+                            }
+                        },
+                    };
+                },
+            }
+            : {}),
+        ...(caps.writeThrough
+            ? {
+                async write(path, content) {
+                    await call("write", { path, content });
+                },
+                async remove(path) {
+                    await call("remove", { path });
+                },
+            }
+            : {}),
+        async close() {
+            rl.close();
+            child.stdin.end();
+            if (!child.killed)
+                child.kill("SIGTERM");
+        },
+    };
+    return source;
+}
+// Demultiplex adapter stdout: {"event":"batch"} lines feed the watch listener;
+// every other line is an id-addressed response buffered for nextResponse().
+function messageRouter(rl, onBatch) {
+    const buffered = [];
+    const waiters = [];
+    rl.on("line", (line) => {
+        const trimmed = line.trim();
+        if (!trimmed)
+            return;
+        try {
+            const peek = JSON.parse(trimmed);
+            if (peek.event === "batch") {
+                onBatch(peek.paths ?? []);
+                return;
+            }
+        }
+        catch {
+            // Non-JSON on stdout is a protocol violation; surface it as a response so
+            // the awaiting call() rejects with a parse error rather than hanging.
+        }
+        const w = waiters.shift();
+        if (w)
+            w(trimmed);
+        else
+            buffered.push(trimmed);
+    });
+    return {
+        nextResponse() {
+            const b = buffered.shift();
+            if (b !== undefined)
+                return Promise.resolve(b);
+            return new Promise((resolve) => waiters.push(resolve));
+        },
+    };
+}
+//# sourceMappingURL=external-source.js.map

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

@@ -0,0 +1,42 @@
+import type { Store } from "../core/store/store.js";
+import { type CheckpointResult } from "./checkpoint.js";
+export interface SweepResult extends CheckpointResult {
+    scanned: number;
+    candidates: number;
+    changed: boolean;
+}
+/** Record/refresh a file's stat cache row. 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. Returns the checkpoint result plus scan
+ * counters. Idempotent; safe alongside a live watcher (hash-based echo
+ * suppression makes a double ingest a no-op).
+ */
+export declare function freshnessSweep(store: Store, repoId: string, rootPath: string): SweepResult;
+/**
+ * Counts of ways the DB disagrees with the current filesystem. All fields are
+ * "not yet reconciled" states a freshnessSweep/ingest would resolve.
+ */
+export interface DiskDrift {
+    /** non-deleted docs whose on-disk content hash != the doc's stored file_hash (drifted edits). */
+    changed: number;
+    /** non-deleted docs whose file is no longer on disk (deletes not yet ingested). */
+    deleted: number;
+    /** *.md files on disk with no corresponding non-deleted doc (new files not yet ingested). */
+    untracked: number;
+}
+/**
+ * READ-ONLY disk-drift detector. Mirrors freshnessSweep's staged cheap approach
+ * — stat-compare against file_stats first, hash only the stat-mismatched
+ * candidates — but never ingests, commits, or touches file_stats. It answers a
+ * single question: does the DB still agree with what's on disk right now?
+ *
+ * `changed` is decided by comparing a candidate's content hash to the doc's
+ * stored `file_hash` (the same sha256(bytes) checkpoint writes), so a stat
+ * change without a content change is NOT counted as drift. At the envelope
+ * (≤10⁴ docs) the clean case is a directory walk plus stats (tens of ms);
+ * hashing is bounded to files whose (mtime_ns, size) moved.
+ */
+export declare function detectDiskDrift(store: Store, repoId: string, rootPath: string): DiskDrift;
+/** Rebuild file_stats from scratch by re-statting + re-hashing every file. */
+export declare function rebuildFileStats(store: Store, repoId: string, rootPath: string): number;

package/dist/src/sync/freshness.js

@@ -0,0 +1,152 @@
+import { statSync, readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { sha256 } from "../core/hash.js";
+import { processCheckpoint } from "./checkpoint.js";
+import { walkMarkdown } from "./fs-util.js";
+/** Record/refresh a file's stat cache row. Call after any ingest of the file. */
+export function recordFileStat(store, repoId, path, abs, hash) {
+    if (!existsSync(abs)) {
+        store.db.prepare("DELETE FROM file_stats WHERE repo_id = ? AND path = ?").run(repoId, path);
+        return;
+    }
+    const st = statSync(abs, { bigint: true });
+    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.toString(), Number(st.size), hash);
+}
+/**
+ * Run the freshness sweep for a repo. Returns the checkpoint result plus scan
+ * counters. Idempotent; safe alongside a live watcher (hash-based echo
+ * suppression makes a double ingest a no-op).
+ */
+export function freshnessSweep(store, repoId, rootPath) {
+    const cache = new Map();
+    for (const row of store.db
+        .prepare("SELECT path, mtime_ns, size, hash FROM file_stats WHERE repo_id = ?")
+        .all(repoId)) {
+        cache.set(row.path, { mtime_ns: BigInt(row.mtime_ns), size: row.size, hash: row.hash });
+    }
+    const paths = walkMarkdown(rootPath);
+    const seen = new Set(paths);
+    // Candidates: files whose (mtime_ns, size) differs from cache, or are new.
+    const candidates = [];
+    const freshStats = new Map();
+    for (const path of paths) {
+        const st = statSync(join(rootPath, path), { bigint: true });
+        freshStats.set(path, { mtimeNs: st.mtimeNs, size: Number(st.size) });
+        const cached = cache.get(path);
+        if (!cached || cached.mtime_ns !== st.mtimeNs || cached.size !== Number(st.size)) {
+            candidates.push(path);
+        }
+    }
+    // Deletions: cached paths no longer on disk.
+    const deletedPaths = [...cache.keys()].filter((p) => !seen.has(p));
+    // Hash candidates; only those whose content hash actually differs from the
+    // cached hash need ingesting (mtime can change without content changing).
+    const changedPaths = [];
+    const candHashes = new Map();
+    for (const path of candidates) {
+        const hash = sha256(readFileSync(join(rootPath, path), "utf8"));
+        candHashes.set(path, hash);
+        const cached = cache.get(path);
+        if (!cached || !cached.hash.equals(hash))
+            changedPaths.push(path);
+        else {
+            // Content unchanged; refresh the stat cache so we don't re-hash next time.
+            const fs = freshStats.get(path);
+            store.db
+                .prepare("UPDATE file_stats SET mtime_ns = ?, size = ? WHERE repo_id = ? AND path = ?")
+                .run(fs.mtimeNs.toString(), fs.size, repoId, path);
+        }
+    }
+    const toIngest = [...changedPaths, ...deletedPaths];
+    const result = processCheckpoint(store, repoId, rootPath, toIngest.map((path) => ({ path })));
+    // Refresh stat cache for everything we touched (ingested or echo-suppressed).
+    for (const path of changedPaths) {
+        recordFileStat(store, repoId, path, join(rootPath, path), candHashes.get(path));
+    }
+    for (const path of deletedPaths) {
+        store.db.prepare("DELETE FROM file_stats WHERE repo_id = ? AND path = ?").run(repoId, path);
+    }
+    return {
+        ...result,
+        scanned: paths.length,
+        candidates: candidates.length,
+        changed: result.ingested.length > 0 || result.deleted.length > 0 || result.conflicted.length > 0,
+    };
+}
+/**
+ * READ-ONLY disk-drift detector. Mirrors freshnessSweep's staged cheap approach
+ * — stat-compare against file_stats first, hash only the stat-mismatched
+ * candidates — but never ingests, commits, or touches file_stats. It answers a
+ * single question: does the DB still agree with what's on disk right now?
+ *
+ * `changed` is decided by comparing a candidate's content hash to the doc's
+ * stored `file_hash` (the same sha256(bytes) checkpoint writes), so a stat
+ * change without a content change is NOT counted as drift. At the envelope
+ * (≤10⁴ docs) the clean case is a directory walk plus stats (tens of ms);
+ * hashing is bounded to files whose (mtime_ns, size) moved.
+ */
+export function detectDiskDrift(store, repoId, rootPath) {
+    // Stat cache keyed by path, for cheap change detection.
+    const cache = new Map();
+    for (const row of store.db
+        .prepare("SELECT path, mtime_ns, size, hash FROM file_stats WHERE repo_id = ?")
+        .all(repoId)) {
+        cache.set(row.path, { mtime_ns: BigInt(row.mtime_ns), size: row.size, hash: row.hash });
+    }
+    // Live docs keyed by path, with their durable file_hash (the convergence
+    // signal). This is the authority for changed/deleted/untracked, independent
+    // of the derived file_stats cache.
+    const docs = new Map();
+    for (const row of store.db
+        .prepare("SELECT path, file_hash FROM docs WHERE repo_id = ? AND deleted_commit IS NULL")
+        .all(repoId)) {
+        docs.set(row.path, row.file_hash);
+    }
+    const paths = walkMarkdown(rootPath);
+    const seen = new Set(paths);
+    // Candidates whose (mtime_ns, size) differs from the stat cache (or are new).
+    const candidates = [];
+    for (const path of paths) {
+        const st = statSync(join(rootPath, path), { bigint: true });
+        const cached = cache.get(path);
+        if (!cached || cached.mtime_ns !== st.mtimeNs || cached.size !== Number(st.size)) {
+            candidates.push(path);
+        }
+    }
+    let changed = 0;
+    let untracked = 0;
+    for (const path of candidates) {
+        const doc = docs.get(path);
+        if (doc === undefined) {
+            // No non-deleted doc for an on-disk *.md ⇒ untracked (new file).
+            untracked += 1;
+            continue;
+        }
+        const hash = sha256(readFileSync(join(rootPath, path), "utf8"));
+        // Genuinely drifted only if content hash differs from the doc's file_hash.
+        if (!doc || !doc.equals(hash))
+            changed += 1;
+    }
+    // A doc present in the DB whose path isn't on disk anymore is a pending delete.
+    let deleted = 0;
+    for (const path of docs.keys()) {
+        if (!seen.has(path))
+            deleted += 1;
+    }
+    return { changed, deleted, untracked };
+}
+/** Rebuild file_stats from scratch by re-statting + re-hashing every file. */
+export function rebuildFileStats(store, repoId, rootPath) {
+    store.db.prepare("DELETE FROM file_stats WHERE repo_id = ?").run(repoId);
+    const paths = walkMarkdown(rootPath);
+    for (const path of paths) {
+        const abs = join(rootPath, path);
+        const hash = sha256(readFileSync(abs, "utf8"));
+        recordFileStat(store, repoId, path, abs, hash);
+    }
+    return paths.length;
+}
+//# sourceMappingURL=freshness.js.map

package/dist/src/sync/fs-util.d.ts

@@ -0,0 +1,12 @@
+/** Walk `root` for *.md files, returning repo-relative canonical paths. */
+export declare function walkMarkdown(root: string): string[];
+/**
+ * Async variant of {@link walkMarkdown}: identical result, but yields to the
+ * event loop between directories and invokes `onFound(count)` as matches
+ * accumulate. This lets a caller drive a live progress counter (e.g. beside an
+ * interactive prompt) while the scan runs. `signal` lets the caller stop early
+ * once a decision has been made — the partial result is still returned.
+ */
+export declare function walkMarkdownAsync(root: string, onFound?: (count: number) => void, signal?: {
+    aborted: boolean;
+}): Promise<string[]>;

package/dist/src/sync/fs-util.js

@@ -0,0 +1,55 @@
+import { readdirSync, statSync } from "node:fs";
+import { readdir, stat } from "node:fs/promises";
+import { join, relative, sep } from "node:path";
+// Shared filesystem walk for the in-process one-shot/reconcile paths (attach,
+// checkpoint, freshness). This is NOT the live watcher — chokidar lives only in
+// the external @omgbase/fs-adapter (sync-plugins). node:fs (a builtin) reads
+// are retained here for the one-shot ingest/freshness fast-path.
+const IGNORED_DIRS = new Set([".omgbase", ".git", "node_modules"]);
+/** Walk `root` for *.md files, returning repo-relative canonical paths. */
+export function walkMarkdown(root) {
+    const out = [];
+    const recur = (dir) => {
+        for (const entry of readdirSync(dir)) {
+            if (IGNORED_DIRS.has(entry))
+                continue;
+            const full = join(dir, entry);
+            if (statSync(full).isDirectory())
+                recur(full);
+            else if (entry.endsWith(".md"))
+                out.push(relative(root, full).split(sep).join("/"));
+        }
+    };
+    recur(root);
+    return out;
+}
+/**
+ * Async variant of {@link walkMarkdown}: identical result, but yields to the
+ * event loop between directories and invokes `onFound(count)` as matches
+ * accumulate. This lets a caller drive a live progress counter (e.g. beside an
+ * interactive prompt) while the scan runs. `signal` lets the caller stop early
+ * once a decision has been made — the partial result is still returned.
+ */
+export async function walkMarkdownAsync(root, onFound, signal) {
+    const out = [];
+    const recur = async (dir) => {
+        if (signal?.aborted)
+            return;
+        for (const entry of await readdir(dir)) {
+            if (signal?.aborted)
+                return;
+            if (IGNORED_DIRS.has(entry))
+                continue;
+            const full = join(dir, entry);
+            if ((await stat(full)).isDirectory())
+                await recur(full);
+            else if (entry.endsWith(".md")) {
+                out.push(relative(root, full).split(sep).join("/"));
+                onFound?.(out.length);
+            }
+        }
+    };
+    await recur(root);
+    return out;
+}
+//# sourceMappingURL=fs-util.js.map

package/dist/src/sync/git-heuristics.d.ts

@@ -0,0 +1,6 @@
+export declare function hasConflictMarkers(content: string): boolean;
+export interface RenameCandidate {
+    docId: string;
+    fileHashHex: string;
+}
+export declare function detectRename(newFileHashHex: string, deletedCandidates: RenameCandidate[]): string | null;

package/dist/src/sync/git-heuristics.js

@@ -0,0 +1,16 @@
+// Git-related heuristics (01 §6, 07 task 7.1). Conflict-marker detection flags a
+// document `conflicted` (mutations refused until clean); whole-file hash match
+// against a deleted/moved document detects a rename. These are hints layered on
+// the checkpoint model — a checkout arrives as one large checkpoint that
+// hash-locking makes cheap.
+// Git conflict markers: <<<<<<< … ======= … >>>>>>> at line starts.
+export function hasConflictMarkers(content) {
+    // Require both an opening and a closing marker to avoid false positives on
+    // prose that happens to start a line with '======='.
+    return /^<{7}/m.test(content) && /^>{7}/m.test(content);
+}
+export function detectRename(newFileHashHex, deletedCandidates) {
+    const match = deletedCandidates.find((c) => c.fileHashHex === newFileHashHex);
+    return match ? match.docId : null;
+}
+//# sourceMappingURL=git-heuristics.js.map

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

@@ -0,0 +1,63 @@
+import type { Store } from "../core/store/store.js";
+export interface ObserveResult {
+    docId: string;
+    path: string;
+    /** null on an echo (bytes already matched the stored revision — no commit). */
+    rev: string | null;
+    commitId: string | null;
+    /** convergence: sha256(bytes) === the committed revision's rendered_hash. */
+    converged: boolean;
+    /** true when the bytes already matched the stored revision (no new commit). */
+    echo: boolean;
+    /** true when the bytes carry git conflict markers (doc flagged conflicted). */
+    conflicted: boolean;
+    /** disposition kind → count for the commit this observation produced. */
+    dispositions: {
+        kind: string;
+        count: number;
+    }[];
+}
+/** `observeOne` plus the change-tracking hashes batch callers need for their
+ *  checkpoint file-entries: the prior `file_hash` and the new bytes' hash. */
+export interface ObserveOneResult extends ObserveResult {
+    /** prior stored file_hash (hex), or null if the doc was new/absent. */
+    oldHashHex: string | null;
+    /** sha256(content) (hex) — the new file hash. */
+    newHashHex: string;
+}
+/**
+ * The reconcile primitive: echo-gate `content` for `path` and, when it differs
+ * from the stored revision, ingest it as an observed commit (reconciling block
+ * identity against the prior revision). Does NOT sweep the resurrection pool —
+ * the caller does that once per batch. Does NOT write a file.
+ */
+export declare function observeOne(store: Store, repoId: string, path: string, content: string, ts: string): ObserveOneResult;
+/** Observe one file's authoritative bytes as an observed commit (echo-suppressed). */
+export declare function observeFile(store: Store, repoId: string, path: string, content: string, opts?: {
+    ts?: string;
+}): ObserveResult;
+/** Observe a batch of files under one timestamp + one resurrection sweep. The
+ *  batch form of `observeFile`; each item is echo-gated independently. */
+export declare function observeMany(store: Store, repoId: string, items: {
+    path: string;
+    content: string;
+}[], opts?: {
+    ts?: string;
+}): ObserveResult[];
+export interface ObserveDeleteResult {
+    docId: string | null;
+    path: string;
+    /** true when a live doc existed at `path` and was tombstoned. */
+    deleted: boolean;
+}
+/**
+ * Observe that `path` left the source scope: tombstone the live doc as an
+ * OBSERVED deletion (blocks pooled for resurrection; no file removed — the file
+ * is already gone from the source). The deletion counterpart to `observeFile`,
+ * for a synchronizer mirroring an external delete. Idempotent: a path with no
+ * live doc is a no-op (`deleted:false`). Distinct from `docs_delete`, which is
+ * an api-origin, intentional, non-pooled removal that also unlinks the file.
+ */
+export declare function observeDelete(store: Store, repoId: string, path: string, opts?: {
+    ts?: string;
+}): ObserveDeleteResult;

package/dist/src/sync/observe.js

@@ -0,0 +1,84 @@
+import { sha256 } from "../core/hash.js";
+import { ingestFile } from "../core/ingest.js";
+import { makeReconcilingResolver } from "./reconciling-ingest.js";
+import { hasConflictMarkers } from "./git-heuristics.js";
+import { tombstoneObservedDeletion } from "./tombstone.js";
+import { sweepResurrectionPool } from "../core/store/gc.js";
+/**
+ * The reconcile primitive: echo-gate `content` for `path` and, when it differs
+ * from the stored revision, ingest it as an observed commit (reconciling block
+ * identity against the prior revision). Does NOT sweep the resurrection pool —
+ * the caller does that once per batch. Does NOT write a file.
+ */
+export function observeOne(store, repoId, path, content, ts) {
+    const existing = store.db
+        .prepare("SELECT doc_id, file_hash FROM docs WHERE repo_id = ? AND path = ? AND deleted_commit IS NULL")
+        .get(repoId, path);
+    const oldHashHex = existing?.file_hash?.toString("hex") ?? null;
+    const diskHash = sha256(content);
+    const newHashHex = diskHash.toString("hex");
+    // Echo: the stored revision already equals these bytes → no commit. The
+    // 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)) {
+        return { docId: existing.doc_id, path, rev: null, commitId: null, converged: true, echo: true, conflicted: false, dispositions: [], oldHashHex, newHashHex };
+    }
+    const conflicted = hasConflictMarkers(content);
+    const resolveIds = makeReconcilingResolver(store, repoId, { ts, path });
+    const res = ingestFile(store, repoId, path, content, { ts, origin: "observed", resolveIds });
+    store.db.prepare("UPDATE docs SET conflicted = ? WHERE repo_id = ? AND path = ?").run(conflicted ? 1 : 0, repoId, path);
+    const rows = store.db
+        .prepare("SELECT kind, count(*) n FROM dispositions WHERE commit_id = ? GROUP BY kind ORDER BY kind")
+        .all(res.commitId);
+    return {
+        docId: res.docId,
+        path,
+        rev: res.revId,
+        commitId: res.commitId,
+        converged: res.converged,
+        echo: false,
+        conflicted,
+        dispositions: rows.map((r) => ({ kind: r.kind, count: r.n })),
+        oldHashHex,
+        newHashHex,
+    };
+}
+function toPublic(r) {
+    const { oldHashHex: _o, newHashHex: _n, ...pub } = r;
+    return pub;
+}
+/** Observe one file's authoritative bytes as an observed commit (echo-suppressed). */
+export function observeFile(store, repoId, path, content, opts = {}) {
+    const ts = opts.ts ?? new Date().toISOString();
+    const r = observeOne(store, repoId, path, content, ts);
+    sweepResurrectionPool(store, ts);
+    return toPublic(r);
+}
+/** Observe a batch of files under one timestamp + one resurrection sweep. The
+ *  batch form of `observeFile`; each item is echo-gated independently. */
+export function observeMany(store, repoId, items, opts = {}) {
+    const ts = opts.ts ?? new Date().toISOString();
+    const out = items.map((it) => toPublic(observeOne(store, repoId, it.path, it.content, ts)));
+    sweepResurrectionPool(store, ts);
+    return out;
+}
+/**
+ * Observe that `path` left the source scope: tombstone the live doc as an
+ * OBSERVED deletion (blocks pooled for resurrection; no file removed — the file
+ * is already gone from the source). The deletion counterpart to `observeFile`,
+ * for a synchronizer mirroring an external delete. Idempotent: a path with no
+ * live doc is a no-op (`deleted:false`). Distinct from `docs_delete`, which is
+ * an api-origin, intentional, non-pooled removal that also unlinks the file.
+ */
+export function observeDelete(store, repoId, path, opts = {}) {
+    const ts = opts.ts ?? new Date().toISOString();
+    const existing = store.db
+        .prepare("SELECT doc_id FROM docs WHERE repo_id = ? AND path = ? AND deleted_commit IS NULL")
+        .get(repoId, path);
+    if (!existing)
+        return { docId: null, path, deleted: false };
+    tombstoneObservedDeletion(store, repoId, existing.doc_id, ts);
+    sweepResurrectionPool(store, ts);
+    return { docId: existing.doc_id, path, deleted: true };
+}
+//# sourceMappingURL=observe.js.map