@itookit/dsht 0.5.1 → 0.6.0

package/dist/controller/loop-source.js

@@ -0,0 +1,224 @@
+/** Resolve the records `/loop` runs: the shipped loop.yaml, a user file layered over it, and the
+ * table compiled into this build as the last resort.
+ *
+ * The loop record is configuration, not code: the shipped file travels with the package and is read
+ * at startup, so a fix to a rubric reaches an install without a TypeScript build, and `DSHT_LOOP_FILE`
+ * or `<config>/loop.yaml` lets an operator add a record or correct one without forking the project.
+ *
+ * Layering is per record, never per file. A user file that overrides one record leaves every other
+ * shipped record following the package, so the next version's fixes still arrive; a whole-file
+ * replacement would freeze the shipped records at whatever the operator copied. A record the user does
+ * override can never be updated for them — the tool cannot know whether their copy is deliberate — so
+ * the shipped record's digest is stamped under the state directory and a change is reported, not
+ * applied.
+ *
+ * `loop-prompts.generated.ts` stays as the fallback: a package whose loop.yaml is missing or corrupt
+ * still starts on the records this build was compiled with, which is also what keeps the module
+ * self-contained for a test that must not touch the filesystem.
+ */
+import { createHash } from 'node:crypto';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parse } from 'yaml';
+import { LOOP_PROMPTS } from "./loop-prompts.generated.js";
+import { validateLoopOverlayPrompts, validateLoopPrompts } from "./loop-prompts-schema.js";
+import { ensureDirectory, readText, writePrivateFile } from "../storage/index.js";
+/** Path of the `loop.yaml` shipped beside this module.
+ *
+ * The path is relative to the module, so it resolves both in the source tree (`src/controller/`) and
+ * in the published build (`dist/controller/`), exactly as the version read in `cli/dsht.tsx` does.
+ * @returns Absolute path to the shipped record file.
+ */
+export function shippedLoopFile() {
+    return fileURLToPath(new URL('../../loop.yaml', import.meta.url));
+}
+/** The overlay file a process reads, if it reads one at all.
+ *
+ * An explicit file wins over the configuration directory: it is how a script or a second checkout
+ * points at another set of records without moving the one the interactive client uses.
+ * @param options - Resolved options.
+ * @returns Absolute path of the overlay to try.
+ */
+export function loopOverlayFile(options) {
+    return options.overlayFile ?? join(options.configDirectory, 'loop.yaml');
+}
+/** Layer one user file over the shipped records.
+ *
+ * A record is taken whole: replacing one does not merge its fields with the shipped copy, because a
+ * record is a single prompt contract and a half-new brief with a half-old round table is a protocol
+ * nobody wrote. Records the file does not name are untouched, which is what lets a shipped fix reach
+ * an install that customises something else.
+ * @param builtin - Shipped records.
+ * @param overlay - Parsed user file.
+ * @returns The merged table and the names the user file replaced or added.
+ */
+export function mergeLoopSource(builtin, overlay) {
+    const overridden = [];
+    const added = [];
+    for (const name of Object.keys(overlay.protocols ?? {})) {
+        (Object.hasOwn(builtin.protocols, name) ? overridden : added).push(name);
+    }
+    return {
+        source: {
+            version: 1,
+            defaults: {
+                score: overlay.defaults?.score ?? builtin.defaults.score,
+                tries: overlay.defaults?.tries ?? builtin.defaults.tries,
+            },
+            protocols: { ...builtin.protocols, ...(overlay.protocols ?? {}) },
+        },
+        overridden,
+        added,
+    };
+}
+/** Read the merged records for one process.
+ *
+ * The shipped file falls back to the compiled-in table with a warning, because a packaging mistake
+ * should not stop the client; a user file does not, because an invalid override the operator wrote is
+ * a mistake they can fix and a silent fallback would run the shipped records while they believe their
+ * own are in force. An absent overlay is ordinary: most installs have none.
+ * @param options - Resolution options.
+ * @returns The merged records, their sources and the notes to show the operator.
+ * @throws when the overlay exists but is not a valid loop file.
+ */
+export async function loadLoopSource(options) {
+    const fallback = options.fallback ?? LOOP_PROMPTS;
+    const warnings = [];
+    const shipped = await readShipped(options.builtinFile ?? shippedLoopFile(), fallback, warnings);
+    const overlayPath = loopOverlayFile(options);
+    const raw = await readText(overlayPath);
+    if (raw === undefined) {
+        return {
+            source: shipped.source,
+            info: {
+                ...(shipped.file === undefined ? {} : { builtin: shipped.file }),
+                overridden: [], added: [], warnings,
+            },
+        };
+    }
+    const overlay = parseOverlay(overlayPath, raw);
+    const merged = mergeLoopSource(shipped.source, overlay);
+    const drift = await stampOverrides(options.stateDirectory, shipped.source, merged.overridden, overlayPath);
+    return {
+        source: merged.source,
+        info: {
+            ...(shipped.file === undefined ? {} : { builtin: shipped.file }),
+            file: overlayPath,
+            overridden: merged.overridden,
+            added: merged.added,
+            warnings: [...warnings, ...drift],
+        },
+    };
+}
+/** Read and validate the shipped file, falling back to the compiled-in table.
+ * @param path - Shipped file path.
+ * @param fallback - Table to use when the file cannot be read or is invalid.
+ * @param warnings - Collector for the note that explains a fallback.
+ * @returns The shipped records and the file they came from, if any.
+ */
+async function readShipped(path, fallback, warnings) {
+    const raw = await readText(path);
+    if (raw === undefined) {
+        warnings.push(`Cannot read the shipped records at ${path}; using the table compiled into this build.`);
+        return { source: fallback };
+    }
+    let parsed;
+    try {
+        parsed = parse(raw);
+    }
+    catch (error) {
+        warnings.push(`Cannot parse the shipped records at ${path}: ${message(error)}. Using the table compiled into this build.`);
+        return { source: fallback };
+    }
+    const errors = validateLoopPrompts(parsed);
+    if (errors.length > 0) {
+        warnings.push(`The shipped records at ${path} are invalid: ${errors.join('; ')}. Using the table compiled into this build.`);
+        return { source: fallback };
+    }
+    return { source: parsed, file: path };
+}
+/** Parse one overlay file, refusing anything the renderer would misread.
+ * @param path - Overlay file path, used in every message.
+ * @param raw - File contents.
+ * @returns The parsed overlay.
+ * @throws when the file is not valid YAML or does not satisfy the overlay schema.
+ */
+function parseOverlay(path, raw) {
+    let parsed;
+    try {
+        parsed = parse(raw);
+    }
+    catch (error) {
+        throw new Error(`${path}: ${message(error)}`);
+    }
+    const errors = validateLoopOverlayPrompts(parsed);
+    if (errors.length > 0)
+        throw new Error(`${path}:\n- ${errors.join('\n- ')}`);
+    return parsed;
+}
+/** Report a shipped record that changed under the operator's override.
+ *
+ * The stamp is the only durable trace of which shipped copy an override was written against. When a
+ * later version ships a different definition of a record this install overrides, that update cannot
+ * be applied — the operator's file wins by design — so it is reported once per change instead of
+ * being lost silently. The write is best effort: a state directory that cannot be written costs a
+ * warning, never a failed start.
+ * @param stateDirectory - Directory holding the stamp; omitted disables the check.
+ * @param builtin - Shipped records, read before merging.
+ * @param overridden - Names the overlay replaced.
+ * @param overlayPath - Overlay file the names came from, named in the warning.
+ * @returns One warning per shipped record that changed since it was last seen.
+ */
+async function stampOverrides(stateDirectory, builtin, overridden, overlayPath) {
+    if (stateDirectory === undefined)
+        return [];
+    const path = join(stateDirectory, 'loop-overrides.json');
+    const warnings = [];
+    const current = {};
+    let previous = {};
+    const raw = await readText(path);
+    // No override and no stamp: an install that never customised a shipped record leaves no file behind.
+    if (raw === undefined && overridden.length === 0)
+        return [];
+    if (raw !== undefined) {
+        try {
+            const parsed = JSON.parse(raw);
+            if (parsed.records !== null && typeof parsed.records === 'object')
+                previous = parsed.records;
+        }
+        catch {
+            previous = {};
+        }
+    }
+    for (const name of overridden) {
+        const record = builtin.protocols[name];
+        // A name the shipped table does not have is an addition, not an override: there is no upstream
+        // definition for it to fall behind.
+        if (record === undefined)
+            continue;
+        const digest = digestOf(record);
+        current[name] = digest;
+        if (previous[name] !== undefined && previous[name] !== digest) {
+            warnings.push(`Your ${name} in ${overlayPath} replaces a shipped record that changed in this version; `
+                + `the shipped update is not applied to your copy.`);
+        }
+    }
+    const stamp = `${JSON.stringify({ version: 1, records: current }, null, 2)}\n`;
+    if (stamp !== raw) {
+        try {
+            await ensureDirectory(stateDirectory);
+            await writePrivateFile(path, stamp);
+        }
+        catch { /* The stamp only enables a warning; failing to write it must not stop the client. */ }
+    }
+    return warnings;
+}
+/** Content digest of one record, stable across key order because it hashes the serialized record.
+ * @param record - Shipped record.
+ * @returns Lowercase hex sha256.
+ */
+function digestOf(record) {
+    return createHash('sha256').update(JSON.stringify(record)).digest('hex');
+}
+/** Readable text for anything thrown. */
+function message(error) { return error instanceof Error ? error.message : String(error); }

package/dist/controller/verifier.d.ts

@@ -123,4 +123,8 @@ export interface VerifierPort {
      * @returns The verdict, or a note explaining why there is none.
      */
     verify(request: VerifierRequest, signal: AbortSignal): Promise<VerifierOutcome>;
+    /** Drain adapter-owned cleanup after all run signals have been aborted, before closing the host.
+     * Adapters with child processes or remote sessions implement this; pure in-memory judges need not.
+     */
+    settle?(): Promise<void>;
 }

package/dist/cost/controller.d.ts

@@ -12,6 +12,8 @@ export interface CostHost {
     signal(): AbortSignal;
     /** Re-publish controller state after the ledger changes. */
     publish(): void;
+    /** Session the operator is reading; always scanned, so its own total is shown even when it is old. */
+    selectedSessionId?(): string | undefined;
     /** Hand one already-read history page to another consumer, which owns what it does with it. */
     scanPage?(sessionId: string, records: readonly Json[]): void;
     /** Report that a session's history was read to its beginning. */
@@ -35,7 +37,7 @@ export declare class CostController {
      * sessions.
      */
     start(): void;
-    /** Stop the timer and wait for an in-flight scan; the ledger keeps its folded totals. */
+    /** Cancel the timer and active scan, then wait for cleanup; keep already folded totals. */
     stop(): Promise<void>;
     /** Refresh after the host reports a turn complete. */
     onTurnIdle(): void;

package/dist/cost/controller.js

@@ -1,4 +1,5 @@
 import { array, errorText, object, string } from "../transport/wire.js";
+import { costDayStart, costWindowStart } from "./pricing.js";
 import { sessionCostHistory } from "./scanner.js";
 /** Refresh interval for the background cost scan. */
 const REFRESH_INTERVAL_MS = 60_000;
@@ -30,10 +31,11 @@ export class CostController {
         this.timer = setInterval(() => { if (this.host.online())
             void this.refresh().catch(() => undefined); }, REFRESH_INTERVAL_MS);
     }
-    /** Stop the timer and wait for an in-flight scan; the ledger keeps its folded totals. */
+    /** Cancel the timer and active scan, then wait for cleanup; keep already folded totals. */
     async stop() {
         clearInterval(this.timer);
         this.timer = undefined;
+        this.abort?.abort();
         await this.task;
     }
     /** Refresh after the host reports a turn complete. */
@@ -45,8 +47,11 @@ export class CostController {
      * @param signal - Optional cancellation for an explicit `/cost` refresh.
      */
     async refresh(signal = this.host.signal()) {
+        signal.throwIfAborted();
+        this.host.signal().throwIfAborted();
         if (this.task) {
-            const cancel = () => this.abort?.abort();
+            const scanAbort = this.abort;
+            const cancel = () => scanAbort?.abort();
             signal.addEventListener('abort', cancel, { once: true });
             try {
                 await this.task;
@@ -64,24 +69,36 @@ export class CostController {
         const ledger = this.ledger;
         ledger.scanning = true;
         ledger.error = '';
-        this.host.publish();
-        const task = (async () => {
+        const task = Promise.resolve().then(async () => {
             try {
+                combined.throwIfAborted();
                 const sessions = array(object(await client.call('session/list', { _request: {} }, combined)).items).map(object);
                 combined.throwIfAborted();
                 const failures = [];
                 let scanned = 0, pages = 0, events = 0;
+                // Sessions that cannot have spent anything inside the retained window are not worth paging:
+                // their whole history would fold into days the ledger does not keep. Billable activity moves
+                // `updatedAt`, so anything that happened while this client was away is still read.
+                const floor = costDayStart(costWindowStart(Date.now()));
+                const selected = this.host.selectedSessionId?.();
                 for (const session of sessions) {
                     combined.throwIfAborted();
                     const sessionId = string(session.sessionId);
-                    if (!session.running && typeof session.updatedAt === 'number' && this.updates.get(sessionId) === session.updatedAt)
-                        continue;
+                    // The selected session is exempt from the window, not from the within-generation skip: the
+                    // panel reports its own total, but an unchanged history is still not read twice a minute.
+                    if (!session.running && typeof session.updatedAt === 'number') {
+                        if (sessionId !== selected && session.updatedAt < floor)
+                            continue;
+                        if (this.updates.get(sessionId) === session.updatedAt)
+                            continue;
+                    }
                     try {
                         const history = await sessionCostHistory(client, session, combined, () => { pages++; }, records => this.host.scanPage?.(sessionId, records));
                         this.host.scanDone?.(sessionId);
                         scanned++;
                         events += history.events.length;
                         await ledger.replace(sessionId, history.cursor, history.events);
+                        combined.throwIfAborted();
                         if (!session.running && typeof session.updatedAt === 'number')
                             this.updates.set(sessionId, session.updatedAt);
                         this.host.publish();
@@ -103,8 +120,10 @@ export class CostController {
                 ledger.scanning = false;
                 this.host.publish();
             }
-        })();
+        });
         this.task = task;
+        // Publish only after reserving the scan: an observer may synchronously join or cancel it.
+        this.host.publish();
         try {
             await task;
         }

package/dist/cost/index.d.ts

@@ -3,7 +3,7 @@ export { CostController } from './controller.ts';
 export type { CostHost } from './controller.ts';
 export { CostLedger } from './ledger.ts';
 export { loadPrices } from './config.ts';
-export { candidates, canonicalModel, chargeFor, costDay, DEFAULT_PRICES, isUncorrectedSeed, priceAt, PRICES_REVISION, PRICING_ENGINE_VERSION, pricesDigest, pricesFrom } from './pricing.ts';
+export { candidates, canonicalModel, chargeFor, costDay, costDayStart, costDaysBefore, costMonthStart, costWeekStart, costWindowStart, COST_WINDOW_DAYS, DEFAULT_PRICES, isUncorrectedSeed, priceAt, PRICES_REVISION, PRICING_ENGINE_VERSION, pricesDigest, pricesFrom } from './pricing.ts';
 export { costRecords, foldSamples } from './records.ts';
 export { costAddresses, sessionCostHistory } from './scanner.ts';
 export { MISSING_TIME, MISSING_USAGE, UNSUPPORTED_USAGE } from './types.ts';

package/dist/cost/index.js

@@ -2,7 +2,7 @@
 export { CostController } from "./controller.js";
 export { CostLedger } from "./ledger.js";
 export { loadPrices } from "./config.js";
-export { candidates, canonicalModel, chargeFor, costDay, DEFAULT_PRICES, isUncorrectedSeed, priceAt, PRICES_REVISION, PRICING_ENGINE_VERSION, pricesDigest, pricesFrom } from "./pricing.js";
+export { candidates, canonicalModel, chargeFor, costDay, costDayStart, costDaysBefore, costMonthStart, costWeekStart, costWindowStart, COST_WINDOW_DAYS, DEFAULT_PRICES, isUncorrectedSeed, priceAt, PRICES_REVISION, PRICING_ENGINE_VERSION, pricesDigest, pricesFrom } from "./pricing.js";
 export { costRecords, foldSamples } from "./records.js";
 export { costAddresses, sessionCostHistory } from "./scanner.js";
 export { MISSING_TIME, MISSING_USAGE, UNSUPPORTED_USAGE } from "./types.js";

package/dist/cost/ledger-files.d.ts

@@ -1,5 +1,8 @@
 import type { SavedCost } from './types.ts';
 /** Load every session's stored totals; a file this build cannot read is left for the next scan.
+ *
+ * A slice is a projection of the host log, so a file this build cannot parse costs a rescan and never
+ * stops the client: an unreadable or malformed one is skipped exactly like an older generation.
  * @param directory - Origin-scoped ledger directory, or undefined when persistence is disabled.
  * @returns The newest saved slice per session identity.
  */
@@ -14,3 +17,20 @@ export declare function loadLedgers(directory: string | undefined): Promise<Map<
  * @returns Whether the directory now holds this slice.
  */
 export declare function saveLedger(directory: string, saved: SavedCost): Promise<boolean>;
+/** Delete the ledger files a retention window no longer needs.
+ *
+ * Two rules, because a file this build cannot parse still has to age out: a loaded slice whose newest
+ * day is outside the window goes immediately, and any ledger-shaped file whose modification time
+ * predates the window goes whatever it holds — which is how a file of an older generation, one this
+ * build can no longer read, is collected instead of sitting in the directory forever. A slice is
+ * always written after the last day it records, so a file older than the window cannot hold a day
+ * inside it: neither rule can delete a day the panel would still have shown.
+ *
+ * Retention is housekeeping, so every failure here is swallowed: a state directory that is read-only,
+ * owned by someone else, or being written by another process costs a stale file, never a start.
+ * @param directory - Origin-scoped ledger directory, or undefined when persistence is disabled.
+ * @param floorDay - Oldest Beijing day still kept, YYYY-MM-DD.
+ * @param loaded - Slices just loaded, so their own days decide before their timestamp does.
+ * @returns Session identities whose loaded slice was deleted.
+ */
+export declare function pruneLedgers(directory: string | undefined, floorDay: string, loaded: ReadonlyMap<string, SavedCost>): Promise<string[]>;

package/dist/cost/ledger-files.js

@@ -1,14 +1,17 @@
 /** Atomic per-session persistence for folded cost totals. */
 import { createHash } from 'node:crypto';
 import { join } from 'node:path';
-import { ensureDirectory, listEntries, readText, writePrivateFile } from "../storage/index.js";
+import { ensureDirectory, listEntries, modifiedAt, readText, removeFile, writePrivateFile } from "../storage/index.js";
 /** Current on-disk ledger generation. A file of another generation is ignored: the next scan rebuilds it. */
-const LEDGER_VERSION = 3;
+const LEDGER_VERSION = 4;
 /** The one file that holds a session's totals: the fixed per-session name. */
 function ledgerName(sessionId) {
     return `${createHash('sha256').update(sessionId).digest('hex')}.json`;
 }
 /** Load every session's stored totals; a file this build cannot read is left for the next scan.
+ *
+ * A slice is a projection of the host log, so a file this build cannot parse costs a rescan and never
+ * stops the client: an unreadable or malformed one is skipped exactly like an older generation.
  * @param directory - Origin-scoped ledger directory, or undefined when persistence is disabled.
  * @returns The newest saved slice per session identity.
  */
@@ -26,7 +29,6 @@ export async function loadLedgers(directory) {
         if (raw === undefined)
             continue;
         const saved = parseLedger(raw);
-        // A slice is a projection of the host log: one this build cannot use costs a rescan, not data.
         if (saved === undefined)
             continue;
         if ((sessions.get(saved.sessionId)?.cut ?? -2) <= saved.cut)
@@ -54,6 +56,83 @@ export async function saveLedger(directory, saved) {
     await writePrivateFile(path, JSON.stringify(saved) + '\n');
     return true;
 }
+/** Delete the ledger files a retention window no longer needs.
+ *
+ * Two rules, because a file this build cannot parse still has to age out: a loaded slice whose newest
+ * day is outside the window goes immediately, and any ledger-shaped file whose modification time
+ * predates the window goes whatever it holds — which is how a file of an older generation, one this
+ * build can no longer read, is collected instead of sitting in the directory forever. A slice is
+ * always written after the last day it records, so a file older than the window cannot hold a day
+ * inside it: neither rule can delete a day the panel would still have shown.
+ *
+ * Retention is housekeeping, so every failure here is swallowed: a state directory that is read-only,
+ * owned by someone else, or being written by another process costs a stale file, never a start.
+ * @param directory - Origin-scoped ledger directory, or undefined when persistence is disabled.
+ * @param floorDay - Oldest Beijing day still kept, YYYY-MM-DD.
+ * @param loaded - Slices just loaded, so their own days decide before their timestamp does.
+ * @returns Session identities whose loaded slice was deleted.
+ */
+export async function pruneLedgers(directory, floorDay, loaded) {
+    if (!directory)
+        return [];
+    const dropped = [];
+    try {
+        await ensureDirectory(directory);
+    }
+    catch {
+        return dropped;
+    }
+    const gone = new Set();
+    for (const [sessionId, session] of loaded) {
+        // The days are sorted oldest first, so the last one is the newest thing this slice knows. A slice
+        // with no days at all carries nothing — no total, no day — and goes too.
+        const newest = session.days[session.days.length - 1]?.day;
+        if (newest !== undefined && newest >= floorDay)
+            continue;
+        // A slice that cannot be removed stays loaded: the file is still there, so the totals it holds are
+        // still this run's to report.
+        if (!await dropLedger(directory, sessionId))
+            continue;
+        gone.add(sessionId);
+        dropped.push(sessionId);
+    }
+    const floorMs = Date.parse(`${floorDay}T00:00:00+08:00`);
+    const kept = new Set([...loaded.keys()].filter(sessionId => !gone.has(sessionId)).map(ledgerName));
+    let names;
+    try {
+        names = await listEntries(directory);
+    }
+    catch {
+        return dropped;
+    }
+    for (const name of names) {
+        if (!/^[0-9a-f]{64}\.json$/.test(name) || kept.has(name))
+            continue;
+        try {
+            // A file removed between listing and stating is simply absent, and needs no deletion.
+            const modified = await modifiedAt(join(directory, name));
+            if (modified === undefined || modified >= floorMs)
+                continue;
+            await removeFile(join(directory, name));
+        }
+        catch { /* best effort: see the contract above */ }
+    }
+    return dropped;
+}
+/** Remove one slice, reporting whether the directory is now free of it.
+ * @param directory - Origin-scoped ledger directory.
+ * @param sessionId - Session whose slice should go.
+ * @returns True when the file is gone; false when the removal failed and the file remains.
+ */
+async function dropLedger(directory, sessionId) {
+    try {
+        await removeFile(join(directory, ledgerName(sessionId)));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /** Validate one persisted slice; another generation or an unreadable shape is absent. */
 function parseLedger(raw) {
     let value;
@@ -68,18 +147,39 @@ function parseLedger(raw) {
     const record = value;
     if (record.version !== LEDGER_VERSION)
         return undefined;
-    if (typeof record.sessionId !== 'string' || !Number.isSafeInteger(record.cut))
-        throw new Error('Invalid cost ledger');
-    if (!Number.isSafeInteger(record.engine) || typeof record.catalog !== 'string')
-        throw new Error('Invalid cost ledger');
-    const total = validTotal(record.total);
-    const day = validDay(record.day);
-    if (total === undefined || day === undefined)
-        throw new Error('Invalid cost ledger');
-    if (!Array.isArray(record.unpriced) || record.unpriced.some(reason => typeof reason !== 'string'))
-        throw new Error('Invalid cost ledger');
-    return { version: LEDGER_VERSION, sessionId: record.sessionId, cut: record.cut, engine: record.engine,
-        catalog: record.catalog, total, day, unpriced: record.unpriced };
+    try {
+        if (typeof record.sessionId !== 'string' || !Number.isSafeInteger(record.cut))
+            throw new Error('Invalid cost ledger');
+        if (!Number.isSafeInteger(record.engine) || typeof record.catalog !== 'string')
+            throw new Error('Invalid cost ledger');
+        const total = validTotal(record.total);
+        const days = validDays(record.days);
+        if (total === undefined || days === undefined)
+            throw new Error('Invalid cost ledger');
+        if (!Array.isArray(record.unpriced) || record.unpriced.some(reason => typeof reason !== 'string'))
+            throw new Error('Invalid cost ledger');
+        return { version: LEDGER_VERSION, sessionId: record.sessionId, cut: record.cut, engine: record.engine,
+            catalog: record.catalog, total, days, unpriced: record.unpriced };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Accept every stored day, or none: a partial day list would silently under-report a period.
+ * @param value - The `days` field as parsed.
+ * @returns The validated days, or undefined when any entry is unusable.
+ */
+function validDays(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const days = [];
+    for (const entry of value) {
+        const total = validDay(entry);
+        if (total === undefined)
+            return undefined;
+        days.push(total);
+    }
+    return days;
 }
 /** Accept one stored subtotal only when the amount is finite and the counts are whole.
  * Costs are fractional, so only the counts are required to be integers. */

package/dist/cost/ledger.d.ts

@@ -1,7 +1,7 @@
-/** CNY estimates folded from host history: per-session totals, re-decided by every scan. */
+/** CNY estimates folded from host history: per-session totals and per-day buckets, re-decided by every scan. */
 import type { ObjectValue } from '../transport/wire.ts';
 import { type CostTotal, type Coverage, type PriceVersion } from './types.ts';
-/** Per-origin cache of folded session totals; every scan replaces a session at its cut. */
+/** Per-origin cache of folded session totals and day buckets; every scan replaces a session at its cut. */
 export declare class CostLedger {
     readonly prices: PriceVersion[];
     readonly directory?: string | undefined;
@@ -26,8 +26,14 @@ export declare class CostLedger {
      * @returns Coverage of the current totals, so callers can mark them without re-deriving the rule.
      */
     get coverage(): Coverage;
-    /** Load the newest cut per session; a stored total is read as it was decided. */
-    load(): Promise<void>;
+    /** Load the newest cut per session; a stored total is read as it was decided.
+     *
+     * Slices and dead files that have left the retention window are deleted in the same pass, so the
+     * directory cannot grow with every session this client has ever seen. A slice is a projection of the
+     * host log, so letting one go costs a rescan of that session, never data.
+     * @param now - Clock that names the window, so a caller or a test can pin the boundary.
+     */
+    load(now?: number): Promise<void>;
     /** Replace one session using all billing events through the opening snapshot cut.
      *
      * The fold is the projection: every sample is decided again with the table loaded now, so a
@@ -64,12 +70,31 @@ export declare class CostLedger {
     total(sessionId: string): CostTotal;
     /** Every session's requests on one Beijing calendar day.
      *
-     * A slice keeps only the day its last scan ran on, so another day reads as nothing spent today
-     * rather than as the last day that was scanned.
+     * The day is a real bucket rather than only the day a scan ran on, so asking for another day
+     * reports that day's spend; the retention window is what limits how far back the answer reaches.
      * @param now - Clock that names the day to report.
      * @returns The day's total across cached sessions.
      */
     today(now?: number): CostTotal;
+    /** Every session's requests in the natural week containing a day, through that day.
+     * @param now - Clock that names the day to report.
+     * @returns The week-to-date total across cached sessions.
+     */
+    week(now?: number): CostTotal;
+    /** Every session's requests in the natural month containing a day, through that day.
+     * @param now - Clock that names the day to report.
+     * @returns The month-to-date total across cached sessions.
+     */
+    month(now?: number): CostTotal;
+    /** Sum stored day buckets over a Beijing day range, inclusive at both ends.
+     *
+     * Days outside the retention window are absent rather than zero, so a range wider than the window
+     * reports what is still kept — which is why the fold and this sum share one window constant.
+     * @param from - First day to include, YYYY-MM-DD.
+     * @param to - Last day to include, YYYY-MM-DD.
+     * @returns The range's total across cached sessions.
+     */
+    private period;
 }
 /** Compact estimates retain an asterisk whenever a subtotal is not exact.
  * @param total - Summary from the ledger.