@cleocode/core 2026.9.20 → 2026.9.21

package/dist/store/snapshot-gate.d.ts

@@ -0,0 +1,239 @@
+/**
+ * Project-wide admission gate and retention policy for SQLite snapshots.
+ *
+ * `cleo session end` snapshots the project databases. When many agents end
+ * their sessions together, each process used to run its own snapshot, because
+ * the debounce lived in process memory and the session-end hook bypassed it
+ * with `force: true`. On 2026-09-27 that produced four 1.3 GB snapshots in ten
+ * seconds, and the newest-10 rotation then evicted the older recovery points.
+ *
+ * This module closes that path with three mechanisms:
+ *
+ *   1. **Lock** — a cross-process lock ({@link acquireLock}, proper-lockfile)
+ *      on `<backupDir>/.snapshot-gate`. At most one snapshot runs per project.
+ *   2. **Admission** — gate state lives in the project `cleo.db`
+ *      (`tasks_schema_meta`, key {@link SNAPSHOT_GATE_META_KEY}) and is re-read
+ *      under the lock. It holds a monotonic snapshot GENERATION counter,
+ *      claimed under the lock when a snapshot starts, and per prefix the
+ *      generation and start time of its last satisfied snapshot. Two modes
+ *      ({@link SnapshotGateMode}) use it:
+ *        - `routine` (per-write checkpoints): debounced for
+ *          {@link SNAPSHOT_DEBOUNCE_MS}, and the lock is tried once — a caller
+ *          that finds a snapshot in flight skips.
+ *        - `required` (session end, pre-destructive checkpoints): not
+ *          debounced. The caller records the generation it saw when it made
+ *          the request, WAITS for the lock (bounded), and is satisfied only
+ *          by a snapshot of a LATER generation — one that started after the
+ *          request, so it contains every write made before it. Requests queued
+ *          behind one snapshot are all covered by it, so a burst produces one
+ *          snapshot. Works without a state store. No wall clock is involved,
+ *          so a stepped clock cannot fake coverage.
+ *      A prefix whose database does not exist in this project (e.g. no
+ *      `llmtxt.db`) is `absent`: it satisfies admission like a written
+ *      snapshot and is never reported as failed. There is no mode that
+ *      bypasses the lock.
+ *   3. **Retention** — {@link selectSnapshotsToKeep} keeps time-spread slots
+ *      (latest, quarter-hourly, hourly, daily) instead of the newest N, so a
+ *      burst cannot evict older recovery points. The file just written is
+ *      always kept.
+ *
+ * @task T12508
+ */
+import type { DatabaseSync } from 'node:sqlite';
+/** Minimum interval between two `routine` snapshot starts of a prefix, per project. */
+export declare const SNAPSHOT_DEBOUNCE_MS: number;
+/**
+ * Age after which a held gate lock is considered abandoned. `VACUUM INTO` is
+ * synchronous and blocks the event loop, so the lock's mtime cannot be
+ * refreshed while it runs; this value must exceed the longest snapshot.
+ */
+export declare const SNAPSHOT_LOCK_STALE_MS: number;
+/**
+ * Default lock retries for a `required` request (pre-destructive
+ * checkpoints). proper-lockfile backs off from 100 ms to 1 s per attempt, so
+ * 90 retries bound the wait to about 90 s.
+ */
+export declare const SNAPSHOT_LOCK_WAIT_RETRIES = 90;
+/**
+ * Lock retries for the session-end snapshot: about 6.5 s (100 + 200 + 400 +
+ * 800 ms, then 1 s each). Session end runs inside host shutdown hooks that
+ * may be killed, so it must not wait long; the session is already persisted
+ * when it runs.
+ */
+export declare const SESSION_END_LOCK_WAIT_RETRIES = 9;
+/** `tasks_schema_meta` key holding the persisted snapshot gate state. */
+export declare const SNAPSHOT_GATE_META_KEY = "sqlite_snapshot_gate";
+/**
+ * How a snapshot request is admitted.
+ *
+ * - `routine` — debounced; skips when a snapshot is in flight; needs the state
+ *   store (without it nothing is admitted, so a broken store cannot storm).
+ * - `required` — not debounced; waits for the lock; skipped only when a
+ *   snapshot of a later generation than the one seen at request time
+ *   satisfied the prefix.
+ */
+export type SnapshotGateMode = 'routine' | 'required';
+/**
+ * What a snapshot function did for one prefix: wrote a file, hard-linked the
+ * file already written in this run for the same physical database, or found
+ * no database to snapshot.
+ */
+export type SnapshotOutcome = 'written' | 'linked' | 'absent';
+/** Why a gated snapshot request did not snapshot anything. */
+export type SnapshotGateSkipReason = 'debounced' | 'in-flight' | 'covered' | 'state-unavailable' | 'lock-timeout';
+/** Outcome of {@link runGatedSnapshot}. */
+export interface SnapshotGateResult {
+    /** Prefixes that have a snapshot file from this call (written or hard-linked). */
+    readonly snapshotted: readonly string[];
+    /**
+     * Subset of `snapshotted` that shares its file with an earlier prefix of the
+     * same run (same physical database — one VACUUM, hard-linked).
+     */
+    readonly linked: readonly string[];
+    /** Prefixes whose database does not exist in this project (nothing to snapshot). */
+    readonly absent: readonly string[];
+    /** Prefixes whose snapshot was attempted and threw. */
+    readonly failed: readonly string[];
+    /** Set when no snapshot was attempted; `null` when at least one prefix was admitted. */
+    readonly skipped: SnapshotGateSkipReason | null;
+    /** Human-readable cause when `skipped` is `lock-timeout`. */
+    readonly error?: string;
+}
+/** Options for {@link runGatedSnapshot}. */
+export interface SnapshotGateOptions {
+    /** Absolute snapshot directory; the lock lives here. Must exist. */
+    readonly backupDir: string;
+    /**
+     * Handle on the project `cleo.db` that stores the gate state, or `null` when
+     * it cannot be opened. `routine` requests admit nothing without it;
+     * `required` requests snapshot anyway.
+     */
+    readonly stateDb: DatabaseSync | null;
+    /** Snapshot prefixes requested by the caller, in snapshot order. */
+    readonly prefixes: readonly string[];
+    /** Admission mode. Defaults to `routine`. */
+    readonly mode?: SnapshotGateMode;
+    /**
+     * `required` mode: the gate generation observed when the request was made
+     * (after the caller's last write). Only a later generation covers it.
+     * Defaults to the generation read at the start of this call.
+     */
+    readonly seenGeneration?: number;
+    /**
+     * `required` mode: never treat a prefix as covered — snapshot every
+     * requested prefix once the lock is held. Used by the session-end worker:
+     * requests coalesce onto it while it is queued, so no generation it could
+     * observe proves those requests' writes are in an earlier snapshot.
+     */
+    readonly alwaysSnapshot?: boolean;
+    /** Lock retries for `required` mode. Defaults to {@link SNAPSHOT_LOCK_WAIT_RETRIES}. */
+    readonly lockWaitRetries?: number;
+    /**
+     * Called under the lock BEFORE the state is re-read and the generation is
+     * claimed. The session-end worker uses it to drop its "worker pending"
+     * marker: a request that saw the marker was made before this point, so the
+     * generation claimed next covers it. Errors are ignored.
+     */
+    readonly onLockAcquired?: () => void;
+    /** Clock override for tests (debounce and timestamps only). Defaults to `Date.now`. */
+    readonly now?: () => number;
+}
+/**
+ * Read the current snapshot generation — what a `required` request should
+ * pass as `seenGeneration` when it is made. Returns `null` without a usable
+ * state store (the request is then never considered covered).
+ *
+ * @param db - Handle on the project `cleo.db`, or `null`.
+ * @returns The highest claimed generation, or `null`.
+ * @task T12508
+ */
+export declare function readSnapshotGeneration(db: DatabaseSync | null): number | null;
+/**
+ * Run `snapshot` for every requested prefix that needs one, while holding the
+ * project-wide snapshot lock. See the module comment for the two modes.
+ *
+ * `snapshot` resolves `'written'` when it wrote a snapshot file and
+ * `'absent'` when the database does not exist; a rejection counts as a
+ * failure. Written and absent prefixes are recorded (they satisfy admission);
+ * a failed one is not, so a failed attempt never uses up the debounce window
+ * or covers a later request.
+ *
+ * Never throws; every failure is reported in the result.
+ *
+ * @param opts - Backup directory, state store, prefixes, and mode.
+ * @param snapshot - Performs one prefix's snapshot. Runs under the lock.
+ * @returns Which prefixes were written, absent or failed, or why none ran.
+ * @task T12508
+ */
+export declare function runGatedSnapshot(opts: SnapshotGateOptions, snapshot: (prefix: string) => Promise<SnapshotOutcome>): Promise<SnapshotGateResult>;
+/**
+ * Explain why a `required` snapshot request left no fresh snapshot behind, or
+ * return `null` when it succeeded (written, covered by a later snapshot, or
+ * every prefix absent). Used by callers that must tell the user.
+ *
+ * @param result - Gate outcome; `null` means nothing could be attempted.
+ * @returns A one-line reason, or `null` on success.
+ * @task T12508
+ */
+export declare function describeSnapshotMiss(result: SnapshotGateResult | null): string | null;
+/**
+ * Time-spread retention policy. Each slot kind keeps the NEWEST snapshot in
+ * each of its most recent non-empty buckets; the kept set is the union. Slots
+ * overlap (the latest snapshot is usually also the newest of its quarter hour,
+ * hour and day), so the slotted file count is at most the sum of the counts.
+ */
+export interface SnapshotRetentionPolicy {
+    /** Number of most recent snapshots kept unconditionally. */
+    readonly latest: number;
+    /** Number of most recent distinct 15-minute buckets that keep one snapshot each. */
+    readonly quarterHourly: number;
+    /** Number of most recent distinct clock hours that keep one snapshot each. */
+    readonly hourly: number;
+    /** Number of most recent distinct calendar days that keep one snapshot each. */
+    readonly daily: number;
+}
+/**
+ * Default policy: at most 10 slotted files per prefix, the same ceiling as the
+ * former newest-10 rotation, spread across quarter hours, hours and days. The
+ * quarter-hour slots keep an active session's history from collapsing into
+ * the one hourly bucket it is in.
+ */
+export declare const DEFAULT_SNAPSHOT_RETENTION: SnapshotRetentionPolicy;
+/** Inputs to {@link selectSnapshotsToKeep} besides the filenames. */
+export interface SnapshotRetentionContext {
+    /** Slot counts; defaults to {@link DEFAULT_SNAPSHOT_RETENTION}. */
+    readonly policy?: SnapshotRetentionPolicy;
+    /** The snapshot just written; always kept, whatever its stamp. */
+    readonly pinned?: string;
+    /**
+     * The current local time as a `YYYYMMDD-HHmmss` stamp. Files stamped later
+     * than this are unslotted (kept, but they win no slot). Omit to skip the check.
+     */
+    readonly nowStamp?: string;
+}
+/**
+ * Choose which snapshot files survive retention.
+ *
+ * Buckets come from the `YYYYMMDD-HHmmss` stamp in each filename (the local
+ * time the snapshot was taken), not from mtime, so copying or touching a file
+ * cannot move it between buckets. Buckets are the most recent ones that HOLD
+ * a snapshot, not the most recent hours on the clock: when no snapshots are
+ * taken for a week, last week's history is kept rather than aged out.
+ *
+ * Never deleted: the pinned file (the one just written), files without a
+ * stamp, files with an impossible stamp, and files stamped in the future.
+ * The last two are also unslotted — a skewed or bogus stamp cannot win a slot
+ * and push a real snapshot out.
+ *
+ * Local stamps repeat an hour at the DST fall-back (01:30 PDT, then 01:10
+ * PST). During the repeated hour the earlier PDT file carries a stamp later
+ * than the clock, so it is unslotted and kept; the PST file just written is
+ * pinned. Once the hour passes, both share one hourly bucket.
+ *
+ * @param names - Snapshot filenames for a single prefix.
+ * @param ctx - Policy, pinned file, and current stamp.
+ * @returns The filenames to keep.
+ * @task T12508
+ */
+export declare function selectSnapshotsToKeep(names: readonly string[], ctx?: SnapshotRetentionContext): Set<string>;
+//# sourceMappingURL=snapshot-gate.d.ts.map

package/dist/store/snapshot-gate.d.ts.map

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

package/dist/store/snapshot-gate.js

@@ -0,0 +1,398 @@
+/**
+ * Project-wide admission gate and retention policy for SQLite snapshots.
+ *
+ * `cleo session end` snapshots the project databases. When many agents end
+ * their sessions together, each process used to run its own snapshot, because
+ * the debounce lived in process memory and the session-end hook bypassed it
+ * with `force: true`. On 2026-09-27 that produced four 1.3 GB snapshots in ten
+ * seconds, and the newest-10 rotation then evicted the older recovery points.
+ *
+ * This module closes that path with three mechanisms:
+ *
+ *   1. **Lock** — a cross-process lock ({@link acquireLock}, proper-lockfile)
+ *      on `<backupDir>/.snapshot-gate`. At most one snapshot runs per project.
+ *   2. **Admission** — gate state lives in the project `cleo.db`
+ *      (`tasks_schema_meta`, key {@link SNAPSHOT_GATE_META_KEY}) and is re-read
+ *      under the lock. It holds a monotonic snapshot GENERATION counter,
+ *      claimed under the lock when a snapshot starts, and per prefix the
+ *      generation and start time of its last satisfied snapshot. Two modes
+ *      ({@link SnapshotGateMode}) use it:
+ *        - `routine` (per-write checkpoints): debounced for
+ *          {@link SNAPSHOT_DEBOUNCE_MS}, and the lock is tried once — a caller
+ *          that finds a snapshot in flight skips.
+ *        - `required` (session end, pre-destructive checkpoints): not
+ *          debounced. The caller records the generation it saw when it made
+ *          the request, WAITS for the lock (bounded), and is satisfied only
+ *          by a snapshot of a LATER generation — one that started after the
+ *          request, so it contains every write made before it. Requests queued
+ *          behind one snapshot are all covered by it, so a burst produces one
+ *          snapshot. Works without a state store. No wall clock is involved,
+ *          so a stepped clock cannot fake coverage.
+ *      A prefix whose database does not exist in this project (e.g. no
+ *      `llmtxt.db`) is `absent`: it satisfies admission like a written
+ *      snapshot and is never reported as failed. There is no mode that
+ *      bypasses the lock.
+ *   3. **Retention** — {@link selectSnapshotsToKeep} keeps time-spread slots
+ *      (latest, quarter-hourly, hourly, daily) instead of the newest N, so a
+ *      burst cannot evict older recovery points. The file just written is
+ *      always kept.
+ *
+ * @task T12508
+ */
+import { join } from 'node:path';
+import { acquireLock } from './lock.js';
+/** Minimum interval between two `routine` snapshot starts of a prefix, per project. */
+export const SNAPSHOT_DEBOUNCE_MS = 5 * 60_000;
+/**
+ * Age after which a held gate lock is considered abandoned. `VACUUM INTO` is
+ * synchronous and blocks the event loop, so the lock's mtime cannot be
+ * refreshed while it runs; this value must exceed the longest snapshot.
+ */
+export const SNAPSHOT_LOCK_STALE_MS = 10 * 60_000;
+/**
+ * Default lock retries for a `required` request (pre-destructive
+ * checkpoints). proper-lockfile backs off from 100 ms to 1 s per attempt, so
+ * 90 retries bound the wait to about 90 s.
+ */
+export const SNAPSHOT_LOCK_WAIT_RETRIES = 90;
+/**
+ * Lock retries for the session-end snapshot: about 6.5 s (100 + 200 + 400 +
+ * 800 ms, then 1 s each). Session end runs inside host shutdown hooks that
+ * may be killed, so it must not wait long; the session is already persisted
+ * when it runs.
+ */
+export const SESSION_END_LOCK_WAIT_RETRIES = 9;
+/** `tasks_schema_meta` key holding the persisted snapshot gate state. */
+export const SNAPSHOT_GATE_META_KEY = 'sqlite_snapshot_gate';
+/** Basename of the lock target inside the backup directory. */
+const GATE_LOCK_BASENAME = '.snapshot-gate';
+/**
+ * Read the persisted gate state. Throws when the store cannot be read, so the
+ * caller can distinguish "no state yet" (empty state) from "no state store".
+ */
+function readGateState(db) {
+    const row = db
+        .prepare('SELECT value FROM tasks_schema_meta WHERE key = ?')
+        .get(SNAPSHOT_GATE_META_KEY);
+    const state = { generation: 0, prefixes: {} };
+    if (!row)
+        return state;
+    try {
+        const parsed = JSON.parse(row.value);
+        if (parsed === null || typeof parsed !== 'object')
+            return state;
+        if (typeof parsed.generation === 'number' && Number.isSafeInteger(parsed.generation)) {
+            state.generation = parsed.generation;
+        }
+        for (const [prefix, e] of Object.entries(parsed.prefixes ?? {})) {
+            if (e &&
+                typeof e.generation === 'number' &&
+                typeof e.startedAt === 'number' &&
+                typeof e.completedAt === 'number') {
+                state.prefixes[prefix] = {
+                    generation: e.generation,
+                    startedAt: e.startedAt,
+                    completedAt: e.completedAt,
+                };
+            }
+        }
+    }
+    catch {
+        // A corrupt value (or the pre-generation layout) is treated as "no
+        // history"; the next write replaces it.
+    }
+    return state;
+}
+/** Persist the gate state (upsert). */
+function writeGateState(db, state) {
+    db.prepare('INSERT INTO tasks_schema_meta (key, value) VALUES (?, ?) ' +
+        'ON CONFLICT(key) DO UPDATE SET value = excluded.value').run(SNAPSHOT_GATE_META_KEY, JSON.stringify(state));
+}
+/** Read the state, or `null` when there is no usable state store. */
+function tryReadGateState(db) {
+    if (!db)
+        return null;
+    try {
+        return readGateState(db);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Read the current snapshot generation — what a `required` request should
+ * pass as `seenGeneration` when it is made. Returns `null` without a usable
+ * state store (the request is then never considered covered).
+ *
+ * @param db - Handle on the project `cleo.db`, or `null`.
+ * @returns The highest claimed generation, or `null`.
+ * @task T12508
+ */
+export function readSnapshotGeneration(db) {
+    return tryReadGateState(db)?.generation ?? null;
+}
+/**
+ * Whether a prefix needs a snapshot.
+ *
+ * `routine`: the last satisfied start is outside the debounce window. A start
+ * in the future (the clock moved backwards) does not block.
+ * `required`: no snapshot of a generation later than `seenGeneration`
+ * satisfied it (`seenGeneration === null` means never covered).
+ */
+function needsSnapshot(entry, mode, nowMs, seenGeneration) {
+    if (!entry)
+        return true;
+    if (mode === 'required')
+        return seenGeneration === null || entry.generation <= seenGeneration;
+    const elapsed = nowMs - entry.startedAt;
+    return elapsed < 0 || elapsed >= SNAPSHOT_DEBOUNCE_MS;
+}
+/**
+ * Run `snapshot` for every requested prefix that needs one, while holding the
+ * project-wide snapshot lock. See the module comment for the two modes.
+ *
+ * `snapshot` resolves `'written'` when it wrote a snapshot file and
+ * `'absent'` when the database does not exist; a rejection counts as a
+ * failure. Written and absent prefixes are recorded (they satisfy admission);
+ * a failed one is not, so a failed attempt never uses up the debounce window
+ * or covers a later request.
+ *
+ * Never throws; every failure is reported in the result.
+ *
+ * @param opts - Backup directory, state store, prefixes, and mode.
+ * @param snapshot - Performs one prefix's snapshot. Runs under the lock.
+ * @returns Which prefixes were written, absent or failed, or why none ran.
+ * @task T12508
+ */
+export async function runGatedSnapshot(opts, snapshot) {
+    const now = opts.now ?? Date.now;
+    const mode = opts.mode ?? 'routine';
+    const db = opts.stateDb;
+    const none = (skipped, error) => ({
+        snapshotted: [],
+        linked: [],
+        absent: [],
+        failed: [],
+        skipped,
+        ...(error !== undefined && { error }),
+    });
+    // Read once without the lock: the routine fast path, and the generation a
+    // `required` request was made at (when the caller did not record it).
+    const entryState = tryReadGateState(db);
+    const seenGeneration = mode === 'required' ? (opts.seenGeneration ?? entryState?.generation ?? null) : null;
+    if (mode === 'routine') {
+        if (!entryState)
+            return none('state-unavailable');
+        const nowMs = now();
+        if (!opts.prefixes.some((p) => needsSnapshot(entryState.prefixes[p], mode, nowMs, null))) {
+            return none('debounced');
+        }
+    }
+    const lockPath = join(opts.backupDir, GATE_LOCK_BASENAME);
+    let release;
+    try {
+        release = await acquireLock(lockPath, {
+            retries: mode === 'required' ? (opts.lockWaitRetries ?? SNAPSHOT_LOCK_WAIT_RETRIES) : 0,
+            stale: SNAPSHOT_LOCK_STALE_MS,
+            // A compromised lock (e.g. the backup dir was removed) must not throw
+            // from a timer and crash the host process.
+            onCompromised: () => { },
+        });
+    }
+    catch {
+        if (mode === 'routine')
+            return none('in-flight');
+        return none('lock-timeout', `Snapshot lock ${lockPath}.lock is still held after waiting. Another snapshot is ` +
+            `running, or a crashed process left the lock (it expires after ` +
+            `${SNAPSHOT_LOCK_STALE_MS / 60_000} minutes). Remove it if no snapshot is running.`);
+    }
+    try {
+        try {
+            opts.onLockAcquired?.();
+        }
+        catch {
+            // A failing hook must not cost the snapshot.
+        }
+        // Re-read under the lock: another process may have snapshotted meanwhile.
+        const state = tryReadGateState(db);
+        if (!state && mode === 'routine')
+            return none('state-unavailable');
+        const startMs = now();
+        const admitted = mode === 'required' && opts.alwaysSnapshot === true
+            ? [...opts.prefixes]
+            : opts.prefixes.filter((p) => needsSnapshot(state?.prefixes[p], mode, startMs, seenGeneration));
+        if (admitted.length === 0)
+            return none(mode === 'routine' ? 'debounced' : 'covered');
+        // Claim the next generation BEFORE snapshotting, so a request made while
+        // this run is in flight sees it and is not covered by it.
+        // If the claim cannot be persisted, this run records nothing: recording
+        // under an unclaimed generation could cover a request made while the run
+        // was in flight (it would have seen the old generation).
+        const generation = (state?.generation ?? 0) + 1;
+        let claimed = false;
+        if (db && state) {
+            try {
+                writeGateState(db, { ...state, generation });
+                claimed = true;
+            }
+            catch {
+                // Unclaimed: later requests are simply not covered by this run.
+            }
+        }
+        const snapshotted = [];
+        const linked = [];
+        const absent = [];
+        const failed = [];
+        for (const prefix of admitted) {
+            try {
+                const outcome = await snapshot(prefix);
+                if (outcome === 'absent')
+                    absent.push(prefix);
+                else {
+                    snapshotted.push(prefix);
+                    if (outcome === 'linked')
+                        linked.push(prefix);
+                }
+            }
+            catch {
+                failed.push(prefix);
+            }
+        }
+        const satisfied = [...snapshotted, ...absent];
+        if (db && claimed && satisfied.length > 0) {
+            try {
+                const latest = readGateState(db);
+                const completedAt = now();
+                latest.generation = Math.max(latest.generation, generation);
+                for (const p of satisfied) {
+                    latest.prefixes[p] = { generation, startedAt: startMs, completedAt };
+                }
+                writeGateState(db, latest);
+            }
+            catch {
+                // The snapshot exists; losing its record only makes the next request run.
+            }
+        }
+        return { snapshotted, linked, absent, failed, skipped: null };
+    }
+    finally {
+        await release().catch(() => { });
+    }
+}
+/**
+ * Explain why a `required` snapshot request left no fresh snapshot behind, or
+ * return `null` when it succeeded (written, covered by a later snapshot, or
+ * every prefix absent). Used by callers that must tell the user.
+ *
+ * @param result - Gate outcome; `null` means nothing could be attempted.
+ * @returns A one-line reason, or `null` on success.
+ * @task T12508
+ */
+export function describeSnapshotMiss(result) {
+    if (!result)
+        return 'the backup directory could not be resolved';
+    if (result.skipped === 'lock-timeout')
+        return result.error ?? 'the snapshot lock stayed held';
+    if (result.skipped !== null && result.skipped !== 'covered') {
+        return `the snapshot was skipped (${result.skipped})`;
+    }
+    if (result.failed.length > 0)
+        return `the snapshot failed for: ${result.failed.join(', ')}`;
+    return null;
+}
+/**
+ * Default policy: at most 10 slotted files per prefix, the same ceiling as the
+ * former newest-10 rotation, spread across quarter hours, hours and days. The
+ * quarter-hour slots keep an active session's history from collapsing into
+ * the one hourly bucket it is in.
+ */
+export const DEFAULT_SNAPSHOT_RETENTION = {
+    latest: 1,
+    quarterHourly: 3,
+    hourly: 3,
+    daily: 3,
+};
+/** `YYYYMMDD-HHmmss` stamp embedded in a snapshot filename. */
+const STAMP_PATTERN = /-(\d{8})-(\d{6})\.db$/;
+/** Whether `YYYYMMDD` + `HHmmss` name a real calendar date and time. */
+function isValidStamp(ymd, hms) {
+    const y = Number(ymd.slice(0, 4));
+    const mo = Number(ymd.slice(4, 6));
+    const d = Number(ymd.slice(6, 8));
+    const h = Number(hms.slice(0, 2));
+    const mi = Number(hms.slice(2, 4));
+    const se = Number(hms.slice(4, 6));
+    if (mo < 1 || mo > 12 || d < 1 || h > 23 || mi > 59 || se > 59)
+        return false;
+    // Day-of-month check via UTC so no time zone can shift the date.
+    const probe = new Date(Date.UTC(y, mo - 1, d));
+    return probe.getUTCFullYear() === y && probe.getUTCMonth() === mo - 1 && probe.getUTCDate() === d;
+}
+/**
+ * Choose which snapshot files survive retention.
+ *
+ * Buckets come from the `YYYYMMDD-HHmmss` stamp in each filename (the local
+ * time the snapshot was taken), not from mtime, so copying or touching a file
+ * cannot move it between buckets. Buckets are the most recent ones that HOLD
+ * a snapshot, not the most recent hours on the clock: when no snapshots are
+ * taken for a week, last week's history is kept rather than aged out.
+ *
+ * Never deleted: the pinned file (the one just written), files without a
+ * stamp, files with an impossible stamp, and files stamped in the future.
+ * The last two are also unslotted — a skewed or bogus stamp cannot win a slot
+ * and push a real snapshot out.
+ *
+ * Local stamps repeat an hour at the DST fall-back (01:30 PDT, then 01:10
+ * PST). During the repeated hour the earlier PDT file carries a stamp later
+ * than the clock, so it is unslotted and kept; the PST file just written is
+ * pinned. Once the hour passes, both share one hourly bucket.
+ *
+ * @param names - Snapshot filenames for a single prefix.
+ * @param ctx - Policy, pinned file, and current stamp.
+ * @returns The filenames to keep.
+ * @task T12508
+ */
+export function selectSnapshotsToKeep(names, ctx = {}) {
+    const policy = ctx.policy ?? DEFAULT_SNAPSHOT_RETENTION;
+    const keep = new Set();
+    const stamped = [];
+    for (const name of names) {
+        const m = STAMP_PATTERN.exec(name);
+        const ymd = m?.[1];
+        const hms = m?.[2];
+        if (!ymd || !hms || !isValidStamp(ymd, hms)) {
+            keep.add(name);
+            continue;
+        }
+        const stamp = `${ymd}-${hms}`;
+        if (ctx.nowStamp !== undefined && stamp > ctx.nowStamp) {
+            keep.add(name);
+            continue;
+        }
+        stamped.push({ name, stamp });
+    }
+    if (ctx.pinned !== undefined && names.includes(ctx.pinned))
+        keep.add(ctx.pinned);
+    // Newest first; the stamp sorts lexicographically in time order.
+    stamped.sort((a, b) => (a.stamp < b.stamp ? 1 : a.stamp > b.stamp ? -1 : 0));
+    for (const s of stamped.slice(0, policy.latest))
+        keep.add(s.name);
+    const keepNewestPerBucket = (bucketOf, slots) => {
+        const seen = new Set();
+        for (const s of stamped) {
+            const bucket = bucketOf(s.stamp);
+            if (seen.has(bucket))
+                continue;
+            if (seen.size >= slots)
+                break;
+            seen.add(bucket);
+            keep.add(s.name);
+        }
+    };
+    // YYYYMMDD-HH + quarter index (minutes 00-14 → 0, 15-29 → 1, …)
+    keepNewestPerBucket((stamp) => `${stamp.slice(0, 11)}q${Math.floor(Number(stamp.slice(11, 13)) / 15)}`, policy.quarterHourly);
+    keepNewestPerBucket((stamp) => stamp.slice(0, 11), policy.hourly); // YYYYMMDD-HH
+    keepNewestPerBucket((stamp) => stamp.slice(0, 8), policy.daily); // YYYYMMDD
+    return keep;
+}
+//# sourceMappingURL=snapshot-gate.js.map

package/dist/store/snapshot-gate.js.map

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