rag-memory-epf-mcp 3.5.2 → 3.6.0

package/dist/src/embeddingGate.js

@@ -0,0 +1,227 @@
+// v3.6 lite install (spec 2026-07-18 v5 §3): EmbeddingGate owns the embedding
+// model lifecycle — nothing else. State machine + single-flight load/retry +
+// prioritized serial inference queue. It does NOT touch the DB, backfill
+// policy, FTS SQL, or tool response shapes (A′ boundary).
+//
+// Consumers never read state and then call separately (TOCTOU): embed() decides
+// and executes inside one boundary, rejecting with typed errors when the model
+// is unavailable so each tool can honor its own not-ready contract.
+export class GateDisabledError extends Error {
+    code = 'EMBEDDINGS_DISABLED';
+    state = 'disabled';
+    constructor() {
+        super('Embeddings are disabled (RAG_MEMORY_EMBEDDINGS=off)');
+        this.name = 'GateDisabledError';
+    }
+}
+export class GateNotReadyError extends Error {
+    state;
+    retryAfterMs;
+    code = 'MODEL_NOT_READY';
+    constructor(state, retryAfterMs) {
+        super(`Embedding model not ready (state=${state})`);
+        this.state = state;
+        this.retryAfterMs = retryAfterMs;
+        this.name = 'GateNotReadyError';
+    }
+}
+// Configuration incompatibility (e.g. a non-1024-dim custom model): retrying or
+// quarantining the cache cannot fix it — the gate parks in terminal 'failed'
+// with no reload schedule (beta 2R B3).
+export class TerminalConfigError extends Error {
+    terminal = true;
+    constructor(message) {
+        super(message);
+        this.name = 'TerminalConfigError';
+    }
+}
+const PRIO = { interactive: 0, bulk: 1, backfill: 2 };
+const DEFAULT_BACKOFF_MS = [30_000, 120_000, 600_000, 3_600_000];
+export class EmbeddingGate {
+    opts;
+    state;
+    embedFn = null;
+    startPromise = null;
+    queue = [];
+    running = false;
+    seq = 0;
+    generation = 0;
+    shuttingDown = false;
+    retryTimer = null;
+    attempt = 0;
+    // Systemic-failure detector (beta 2R B4): DISTINCT failed inputs within the
+    // current load epoch (cleared on successful load AND on any inference
+    // success). Same-input retries are data-specific (poison row) and never
+    // demote. `demotions` escalates the reload backoff across repeated
+    // demote-reload cycles and only resets on a real inference success.
+    failedInputs = new Set();
+    demotions = 0;
+    terminalFailure = false;
+    abort = new AbortController(); // loader passes this to lock waits / fetches
+    readySince;
+    lastError;
+    retryAt;
+    backoff;
+    constructor(opts) {
+        this.opts = opts;
+        this.backoff = opts.backoffMs ?? DEFAULT_BACKOFF_MS;
+        this.state = opts.mode === 'off' ? 'disabled' : 'idle';
+    }
+    get status() {
+        return { state: this.state, readySince: this.readySince, lastError: this.lastError, retryAt: this.retryAt };
+    }
+    get isReady() { return this.state === 'ready'; }
+    get isDisabled() { return this.state === 'disabled'; }
+    setState(s) {
+        if (this.state !== s) {
+            this.state = s;
+            this.opts.onStateChange?.(s);
+        }
+    }
+    // Single-flight: concurrent calls share one load; after a failure the next
+    // scheduled retry (or explicit call) re-enters loadOnce.
+    start() {
+        if (this.state === 'disabled' || this.shuttingDown)
+            return Promise.resolve();
+        if (!this.startPromise)
+            this.startPromise = this.loadOnce();
+        return this.startPromise;
+    }
+    // loading -> downloading is reported by the loader via markDownloading().
+    markDownloading() {
+        if (this.state === 'loading')
+            this.setState('downloading');
+    }
+    async loadOnce() {
+        this.setState('loading');
+        try {
+            this.embedFn = await this.opts.loadModel();
+            this.attempt = 0;
+            this.retryAt = undefined;
+            this.lastError = undefined;
+            this.failedInputs.clear(); // fresh load epoch (beta 2R B4)
+            this.readySince = new Date().toISOString();
+            this.setState('ready');
+            this.opts.onReady?.();
+            this.pump();
+        }
+        catch (e) {
+            this.lastError = e instanceof Error ? e.message : String(e);
+            this.setState('failed');
+            this.startPromise = null;
+            if (e?.terminal === true) {
+                // Config incompatibility (beta 2R B3): retrying or quarantining cannot
+                // fix it — no reload schedule; a restart with a fixed config is the
+                // only recovery.
+                this.terminalFailure = true;
+                this.retryAt = undefined;
+                console.error(`❌ embeddings disabled for this run (config): ${this.lastError}`);
+                throw e;
+            }
+            this.scheduleRetry(this.attempt++);
+            throw e;
+        }
+    }
+    // Shared retry scheduler with jitter; escalation index picks the backoff slot.
+    scheduleRetry(escalation) {
+        if (this.shuttingDown || this.terminalFailure)
+            return;
+        const base = this.backoff[Math.min(escalation, this.backoff.length - 1)];
+        const delay = Math.round(base * (0.8 + Math.random() * 0.4)); // jitter ±20%
+        this.retryAt = new Date(Date.now() + delay).toISOString();
+        this.retryTimer = setTimeout(() => {
+            this.retryTimer = null;
+            void this.start().catch(() => { });
+        }, delay);
+        this.retryTimer.unref?.();
+    }
+    embed(text, o) {
+        if (this.state === 'disabled')
+            return Promise.reject(new GateDisabledError());
+        if (this.shuttingDown)
+            return Promise.reject(new GateNotReadyError(this.state));
+        if (this.state !== 'ready') {
+            const retryAfterMs = this.retryAt ? Math.max(0, Date.parse(this.retryAt) - Date.now()) : undefined;
+            return Promise.reject(new GateNotReadyError(this.state, retryAfterMs));
+        }
+        return new Promise((resolve, reject) => {
+            this.queue.push({
+                text, dims: o.dims ?? 1024, isQuery: o.isQuery ?? false,
+                prio: PRIO[o.priority], seq: this.seq++, gen: this.generation, resolve, reject,
+            });
+            this.queue.sort((a, b) => a.prio - b.prio || a.seq - b.seq);
+            this.pump();
+        });
+    }
+    pump() {
+        if (this.running || !this.embedFn)
+            return;
+        const job = this.queue.shift();
+        if (!job)
+            return;
+        this.running = true;
+        void this.embedFn(job.text, job.dims, job.isQuery)
+            .then(v => {
+            this.failedInputs.clear();
+            this.demotions = 0; // a real success resets escalation
+            if (job.gen === this.generation)
+                job.resolve(v);
+            else
+                job.reject(new Error('embedding discarded: gate shut down'));
+        })
+            .catch(e => {
+            // Systemic-failure detection (beta 2R B4): 3 DISTINCT failed inputs in
+            // this load epoch -> demote to failed + reload with ESCALATING backoff
+            // (demotions counter survives reloads; only an inference success
+            // resets it — so a persistently broken runtime backs off instead of
+            // hot-looping). Same-input repeats (A→A) and A→B→A count 2 distinct.
+            this.failedInputs.add(`${job.text}|${job.dims}|${job.isQuery}`);
+            if (this.failedInputs.size >= 3 && this.state === 'ready' && !this.shuttingDown) {
+                this.lastError = e instanceof Error ? e.message : String(e);
+                this.embedFn = null;
+                this.startPromise = null;
+                this.failedInputs.clear();
+                this.setState('failed');
+                this.scheduleRetry(this.demotions++);
+                for (const j of this.queue.splice(0))
+                    j.reject(new GateNotReadyError('failed'));
+            }
+            job.reject(e);
+        })
+            .finally(() => {
+            this.running = false;
+            this.pump();
+        });
+    }
+    // Was the load still in flight when shutdown settled? (index.ts uses this to
+    // decide whether a bounded exit is needed — see shutdownAll.)
+    get loadInFlight() {
+        return this.startPromise !== null && this.state !== 'ready' && this.state !== 'failed' && this.state !== 'disabled';
+    }
+    // Graceful shutdown (spec §3, beta B1): block new work, abort what we can
+    // (lock waits via this.abort), discard in-flight inference results via the
+    // generation token, clear retry timers, then wait (bounded) for BOTH the
+    // current inference and an in-flight model load to settle.
+    async shutdown(deadlineMs = 5000) {
+        this.shuttingDown = true;
+        this.generation++;
+        this.abort.abort();
+        if (this.retryTimer) {
+            clearTimeout(this.retryTimer);
+            this.retryTimer = null;
+        }
+        for (const j of this.queue.splice(0))
+            j.reject(new Error('gate shutdown'));
+        const deadline = Date.now() + deadlineMs;
+        if (this.startPromise) {
+            const remaining = () => Math.max(0, deadline - Date.now());
+            await Promise.race([
+                this.startPromise.catch(() => { }),
+                new Promise(r => setTimeout(r, remaining())),
+            ]);
+        }
+        while (this.running && Date.now() < deadline) {
+            await new Promise(r => setTimeout(r, 20));
+        }
+    }
+}

package/dist/src/migrations/migrations.js

@@ -570,5 +570,76 @@ export const migrations = [
             // No clean reversal: would need the original document content to recompute
             // UTF-16 indices, and we never recorded which chunks were touched. No-op.
         }
+    },
+    // v3.6 (spec 2026-07-18 lite-install v5 §6c): embedding provenance + narrowed FTS trigger.
+    // ADD COLUMN is guarded by PRAGMA table_info so re-runs are idempotent.
+    {
+        version: 12,
+        description: 'Embedding provenance (profiles, input_hash, provenance_state), backfill failures, narrowed chunks_fts_update trigger',
+        up: (db) => {
+            const hasCol = (table, col) => db.prepare(`PRAGMA table_info(${table})`).all().some(c => c.name === col);
+            for (const table of ['chunk_metadata', 'entity_embedding_metadata']) {
+                if (!hasCol(table, 'input_hash'))
+                    db.exec(`ALTER TABLE ${table} ADD COLUMN input_hash TEXT`);
+                if (!hasCol(table, 'profile_id'))
+                    db.exec(`ALTER TABLE ${table} ADD COLUMN profile_id INTEGER`);
+                if (!hasCol(table, 'provenance_state'))
+                    db.exec(`ALTER TABLE ${table} ADD COLUMN provenance_state TEXT`);
+            }
+            db.exec(`
+        CREATE TABLE IF NOT EXISTS embedding_profiles (
+          id INTEGER PRIMARY KEY AUTOINCREMENT,
+          model_id TEXT NOT NULL,
+          revision TEXT NOT NULL,
+          dtype TEXT NOT NULL,
+          dims INTEGER NOT NULL,
+          pooling TEXT NOT NULL,
+          normalize INTEGER NOT NULL,
+          created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+          UNIQUE(model_id, revision, dtype, dims, pooling, normalize)
+        )
+      `);
+            db.exec(`
+        CREATE TABLE IF NOT EXISTS embedding_backfill_failures (
+          kind TEXT NOT NULL,
+          target_id TEXT NOT NULL,
+          input_hash TEXT,
+          profile_id INTEGER,
+          attempts INTEGER NOT NULL DEFAULT 0,
+          last_error TEXT,
+          updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+          UNIQUE(kind, target_id)
+        )
+      `);
+            db.exec(`CREATE TABLE IF NOT EXISTS server_meta (key TEXT PRIMARY KEY, value TEXT)`);
+            // Narrow the broad AFTER UPDATE trigger (installed by v8) so provenance-only
+            // updates do not rewrite the FTS index (advisor 4R must-fix 1).
+            db.exec(`DROP TRIGGER IF EXISTS chunks_fts_update`);
+            db.exec(`
+        CREATE TRIGGER chunks_fts_update AFTER UPDATE OF text, chunk_id ON chunk_metadata BEGIN
+          INSERT INTO chunks_fts(chunks_fts, rowid, text, chunk_id)
+            VALUES ('delete', old.rowid, old.text, old.chunk_id);
+          INSERT INTO chunks_fts(rowid, text, chunk_id)
+            VALUES (new.rowid, new.text, new.chunk_id);
+        END
+      `);
+        },
+        down: (db) => {
+            // Restore the broad v8 trigger; drop v12 tables. Added columns are left in
+            // place (SQLite DROP COLUMN restrictions with dependent objects) — pre-v12
+            // code ignores unknown columns, so rollback stays safe (spec §8-4).
+            db.exec(`DROP TRIGGER IF EXISTS chunks_fts_update`);
+            db.exec(`
+        CREATE TRIGGER chunks_fts_update AFTER UPDATE ON chunk_metadata BEGIN
+          INSERT INTO chunks_fts(chunks_fts, rowid, text, chunk_id)
+            VALUES ('delete', old.rowid, old.text, old.chunk_id);
+          INSERT INTO chunks_fts(rowid, text, chunk_id)
+            VALUES (new.rowid, new.text, new.chunk_id);
+        END
+      `);
+            db.exec(`DROP TABLE IF EXISTS embedding_backfill_failures`);
+            db.exec(`DROP TABLE IF EXISTS embedding_profiles`);
+            db.exec(`DROP TABLE IF EXISTS server_meta`);
+        }
     }
 ];

package/dist/src/modelCache.d.ts

@@ -0,0 +1,33 @@
+export declare function resolveModelCacheDir(env: Record<string, string | undefined>, platform: string, homedir: string): string;
+export declare function preflightCacheDir(dir: string): {
+    ok: boolean;
+    error?: string;
+};
+export declare function artifactKey(modelId: string, revision: string, dtype: string): string;
+export declare class ModelDownloadLock {
+    readonly lockPath: string;
+    readonly markerPath: string;
+    private held;
+    constructor(cacheDir: string, key: string);
+    private tryAcquire;
+    private isStale;
+    private holderPid;
+    invalidateMarker(): void;
+    acquireOrWait(opts: {
+        pollMs?: number;
+        timeoutMs: number;
+        signal?: AbortSignal;
+    }): Promise<'owner' | 'ready'>;
+    markComplete(): void;
+    release(): void;
+}
+export declare function isCacheIntegrityError(e: unknown, cacheDir?: string): boolean;
+export declare function handleLoaderFailure(opts: {
+    role: 'owner' | 'ready';
+    error: unknown;
+    lock: ModelDownloadLock;
+    cacheDir: string;
+    modelId: string;
+    terminal: boolean;
+}): 'none' | 'marker-invalidated' | 'quarantined';
+export declare function quarantinePartialCache(cacheDir: string, modelId: string): void;

package/dist/src/modelCache.js

@@ -0,0 +1,235 @@
+// v3.6 lite install (spec 2026-07-18 v5 §7): version-independent model cache.
+// The transformers.js default cache lives INSIDE the package directory, which is
+// npx-slot scoped — every engine version bump re-downloads ~1.2GB. This module
+// resolves a user-level cache dir and provides a cross-process download lock so
+// concurrent MCP servers on one machine never write the same model concurrently
+// (transformers' FileCache.put is not atomic).
+//
+// Lock/marker keys use ONLY cache-artifact fields (model id, revision, dtype) —
+// never retrieval config (spec §6c layer 1).
+import { mkdirSync, writeFileSync, readFileSync, unlinkSync, existsSync, renameSync, rmSync, readdirSync } from 'node:fs';
+import { join, sep } from 'node:path';
+import { createHash } from 'node:crypto';
+export function resolveModelCacheDir(env, platform, homedir) {
+    if (env.RAG_MEMORY_MODEL_CACHE_DIR)
+        return env.RAG_MEMORY_MODEL_CACHE_DIR;
+    if (env.XDG_CACHE_HOME)
+        return join(env.XDG_CACHE_HOME, 'rag-memory-epf-mcp');
+    if (platform === 'darwin')
+        return join(homedir, 'Library', 'Caches', 'rag-memory-epf-mcp');
+    if (platform === 'win32' && env.LOCALAPPDATA)
+        return join(env.LOCALAPPDATA, 'rag-memory-epf-mcp');
+    return join(homedir, '.cache', 'rag-memory-epf-mcp');
+}
+// mkdir -p + write probe. On failure the caller must transition the gate to
+// `failed` — silently falling back to the package-internal cache is forbidden.
+export function preflightCacheDir(dir) {
+    try {
+        mkdirSync(dir, { recursive: true });
+        const probe = join(dir, `.write-probe-${process.pid}`);
+        writeFileSync(probe, 'ok');
+        unlinkSync(probe);
+        return { ok: true };
+    }
+    catch (e) {
+        return { ok: false, error: e instanceof Error ? e.message : String(e) };
+    }
+}
+export function artifactKey(modelId, revision, dtype) {
+    return createHash('sha1').update(`${modelId}@${revision}#${dtype}`).digest('hex').slice(0, 12);
+}
+const STALE_LOCK_MS = 30 * 60_000;
+export class ModelDownloadLock {
+    lockPath;
+    markerPath;
+    held = false;
+    constructor(cacheDir, key) {
+        this.lockPath = join(cacheDir, `.download-${key}.lock`);
+        this.markerPath = join(cacheDir, `.complete-${key}`);
+    }
+    tryAcquire() {
+        try {
+            writeFileSync(this.lockPath, JSON.stringify({ pid: process.pid, startedAt: Date.now() }), { flag: 'wx' });
+            this.held = true;
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    // Stale = holder pid is dead or the lock is unreadable. A LIVE pid is never
+    // reclaimed by age alone (beta B5): a slow 1.2GB download has no heartbeat,
+    // so an mtime rule would mint a second concurrent owner — the exact failure
+    // this lock exists to prevent. A hung-but-alive holder instead surfaces as a
+    // waiter timeout -> gate 'failed' + backoff, with the lock path and holder
+    // pid in the error so an operator can verify and remove it manually (the
+    // recovery procedure lives in docs/UPDATING.md). No pid-reuse heuristic:
+    // there is no portable process-start identity to compare against (beta 2R).
+    isStale() {
+        try {
+            const info = JSON.parse(readFileSync(this.lockPath, 'utf-8'));
+            try {
+                process.kill(info.pid, 0);
+            }
+            catch {
+                return true;
+            } // pid dead
+            return false;
+        }
+        catch {
+            return true; // unreadable lock = stale
+        }
+    }
+    holderPid() {
+        try {
+            return JSON.parse(readFileSync(this.lockPath, 'utf-8')).pid;
+        }
+        catch {
+            return null;
+        }
+    }
+    // Corrupted-cache recovery (beta B5): a marker only proves a PAST verified
+    // load. When a marker-holder ('ready' role) later fails to load, the caller
+    // must invalidate the marker so the next attempt becomes a locked owner.
+    invalidateMarker() {
+        try {
+            unlinkSync(this.markerPath);
+        }
+        catch { /* already gone */ }
+    }
+    // (beta 4R M1) Quarantine decisions are made by ERROR CLASS, not by failure
+    // count — see isCacheIntegrityError below.
+    // Returns 'owner' (caller must download, then markComplete + release) or
+    // 'ready' (a completed, verified cache already exists). Async polling only —
+    // never blocks the event loop (spec §7 / 3R M14).
+    async acquireOrWait(opts) {
+        const poll = opts.pollMs ?? 500;
+        const deadline = Date.now() + opts.timeoutMs;
+        for (;;) {
+            // Abort FIRST (beta 2R B5): a shutdown-aborted waiter must never become
+            // an owner or report 'ready' and start a pipeline load.
+            if (opts.signal?.aborted)
+                throw new Error('model download lock wait aborted');
+            if (existsSync(this.markerPath))
+                return 'ready';
+            if (this.tryAcquire())
+                return 'owner';
+            if (this.isStale()) {
+                try {
+                    unlinkSync(this.lockPath);
+                }
+                catch { /* raced with another reclaimer */ }
+                continue;
+            }
+            if (Date.now() > deadline) {
+                throw new Error(`model download lock wait timed out — holder pid=${this.holderPid() ?? 'unknown'}, lock=${this.lockPath}. If that process is hung, verify and remove the lock file manually (see docs/UPDATING.md).`);
+            }
+            // Abortable sleep with symmetric listener cleanup (beta 3R M4): a
+            // 10-minute wait at 500ms polls must not accumulate ~1200 abort
+            // listeners on the shared shutdown signal.
+            await new Promise(resolve => {
+                const onAbort = () => { clearTimeout(t); resolve(); };
+                const t = setTimeout(() => {
+                    opts.signal?.removeEventListener('abort', onAbort);
+                    resolve();
+                }, poll);
+                opts.signal?.addEventListener('abort', onAbort, { once: true });
+            });
+        }
+    }
+    // Only call after a verified cache load — a memory-only load success without
+    // durable cache files must NOT produce a marker (3R M14).
+    markComplete() {
+        const tmp = `${this.markerPath}.tmp.${process.pid}`;
+        writeFileSync(tmp, new Date().toISOString());
+        renameSync(tmp, this.markerPath);
+    }
+    release() {
+        if (this.held) {
+            try {
+                unlinkSync(this.lockPath);
+            }
+            catch { /* already gone */ }
+            this.held = false;
+        }
+    }
+}
+// (beta 4R M1 -> 5R M2) Error classification for cache handling: ONLY strong
+// serialization/truncation/corruption signatures justify quarantining a 1.2GB
+// cache. Generic words (parse, invalid model, byte length) and bare ENOENT
+// match far too much outside the cache — ENOENT counts only when the message
+// points INSIDE the model cache directory. OOM / allocation / network errors
+// preserve the cache regardless of repetition. Residual risk (documented): a
+// corruption with no matching signature stays put; docs/UPDATING.md tells the
+// operator to delete the model cache directory manually.
+const CACHE_INTEGRITY_SIGNATURES = [
+    /protobuf/i, /corrupt/i, /unexpected end/i, /deseriali[sz]e/i,
+    /magic number/i, /truncated/i, /checksum/i,
+];
+const CACHE_PRESERVE_SIGNATURES = [
+    /out of memory/i, /bad_alloc/i, /allocation/i, /OOM/i, /ETIMEDOUT/, /ECONNRESET/, /fetch/i, /network/i,
+];
+export function isCacheIntegrityError(e, cacheDir) {
+    const msg = e instanceof Error ? `${e.name}: ${e.message}` : String(e);
+    if (CACHE_PRESERVE_SIGNATURES.some(re => re.test(msg)))
+        return false;
+    if (CACHE_INTEGRITY_SIGNATURES.some(re => re.test(msg)))
+        return true;
+    // Missing-file errors are integrity ONLY when they point INSIDE the cache
+    // dir (path-boundary-safe: '/cache' must not match '/cache-old' — 6R note).
+    if (cacheDir && (/ENOENT/.test(msg) || /no such file/i.test(msg))
+        && (msg.includes(cacheDir + sep) || msg.includes(cacheDir + '/')))
+        return true;
+    return false;
+}
+// (beta 5R M1) Loader-failure cache policy, extracted for unit testing.
+// Quarantine requires EXCLUSIVITY: only the lock-holding OWNER may rename or
+// delete shared cache files — a ready-role process (no lock) racing other
+// readers must never touch the directory; it only drops the marker so the
+// next retry becomes a locked owner and re-proves the same integrity error
+// before any destructive action.
+export function handleLoaderFailure(opts) {
+    if (opts.terminal)
+        return 'none'; // config error: cache is fine
+    if (!isCacheIntegrityError(opts.error, opts.cacheDir)) {
+        // OOM / network / unknown: preserve everything (marker included — a
+        // transient error does not disprove a verified cache).
+        return 'none';
+    }
+    if (opts.role === 'ready') {
+        opts.lock.invalidateMarker();
+        return 'marker-invalidated';
+    }
+    opts.lock.invalidateMarker();
+    quarantinePartialCache(opts.cacheDir, opts.modelId);
+    return 'quarantined';
+}
+// Owner-side failure handling: partially downloaded model dirs are quarantined
+// (renamed aside) rather than left in place, so the next attempt starts clean.
+// transformers.js FileCache keys are `<org>/<model>/...` — the on-disk layout
+// nests the model id's path segments under cacheDir (beta B5: a flattened
+// `org_model` path would miss the real files entirely).
+export function quarantinePartialCache(cacheDir, modelId) {
+    const dir = join(cacheDir, ...modelId.split('/'));
+    if (existsSync(dir)) {
+        try {
+            renameSync(dir, `${dir}.quarantine.${Date.now()}`);
+        }
+        catch {
+            rmSync(dir, { recursive: true, force: true });
+        }
+    }
+    // Retention (beta 2R B3): keep only the newest quarantine — repeated failures
+    // must not accumulate 1.2GB directories.
+    try {
+        const parent = join(cacheDir, ...modelId.split('/').slice(0, -1));
+        const leaf = modelId.split('/').pop();
+        const quarantines = readdirSync(parent)
+            .filter(f => f.startsWith(`${leaf}.quarantine.`))
+            .sort();
+        for (const old of quarantines.slice(0, -1)) {
+            rmSync(join(parent, old), { recursive: true, force: true });
+        }
+    }
+    catch { /* parent may not exist */ }
+}