codex-multi-auth 2.17.2 → 2.18.0

package/dist/lib/storage/json-store-lock.js

@@ -0,0 +1,259 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { promises as fs } from "node:fs";
+import { dirname } from "node:path";
+import { withRetry } from "../fs-retry.js";
+import { tempPathFor } from "../temp-path.js";
+import { withFileTransactionLock } from "./file-lock.js";
+/**
+ * Shared concurrency machinery for the file-backed governance JSON stores
+ * (config, unified settings, budget guards, routing profiles, account
+ * policies, local client tokens, quota cache).
+ *
+ * Three cooperating guards, extracted from lib/config.ts's save path so every
+ * store gets the same semantics instead of each re-deriving a subset:
+ *
+ * 1. {@link withJsonStoreWriteQueue} — a per-path in-process promise queue
+ *    that serializes writers inside this process (replaces each store's
+ *    hand-rolled `writeQueue` module variable).
+ * 2. {@link withJsonStoreFileLock} — a cross-process lock directory
+ *    (`<path>.write-lock`) delegated to {@link withFileTransactionLock}: a
+ *    pre-populated candidate directory is published by atomic rename, and a
+ *    crashed holder's lock is recovered only when its owner PID is dead —
+ *    live holders are NEVER evicted, so a takeover can never unlink a newly
+ *    acquired lock (the stale-check→unlink TOCTOU that a single lockfile
+ *    cannot close: POSIX has no delete-if-unchanged primitive, and renaming
+ *    the file aside leaves an empty path another `wx` create can claim).
+ *    The promise queue only serializes THIS process; the lock directory
+ *    closes the read→check→merge→rename TOCTOU window against OTHER
+ *    processes. Re-entrant within one async context so a nested write on the
+ *    same path cannot deadlock itself.
+ * 3. mtime compare-and-swap — {@link getJsonStoreFileMtimeMs} /
+ *    {@link assertJsonStoreFileMtimeUnchanged} /
+ *    {@link writeJsonStoreFileAtomicWithRetry} plus
+ *    {@link withJsonStoreCasRetry}: each attempt re-stats, re-reads, and
+ *    re-merges against the latest on-disk state before writing, aborting with
+ *    `ESTALE` when another writer moved the file under us. This stays on as a
+ *    second-line guard for writers that do not take the lockfile.
+ *
+ * Storage layer: this module sits below the governance stores (which live in
+ * lib/ root) and below lib/config.ts; it must only depend on leaf utilities.
+ */
+const JSON_STORE_WRITE_RETRY_CODES = new Set(["EBUSY", "EPERM"]);
+const JSON_STORE_READ_RETRY_CODES = new Set(["EBUSY", "EPERM", "EAGAIN"]);
+const JSON_STORE_CAS_MAX_ATTEMPTS = 3;
+/**
+ * Stamp `updatedAt` for a per-key governance entry with a hybrid logical
+ * floor: when the wall clock regressed below the timestamp the entry being
+ * overwritten already carries, stamp `prior + 1` instead of `now`. Every
+ * upsert-only store merges with `updatedAt >=`, so a backward clock jump
+ * would otherwise stamp a semantically-newer write below its own
+ * predecessor and the merge would silently drop it. Equal or forward wall
+ * times pass through unchanged — ties already resolve to the caller's
+ * write under `>=`.
+ *
+ * `prior` is the entry the writer saw, which can trail the freshest on-disk
+ * entry when a concurrent writer lands between the caller's load and its
+ * save; baseline-aware save merges re-apply this same floor against the
+ * on-disk entry at merge time so the edit still cannot be lost.
+ */
+export function stampUpdatedAt(now, prior) {
+    return typeof prior === "number" && Number.isFinite(prior) && now < prior
+        ? prior + 1
+        : now;
+}
+// ---------------------------------------------------------------------------
+// 1. Per-path in-process write queue
+// ---------------------------------------------------------------------------
+const jsonStoreWriteQueues = new Map();
+// Async-local re-entrancy map for the write queue (keyed by the raw path
+// string, matching the queue key): a nested withJsonStoreWriteQueue on the
+// same path inside one async context runs inside the outer critical section
+// instead of deadlocking on its own queue slot — e.g. config.ts wraps
+// saveUnifiedPluginConfig (which queues on settings.json) in an outer queue
+// for the same path.
+const jsonStoreQueueLeases = new AsyncLocalStorage();
+/**
+ * Serialize `task` behind the previous write queued for `path`, so same-file
+ * writers inside this process run one at a time in submission order. A failed
+ * predecessor never blocks or fails successors. Re-entrant for the same path
+ * within one async context.
+ *
+ * This is the per-path generalization of the module-local `writeQueue`
+ * variables the governance stores used to keep by hand.
+ */
+export async function withJsonStoreWriteQueue(path, task) {
+    const held = jsonStoreQueueLeases.getStore();
+    if (held?.get(path)?.active) {
+        return task();
+    }
+    const previous = jsonStoreWriteQueues.get(path) ?? Promise.resolve();
+    const lease = { active: true };
+    const context = new Map(held);
+    context.set(path, lease);
+    const queued = previous.catch(() => { }).then(async () => {
+        try {
+            return await jsonStoreQueueLeases.run(context, task);
+        }
+        finally {
+            lease.active = false;
+        }
+    });
+    // Store the settled (never-rejecting) wrapper so successors chain cleanly;
+    // keep the reference for the same-object check below.
+    const stored = queued.then(() => undefined, () => undefined);
+    jsonStoreWriteQueues.set(path, stored);
+    try {
+        return await queued;
+    }
+    finally {
+        if (jsonStoreWriteQueues.get(path) === stored) {
+            jsonStoreWriteQueues.delete(path);
+        }
+    }
+}
+/** Test helper: drop queued-write bookkeeping (all paths, or one when given). */
+export function resetJsonStoreWriteQueuesForTests(path) {
+    if (path !== undefined) {
+        jsonStoreWriteQueues.delete(path);
+        return;
+    }
+    jsonStoreWriteQueues.clear();
+}
+// ---------------------------------------------------------------------------
+// 2. mtime compare-and-swap + atomic JSON write
+// ---------------------------------------------------------------------------
+/**
+ * Stat `filePath` for its mtime with bounded transient-FS retry (the save
+ * path is Windows-sensitive: a single transient EBUSY/EPERM/EAGAIN from an
+ * AV/indexer lock must not abort the whole save). ENOENT returns `null`
+ * immediately; on exhaustion the last failure surfaces so the caller treats
+ * it as a real save error rather than a phantom missing file.
+ */
+export async function getJsonStoreFileMtimeMs(filePath) {
+    return withRetry(async () => {
+        try {
+            return (await fs.stat(filePath)).mtimeMs;
+        }
+        catch (error) {
+            if (error?.code === "ENOENT") {
+                return null;
+            }
+            throw error;
+        }
+    }, {
+        maxAttempts: 5,
+        backoffMs: (attempt) => 10 * 2 ** (attempt - 1),
+        retryableCodes: JSON_STORE_READ_RETRY_CODES,
+    });
+}
+/**
+ * The `ESTALE` signal used by the CAS retry loop: the file's mtime moved
+ * between the caller's stat and its write, so the attempt must re-read and
+ * re-merge against the latest on-disk state instead of clobbering it.
+ */
+export function createJsonStoreStaleError(filePath) {
+    const staleError = new Error(`JSON store at ${filePath} changed on disk during save; retrying with latest state.`);
+    staleError.code = "ESTALE";
+    return staleError;
+}
+/**
+ * Throw `ESTALE` when `filePath`'s current mtime differs from
+ * `expectedMtimeMs` (`null` means "file must still be absent"). Writers that
+ * keep their own temp+rename flow call this just before the rename, matching
+ * {@link writeJsonStoreFileAtomicWithRetry}'s inline check.
+ */
+export async function assertJsonStoreFileMtimeUnchanged(filePath, expectedMtimeMs) {
+    const currentMtimeMs = await getJsonStoreFileMtimeMs(filePath);
+    if (currentMtimeMs !== expectedMtimeMs) {
+        throw createJsonStoreStaleError(filePath);
+    }
+}
+/**
+ * Atomic JSON write: serialize `payload` pretty-printed with a trailing
+ * newline to a crypto-random sibling temp file, then rename it over
+ * `filePath` with bounded transient-FS retry. Optionally CAS-checks the
+ * target mtime first and fsyncs the temp file; on failure the temp is
+ * removed best-effort.
+ */
+export async function writeJsonStoreFileAtomicWithRetry(filePath, payload, options) {
+    const tempPath = tempPathFor(filePath);
+    await fs.mkdir(dirname(filePath), { recursive: true });
+    const handle = await fs.open(tempPath, "w", options?.mode);
+    try {
+        await handle.writeFile(`${JSON.stringify(payload, null, 2)}\n`, "utf8");
+        if (options?.fsync) {
+            await handle.sync();
+        }
+    }
+    finally {
+        await handle.close();
+    }
+    let renamed = false;
+    try {
+        if (options && "expectedMtimeMs" in options) {
+            await assertJsonStoreFileMtimeUnchanged(filePath, options.expectedMtimeMs ?? null);
+        }
+        await withRetry(() => fs.rename(tempPath, filePath), {
+            maxAttempts: 5,
+            backoffMs: (attempt) => 10 * 2 ** (attempt - 1),
+            retryableCodes: options?.retryableCodes ?? JSON_STORE_WRITE_RETRY_CODES,
+        });
+        renamed = true;
+    }
+    finally {
+        if (!renamed) {
+            try {
+                await fs.unlink(tempPath);
+            }
+            catch {
+                // Best-effort temp cleanup.
+            }
+        }
+    }
+}
+/**
+ * Run `task`, retrying `ESTALE` CAS aborts so each attempt can re-read and
+ * re-merge against the latest on-disk state (matches the config save loop:
+ * 3 attempts, immediate retry, ESTALE-only).
+ */
+export async function withJsonStoreCasRetry(task) {
+    return withRetry(task, {
+        maxAttempts: JSON_STORE_CAS_MAX_ATTEMPTS,
+        backoffMs: 0,
+        retryableCodes: ["ESTALE"],
+    });
+}
+// ---------------------------------------------------------------------------
+// 3. Cross-process lockfile
+// ---------------------------------------------------------------------------
+const JSON_STORE_LOCK_WAIT_TIMEOUT_MS = 10_000;
+/**
+ * Cross-process mutex for a JSON store file, delegated to the proven
+ * candidate-directory transaction lock in lib/storage/file-lock.ts: each
+ * acquirer stages `<path>.write-lock.candidate-*` containing its unique
+ * `<host>.<pid>.<uuid>` owner file, then publishes it with a single atomic
+ * `rename` (which only succeeds while the lock directory is absent or empty,
+ * so there is no ownerless acquisition window). A crashed holder's lock is
+ * recovered by unlinking exactly that dead owner's unique filename and
+ * removing the directory only while it is still empty — an `rmdir` can never
+ * erase a lock that was republished in the meantime, so takeover can never
+ * delete another owner's live lock. Waiters on a live holder retry inside
+ * `waitTimeoutMs` (default 10s), then this wrapper surfaces the exhaustion
+ * as `ELOCKTIMEOUT`. Re-entrant for the same resolved path within one async
+ * context.
+ */
+export async function withJsonStoreFileLock(targetPath, task, options) {
+    try {
+        return await withFileTransactionLock(targetPath, task, {
+            waitMs: options?.waitTimeoutMs ?? JSON_STORE_LOCK_WAIT_TIMEOUT_MS,
+        });
+    }
+    catch (error) {
+        if (error?.code === "ELOCKED") {
+            const timeoutError = new Error(`Timed out acquiring JSON store lock at ${targetPath}.`);
+            timeoutError.code = "ELOCKTIMEOUT";
+            throw timeoutError;
+        }
+        throw error;
+    }
+}

package/dist/lib/storage/metadata-section.d.ts

@@ -13,4 +13,3 @@ export declare function buildMetadataSection<TSnapshot extends {
     validSnapshotCount: number;
     snapshots: TSnapshot[];
 };
-//# sourceMappingURL=metadata-section.d.ts.map

package/dist/lib/storage/migrations.d.ts

@@ -33,4 +33,3 @@ export interface AccountStorageV1 {
 }
 export declare function migrateV1ToV3(v1: AccountStorageV1): AccountStorageV3;
 export {};
-//# sourceMappingURL=migrations.d.ts.map

package/dist/lib/storage/migrations.js

@@ -7,38 +7,51 @@
  * ./public-types.ts.
  */
 import { MODEL_FAMILIES } from "../request/helpers/model-map.js";
+import { isRecord } from "./record-utils.js";
 function nowMs() {
     return Date.now();
 }
 export function migrateV1ToV3(v1) {
     const now = nowMs();
+    const rawActiveIndexByFamily = isRecord(v1.activeIndexByFamily)
+        ? v1
+            .activeIndexByFamily
+        : {};
     return {
         version: 3,
-        accounts: v1.accounts.map((account) => {
+        accounts: v1.accounts
+            .filter((account) => account !== null && typeof account === "object")
+            .map((account) => {
+            const { rateLimitResetTime, rateLimitResetTimes: existingResets, ...passthrough } = account;
+            // A pre-existing V3 map wins per key; the legacy scalar only fills
+            // families the map does not already cover.
             const rateLimitResetTimes = {};
-            if (typeof account.rateLimitResetTime === "number" && account.rateLimitResetTime > now) {
+            if (isRecord(existingResets)) {
+                for (const [family, value] of Object.entries(existingResets)) {
+                    if (typeof value === "number") {
+                        rateLimitResetTimes[family] = value;
+                    }
+                }
+            }
+            if (typeof rateLimitResetTime === "number" && rateLimitResetTime > now) {
                 for (const family of MODEL_FAMILIES) {
-                    rateLimitResetTimes[family] = account.rateLimitResetTime;
+                    rateLimitResetTimes[family] ??= rateLimitResetTime;
                 }
             }
             return {
-                accountId: account.accountId,
-                accountIdSource: account.accountIdSource,
-                accountLabel: account.accountLabel,
-                email: account.email,
-                refreshToken: account.refreshToken,
-                accessToken: account.accessToken,
-                expiresAt: account.expiresAt,
-                enabled: account.enabled,
-                addedAt: account.addedAt,
-                lastUsed: account.lastUsed,
-                lastSwitchReason: account.lastSwitchReason,
-                rateLimitResetTimes: Object.keys(rateLimitResetTimes).length > 0 ? rateLimitResetTimes : undefined,
-                coolingDownUntil: account.coolingDownUntil,
-                cooldownReason: account.cooldownReason,
+                ...passthrough,
+                rateLimitResetTimes: Object.keys(rateLimitResetTimes).length > 0
+                    ? rateLimitResetTimes
+                    : undefined,
             };
         }),
         activeIndex: v1.activeIndex,
-        activeIndexByFamily: Object.fromEntries(MODEL_FAMILIES.map((family) => [family, v1.activeIndex])),
+        activeIndexByFamily: Object.fromEntries(MODEL_FAMILIES.map((family) => {
+            const perFamily = rawActiveIndexByFamily[family];
+            return [
+                family,
+                typeof perFamily === "number" ? perFamily : v1.activeIndex,
+            ];
+        })),
     };
 }

package/dist/lib/storage/named-backup-entry.d.ts

@@ -12,4 +12,3 @@ export declare function exportNamedBackupEntry(params: {
     getStoragePath: () => string;
     exportAccounts: (filePath: string, force?: boolean, beforeCommit?: (resolvedPath: string) => Promise<void> | void) => Promise<void>;
 }): Promise<string>;
-//# sourceMappingURL=named-backup-entry.d.ts.map

package/dist/lib/storage/named-backups-entry.d.ts

@@ -16,4 +16,3 @@ export declare function getNamedBackupsEntry(params: {
     }>;
     logDebug: (message: string, details: Record<string, unknown>) => void;
 }): Promise<NamedBackupSummary[]>;
-//# sourceMappingURL=named-backups-entry.d.ts.map

package/dist/lib/storage/named-backups.d.ts

@@ -12,4 +12,3 @@ export declare function collectNamedBackups(storagePath: string, deps: {
     }>;
     logDebug: (message: string, details: Record<string, unknown>) => void;
 }): Promise<NamedBackupSummary[]>;
-//# sourceMappingURL=named-backups.d.ts.map

package/dist/lib/storage/path-state.d.ts

@@ -10,4 +10,3 @@ export declare function setStoragePathDirectState(state: StoragePathState): void
 export declare function runWithStoragePathState<T>(state: StoragePathState, fn: () => T | Promise<T>): Promise<T>;
 /** Temporarily use the shared pool without mutating the caller or sibling async scopes. */
 export declare function runWithGlobalStoragePath<T>(fn: () => T | Promise<T>): Promise<T>;
-//# sourceMappingURL=path-state.d.ts.map

package/dist/lib/storage/paths.d.ts

@@ -59,4 +59,3 @@ export declare function resolveProjectStorageIdentityRoot(projectRoot: string):
 export declare function isProjectDirectory(dir: string): boolean;
 export declare function findProjectRoot(startDir: string): string | null;
 export declare function resolvePath(filePath: string): string;
-//# sourceMappingURL=paths.d.ts.map

package/dist/lib/storage/pending-auth.d.ts

@@ -11,8 +11,14 @@ export declare function recordPendingAuth(storagePath: string, auth: {
 }): Promise<void>;
 /** Overlay pending rotated credentials on rows that still hold the spent token. */
 export declare function applyPendingAuth(storagePath: string, storage: AccountStorageV3 | null): Promise<AccountStorageV3 | null>;
-/** After a save, drop entries whose spent token is no longer on disk (persisted or superseded). */
-export declare function prunePendingAuth(storagePath: string, saved: AccountStorageV3): Promise<void>;
+/**
+ * After a save, drop entries whose spent token is no longer in any restorable
+ * state. `saved` is the primary content just persisted; callers may also
+ * supply `restorableRefreshTokens` — refresh tokens still present in recovery
+ * sources (rotating/discovered backups, a WAL payload) — since a restore can
+ * resurface a spent token, its entry must survive until no source holds it.
+ * A scan failure keeps every entry: retention is the safe direction.
+ */
+export declare function prunePendingAuth(storagePath: string, saved: AccountStorageV3, restorableRefreshTokens?: () => Promise<Iterable<string>>): Promise<void>;
 /** Coordinate resets with pending credential writers, including Windows rename locks. */
 export declare function clearPendingAuth(storagePath: string): Promise<void>;
-//# sourceMappingURL=pending-auth.d.ts.map

package/dist/lib/storage/pending-auth.js

@@ -79,15 +79,17 @@ export async function recordPendingAuth(storagePath, auth) {
         }
         const prior = hash(auth.priorRefreshToken);
         const entries = (await read(path)).filter((entry) => entry.prior !== prior && entry.prior !== hash(auth.refreshToken));
-        // Rotating a token that is itself only journaled: the row on disk still holds
-        // the original spent token, so extend that entry rather than add one that
-        // no disk row can match.
+        // Rotating a token that is itself only journaled: extend that entry to the
+        // newest credential, but ALSO keep an entry keyed by the token this
+        // rotation just spent. A backup slot or WAL can still hold that
+        // intermediate token, and pruning now keeps entries whose spent token any
+        // recovery source can surface — a stale-snapshot restore then self-heals
+        // straight to the newest credential instead of reviving a spent token.
         const chained = entries.find((entry) => entry.refreshToken === auth.priorRefreshToken);
-        const current = chained ?? { prior, recordId: auth.recordId, refreshToken: auth.refreshToken, accessToken: auth.accessToken, expiresAt: auth.expiresAt, at: auth.at };
         if (chained)
             Object.assign(chained, { recordId: chained.recordId ?? auth.recordId, refreshToken: auth.refreshToken, accessToken: auth.accessToken, expiresAt: auth.expiresAt, at: auth.at });
-        else
-            entries.push(current);
+        const current = { prior, recordId: auth.recordId, refreshToken: auth.refreshToken, accessToken: auth.accessToken, expiresAt: auth.expiresAt, at: auth.at };
+        entries.push(current);
         const excess = entries.length - MAX_ENTRIES;
         if (excess > 0) {
             // Drop the oldest other entries, never the credential being recorded now.
@@ -134,14 +136,34 @@ export async function applyPendingAuth(storagePath, storage) {
     }
     return storage;
 }
-/** After a save, drop entries whose spent token is no longer on disk (persisted or superseded). */
-export async function prunePendingAuth(storagePath, saved) {
+/**
+ * After a save, drop entries whose spent token is no longer in any restorable
+ * state. `saved` is the primary content just persisted; callers may also
+ * supply `restorableRefreshTokens` — refresh tokens still present in recovery
+ * sources (rotating/discovered backups, a WAL payload) — since a restore can
+ * resurface a spent token, its entry must survive until no source holds it.
+ * A scan failure keeps every entry: retention is the safe direction.
+ */
+export async function prunePendingAuth(storagePath, saved, restorableRefreshTokens) {
     const path = getPendingAuthPath(storagePath);
     const current = await read(path);
     if (!current.length)
         return;
     await withFileTransactionLock(path, async () => {
         const spent = new Set(saved.accounts.map((account) => hash(account.refreshToken)));
+        if (restorableRefreshTokens) {
+            try {
+                for (const token of await restorableRefreshTokens()) {
+                    spent.add(hash(token));
+                }
+            }
+            catch (error) {
+                log.warn("Recovery-source scan failed; keeping all pending rotated credentials", {
+                    code: typeof error.code === "string" && /^[A-Z_]{1,40}$/.test(error.code ?? "") ? error.code : "UNKNOWN",
+                });
+                return;
+            }
+        }
         const entries = await read(path);
         const remaining = entries.filter((entry) => spent.has(entry.prior));
         if (remaining.length !== entries.length)

package/dist/lib/storage/project-migration.d.ts

@@ -7,4 +7,3 @@ export declare function loadNormalizedStorageFromPath(path: string, label: strin
     logWarn: (message: string, details: Record<string, unknown>) => void;
 }): Promise<AccountStorageV3 | null>;
 export declare function mergeStorageForMigration(current: AccountStorageV3 | null, incoming: AccountStorageV3, normalizeAccountStorage: (value: unknown) => AccountStorageV3 | null, findMatchingAccountIndex: (accounts: AccountStorageV3["accounts"], candidate: AccountStorageV3["accounts"][number]) => number | undefined): AccountStorageV3;
-//# sourceMappingURL=project-migration.d.ts.map

package/dist/lib/storage/public-types.d.ts

@@ -86,4 +86,3 @@ export interface FlaggedAccountStorageV1 {
     version: 1;
     accounts: FlaggedAccountMetadataV1[];
 }
-//# sourceMappingURL=public-types.d.ts.map

package/dist/lib/storage/record-identity.d.ts

@@ -13,4 +13,3 @@ export declare function resolveAccountRecordId(account: {
     refreshToken: string;
     addedAt: number;
 }): string;
-//# sourceMappingURL=record-identity.d.ts.map

package/dist/lib/storage/record-utils.d.ts

@@ -1,3 +1,2 @@
 export declare function isRecord(value: unknown): value is Record<string, unknown>;
 export declare function clampIndex(index: number, length: number): number;
-//# sourceMappingURL=record-utils.d.ts.map

package/dist/lib/storage/restore-assessment.d.ts

@@ -4,4 +4,3 @@ export declare function buildRestoreAssessment(params: {
     backupMetadata: BackupMetadata;
     hasResetMarker: boolean;
 }): RestoreAssessment;
-//# sourceMappingURL=restore-assessment.d.ts.map

package/dist/lib/storage/restore-backup-entry.d.ts

@@ -21,4 +21,3 @@ export declare function restoreAccountsFromBackupEntry(params: {
     }>;
     saveAccounts: (storage: AccountStorageV3) => Promise<void>;
 }): Promise<AccountStorageV3>;
-//# sourceMappingURL=restore-backup-entry.d.ts.map

package/dist/lib/storage/restore-metadata.d.ts

@@ -7,4 +7,3 @@ type AccountStorageWithMetadata = AccountStorageV3 & {
 export declare function createEmptyStorageWithRestoreMetadata(restoreEligible: boolean, restoreReason: RestoreReason): AccountStorageWithMetadata;
 export declare function withRestoreMetadata(storage: AccountStorageV3, restoreEligible: boolean, restoreReason: RestoreReason): AccountStorageWithMetadata;
 export {};
-//# sourceMappingURL=restore-metadata.d.ts.map

package/dist/lib/storage/save-retry.d.ts

@@ -7,4 +7,3 @@
 import type { AccountStorageV3 } from "./public-types.js";
 export declare function isRetryableStorageWriteError(error: unknown): boolean;
 export declare function saveAccountsWithRetry(storage: AccountStorageV3, saveAccounts: (storage: AccountStorageV3) => Promise<void>): Promise<void>;
-//# sourceMappingURL=save-retry.d.ts.map

package/dist/lib/storage/snapshot-inspectors.d.ts

@@ -19,4 +19,3 @@ export declare function describeFlaggedSnapshot(path: string, kind: BackupSnapsh
     loadFlaggedAccountsFromPath: (path: string) => Promise<FlaggedAccountStorageV1>;
     logWarn?: (message: string, meta: Record<string, unknown>) => void;
 }): Promise<BackupSnapshotMetadata>;
-//# sourceMappingURL=snapshot-inspectors.d.ts.map

package/dist/lib/storage/snapshot-merge.d.ts

@@ -13,4 +13,3 @@ export declare function mergeAccountSnapshot(base: AccountStorageV3 | null, curr
 /** Save observations independently of unresolved user-edit conflicts. Inventory stays disk-owned. */
 export declare function mergeAccountRuntimeObservations(base: AccountStorageV3, current: AccountStorageV3, local: AccountStorageV3): AccountStorageV3;
 export {};
-//# sourceMappingURL=snapshot-merge.d.ts.map

package/dist/lib/storage/storage-parser.d.ts

@@ -28,5 +28,6 @@ export declare function loadAccountsFromPath(path: string, deps: {
     normalized: AccountStorageV3 | null;
     storedVersion: unknown;
     schemaErrors: string[];
+    /** sha256 of the exact bytes read, for cheap unchanged-content checks. */
+    contentSha256: string;
 }>;
-//# sourceMappingURL=storage-parser.d.ts.map

package/dist/lib/storage/storage-parser.js

@@ -1,6 +1,7 @@
 import { promises as fs } from "node:fs";
 import { AnyAccountStorageSchema, getValidationErrors, safeParseJson, } from "../schemas.js";
 import { withFileOperationRetry } from "../fs-retry.js";
+import { computeSha256 } from "./hash.js";
 export function parseAndNormalizeStorage(data, normalizeAccountStorage, isRecord) {
     const schemaErrors = getValidationErrors(AnyAccountStorageSchema, data);
     const normalized = normalizeAccountStorage(data);
@@ -33,18 +34,25 @@ export async function loadAccountsFromPath(path, deps) {
     // unchanged; JSON.parse runs outside the retry, so the SyntaxError → recovery
     // contract documented above is also preserved.
     const content = await withFileOperationRetry(() => fs.readFile(path, "utf-8"));
+    const contentSha256 = computeSha256(content);
     // Run the Zod-guarded JSON boundary first. Returns null on either a
     // `SyntaxError` or a schema mismatch; we disambiguate below so the
     // `SyntaxError` contract keeps propagating to callers that rely on it
     // for WAL / backup recovery.
     const validated = safeParseJson(content, AnyAccountStorageSchema, "storage-parser.loadAccountsFromPath");
     if (validated !== null) {
-        return parseAndNormalizeStorage(validated, deps.normalizeAccountStorage, deps.isRecord);
+        return {
+            ...parseAndNormalizeStorage(validated, deps.normalizeAccountStorage, deps.isRecord),
+            contentSha256,
+        };
     }
     // `validated === null`: either SyntaxError or schema mismatch.
     // A raw JSON.parse distinguishes them: SyntaxError propagates to preserve
     // existing recovery semantics; otherwise fall through to the TS normalizer
     // (legacy unknown-shape path, surfaced via `schemaErrors`).
     const data = JSON.parse(content);
-    return parseAndNormalizeStorage(data, deps.normalizeAccountStorage, deps.isRecord);
+    return {
+        ...parseAndNormalizeStorage(data, deps.normalizeAccountStorage, deps.isRecord),
+        contentSha256,
+    };
 }

package/dist/lib/storage/transactions.d.ts

@@ -29,4 +29,3 @@ export declare function withAccountAndFlaggedStorageTransaction<T>(handler: (cur
     cloneAccountStorageForPersistence: (storage: AccountStorageV3 | null | undefined) => AccountStorageV3;
     logRollbackError: (error: unknown, rollbackError: unknown) => void;
 }): Promise<T>;
-//# sourceMappingURL=transactions.d.ts.map

package/dist/lib/storage.d.ts

@@ -156,7 +156,21 @@ export declare function withFlaggedStorageTransaction<T>(handler: (current: Flag
  * @param storage - Account storage data to save
  * @throws StorageError with platform-aware hints on failure
  */
-/** Clone a loaded working snapshot without losing its optimistic-concurrency baseline. */
+/**
+ * Clone a loaded working snapshot without losing its optimistic-concurrency baseline.
+ *
+ * Baseline contract: `saveAccounts` only runs the three-way merge
+ * (`mergeAccountSnapshot` against a fresh `loadPrimaryAccountsForMerge` read)
+ * when the saved object is registered in `loadedAccountSnapshots` — and that
+ * WeakMap is keyed by OBJECT IDENTITY, so registration does not survive
+ * `structuredClone`, `JSON.parse(JSON.stringify(...))`, spread copies, or
+ * manual reconstruction. A baseline-less save writes the object as-is
+ * (last-writer-wins): concurrent changes are neither merged nor flagged with
+ * ESTALE, and when the primary on disk differs from the state this process
+ * last read or wrote the save additionally emits a one-time baseline-less
+ * overwrite warning. Use this helper — or mutate the loaded object in place —
+ * to keep the merge armed.
+ */
 export declare function cloneTrackedAccountStorage(storage: AccountStorageV3): AccountStorageV3;
 export declare function saveAccounts(storage: AccountStorageV3): Promise<void>;
 /**
@@ -185,4 +199,3 @@ export declare function importAccounts(filePath: string): Promise<{
     total: number;
     skipped: number;
 }>;
-//# sourceMappingURL=storage.d.ts.map