@tyroneross/navgator 0.2.2 → 0.10.0

package/dist/freshness/dirty-ledger.js

@@ -0,0 +1,310 @@
+/**
+ * Concurrency-safe dirty ledger.
+ *
+ * Every mutation is an immutable, uniquely named event under `dirty.d/`.
+ * A scan captures exact event filenames and clears only those files after it
+ * finishes. Late writes — including another edit to the same path — land in a
+ * different event and therefore cannot be erased by snapshot reconciliation.
+ * `dirty.json` remains a read/migrate compatibility surface for older installs.
+ */
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { acquireScanLease } from '../scan-lock.js';
+import { dirtyEventsPath, dirtyLedgerPath, dirtyMutationLockPath, stampPath, } from './paths.js';
+function normalizedPaths(paths) {
+    return [...new Set(paths.map((value) => value.trim()).filter(Boolean))].sort();
+}
+function readEvent(filePath) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+        if (parsed.version === 2 && Array.isArray(parsed.paths)) {
+            return {
+                version: 2,
+                paths: normalizedPaths(parsed.paths),
+                created_at: typeof parsed.created_at === 'number' ? parsed.created_at : 0,
+            };
+        }
+    }
+    catch {
+        // A corrupt event is ignored; it never causes valid sibling events to reset.
+    }
+    return null;
+}
+function writeEvent(paths, root) {
+    const values = normalizedPaths(paths);
+    if (values.length === 0)
+        return;
+    const dir = dirtyEventsPath(root);
+    fs.mkdirSync(dir, { recursive: true });
+    const id = `${Date.now()}-${process.pid}-${crypto.randomUUID()}`;
+    const candidate = path.join(dir, `.${id}.tmp`);
+    const target = path.join(dir, `${id}.json`);
+    const payload = { version: 2, paths: values, created_at: Date.now() };
+    try {
+        fs.writeFileSync(candidate, JSON.stringify(payload), { flag: 'wx' });
+        fs.renameSync(candidate, target);
+    }
+    finally {
+        try {
+            fs.unlinkSync(candidate);
+        }
+        catch { /* renamed or best effort */ }
+    }
+}
+function readLegacyFile(filePath, afterRead) {
+    let fd;
+    try {
+        // The bytes and identity must come from the same descriptor. Reading the
+        // pathname and then statting it can pair old bytes with a concurrently
+        // replaced inode, causing the replacement to be cleared as the snapshot.
+        fd = fs.openSync(filePath, 'r');
+        const parsed = JSON.parse(fs.readFileSync(fd, 'utf8'));
+        afterRead?.();
+        if (parsed.version !== 1 || !Array.isArray(parsed.paths))
+            return { paths: [] };
+        const stat = fs.fstatSync(fd, { bigint: true });
+        return {
+            paths: normalizedPaths(parsed.paths),
+            fingerprint: `${stat.dev}:${stat.ino}:${stat.mtimeNs}:${stat.size}`,
+        };
+    }
+    catch {
+        return { paths: [] };
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                fs.closeSync(fd);
+            }
+            catch { /* best effort */ }
+        }
+    }
+}
+function readLegacy(root, afterRead) {
+    return readLegacyFile(dirtyLedgerPath(root), afterRead);
+}
+function sleepSync(ms) {
+    if (ms <= 0)
+        return;
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+/**
+ * Serialize event mutations with publication of a clean freshness stamp.
+ * Actions are deliberately synchronous so a same-process callback cannot run
+ * while the mutex is held and deadlock attempting a nested mutation.
+ */
+export function withDirtyLedgerMutationLock(root, action) {
+    const lockPath = dirtyMutationLockPath(root);
+    const deadline = Date.now() + 5000;
+    while (true) {
+        const acquired = acquireScanLease(lockPath, 'dirty-ledger-mutation', {
+            startHeartbeat: false,
+            gateWaitMs: Math.max(1, deadline - Date.now()),
+        });
+        if (acquired.ok) {
+            try {
+                return action();
+            }
+            finally {
+                acquired.lease.release();
+            }
+        }
+        if (!acquired.retryable || Date.now() >= deadline) {
+            throw new Error(`Could not acquire dirty-ledger mutation lock: ${acquired.message}`);
+        }
+        sleepSync(2);
+    }
+}
+function tryWithDirtyLedgerMutationLock(root, action) {
+    const acquired = acquireScanLease(dirtyMutationLockPath(root), 'dirty-stamp-refresh', {
+        startHeartbeat: false,
+        gateWaitMs: 50,
+    });
+    if (!acquired.ok)
+        return false;
+    try {
+        action();
+        return true;
+    }
+    finally {
+        acquired.lease.release();
+    }
+}
+function refreshStampAfterDirtyMutation(root, hooks = {}) {
+    const target = stampPath(root);
+    let current;
+    try {
+        current = JSON.parse(fs.readFileSync(target, 'utf8'));
+        if (current['version'] !== 1)
+            return;
+    }
+    catch {
+        // Missing/corrupt stamps are already non-authoritative. The freshness
+        // command will synthesize a dirty view directly from the ledger.
+        return;
+    }
+    const dirty = captureDirtySnapshot(root).paths;
+    const candidate = `${target}.tmp.${process.pid}.${crypto.randomUUID()}`;
+    try {
+        fs.writeFileSync(candidate, JSON.stringify({
+            ...current,
+            dirty_files: dirty,
+            dirty_count: dirty.length,
+        }, null, 2), 'utf8');
+        hooks.beforeStampRename?.();
+        fs.renameSync(candidate, target);
+    }
+    finally {
+        try {
+            fs.unlinkSync(candidate);
+        }
+        catch { /* renamed or best effort */ }
+    }
+}
+/** Capture an immutable event set; later events are excluded by filename. */
+export function captureDirtySnapshot(root, hooks = {}) {
+    const legacy = readLegacy(root, hooks.afterLegacyRead);
+    const dir = dirtyEventsPath(root);
+    let files = [];
+    try {
+        files = fs.readdirSync(dir).filter((file) => file.endsWith('.json')).sort();
+    }
+    catch {
+        // No event directory yet.
+    }
+    hooks.afterEventList?.();
+    const events = [];
+    for (const file of files) {
+        const event = readEvent(path.join(dir, file));
+        if (event)
+            events.push({ file, paths: event.paths });
+    }
+    return {
+        paths: normalizedPaths([
+            ...legacy.paths,
+            ...events.flatMap((event) => event.paths),
+        ]),
+        events,
+        legacyFingerprint: legacy.fingerprint,
+        legacyPaths: legacy.paths,
+    };
+}
+/** Append one immutable event. Concurrent writers never share a temp path. */
+export function markDirty(paths, root, hooks = {}) {
+    if (normalizedPaths(paths).length === 0)
+        return;
+    // The immutable event is the canonical commit and intentionally takes no
+    // global mutex: editor hooks must remain lossless under high fanout. Stamp
+    // refresh is advisory/best-effort; freshness readers overlay this ledger so
+    // a crash or permission error after the event cannot hide dirty work.
+    writeEvent(paths, root);
+    if (!fs.existsSync(stampPath(root)))
+        return;
+    try {
+        // A delayed candidate must not overwrite a newer drain lifecycle stamp.
+        // Refresh only while holding the same mutex used by drain-side writers.
+        tryWithDirtyLedgerMutationLock(root, () => refreshStampAfterDirtyMutation(root, hooks));
+    }
+    catch {
+        // The durable event is authoritative. A later read/drain self-heals stamp.
+    }
+}
+export function readDirty(root) {
+    return captureDirtySnapshot(root).paths;
+}
+function clearCapturedLegacy(snapshot, root) {
+    if (!snapshot.legacyFingerprint)
+        return;
+    const target = dirtyLedgerPath(root);
+    const retired = `${target}.retired.${process.pid}.${crypto.randomUUID()}`;
+    try {
+        // Rename first, then inspect the exact inode moved. If a legacy writer
+        // replaced dirty.json after capture, its paths are migrated to an immutable
+        // event instead of being unlinked as though they belonged to the snapshot.
+        fs.renameSync(target, retired);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        throw error;
+    }
+    let discard = false;
+    try {
+        const current = readLegacyFile(retired);
+        if (current.fingerprint === snapshot.legacyFingerprint) {
+            discard = true;
+            return;
+        }
+        if (current.paths.length > 0) {
+            writeEvent(current.paths, root);
+            discard = true;
+            return;
+        }
+        // Preserve an unreadable replacement at the compatibility pathname when
+        // no newer writer has already recreated it.
+        try {
+            fs.linkSync(retired, target);
+            discard = true;
+        }
+        catch (error) {
+            if (error.code === 'EEXIST')
+                discard = true;
+            else
+                throw error;
+        }
+    }
+    finally {
+        if (discard) {
+            try {
+                fs.unlinkSync(retired);
+            }
+            catch { /* best effort */ }
+        }
+    }
+}
+/** Clear exactly the immutable events captured before a scan. */
+export function clearDirtySnapshot(snapshot, root, hooks = {}) {
+    hooks.beforeSnapshotDelete?.();
+    withDirtyLedgerMutationLock(root, () => {
+        const dir = dirtyEventsPath(root);
+        for (const event of snapshot.events) {
+            try {
+                fs.unlinkSync(path.join(dir, event.file));
+            }
+            catch { /* already cleared */ }
+        }
+        clearCapturedLegacy(snapshot, root);
+    });
+}
+/**
+ * Compatibility helper: clear selected paths from events visible at call time.
+ * New events created after the snapshot are never inspected or removed.
+ */
+export function clearDirty(drained, root) {
+    const drop = new Set(normalizedPaths(drained));
+    if (drop.size === 0)
+        return;
+    const snapshot = captureDirtySnapshot(root);
+    withDirtyLedgerMutationLock(root, () => {
+        const dir = dirtyEventsPath(root);
+        for (const event of snapshot.events) {
+            const remaining = event.paths.filter((value) => !drop.has(value));
+            if (remaining.length !== event.paths.length) {
+                if (remaining.length > 0)
+                    writeEvent(remaining, root);
+                try {
+                    fs.unlinkSync(path.join(dir, event.file));
+                }
+                catch { /* already cleared */ }
+            }
+        }
+        if (snapshot.legacyPaths.some((value) => drop.has(value))) {
+            const remaining = snapshot.legacyPaths.filter((value) => !drop.has(value));
+            if (remaining.length > 0)
+                writeEvent(remaining, root);
+            clearCapturedLegacy(snapshot, root);
+        }
+    });
+}
+//# sourceMappingURL=dirty-ledger.js.map

package/dist/freshness/dirty-ledger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dirty-ledger.js","sourceRoot":"","sources":["../../src/freshness/dirty-ledger.ts"],"names":[],"mappings":"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"}

package/dist/freshness/drainer.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The background drainer. Coalesces the dirty set and runs one incremental scan
+ * through scan()'s single-writer lease, then writes an honest stamp. Designed to be
+ * invoked repeatedly and cheaply (by the hook, the orchestrator, or a timer):
+ *  - busy      -> scan() could not acquire the shared lease; dirty work stays.
+ *  - debounced -> a drain ran within minIntervalMs; skipped (dirty set kept).
+ *  - clean     -> nothing dirty; stamp refreshed only.
+ *  - drained   -> scanned, cleared the drained subset, stamp updated.
+ *  - error     -> scan threw; dirty set left intact for a retry.
+ */
+import { type DirtyLedgerSnapshot } from './dirty-ledger.js';
+export type DrainStatus = 'busy' | 'debounced' | 'clean' | 'drained' | 'error';
+export interface DrainResult {
+    status: DrainStatus;
+    scanned: number;
+    error?: string;
+}
+export interface DrainOptions {
+    /** Injected scanner. `scan()` itself is the sole scan-lease owner. */
+    scanFn: (root: string, changed: string[], lifecycle: DrainScanLifecycle) => Promise<DrainScanOutcome>;
+    /** Skip if the last stamp was generated within this window (default 3000ms). */
+    minIntervalMs?: number;
+    /** Test-only seam for an edit arriving after an empty snapshot. */
+    _afterEmptySnapshot?: () => void;
+}
+export type DrainScanOutcome = {
+    status: 'completed' | 'noop';
+    retryable?: false;
+} | {
+    status: 'busy';
+    retryable: true;
+    message: string;
+};
+export interface DrainScanLifecycle {
+    onLeaseAcquired: () => Promise<void>;
+    beforeLeaseRelease: () => Promise<void>;
+    onLeaseFailureBeforeRelease: () => Promise<void>;
+}
+export { captureDirtySnapshot, type DirtyLedgerSnapshot } from './dirty-ledger.js';
+export declare function drain(root: string, opts: DrainOptions): Promise<DrainResult>;
+export interface DrainUntilCleanOptions extends DrainOptions {
+    /** Max drain attempts before giving up (default 12). Bounds worst-case time. */
+    maxAttempts?: number;
+    /** Override the post-attempt wait; defaults to minIntervalMs (busy waits less). */
+    waitMs?: number;
+}
+/**
+ * Trailing-edge guarantee. A single `drain()` can leave the *final* edits of a
+ * burst undrained (debounced) or skipped (busy). This loops past those states —
+ * sleeping out the debounce window between tries — until the ledger is actually
+ * empty, so the view self-heals within ~minIntervalMs of edits stopping instead
+ * of waiting for the 5-minute autoRefresh backstop. The hook spawns this
+ * detached, so the sleeps never block an edit. Returns every attempt's result.
+ */
+export declare function drainUntilClean(root: string, opts: DrainUntilCleanOptions): Promise<DrainResult[]>;
+/**
+ * Stamp coherence for scans that do not originate in the drainer. For example,
+ * `autoRefreshIfStale` captures this snapshot, forces its paths into an auto-mode
+ * scan, then reconciles before releasing the scan lease. Only the captured
+ * immutable events are cleared; events arriving during the scan remain dirty.
+ */
+export declare function reconcileClean(root: string, snapshot?: DirtyLedgerSnapshot): Promise<void>;
+//# sourceMappingURL=drainer.d.ts.map

package/dist/freshness/drainer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"drainer.d.ts","sourceRoot":"","sources":["../../src/freshness/drainer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAKL,KAAK,mBAAmB,EACzB,MAAM,mBAAmB,CAAC;AAO3B,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,WAAW,GAAG,OAAO,GAAG,SAAS,GAAG,OAAO,CAAC;AAE/E,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,WAAW,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,sEAAsE;IACtE,MAAM,EAAE,CACN,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EAAE,EACjB,SAAS,EAAE,kBAAkB,KAC1B,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC/B,gFAAgF;IAChF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,mEAAmE;IACnE,mBAAmB,CAAC,EAAE,MAAM,IAAI,CAAC;CAClC;AAED,MAAM,MAAM,gBAAgB,GACxB;IAAE,MAAM,EAAE,WAAW,GAAG,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,KAAK,CAAA;CAAE,GACnD;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzD,MAAM,WAAW,kBAAkB;IACjC,eAAe,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,kBAAkB,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACxC,2BAA2B,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAClD;AAED,OAAO,EAAE,oBAAoB,EAAE,KAAK,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAmDnF,wBAAsB,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC,CAkGlF;AAID,MAAM,WAAW,sBAAuB,SAAQ,YAAY;IAC1D,gFAAgF;IAChF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mFAAmF;IACnF,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;GAOG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,sBAAsB,GAC3B,OAAO,CAAC,WAAW,EAAE,CAAC,CAaxB;AAED;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,MAAM,EACZ,QAAQ,GAAE,mBAAgD,GACzD,OAAO,CAAC,IAAI,CAAC,CAcf"}

package/dist/freshness/drainer.js

@@ -0,0 +1,199 @@
+/**
+ * The background drainer. Coalesces the dirty set and runs one incremental scan
+ * through scan()'s single-writer lease, then writes an honest stamp. Designed to be
+ * invoked repeatedly and cheaply (by the hook, the orchestrator, or a timer):
+ *  - busy      -> scan() could not acquire the shared lease; dirty work stays.
+ *  - debounced -> a drain ran within minIntervalMs; skipped (dirty set kept).
+ *  - clean     -> nothing dirty; stamp refreshed only.
+ *  - drained   -> scanned, cleared the drained subset, stamp updated.
+ *  - error     -> scan threw; dirty set left intact for a retry.
+ */
+import { captureDirtySnapshot, clearDirtySnapshot, readDirty, withDirtyLedgerMutationLock, } from './dirty-ledger.js';
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { computeStamp, readStamp } from './stamp.js';
+import { stampPath } from './paths.js';
+export { captureDirtySnapshot } from './dirty-ledger.js';
+/**
+ * Stamp writes must remain safe now that multiple drainers may reach scan()
+ * concurrently. The shared stamp writer uses a fixed `.tmp` path, so this
+ * lane uses a unique same-directory candidate before the atomic rename.
+ */
+function writeDrainStamp(root, stamp) {
+    const target = stampPath(root);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    const candidate = `${target}.tmp.${process.pid}.${crypto.randomUUID()}`;
+    try {
+        fs.writeFileSync(candidate, JSON.stringify(stamp, null, 2), 'utf8');
+        fs.renameSync(candidate, target);
+    }
+    finally {
+        try {
+            fs.unlinkSync(candidate);
+        }
+        catch { /* renamed or best effort */ }
+    }
+}
+/**
+ * Serialize drain-side reconciliation and recheck the canonical ledger before
+ * publishing. A concurrent mark is an immutable event; freshness read
+ * boundaries overlay that ledger even if its best-effort stamp refresh races
+ * this publication or the marking process exits immediately afterward.
+ */
+function writeHonestDrainStamp(root, proposed, options = {}) {
+    return withDirtyLedgerMutationLock(root, () => {
+        const dirty = readDirty(root);
+        if (options.requireClean && dirty.length > 0)
+            return false;
+        writeDrainStamp(root, {
+            ...proposed,
+            generated_at: dirty.length > 0
+                ? options.dirtyGeneratedAt ?? proposed.generated_at
+                : options.cleanGeneratedAt ?? proposed.generated_at,
+            dirty_files: dirty,
+            dirty_count: dirty.length,
+        });
+        return true;
+    });
+}
+export async function drain(root, opts) {
+    const minInterval = opts.minIntervalMs ?? 3000;
+    // Debounce off the last stamp's generated_at (only when there IS prior state).
+    const prior = readStamp(root);
+    if (prior && Date.now() - prior.generated_at < minInterval) {
+        return { status: 'debounced', scanned: 0 };
+    }
+    const dirtySnapshot = captureDirtySnapshot(root);
+    const dirty = dirtySnapshot.paths;
+    if (dirty.length === 0) {
+        opts._afterEmptySnapshot?.();
+        const proposed = await computeStamp(root, { inFlight: false });
+        const published = writeHonestDrainStamp(root, proposed, { requireClean: true });
+        return published
+            ? { status: 'clean', scanned: 0 }
+            : { status: 'debounced', scanned: 0 };
+    }
+    let outcome;
+    let leaseAcquired = false;
+    let reconciledBeforeRelease = false;
+    let failureSettledBeforeRelease = false;
+    const onLeaseAcquired = async () => {
+        leaseAcquired = true;
+        const proposed = await computeStamp(root, {
+            inFlight: true,
+            generatedAt: prior?.generated_at,
+        });
+        writeHonestDrainStamp(root, proposed, {
+            dirtyGeneratedAt: prior?.generated_at,
+        });
+    };
+    const beforeLeaseRelease = async () => {
+        if (reconciledBeforeRelease)
+            return;
+        reconciledBeforeRelease = true;
+        await reconcileClean(root, dirtySnapshot);
+    };
+    const onLeaseFailureBeforeRelease = async () => {
+        if (failureSettledBeforeRelease)
+            return;
+        failureSettledBeforeRelease = true;
+        const proposed = await computeStamp(root, {
+            inFlight: false,
+            generatedAt: prior?.generated_at,
+        });
+        writeHonestDrainStamp(root, proposed, {
+            dirtyGeneratedAt: prior?.generated_at,
+        });
+    };
+    try {
+        outcome = await opts.scanFn(root, dirty, {
+            onLeaseAcquired,
+            beforeLeaseRelease,
+            onLeaseFailureBeforeRelease,
+        });
+    }
+    catch (e) {
+        // Lifecycle cleanup must happen under the canonical lease. If the scanner
+        // did not invoke it, leave any in-flight marker conservative for a retry.
+        return { status: 'error', scanned: 0, error: e instanceof Error ? e.message : String(e) };
+    }
+    const outcomeStatus = outcome?.status;
+    if (outcomeStatus !== 'completed' &&
+        outcomeStatus !== 'noop' &&
+        outcomeStatus !== 'busy') {
+        const proposed = await computeStamp(root, {
+            inFlight: false,
+            generatedAt: prior?.generated_at,
+        });
+        writeHonestDrainStamp(root, proposed, {
+            dirtyGeneratedAt: prior?.generated_at,
+        });
+        return { status: 'error', scanned: 0, error: 'scan returned an unknown outcome' };
+    }
+    if (outcome.status === 'busy') {
+        // No lease-acquired callback means this attempt never wrote in-flight.
+        if (leaseAcquired) {
+            return { status: 'error', scanned: 0, error: 'busy returned after lease acquisition' };
+        }
+        return { status: 'busy', scanned: 0, error: outcome.message };
+    }
+    if (!leaseAcquired || !reconciledBeforeRelease) {
+        // A completed scanner that skipped the lease-held callback is unsafe: it
+        // may already have released, so post-hoc ledger clearing could erase late
+        // work or race a new scan. Preserve everything and require a retry.
+        return {
+            status: 'error',
+            scanned: 0,
+            error: 'scan completed without lease-held freshness lifecycle',
+        };
+    }
+    return { status: 'drained', scanned: dirty.length };
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * Trailing-edge guarantee. A single `drain()` can leave the *final* edits of a
+ * burst undrained (debounced) or skipped (busy). This loops past those states —
+ * sleeping out the debounce window between tries — until the ledger is actually
+ * empty, so the view self-heals within ~minIntervalMs of edits stopping instead
+ * of waiting for the 5-minute autoRefresh backstop. The hook spawns this
+ * detached, so the sleeps never block an edit. Returns every attempt's result.
+ */
+export async function drainUntilClean(root, opts) {
+    const maxAttempts = opts.maxAttempts ?? 12;
+    const baseWait = opts.waitMs ?? opts.minIntervalMs ?? 3000;
+    const results = [];
+    for (let i = 0; i < maxAttempts; i++) {
+        const res = await drain(root, { scanFn: opts.scanFn, minIntervalMs: opts.minIntervalMs });
+        results.push(res);
+        const settled = res.status === 'drained' || res.status === 'clean';
+        if (settled && readDirty(root).length === 0)
+            break; // ledger truly empty → done
+        if (res.status === 'error')
+            break; // a scan that throws won't fix itself by retrying
+        await sleep(res.status === 'busy' ? Math.min(1000, baseWait) : baseWait);
+    }
+    return results;
+}
+/**
+ * Stamp coherence for scans that do not originate in the drainer. For example,
+ * `autoRefreshIfStale` captures this snapshot, forces its paths into an auto-mode
+ * scan, then reconciles before releasing the scan lease. Only the captured
+ * immutable events are cleared; events arriving during the scan remain dirty.
+ */
+export async function reconcileClean(root, snapshot = captureDirtySnapshot(root)) {
+    // Delete only immutable event filenames captured before the scan. Late
+    // events, including repeated edits to the same path, have distinct names.
+    clearDirtySnapshot(snapshot, root);
+    const prior = readStamp(root);
+    const completedAt = Date.now();
+    const proposed = await computeStamp(root, {
+        inFlight: false,
+        generatedAt: completedAt,
+    });
+    writeHonestDrainStamp(root, proposed, {
+        cleanGeneratedAt: completedAt,
+        dirtyGeneratedAt: prior?.generated_at,
+    });
+}
+//# sourceMappingURL=drainer.js.map

package/dist/freshness/drainer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"drainer.js","sourceRoot":"","sources":["../../src/freshness/drainer.ts"],"names":[],"mappings":"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"}

package/dist/freshness/paths.d.ts

@@ -0,0 +1,13 @@
+/** The `.navgator` base dir for a project root (sibling of `architecture/`). */
+export declare function navgatorBase(root: string): string;
+/** Dirty-set ledger: append-only set of changed paths since the last clean drain. */
+export declare function dirtyLedgerPath(root: string): string;
+/** Immutable per-mutation events used by the concurrency-safe dirty ledger. */
+export declare function dirtyEventsPath(root: string): string;
+/** Short-lived mutex for ledger mutation and clean-stamp publication. */
+export declare function dirtyMutationLockPath(root: string): string;
+/** Single-writer scan lock. */
+export declare function scanLockPath(root: string): string;
+/** Freshness stamp, stored next to the graph it describes. */
+export declare function stampPath(root: string): string;
+//# sourceMappingURL=paths.d.ts.map

package/dist/freshness/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/freshness/paths.ts"],"names":[],"mappings":"AAQA,gFAAgF;AAChF,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKjD;AAED,qFAAqF;AACrF,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,+EAA+E;AAC/E,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,yEAAyE;AACzE,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED,+BAA+B;AAC/B,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED,8DAA8D;AAC9D,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE9C"}

package/dist/freshness/paths.js

@@ -0,0 +1,35 @@
+/**
+ * Single source of truth for freshness-subsystem file locations.
+ * Derived from NavGator config so local vs shared storage mode is honored:
+ * getStoragePath() returns <base>/architecture, so its dirname is the base.
+ */
+import * as path from 'path';
+import { getConfig, getStoragePath } from '../config.js';
+/** The `.navgator` base dir for a project root (sibling of `architecture/`). */
+export function navgatorBase(root) {
+    const storagePath = getStoragePath(getConfig(), root);
+    return path.basename(storagePath) === 'architecture'
+        ? path.dirname(storagePath)
+        : storagePath;
+}
+/** Dirty-set ledger: append-only set of changed paths since the last clean drain. */
+export function dirtyLedgerPath(root) {
+    return path.join(navgatorBase(root), 'dirty.json');
+}
+/** Immutable per-mutation events used by the concurrency-safe dirty ledger. */
+export function dirtyEventsPath(root) {
+    return path.join(navgatorBase(root), 'dirty.d');
+}
+/** Short-lived mutex for ledger mutation and clean-stamp publication. */
+export function dirtyMutationLockPath(root) {
+    return path.join(navgatorBase(root), 'dirty.lock');
+}
+/** Single-writer scan lock. */
+export function scanLockPath(root) {
+    return path.join(navgatorBase(root), 'scan.lock');
+}
+/** Freshness stamp, stored next to the graph it describes. */
+export function stampPath(root) {
+    return path.join(getStoragePath(getConfig(), root), 'freshness.json');
+}
+//# sourceMappingURL=paths.js.map

package/dist/freshness/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../src/freshness/paths.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAC7B,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEzD,gFAAgF;AAChF,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,MAAM,WAAW,GAAG,cAAc,CAAC,SAAS,EAAE,EAAE,IAAI,CAAC,CAAC;IACtD,OAAO,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,KAAK,cAAc;QAClD,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC;QAC3B,CAAC,CAAC,WAAW,CAAC;AAClB,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,OAAO,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,EAAE,YAAY,CAAC,CAAC;AACrD,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,OAAO,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC,CAAC;AAClD,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,qBAAqB,CAAC,IAAY;IAChD,OAAO,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,EAAE,YAAY,CAAC,CAAC;AACrD,CAAC;AAED,+BAA+B;AAC/B,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,OAAO,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,EAAE,WAAW,CAAC,CAAC;AACpD,CAAC;AAED,8DAA8D;AAC9D,MAAM,UAAU,SAAS,CAAC,IAAY;IACpC,OAAO,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,SAAS,EAAE,EAAE,IAAI,CAAC,EAAE,gBAAgB,CAAC,CAAC;AACxE,CAAC"}