mixdog 0.9.87 → 0.9.89

package/src/runtime/agent/orchestrator/session/store/load-cache.mjs

@@ -1,5 +1,6 @@
-import { statSync, existsSync, readFileSync } from 'fs';
+import { statSync, readFileSync } from 'fs';
 import { getPluginData } from '../../config.mjs';
+import { readTopLevelLifecycleRecord, isLifecycleUnreadable } from '../lifecycle-scan.mjs';
 
 // Recent full-session reads are much hotter than writes while a user hops
 // between conversations. Verify the file identity on every access, but reuse
@@ -8,42 +9,224 @@ const SESSION_LOAD_CACHE_LIMIT = 8;
 const _sessionLoadCache = new Map(); // path → { signature, session }
 let _sessionLoadCacheDataDir = null;
 
-export function _readStoredSessionCached(id, path) {
-    const dataDir = getPluginData();
-    if (_sessionLoadCacheDataDir !== dataDir) {
-        _sessionLoadCacheDataDir = dataDir;
-        _sessionLoadCache.clear();
+// A session file is only ever replaced atomically (write tmp → rename over
+// the canonical path). A reader that stats one inode and then reads "the
+// path" can therefore straddle a replacement: the stat describes the old
+// file while the read returns the new bytes, or the old inode is already
+// gone (ENOENT) even though a perfectly valid replacement exists — which the
+// naive version reported as {exists:true, session:null} / {exists:false},
+// i.e. loadSession()/getSession() returning null for a live session. Every
+// observation below is therefore a STABLE SNAPSHOT: stat → read → stat, and
+// the result is only trusted (and only cached) when the identity signature is
+// unchanged around the read. An unstable observation is retried a bounded
+// number of times, so the replacement window closes and we still fail closed
+// on genuine corruption instead of spinning.
+const SESSION_LOAD_STABLE_ATTEMPTS = 5;
+
+// Deterministic fault injection point (tests only): invoked immediately
+// before every stat and every read with { phase, path, attempt }. The hook
+// may mutate the file system (simulating an atomic rename landing between
+// the two syscalls) or return an Error to make that syscall fail.
+//
+// STRUCTURAL GATE: the seam is inert unless the process was started in
+// explicit fault-injection test mode. Installing a hook without the gate is
+// a no-op (returns false), and an already-installed hook is dropped the
+// moment the gate stops being set, so a production build can never activate
+// it accidentally — not via a stray import, not via a leaked reference.
+const SESSION_LOAD_FAULT_ENV = 'MIXDOG_SESSION_LOAD_FAULT_HOOKS';
+let _sessionLoadFaultHook = null;
+
+function _faultHooksEnabled() {
+    return process.env[SESSION_LOAD_FAULT_ENV] === '1';
+}
+
+export function _setSessionLoadFaultHook(hook) {
+    if (!_faultHooksEnabled()) {
+        _sessionLoadFaultHook = null;
+        return false;
+    }
+    _sessionLoadFaultHook = typeof hook === 'function' ? hook : null;
+    return _sessionLoadFaultHook !== null;
+}
+
+// Test/diagnostic view of the cache: proves a signature is never paired with
+// content that came from a different inode.
+export function _inspectSessionLoadCache() {
+    return [..._sessionLoadCache.entries()].map(([path, entry]) => ({
+        path,
+        signature: entry.signature,
+        session: entry.session,
+    }));
+}
+
+function _fault(phase, path, attempt) {
+    if (!_sessionLoadFaultHook) return;
+    if (!_faultHooksEnabled()) {
+        _sessionLoadFaultHook = null; // gate revoked after install: stay inert
+        return;
     }
-    let signature;
+    const injected = _sessionLoadFaultHook({ phase, path, attempt });
+    if (injected instanceof Error) throw injected;
+}
+
+// Only these mean "nothing is at this path right now". Everything else
+// (EACCES, EPERM, EIO, EBUSY, EMFILE, ELOOP, unknown) means a file is very
+// likely THERE and we simply cannot look at it: that must never be reported
+// as absence, because absence lets loadSession() fall back to in-memory
+// state and thereby mask an unreadable file that owns the identity.
+const ABSENT_CODES = new Set(['ENOENT', 'ENOTDIR']);
+
+// Observation states: 'present' (signature valid), 'absent' (ENOENT-class),
+// 'unreadable' (persistent/transient failure — fail closed).
+function _observe(path, attempt) {
     try {
+        _fault('stat', path, attempt);
         const info = statSync(path, { bigint: true });
-        signature = `${info.dev}:${info.ino}:${info.size}:${info.mtimeNs}`;
-    } catch {
-        _sessionLoadCache.delete(path);
-        return { exists: existsSync(path), session: null };
+        return { state: 'present', signature: `${info.dev}:${info.ino}:${info.size}:${info.mtimeNs}`, code: null };
+    } catch (err) {
+        const code = err?.code || 'EUNKNOWN';
+        if (ABSENT_CODES.has(code)) return { state: 'absent', signature: null, code };
+        return { state: 'unreadable', signature: null, code };
     }
-    const cached = _sessionLoadCache.get(path);
-    if (cached?.signature === signature) {
-        _sessionLoadCache.delete(path);
-        _sessionLoadCache.set(path, cached);
-        return { exists: true, session: cached.session };
+}
+
+// A decision is always derived from ONE observation that was actually made —
+// never from a second, independent existence probe (the old
+// `stat → null → existsSync(path)` pair was a TOCTOU window that could turn a
+// live file into {exists:false}).
+function _decide(observation) {
+    if (observation.state === 'absent') return { exists: false, session: null };
+    return { exists: true, session: null };
+}
+
+// Content is only this session's when it parses UNAMBIGUOUSLY and claims this
+// id. readTopLevelLifecycleRecord is the strict parse (no separate JSON.parse
+// authority to diverge from): a duplicate top-level `id` is last-wins under
+// JSON.parse, which would hand the runtime a foreign/ambiguous transcript to
+// serve, re-save and tombstone from. Ambiguity reads as corruption here —
+// `null` keeps the file owning the identity and fails closed.
+function _ownedSession(id, text) {
+    const record = readTopLevelLifecycleRecord(text);
+    if (isLifecycleUnreadable(record)) return null;
+    return record.id === id ? record.doc : null;
+}
+
+function _cacheStable(path, signature, session) {
+    _sessionLoadCache.delete(path);
+    _sessionLoadCache.set(path, { signature, session });
+    while (_sessionLoadCache.size > SESSION_LOAD_CACHE_LIMIT) {
+        const oldest = _sessionLoadCache.keys().next().value;
+        if (oldest === undefined) break;
+        _sessionLoadCache.delete(oldest);
     }
+}
+
+// The inode we stat'ed vanished under the read on the LAST attempt: no retry
+// is left, but a replacement may already own the path. Take ONE decisive
+// snapshot (observe, then read what is actually there) instead of classifying
+// from the observation alone — reporting {exists:true, session:null} for a
+// perfectly readable replacement is the same false corruption the retry loop
+// exists to avoid. Uncached: no identity was verified around this read.
+function _decisiveReplacementSnapshot(id, path, attempt) {
+    const observed = _observe(path, attempt);
+    if (observed.state === 'absent') return { exists: false, session: null };
+    if (observed.state !== 'present') return { exists: true, session: null };
+    let text = null;
     try {
-        const stored = JSON.parse(readFileSync(path, 'utf-8'));
-        if (stored?.id !== id) {
+        _fault('read', path, attempt);
+        text = readFileSync(path, 'utf-8');
+    } catch (err) {
+        const code = err?.code || 'EUNKNOWN';
+        return ABSENT_CODES.has(code) ? { exists: false, session: null } : { exists: true, session: null };
+    }
+    return { exists: true, session: _ownedSession(id, text) };
+}
+
+export function _readStoredSessionCached(id, path) {
+    const dataDir = getPluginData();
+    if (_sessionLoadCacheDataDir !== dataDir) {
+        _sessionLoadCacheDataDir = dataDir;
+        _sessionLoadCache.clear();
+    }
+    let last = { state: 'absent', signature: null, code: 'ENOENT' };
+    for (let attempt = 0; attempt < SESSION_LOAD_STABLE_ATTEMPTS; attempt++) {
+        // The final attempt must DECIDE — it may not defer to yet another
+        // observation, so a replacement landing on that last boundary is
+        // parsed (if its bytes are readable and ours) or reported as
+        // present-but-invalid, never as absence.
+        const isFinal = attempt === SESSION_LOAD_STABLE_ATTEMPTS - 1;
+        const before = _observe(path, attempt);
+        last = before;
+        if (before.state !== 'present') {
+            // Absent: possibly the unlink → rename hole, retry.
+            // Unreadable: EACCES/EIO/EBUSY — retry in case it is transient,
+            // but this observation already means "present, fail closed".
             _sessionLoadCache.delete(path);
-            return { exists: true, session: null };
+            continue;
+        }
+        const cached = _sessionLoadCache.get(path);
+        if (cached?.signature === before.signature) {
+            // The cached object was stored under a verified-stable signature,
+            // and dev/ino/size/mtimeNs still describe that same file.
+            _sessionLoadCache.delete(path);
+            _sessionLoadCache.set(path, cached);
+            return { exists: true, session: cached.session };
+        }
+        let text = null;
+        let readCode = null;
+        try {
+            _fault('read', path, attempt);
+            text = readFileSync(path, 'utf-8');
+        } catch (err) {
+            readCode = err?.code || 'EUNKNOWN';
         }
-        _sessionLoadCache.delete(path);
-        _sessionLoadCache.set(path, { signature, session: stored });
-        while (_sessionLoadCache.size > SESSION_LOAD_CACHE_LIMIT) {
-            const oldest = _sessionLoadCache.keys().next().value;
-            if (oldest === undefined) break;
-            _sessionLoadCache.delete(oldest);
+        if (readCode !== null) {
+            _sessionLoadCache.delete(path);
+            if (!ABSENT_CODES.has(readCode)) {
+                // EACCES/EIO/EBUSY on the read: the file is there and we
+                // cannot have it. Fail closed, now or after the retries.
+                last = { state: 'unreadable', signature: null, code: readCode };
+                if (isFinal) return { exists: true, session: null };
+                continue;
+            }
+            // The inode we stat'ed vanished under us: replacement window, not
+            // corruption. Retry and let the new file answer.
+            last = { state: 'absent', signature: null, code: readCode };
+            // On the last boundary there is no retry left: read the
+            // replacement rather than classify it from a bare stat.
+            if (isFinal) return _decisiveReplacementSnapshot(id, path, attempt);
+            continue;
+        }
+        const after = _observe(path, attempt);
+        if (after.state !== 'present' || after.signature !== before.signature) {
+            // A rename landed around the read — these bytes may belong to a
+            // different inode than `before`, so they must never be cached
+            // under it.
+            _sessionLoadCache.delete(path);
+            last = after;
+            if (!isFinal) continue;
+            // Last boundary: the bytes still came from a real file at this
+            // path. If they are a valid session for this id, answer with them
+            // (uncached, since no identity was verified) rather than invent an
+            // absence/null for a perfectly readable replacement; otherwise
+            // stay conservatively present-but-invalid.
+            return { exists: true, session: _ownedSession(id, text) };
+        }
+        // Stable snapshot: `text` provably belongs to the file identified by
+        // `before`. Whatever it says is now authoritative, including "this is
+        // not valid session JSON" / "this is a foreign id" — fail closed.
+        const stored = _ownedSession(id, text);
+        if (stored === null) {
+            _sessionLoadCache.delete(path);
+            return { exists: true, session: null };
         }
+        _cacheStable(path, before.signature, stored);
         return { exists: true, session: stored };
-    } catch {
-        _sessionLoadCache.delete(path);
-        return { exists: true, session: null };
     }
+    // Bounded retries exhausted. `last` is the most recent observation we
+    // actually made, so the answer needs no further syscall: ENOENT-class ⇒
+    // genuinely absent, anything else ⇒ present-but-unreadable, which keeps
+    // owning the identity and fails closed like real external corruption.
+    _sessionLoadCache.delete(path);
+    return _decide(last);
 }

package/src/runtime/agent/orchestrator/session/store/save-fault.mjs

@@ -0,0 +1,313 @@
+/**
+ * Session-save commit faults and scratch-file hygiene.
+ *
+ * Two responsibilities, both about the *commit edge* of the store's atomic
+ * save (write `<id>.json.<hex>.tmp`, then rename it onto `<id>.json`):
+ *
+ *  1. A deterministic commit fault, STRUCTURALLY GATED to explicit test mode
+ *     (MIXDOG_SESSION_SAVE_FAULT_HOOKS=1). The synthetic error is raised
+ *     BEFORE renameSync runs, so the destination is never unlinked, truncated
+ *     or replaced — the last-good canonical JSON survives the fault byte for
+ *     byte. This replaces destructive "make the path a directory" fault rigs,
+ *     which prove nothing about canonical integrity because they destroy the
+ *     canonical file first. There is deliberately NO env-driven fault
+ *     configuration: nothing in a production environment can arm this.
+ *  2. Conservative reclamation of the store's OWN abandoned scratch files.
+ *     A failed commit can leave `<id>.json.<hex>.tmp` bytes behind; the store
+ *     used to swallow the unlink failure and leak them forever. Only paths
+ *     THIS realm minted and then failed to unlink are retried, and only when
+ *     they match the store's exact scratch naming. The sessions directory is
+ *     never scanned: an unregistered scratch file may be the save worker's or
+ *     another process's ACTIVE commit, which no registry here can see.
+ */
+import { unlinkSync } from 'fs';
+import { basename } from 'path';
+import { _renameWithRetrySync } from './serialize.mjs';
+
+// `<id>.json.<12 hex>.tmp` — exactly what the store mints
+// (`sessionPath(id) + '.' + randomBytes(6).toString('hex') + '.tmp'`).
+// Anything else in sessions/ is somebody else's file and is left alone.
+const SAVE_TMP_RE = /^[A-Za-z0-9_-]+\.json\.[0-9a-f]{12}\.tmp$/;
+const ORPHAN_TMP_SWEEP_LIMIT = 64;            // registered paths retried per chunk
+const ORPHAN_TMP_DRAIN_MAX_ATTEMPTS = 4096;   // hard ceiling for one drain pass
+const ORPHAN_TMP_TRACK_MAX = 256;             // soft cap: only reclaimed paths leave
+const UNLINK_RETRY_CODES = new Set(['EPERM', 'EACCES', 'EBUSY']);
+
+const _activeSaveTmp = new Set();   // scratch paths this thread is writing now
+const _orphanSaveTmp = new Set();   // scratch paths whose unlink failed
+
+export function _trackSaveTmp(tmp) {
+    if (tmp) _activeSaveTmp.add(tmp);
+    return tmp;
+}
+
+export function _untrackSaveTmp(tmp) {
+    if (tmp) _activeSaveTmp.delete(tmp);
+}
+
+/**
+ * Register a scratch path as explicitly orphaned by THIS realm — the only
+ * class of file the sweeper may remove. Exported for the store's failure
+ * paths and for tests.
+ */
+export function _registerOrphanSaveTmp(tmp) {
+    if (!tmp) return;
+    _activeSaveTmp.delete(tmp);
+    _orphanSaveTmp.add(tmp);
+    if (_orphanSaveTmp.size <= ORPHAN_TMP_TRACK_MAX) return;
+    // Over the soft cap: try to RECLAIM the oldest entries instead of evicting
+    // them. Dropping a path that is still on disk turns it into an orphan no
+    // realm owns any more, which is exactly how scratch files leaked forever.
+    // A path whose unlink still fails keeps its registry slot (retry ownership).
+    for (const oldest of [..._orphanSaveTmp]) {
+        if (_orphanSaveTmp.size <= ORPHAN_TMP_TRACK_MAX) break;
+        if (oldest === tmp) continue;
+        try {
+            unlinkSync(oldest);
+            _orphanSaveTmp.delete(oldest);
+        } catch (err) {
+            if (err?.code === 'ENOENT') _orphanSaveTmp.delete(oldest);
+        }
+    }
+}
+
+/**
+ * Drop a scratch file. Retries the transient win32 codes once, and on final
+ * failure registers the path so the bounded sweeper retries it later instead
+ * of leaking it (the previous `catch { /* ignore *\/ }` was terminal).
+ */
+export function _discardSaveTmp(tmp) {
+    if (!tmp) return true;
+    _activeSaveTmp.delete(tmp);
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            unlinkSync(tmp);
+            _orphanSaveTmp.delete(tmp);
+            return true;
+        } catch (err) {
+            if (err?.code === 'ENOENT') {
+                _orphanSaveTmp.delete(tmp);
+                return true;
+            }
+            if (!UNLINK_RETRY_CODES.has(err?.code)) break;
+        }
+    }
+    _registerOrphanSaveTmp(tmp);
+    return false;
+}
+
+/**
+ * Retry the unlink of scratch files THIS realm minted and abandoned.
+ *
+ * Bounded: at most `limit` registered paths are retried per chunk (default
+ * 64). `drain: true` (exit) walks the WHOLE registry in such chunks, at most
+ * ONE attempt per path and at most `maxAttempts` in total, so a registry
+ * larger than one chunk cannot survive process exit while the pass still
+ * terminates.
+ * Conservative: no directory scan, so a scratch file this realm never
+ * registered — possibly the save worker's or another process's in-flight
+ * commit — is never even looked at, and a registered path whose name is not
+ * the store's exact scratch pattern is dropped from the registry rather than
+ * unlinked. A path whose unlink FAILS stays registered, so a transient
+ * failure is retried by the next pass instead of leaking.
+ * Returns the number of scratch files reclaimed.
+ */
+export function sweepOrphanSessionTmpFiles(options = {}) {
+    const limit = Number.isFinite(options.limit) && options.limit > 0
+        ? options.limit
+        : ORPHAN_TMP_SWEEP_LIMIT;
+    if (options.drain !== true) return _sweepOrphanChunk(limit).removed;
+    const budget = Number.isFinite(options.maxAttempts) && options.maxAttempts > 0
+        ? options.maxAttempts
+        : ORPHAN_TMP_DRAIN_MAX_ATTEMPTS;
+    // One attempt per path per drain: `attempted` is what makes the loop
+    // terminate even when every remaining unlink keeps failing.
+    const attempted = new Set();
+    let removed = 0;
+    let spent = 0;
+    while (spent < budget) {
+        const chunk = _sweepOrphanChunk(Math.min(limit, budget - spent), attempted);
+        if (chunk.attempts === 0) break;
+        removed += chunk.removed;
+        spent += chunk.attempts;
+    }
+    return removed;
+}
+
+function _sweepOrphanChunk(limit, attempted = null) {
+    let removed = 0;
+    let attempts = 0;
+    for (const path of [..._orphanSaveTmp]) {
+        if (attempts >= limit) break;
+        if (attempted?.has(path)) continue;      // already retried in this drain
+        if (_activeSaveTmp.has(path)) continue;  // re-minted since it was registered
+        if (!SAVE_TMP_RE.test(basename(path))) { // never an unrelated/external file
+            _orphanSaveTmp.delete(path);
+            continue;
+        }
+        attempts++;
+        attempted?.add(path);
+        try {
+            unlinkSync(path);
+            _orphanSaveTmp.delete(path);
+            removed++;
+        } catch (err) {
+            if (err?.code === 'ENOENT') _orphanSaveTmp.delete(path);
+        }
+    }
+    return { removed, attempts };
+}
+
+// ── Deterministic commit-fault injection (test-gated) ───────────────────────
+// STRUCTURAL GATE: the seam is inert unless the process was started in
+// explicit fault-injection test mode. Arming it without the gate is refused
+// (setSessionSaveFault returns false), and armed state is dropped the moment
+// the gate stops being set, so no production process — and no environment
+// variable — can make a real save fail.
+const SESSION_SAVE_FAULT_ENV = 'MIXDOG_SESSION_SAVE_FAULT_HOOKS';
+const _programmaticFault = { ids: null, remaining: 0, code: 'EIO' };
+// Config epoch: bumped on every change so a realm that mirrors this state
+// (the save worker) can detect a change — including a CLEAR — without diffing
+// sets. Consumption of `remaining` never bumps it.
+let _faultConfigEpoch = 0;
+let _faultChangeListener = null;
+// Authoritative state pushed in from the owning realm (parent → save worker).
+// Once applied, it REPLACES programmatic resolution in this realm: the worker
+// is long-lived and never runs setSessionSaveFault itself.
+let _syncedFaultApplied = false;
+let _syncedFault = null;
+
+function _faultInjectionEnabled() {
+    return process.env[SESSION_SAVE_FAULT_ENV] === '1';
+}
+
+/**
+ * The store's explicit fault-injection test mode, shared by every structurally
+ * gated seam in the store (see save-worker's detach seam). Production never
+ * has this set, so those seams cannot be reached there.
+ */
+export function _sessionStoreTestMode() {
+    return _faultInjectionEnabled();
+}
+
+function _clearFaultState() {
+    _programmaticFault.ids = null;
+    _programmaticFault.remaining = 0;
+    _programmaticFault.code = 'EIO';
+    _syncedFaultApplied = false;
+    _syncedFault = null;
+}
+
+function _idSet(ids) {
+    if (ids === '*' || ids === true) return '*';
+    const list = Array.isArray(ids) ? ids : [ids];
+    return new Set(list.map((v) => String(v)).filter(Boolean));
+}
+
+/**
+ * Configure (or clear with a falsy argument) in-process commit faults. Only
+ * honoured in explicit fault-injection test mode; returns whether the fault
+ * was armed.
+ * `{ ids: 'sess_x' | ['a','b'] | '*', count?: number, code?: string }`.
+ * `count` is the number of commits to fail (default: unlimited), so a test can
+ * fail exactly one save and let the NEXT save land without extra bookkeeping.
+ */
+export function setSessionSaveFault(spec = null) {
+    if (!spec || !_faultInjectionEnabled()) {
+        _clearFaultState();
+        _faultConfigEpoch++;
+        _notifyFaultChange();
+        return false;
+    }
+    _programmaticFault.ids = _idSet(spec.ids ?? spec.id ?? '*');
+    const count = Number(spec.count);
+    _programmaticFault.remaining = Number.isFinite(count) && count >= 0 ? count : Infinity;
+    _programmaticFault.code = typeof spec.code === 'string' && spec.code ? spec.code : 'EIO';
+    _faultConfigEpoch++;
+    _notifyFaultChange();
+    return true;
+}
+
+function _notifyFaultChange() {
+    if (typeof _faultChangeListener === 'function') {
+        try { _faultChangeListener(); } catch { /* best-effort */ }
+    }
+}
+
+/** Register the realm-sync hook (save-worker.mjs pushes state to the worker). */
+export function _onSessionSaveFaultChange(listener) {
+    _faultChangeListener = typeof listener === 'function' ? listener : null;
+}
+
+/**
+ * Cheap change token for the fault config. A mirroring realm re-syncs only
+ * when this token moves, so steady-state saves pay one compare and never a
+ * postMessage.
+ */
+export function sessionSaveFaultSyncKey() {
+    return String(_faultConfigEpoch);
+}
+
+/** Wire form of the currently effective fault state (null when disabled). */
+export function serializeSessionSaveFault() {
+    const state = _effectiveFaultState();
+    if (!state) return null;
+    return {
+        ids: state.ids === '*' ? '*' : [...state.ids],
+        remaining: state.remaining === Infinity ? null : state.remaining,
+        code: state.code,
+    };
+}
+
+/**
+ * Adopt fault state pushed from the owning realm. `null` DISABLES injection in
+ * this realm outright, which is what makes `setSessionSaveFault(null)` stop
+ * worker-thread faults too.
+ */
+export function applySessionSaveFault(serialized) {
+    _syncedFaultApplied = true;
+    _syncedFault = (serialized && _faultInjectionEnabled())
+        ? {
+            ids: serialized.ids === '*' ? '*' : _idSet(serialized.ids),
+            remaining: serialized.remaining === null || serialized.remaining === undefined
+                ? Infinity
+                : Number(serialized.remaining),
+            code: serialized.code || 'EIO',
+        }
+        : null;
+}
+
+function _effectiveFaultState() {
+    // Gate revoked after arming: stay inert and forget the armed state.
+    if (!_faultInjectionEnabled()) {
+        if (_programmaticFault.ids || _syncedFault) _clearFaultState();
+        return null;
+    }
+    // A synced realm is fully governed by its owner — never by a programmatic
+    // call that never happened there.
+    const state = _syncedFaultApplied ? _syncedFault : (_programmaticFault.ids ? _programmaticFault : null);
+    return state && state.remaining > 0 ? state : null;
+}
+
+function _takeInjectedCommitFault(id) {
+    const state = _effectiveFaultState();
+    if (!state) return null;
+    if (state.ids !== '*' && !state.ids.has(id)) return null;
+    if (state.remaining !== Infinity) state.remaining -= 1;
+    const err = new Error(`[session-store] injected save commit fault for ${id}`);
+    err.code = state.code;
+    err.injectedSaveFault = true;
+    return err;
+}
+
+/**
+ * Commit a staged scratch file onto its canonical path. The injected fault is
+ * raised before the rename, so a fault leaves BOTH files exactly as they were:
+ * the canonical destination stays the last-good session JSON, and the scratch
+ * file is the caller's to discard (see _discardSaveTmp).
+ */
+export function _commitSessionWrite(tmp, target, id) {
+    const injected = _takeInjectedCommitFault(id);
+    if (injected) throw injected;
+    return _renameWithRetrySync(tmp, target);
+}