@openlimiter/core 1.3.5 → 2.0.2

package/dist/activity/spool.js

@@ -0,0 +1,305 @@
+import { randomUUID } from "node:crypto";
+import { chmodSync, closeSync, constants, fstatSync, lstatSync, mkdirSync, openSync, readdirSync, readSync, realpathSync, renameSync, rmdirSync, unlinkSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { isActivityEvent, MAX_ACTIVITY_EVENT_AGE_MS, MAX_ACTIVITY_EVENT_BYTES, MAX_ACTIVITY_SPOOL_BYTES, readActivityEvent } from "./contract.js";
+const EVENT_NAME = /^(\d{16})-([a-f0-9-]{36})\.json$/u;
+const TEMP_NAME = /^\.[a-f0-9-]{36}\.tmp$/u;
+const MAX_ENTRIES = 65_536;
+/* A healthy writer holds the lock for milliseconds; a hook killed mid write
+   (Ctrl+C in the agent) strands it, so recover well before the event age. */
+const STALE_WRITER_LOCK_MS = 10_000;
+function code(error) {
+    return error.code;
+}
+function checkpoint(options) {
+    options.signal?.throwIfAborted();
+    if (options.deadline !== undefined && performance.now() >= options.deadline)
+        throw new Error("activity: deadline");
+}
+/** The root is already canonical. Refuse links in the owned subtree. */
+function directories(target, create) {
+    if (!path.isAbsolute(target))
+        throw new Error("activity: absolute state root required");
+    let current = path.dirname(target);
+    const root = lstatSync(current);
+    if (!root.isDirectory() || root.isSymbolicLink())
+        throw new Error("activity: unsafe directory");
+    let created = false;
+    for (const segment of target.slice(current.length).split(path.sep).filter(Boolean)) {
+        if (segment === "." || segment === "..")
+            throw new Error("activity: path escape");
+        current = path.join(current, segment);
+        let info;
+        try {
+            info = lstatSync(current);
+        }
+        catch (error) {
+            if (!create || code(error) !== "ENOENT")
+                throw error;
+            try {
+                mkdirSync(current, { mode: 0o700 });
+                if (current === target)
+                    created = true;
+            }
+            catch (error) {
+                if (code(error) !== "EEXIST")
+                    throw error;
+            }
+            info = lstatSync(current);
+        }
+        if (!info.isDirectory() || info.isSymbolicLink())
+            throw new Error("activity: unsafe directory");
+    }
+    return created;
+}
+function spoolPath(root, create = false) {
+    if (!path.isAbsolute(root) || root.split(/[\\/]/u).includes(".."))
+        throw new Error("activity: path escape");
+    if (create)
+        mkdirSync(root, { recursive: true, mode: 0o700 });
+    // System roots may contain aliases (macOS /var, Windows junctions). Resolve
+    // only the supplied state root, never activity or any of its entries.
+    return path.join(realpathSync(root), "activity");
+}
+function same(left, right) {
+    return left.dev === right.dev && left.ino === right.ino;
+}
+function regular(info) {
+    return info.isFile() && !info.isSymbolicLink() && info.nlink === 1 &&
+        (process.platform === "win32" ||
+            (info.uid === process.getuid?.() && (info.mode & 0o077) === 0));
+}
+function readFile(file, info, now) {
+    if (!regular(info) || info.size > MAX_ACTIVITY_EVENT_BYTES)
+        throw new Error("activity: unsafe file");
+    const fd = openSync(file, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
+    try {
+        const opened = fstatSync(fd);
+        if (!same(info, opened) || !regular(opened) || opened.size > MAX_ACTIVITY_EVENT_BYTES)
+            throw new Error("activity: changed file");
+        const bytes = Buffer.alloc(MAX_ACTIVITY_EVENT_BYTES + 1);
+        let length = 0;
+        while (length < bytes.length) {
+            const count = readSync(fd, bytes, length, bytes.length - length, null);
+            if (count === 0)
+                break;
+            length += count;
+        }
+        if (length > MAX_ACTIVITY_EVENT_BYTES)
+            throw new Error("activity: oversized file");
+        const serialized = new TextDecoder("utf-8", { fatal: true }).decode(bytes.subarray(0, length));
+        const event = readActivityEvent(serialized, now, "desktop");
+        if (event.source === "hook" && !isActivityEvent(event, now, "hook"))
+            throw new Error("activity: invalid hook process");
+        return event;
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+export async function prepareActivitySpool(options) {
+    checkpoint(options);
+    const directory = spoolPath(options.directory, true);
+    const created = directories(directory, true);
+    const before = lstatSync(directory);
+    if (process.platform === "win32") {
+        const stamp = path.join(directory, ".acl-verified");
+        let verified = false;
+        try {
+            const info = lstatSync(stamp);
+            verified = regular(info) && info.size <= MAX_ACTIVITY_EVENT_BYTES &&
+                (options.now ?? Date.now()) - info.mtimeMs <= MAX_ACTIVITY_EVENT_AGE_MS;
+        }
+        catch (error) {
+            if (code(error) !== "ENOENT")
+                throw error;
+        }
+        if (created || !verified) {
+            if (!options.protectWindowsDirectory)
+                throw new Error("activity: Windows ACL helper required");
+            await options.protectWindowsDirectory(directory);
+            checkpoint(options);
+            directories(directory, false);
+            if (!same(before, lstatSync(directory)))
+                throw new Error("activity: changed directory");
+            const temporary = path.join(directory, "." + randomUUID() + ".tmp");
+            try {
+                const fd = openSync(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW ?? 0), 0o600);
+                try {
+                    writeFileSync(fd, "");
+                }
+                finally {
+                    closeSync(fd);
+                }
+                // Replace only the stamp itself. Never traverse a planted directory or link.
+                try {
+                    const info = lstatSync(stamp);
+                    if (info.isDirectory() && !info.isSymbolicLink())
+                        rmdirSync(stamp);
+                    else if (!regular(info))
+                        unlinkSync(stamp);
+                }
+                catch (error) {
+                    if (code(error) !== "ENOENT")
+                        throw error;
+                }
+                renameSync(temporary, stamp);
+            }
+            finally {
+                try {
+                    unlinkSync(temporary);
+                }
+                catch { /* Published or failed stamp. */ }
+            }
+        }
+    }
+    else {
+        if (before.uid !== process.getuid?.())
+            throw new Error("activity: wrong directory owner");
+        chmodSync(directory, 0o700);
+    }
+    checkpoint(options);
+    directories(directory, false);
+    if (!same(before, lstatSync(directory)))
+        throw new Error("activity: changed directory");
+    return directory;
+}
+/** A global spool lock serializes size accounting and sequence allocation. */
+export async function writeActivityEvent(event, options) {
+    const now = options.now ?? Date.now();
+    if (!isActivityEvent(event, now, event.source === "hook" ? "hook" : "desktop"))
+        throw new Error("activity: invalid event");
+    const directory = await prepareActivitySpool(options);
+    const lock = path.join(directory, ".writer");
+    const deadline = performance.now() + 40;
+    while (true) {
+        checkpoint(options);
+        try {
+            mkdirSync(lock, { mode: 0o700 });
+            break;
+        }
+        catch (error) {
+            if (code(error) !== "EEXIST" || performance.now() >= deadline)
+                throw error;
+            const info = lstatSync(lock);
+            if (!info.isDirectory() || info.isSymbolicLink())
+                throw new Error("activity: unsafe lock");
+            // Only an empty abandoned lock can be recovered. Never recurse into it.
+            if (now - info.mtimeMs > STALE_WRITER_LOCK_MS) {
+                rmdirSync(lock);
+                continue;
+            }
+            await new Promise((resolve) => setTimeout(resolve, 2));
+        }
+    }
+    let temporary;
+    try {
+        directories(directory, false);
+        let total = 0;
+        let sequence = Math.max(event.sequence, now * 1_000);
+        const entries = readdirSync(directory);
+        if (entries.length > MAX_ENTRIES)
+            throw new Error("activity: too many entries");
+        for (const name of entries) {
+            checkpoint(options);
+            if (name === ".writer")
+                continue;
+            const file = path.join(directory, name);
+            const info = lstatSync(file);
+            if (!regular(info))
+                throw new Error("activity: unsafe spool entry");
+            const match = EVENT_NAME.exec(name);
+            const owned = match !== null || TEMP_NAME.test(name);
+            if (owned && now - info.mtimeMs > MAX_ACTIVITY_EVENT_AGE_MS) {
+                unlinkSync(file);
+                continue;
+            }
+            if (info.size > MAX_ACTIVITY_EVENT_BYTES)
+                throw new Error("activity: oversized spool entry");
+            /* Names and times only: parsing every record here made each write O(n)
+               reads and dropped hooks once a busy day filled the spool. A record
+               whose observedAt is stale is refused by the reader and removed by
+               the age cleanup above. */
+            total += info.size;
+            if (match !== null)
+                sequence = Math.max(sequence, Number(match[1]) + 1);
+        }
+        const stored = { ...event, sequence };
+        if (!isActivityEvent(stored, now, event.source === "hook" ? "hook" : "desktop"))
+            throw new Error("activity: invalid sequence");
+        const bytes = Buffer.from(JSON.stringify(stored));
+        if (bytes.length > MAX_ACTIVITY_EVENT_BYTES || total + bytes.length > MAX_ACTIVITY_SPOOL_BYTES)
+            throw new Error("activity: spool full");
+        const id = randomUUID();
+        temporary = path.join(directory, "." + id + ".tmp");
+        const fd = openSync(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW ?? 0), 0o600);
+        try {
+            writeFileSync(fd, bytes);
+        }
+        finally {
+            closeSync(fd);
+        }
+        checkpoint(options);
+        directories(directory, false);
+        renameSync(temporary, path.join(directory, String(sequence).padStart(16, "0") + "-" + id + ".json"));
+        temporary = undefined;
+        return stored;
+    }
+    finally {
+        if (temporary !== undefined) {
+            try {
+                unlinkSync(temporary);
+            }
+            catch { /* Failed writes never publish. */ }
+        }
+        rmdirSync(lock);
+    }
+}
+/** Read only. Invalid, stale, partial and hostile records are counted and skipped. */
+export function readActivitySpool(directory, now = Date.now()) {
+    const events = [];
+    let skipped = 0;
+    try {
+        const spool = spoolPath(directory);
+        directories(spool, false);
+        const info = lstatSync(spool);
+        if (process.platform !== "win32" && (info.uid !== process.getuid?.() || (info.mode & 0o077) !== 0))
+            throw new Error("activity: unsafe directory");
+        const names = readdirSync(spool);
+        let total = 0;
+        for (const [index, name] of names.entries()) {
+            if (name === ".acl-verified" && process.platform === "win32") {
+                const stamp = lstatSync(path.join(spool, name));
+                if (!regular(stamp) || stamp.size > MAX_ACTIVITY_EVENT_BYTES)
+                    skipped += 1;
+                continue;
+            }
+            if (name === ".writer") {
+                const lock = lstatSync(path.join(spool, name));
+                if (!lock.isDirectory() || lock.isSymbolicLink())
+                    skipped += 1;
+                continue;
+            }
+            try {
+                if (index >= MAX_ENTRIES || !EVENT_NAME.test(name))
+                    throw new Error("activity: unexpected name");
+                const file = path.join(spool, name);
+                const info = lstatSync(file);
+                total += info.size;
+                if (total > MAX_ACTIVITY_SPOOL_BYTES)
+                    throw new Error("activity: read cap");
+                events.push(readFile(file, info, now));
+            }
+            catch {
+                skipped += 1;
+            }
+        }
+    }
+    catch (error) {
+        if (code(error) !== "ENOENT")
+            skipped += 1;
+    }
+    events.sort((left, right) => left.sequence - right.sequence || left.observedAt.localeCompare(right.observedAt) || left.eventId.localeCompare(right.eventId));
+    return { events, skipped };
+}
+//# sourceMappingURL=spool.js.map

package/dist/activity/spool.js.map

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

package/dist/cache.d.ts

@@ -1,6 +1,43 @@
+export { freshnessPolicy } from "./data-rules.js";
 import { type CacheState, type CacheSuppression, type CollectionReport } from "./collection.js";
-import type { Snapshot } from "./types.js";
+import type { ProviderCode, Snapshot } from "./types.js";
 export declare const CACHE_FILE_NAME = "openlimiter-cache.json";
+export declare const MAX_POLICY_TIMESTAMP = 253402300799999;
+/** Pure policy shared with the desktop contract. All instants are UTC. */
+export declare function retryPolicy(input: {
+    attemptCount: number;
+    retryAfter: string | null;
+    now: string;
+    jitterSeconds: number;
+    layer: string;
+}): {
+    localDelaySeconds: number;
+    serverDeadline: string | null;
+    nextAllowedAt: string;
+    blockedUntil: string | null;
+};
+export declare function leasePolicy(input: {
+    now: string;
+    requester: string;
+    owner: string | null;
+    expiresAt: string | null;
+    leaseSeconds: number;
+}): {
+    acquired: boolean;
+    takeover: boolean;
+    owner: string | null;
+    expiresAt: string | null;
+};
+export declare function withPolicyFreshness(snapshot: Snapshot): Snapshot;
+export declare function recordAcquisitionAvailability(provider: ProviderCode, availability: "expired_credentials" | "access_denied" | "rate_limited", now: string, retryAt: string | undefined, directory?: string, accountId?: string): Promise<void>;
+export interface MachineLease {
+    readonly attempts: number;
+    stillOwned(now?: number): Promise<boolean>;
+    complete(nextAllowedAt: number, attempts: number, refusalRevision?: string): Promise<void>;
+    release(): Promise<void>;
+}
+/** Provider scope deliberately also excludes aliases of the same account. */
+export declare function acquireMachineLease(provider: string, directory?: string, now?: number, credentialRevision?: string): Promise<MachineLease | null>;
 export declare const CACHE_LOCK_NAME = "openlimiter.lock";
 /** Largest JSON document this package will read into memory. */
 export declare const MAX_JSON_FILE_BYTES = 1048576;
@@ -122,7 +159,7 @@ export interface CacheMergeResult {
  * unchanged result skips the write entirely, which keeps a statusline that
  * renders on every keystroke from churning the disk.
  */
-export declare function mergeSnapshotCache(incoming: readonly Snapshot[], directory?: string): Promise<CacheMergeResult>;
+export declare function mergeSnapshotCache(incoming: readonly Snapshot[], directory?: string, now?: number): Promise<CacheMergeResult>;
 /**
  * Fold rows this machine just acquired into the cache, without ever losing a
  * newer row somebody else wrote.
@@ -166,4 +203,6 @@ export declare function applyCollectionReportToCache(report: CollectionReport, d
     state: CacheState;
     written: boolean;
 }>;
+/** Startup maintenance uses the same lock as all writers and never repairs unreadable state. */
+export declare function pruneSnapshotCache(directory?: string, now?: number): Promise<number>;
 //# sourceMappingURL=cache.d.ts.map

package/dist/cache.d.ts.map

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

package/dist/cache.js

@@ -1,3 +1,5 @@
+import { freshnessPolicy, retainSnapshots } from "./data-rules.js";
+export { freshnessPolicy } from "./data-rules.js";
 import { randomUUID } from "node:crypto";
 import { constants } from "node:fs";
 import { chmod, lstat, mkdir, open, readFile, rename, unlink } from "node:fs/promises";
@@ -7,6 +9,118 @@ import { applyCollectionReport, readSuppressions, snapshotBelongsTo, visibleSnap
 import { MAX_CACHE_ENTRIES, mergeSnapshots, snapshotIdentity } from "./merge.js";
 import { canonicalJson, normalizeMeter, normalizeMeters } from "./normalizer.js";
 export const CACHE_FILE_NAME = "openlimiter-cache.json";
+export const MAX_POLICY_TIMESTAMP = 253_402_300_799_999;
+/** Pure policy shared with the desktop contract. All instants are UTC. */
+export function retryPolicy(input) {
+    const now = Date.parse(input.now);
+    const raw = input.retryAfter?.trim();
+    const server = raw === undefined ? NaN : /^\d+$/u.test(raw)
+        ? Math.min(MAX_POLICY_TIMESTAMP, now + Number(raw) * 1000)
+        : /^[A-Za-z]{3}, /u.test(raw) ? Date.parse(raw) : NaN;
+    const localDelaySeconds = Math.min(60 * 2 ** Math.min(input.attemptCount, 4), 900) + Math.max(0, input.jitterSeconds);
+    const ceiling = now + (input.layer === "collector" ? 86400 : 604800) * 1000;
+    const cappedServer = Math.min(server, ceiling);
+    const serverDeadline = Number.isFinite(server) ? new Date(cappedServer).toISOString() : null;
+    return {
+        localDelaySeconds, serverDeadline,
+        nextAllowedAt: new Date(Math.max(now + localDelaySeconds * 1000, Number.isFinite(server) ? cappedServer : 0)).toISOString(),
+        blockedUntil: server > ceiling ? serverDeadline : null
+    };
+}
+export function leasePolicy(input) {
+    const acquired = input.owner === null || input.expiresAt === null || Date.parse(input.expiresAt) <= Date.parse(input.now);
+    return {
+        acquired, takeover: acquired && input.owner !== null && input.owner !== input.requester,
+        owner: acquired ? input.requester : input.owner,
+        expiresAt: acquired ? new Date(Date.parse(input.now) + input.leaseSeconds * 1000).toISOString() : input.expiresAt
+    };
+}
+export function withPolicyFreshness(snapshot) {
+    if (!["native_payload", "documented_api", "internal_payload", "local_file"].includes(snapshot.source))
+        return snapshot;
+    return { ...snapshot, expiresAt: freshnessPolicy({ ...snapshot, sourceClass: snapshot.source, now: snapshot.observedAt }).expiresAt };
+}
+export async function recordAcquisitionAvailability(provider, availability, now, retryAt, directory = resolveStateDirectory(), accountId) {
+    await withCacheLock(directory, async () => {
+        const state = await readCacheState(directory);
+        if (!state.ok && state.reason !== "missing")
+            throw new Error("Unreadable snapshot cache");
+        const rows = retainSnapshots(state.ok ? state.state.snapshots : [], Date.parse(now));
+        const matches = (row) => row.provider === provider && row.accountId === accountId;
+        const matching = rows.filter(matches);
+        if (matching.some(row => row.observedAt > now))
+            return;
+        const seed = {
+            provider, ...(accountId ? { accountId } : {}), meter: "ACQUISITION", value: 0, unit: "PERCENT", window: { kind: "unknown" }, resetAt: null,
+            source: "internal_payload", precision: "exact", observedAt: now, writer: "cli",
+            expiresAt: freshnessPolicy({ sourceClass: "internal_payload", observedAt: now, now }).expiresAt,
+            labels: { credentialOrigin: "official-local-tool", dataInterfaceStatus: "internal-endpoint", automationRisk: "high", verification: "UNVERIFIED" }
+        };
+        const snapshots = [...rows.filter((row) => !matches(row)), ...(matching.length ? matching : [seed]).map((row) => {
+                const { retryAt: _oldRetry, ...rest } = row;
+                return { ...rest, availability, ...(availability === "rate_limited" && retryAt ? { retryAt } : {}) };
+            })];
+        await replaceCache(directory, snapshots, state.ok ? state.state.suppressions : []);
+    });
+}
+/** Provider scope deliberately also excludes aliases of the same account. */
+export async function acquireMachineLease(provider, directory = resolveStateDirectory(), now = Date.now(), credentialRevision) {
+    const named = provider.toLowerCase().replaceAll("_", "-");
+    const slug = named === "gemini-cli" || named === "antigravity" ? "code-assist" : named;
+    if (!/^[a-z][a-z-]{0,31}$/u.test(slug))
+        throw new Error("Invalid provider");
+    const file = path.join(directory, `acquisition-${slug}.json`);
+    const read = async () => {
+        const result = await readJsonFileSafely(file);
+        if (!result.ok) {
+            if (result.reason !== "missing")
+                throw new Error("Unreadable acquisition policy");
+            return { owner: null, expiresAt: 0, token: "", nextAllowedAt: 0, attempts: 0 };
+        }
+        const value = result.value;
+        if (!isRecord(value) || !Number.isSafeInteger(value.expiresAt) || !Number.isSafeInteger(value.nextAllowedAt) || !Number.isSafeInteger(value.attempts) || typeof value.token !== "string" || (value.owner !== null && value.owner !== "desktop" && value.owner !== "cli"))
+            throw new Error("Invalid acquisition policy");
+        return value;
+    };
+    const state = await withCacheLock(directory, async () => {
+        const current = await read();
+        const decision = leasePolicy({ now: new Date(now).toISOString(), requester: "cli", owner: current.owner, expiresAt: new Date(current.expiresAt).toISOString(), leaseSeconds: 60 });
+        const changedRefusal = typeof current.refusalRevision === "string" && credentialRevision !== undefined && current.refusalRevision !== credentialRevision;
+        if (!decision.acquired || (now < current.nextAllowedAt && !changedRefusal))
+            return null;
+        const next = { ...current, lastAccount: null, owner: "cli", expiresAt: now + 60_000, token: randomUUID() };
+        await writeFileAtomically(file, canonicalJson(next));
+        return next;
+    });
+    if (state === null)
+        return null;
+    const mutate = async (action) => withCacheLock(directory, async () => {
+        const current = await read();
+        if (current.token !== state.token)
+            throw new Error("Acquisition lease lost");
+        action(current);
+        await writeFileAtomically(file, canonicalJson(current));
+    });
+    const started = Date.now();
+    const heartbeat = setInterval(() => {
+        void mutate((current) => {
+            const at = now + Date.now() - started;
+            if (current.owner !== "cli" || at >= current.expiresAt)
+                throw new Error("Acquisition lease expired");
+            current.expiresAt = at + 60_000;
+        }).catch(() => clearInterval(heartbeat));
+    }, 20_000);
+    heartbeat.unref();
+    return {
+        attempts: state.attempts,
+        stillOwned: async (at = Date.now()) => { const current = await read(); return current.token === state.token && current.owner === "cli" && at < current.expiresAt; },
+        complete: async (nextAllowedAt, attempts, refusalRevision) => mutate((current) => { current.nextAllowedAt = nextAllowedAt; current.attempts = attempts; current.refusalRevision = refusalRevision ?? null; }),
+        release: async () => {
+            clearInterval(heartbeat);
+            await mutate((current) => { current.owner = null; current.expiresAt = 0; }).catch(() => undefined);
+        }
+    };
+}
 export const CACHE_LOCK_NAME = "openlimiter.lock";
 /** Largest JSON document this package will read into memory. */
 export const MAX_JSON_FILE_BYTES = 1_048_576;
@@ -477,14 +591,14 @@ export async function writeSnapshotCache(snapshots, directory = resolveStateDire
  * unchanged result skips the write entirely, which keeps a statusline that
  * renders on every keystroke from churning the disk.
  */
-export async function mergeSnapshotCache(incoming, directory = resolveStateDirectory()) {
+export async function mergeSnapshotCache(incoming, directory = resolveStateDirectory(), now = Date.now()) {
     rejectOutOfBounds(incoming);
     return await withCacheLock(directory, async () => {
         const cached = await readCacheState(directory);
         const state = cached.ok
             ? cached.state
             : { snapshots: [], suppressions: [] };
-        const merged = mergeSnapshots(state.snapshots, incoming);
+        const merged = retainSnapshots(mergeSnapshots(state.snapshots, incoming), now);
         if (canonicalJson(merged) === canonicalJson(state.snapshots)) {
             return { merged, written: false };
         }
@@ -519,7 +633,7 @@ export async function mergeAcquiredSnapshots(report, directory = resolveStateDir
     return await withCacheLock(directory, async () => {
         const cached = await readCacheState(directory);
         const before = cached.ok
-            ? cached.state
+            ? { ...cached.state, snapshots: cached.state.snapshots.filter((row) => !(row.provider === report.provider && row.accountId === report.accountId && row.meter === "ACQUISITION" && row.availability !== undefined && row.observedAt <= report.observedAt)) }
             : { snapshots: [], suppressions: [] };
         const held = new Map(before.snapshots.map((snapshot) => [snapshotIdentity(snapshot), snapshot]));
         const taken = [];
@@ -563,7 +677,7 @@ export async function mergeAcquiredSnapshots(report, directory = resolveStateDir
             await replaceCache(directory, after.snapshots, after.suppressions);
             return { written: true, taken: taken.length, deferred };
         }
-        const merged = mergeSnapshots(before.snapshots, taken);
+        const merged = retainSnapshots(mergeSnapshots(before.snapshots, taken), Date.parse(report.observedAt));
         if (canonicalJson(merged) === canonicalJson(before.snapshots)) {
             return { written: false, taken: taken.length, deferred };
         }
@@ -600,4 +714,20 @@ export async function applyCollectionReportToCache(report, directory = resolveSt
         return { state: after, written: true };
     });
 }
+/** Startup maintenance uses the same lock as all writers and never repairs unreadable state. */
+export async function pruneSnapshotCache(directory = resolveStateDirectory(), now = Date.now()) {
+    const existing = await readCacheState(directory);
+    if (!existing.ok)
+        return 0;
+    return withCacheLock(directory, async () => {
+        const cached = await readCacheState(directory);
+        if (!cached.ok)
+            return 0;
+        const snapshots = retainSnapshots(cached.state.snapshots, now);
+        const count = cached.state.snapshots.length - snapshots.length;
+        if (count)
+            await replaceCache(directory, snapshots, cached.state.suppressions);
+        return count;
+    });
+}
 //# sourceMappingURL=cache.js.map