@itookit/dsht 0.3.2 → 0.3.4

package/dist/cost/ledger-files.js

@@ -1,21 +1,14 @@
-/** Atomic per-session persistence for the immutable charge ledger. */
+/** Atomic per-session persistence for folded cost totals. */
 import { createHash } from 'node:crypto';
 import { join } from 'node:path';
-import { ensureDirectory, listEntries, readText, removeFile, writePrivateFile } from "../storage/index.js";
-/** Current on-disk ledger generation. Files of another generation are ignored, not migrated. */
-const LEDGER_VERSION = 2;
-/** Every file this unit owns: the fixed per-session name, or the `<session>-<cut>.json` it replaced. */
-const OWNED_FILE = /^[0-9a-f]{64}(?:-\d+)?\.json$/;
-/** The one file that holds a session's newest cut; the cut itself lives inside the file. */
+import { ensureDirectory, listEntries, readText, 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;
+/** 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 newest cut, leaving one fixed file per session.
- *
- * A file of another generation, a file with an unreadable shape, and a cut file superseded by the
- * newer name all describe work the next scan rebuilds, so loading removes them; the newest slice
- * of a superseded name is rewritten under the fixed one first. Files this unit does not own are
- * left where they are.
+/** Load every session's stored totals; a file this build cannot read is left for the next scan.
  * @param directory - Origin-scoped ledger directory, or undefined when persistence is disabled.
  * @returns The newest saved slice per session identity.
  */
@@ -24,9 +17,8 @@ export async function loadLedgers(directory) {
     if (!directory)
         return sessions;
     await ensureDirectory(directory);
-    const superseded = [];
     for (const name of await listEntries(directory)) {
-        if (!OWNED_FILE.test(name))
+        if (!/^[0-9a-f]{64}\.json$/.test(name))
             continue;
         const path = join(directory, name);
         const raw = await readText(path);
@@ -34,25 +26,19 @@ export async function loadLedgers(directory) {
         if (raw === undefined)
             continue;
         const saved = parseLedger(raw);
-        if (saved === undefined) {
-            await removeFile(path);
+        // 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)
             sessions.set(saved.sessionId, saved);
-        if (name !== ledgerName(saved.sessionId))
-            superseded.push({ path, sessionId: saved.sessionId });
-    }
-    for (const { path, sessionId } of superseded) {
-        await writePrivateFile(join(directory, ledgerName(sessionId)), JSON.stringify(sessions.get(sessionId)) + '\n');
-        await removeFile(path);
     }
     return sessions;
 }
-/** Write one session cut unless the directory already holds a newer one.
+/** Write one session's totals unless the directory already holds a newer scan.
  *
  * The file is the system of record across processes, so a scan that opened an older snapshot must
- * not replace a cut another scan already persisted.
+ * not replace a cut another scan already persisted, and a process holding older decision rules must
+ * not seal its totals over newer ones.
  * @param directory - Origin-scoped ledger directory.
  * @param saved - Complete slice to persist.
  * @returns Whether the directory now holds this slice.
@@ -60,25 +46,15 @@ export async function loadLedgers(directory) {
 export async function saveLedger(directory, saved) {
     const path = join(directory, ledgerName(saved.sessionId));
     const existing = await readText(path);
-    if (existing !== undefined && persistedCut(existing) > saved.cut)
-        return false;
+    if (existing !== undefined) {
+        const previous = parseLedger(existing);
+        if (previous !== undefined && (previous.cut > saved.cut || previous.engine > saved.engine))
+            return false;
+    }
     await writePrivateFile(path, JSON.stringify(saved) + '\n');
     return true;
 }
-/** The cut already persisted in one file, or -1 when it holds no decision worth keeping.
- * @param raw - File contents read from the ledger directory.
- * @returns The persisted cut.
- */
-function persistedCut(raw) {
-    try {
-        return parseLedger(raw)?.cut ?? -1;
-    }
-    // A file of another generation or an unreadable shape carries no decision, so the new cut replaces it.
-    catch {
-        return -1;
-    }
-}
-/** Validate one persisted ledger; another generation or an unreadable shape is absent. */
+/** Validate one persisted slice; another generation or an unreadable shape is absent. */
 function parseLedger(raw) {
     let value;
     try {
@@ -92,37 +68,36 @@ function parseLedger(raw) {
     const record = value;
     if (record.version !== LEDGER_VERSION)
         return undefined;
-    if (typeof record.sessionId !== 'string' || !Number.isSafeInteger(record.cut) || !Array.isArray(record.charges)) {
+    if (typeof record.sessionId !== 'string' || !Number.isSafeInteger(record.cut))
         throw new Error('Invalid cost ledger');
-    }
-    const charges = record.charges;
-    if (!charges.every(validCharge))
+    if (!Number.isSafeInteger(record.engine) || typeof record.catalog !== 'string')
         throw new Error('Invalid cost ledger');
-    return { version: LEDGER_VERSION, sessionId: record.sessionId, cut: record.cut, charges: charges };
+    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 };
 }
-/** One charge is valid when every recorded field is present with the type the fold writes. */
-function validCharge(value) {
+/** 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. */
+function validTotal(value) {
     if (typeof value !== 'object' || value === null || Array.isArray(value))
-        return false;
-    const c = value;
-    if (typeof c.key !== 'string' || typeof c.provider !== 'string' || typeof c.model !== 'string')
-        return false;
-    if (c.priceId !== undefined && typeof c.priceId !== 'string')
-        return false;
-    if (c.reason !== undefined && typeof c.reason !== 'string')
-        return false;
-    if (c.amount !== undefined && (typeof c.amount !== 'number' || !Number.isFinite(c.amount) || c.amount < 0))
-        return false;
-    if (c.estimated !== undefined && c.estimated !== true)
-        return false;
-    if (c.time !== undefined && (typeof c.time !== 'number' || !Number.isFinite(c.time) || c.time < 0 || c.time > 8.64e15))
-        return false;
-    if (c.usage !== undefined) {
-        if (typeof c.usage !== 'object' || c.usage === null || Array.isArray(c.usage))
-            return false;
-        const buckets = Object.values(c.usage);
-        if (buckets.length === 0 || buckets.some(n => typeof n !== 'number' || !Number.isSafeInteger(n) || n < 0))
-            return false;
-    }
-    return true;
+        return undefined;
+    const total = value;
+    const amount = total.amount;
+    if (typeof amount !== 'number' || !Number.isFinite(amount) || amount < 0)
+        return undefined;
+    const counts = [total.unknown, total.records];
+    if (!counts.every(count => typeof count === 'number' && Number.isSafeInteger(count) && count >= 0))
+        return undefined;
+    return { amount, unknown: total.unknown, records: total.records };
+}
+/** Accept one stored day bucket only when it also names the Beijing day it covers. */
+function validDay(value) {
+    const total = validTotal(value);
+    const day = value?.day;
+    return total === undefined || typeof day !== 'string' || day === '' ? undefined : { day, ...total };
 }

package/dist/cost/ledger.d.ts

@@ -1,12 +1,15 @@
-/** Immutable CNY ledger: a charge is priced once and never follows later price configuration. */
+/** CNY estimates folded from host history: per-session totals, 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 decided request charges; each scan replaces a session at a fixed cut. */
+/** Per-origin cache of folded session totals; every scan replaces a session at its cut. */
 export declare class CostLedger {
     readonly prices: PriceVersion[];
     readonly directory?: string | undefined;
+    /** Whether the table came from a file the user maintains, rather than the shipped one. */
+    readonly customPrices: boolean;
     private sessions;
     private totals;
+    private readonly catalog;
     scannedAt?: number;
     scanning: boolean;
     error: string;
@@ -16,47 +19,57 @@ export declare class CostLedger {
         pages: number;
         events: number;
     };
-    constructor(prices?: PriceVersion[], directory?: string | undefined);
-    /** Cached charges count as complete; only a failed scan or an empty ledger is partial.
+    constructor(prices?: PriceVersion[], directory?: string | undefined, 
+    /** Whether the table came from a file the user maintains, rather than the shipped one. */
+    customPrices?: boolean);
+    /** Cached totals count as complete; only a failed scan or an empty ledger is partial.
      * @returns Coverage of the current totals, so callers can mark them without re-deriving the rule.
      */
     get coverage(): Coverage;
-    /** Load the newest complete cut per session; recorded amounts load without re-pricing. */
+    /** Load the newest cut per session; a stored total is read as it was decided. */
     load(): Promise<void>;
     /** Replace one session using all billing events through the opening snapshot cut.
      *
-     * Sampling is replayed, but a charge that an earlier scan already decided keeps its recorded
-     * `priceId` and `amount`, so editing `prices.json` only affects requests decided afterwards.
+     * The fold is the projection: every sample is decided again with the table loaded now, so a
+     * corrected table reaches history on the next scan and a request no table covered yet is priced
+     * as soon as one does. Only the totals are kept, and the cut and engine keep an older scan from
+     * replacing a newer one.
      * @param sessionId - Host session identity.
      * @param cut - Opening cursor, preventing a stale scan from overwriting a newer scan.
      * @param events - Minimal events returned by `costRecords`, across all history pages.
+     * @param now - Clock that names the calendar day the day bucket covers.
      */
-    replace(sessionId: string, cut: number, events: ObjectValue[]): Promise<void>;
+    replace(sessionId: string, cut: number, events: ObjectValue[], now?: number): Promise<void>;
     /** Count the retained ledger so a memory sample can separate it from the transcript window.
-     * @returns Sessions and charges currently held, and how many charges carry no amount.
+     * @returns Sessions, requests and unpriced requests currently held.
      */
     summary(): {
         sessions: number;
-        charges: number;
+        records: number;
         unpriced: number;
     };
     /** Whether this session has a complete cached scan.
-     * @param sessionId - Selected session identity.
-     * @returns True when a complete scan is available.
+     * @param sessionId - Selected session identity, which may be unset before one is picked.
+     * @returns True when a complete scan is available, narrowing the identity to a string.
      */
-    hasSession(sessionId?: string): boolean;
+    hasSession(sessionId: string | undefined): sessionId is string;
     /** Describe unpriced model/usage combinations without exposing conversation content.
      * @returns Unique reasons across cached sessions.
      */
     missing(): string[];
-    /** Summarize recorded requests across one session or Beijing calendar days.
-     * @param sessionId - Optional session restriction.
-     * @param days - Today or today plus the preceding two calendar days.
-     * @param now - Clock used for date attribution.
-     * @returns Known subtotal, unpriceable count, and estimated count; an estimated record always
-     *   names an amount, but a dated range only adds the records it can place inside that range.
+    /** One session's stored totals.
+     * @param sessionId - Session identity to report.
+     * @returns The total a scan folded for it, or zeros when no scan has covered it.
      */
-    total(sessionId?: string, days?: 1 | 3, now?: number): CostTotal;
+    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.
+     * @param now - Clock that names the day to report.
+     * @returns The day's total across cached sessions.
+     */
+    today(now?: number): CostTotal;
 }
 /** Compact estimates retain an asterisk whenever a subtotal is not exact.
  * @param total - Summary from the ledger.

package/dist/cost/ledger.js

@@ -1,37 +1,30 @@
-import { chargeFor, costDay, DEFAULT_PRICES } from "./pricing.js";
+import { chargeFor, costDay, DEFAULT_PRICES, pricesDigest, PRICING_ENGINE_VERSION } from "./pricing.js";
 import { foldSamples } from "./records.js";
 import { loadLedgers, saveLedger } from "./ledger-files.js";
-import { MISSING_USAGE } from "./types.js";
-/** Whether a charge already carries a decision that a later scan must keep. */
-function sealed(charge) {
-    return charge.amount !== undefined || (charge.reason !== undefined && charge.reason !== MISSING_USAGE);
-}
-/** Attach the current table's decision, or reuse the decision an earlier scan recorded.
- *
- * A sample without usage has not finished reporting tokens, so it stays open for the next scan;
- * every other decision — priced, unpriced, or estimated — is final.
- */
-function decide(prices, sample, previous) {
-    if (previous !== undefined && (sealed(previous) || sample.usage === undefined))
-        return previous;
-    return { ...sample, ...chargeFor(prices, sample.provider, sample.model, sample.time, sample.usage) };
-}
-/** Per-origin cache of decided request charges; each scan replaces a session at a fixed cut. */
+/** Reasons one slice keeps at most, so a broken table cannot grow the ledger without bound. */
+const UNPRICED_LIMIT = 8;
+/** Per-origin cache of folded session totals; every scan replaces a session at its cut. */
 export class CostLedger {
     prices;
     directory;
+    customPrices;
     sessions = new Map();
     totals = new Map();
+    catalog;
     scannedAt;
     scanning = false;
     error = '';
     /** Work the last completed scan performed, so a memory sample can attribute its allocation. */
     lastScan;
-    constructor(prices = DEFAULT_PRICES, directory) {
+    constructor(prices = DEFAULT_PRICES, directory, 
+    /** Whether the table came from a file the user maintains, rather than the shipped one. */
+    customPrices = false) {
         this.prices = prices;
         this.directory = directory;
+        this.customPrices = customPrices;
+        this.catalog = pricesDigest(prices);
     }
-    /** Cached charges count as complete; only a failed scan or an empty ledger is partial.
+    /** Cached totals count as complete; only a failed scan or an empty ledger is partial.
      * @returns Coverage of the current totals, so callers can mark them without re-deriving the rule.
      */
     get coverage() {
@@ -41,29 +34,48 @@ export class CostLedger {
             return 'partial';
         return this.scannedAt !== undefined || this.sessions.size > 0 ? 'complete' : 'partial';
     }
-    /** Load the newest complete cut per session; recorded amounts load without re-pricing. */
+    /** Load the newest cut per session; a stored total is read as it was decided. */
     async load() {
         this.totals.clear();
-        for (const [sessionId, saved] of await loadLedgers(this.directory)) {
-            if ((this.sessions.get(sessionId)?.cut ?? -2) <= saved.cut)
-                this.sessions.set(sessionId, saved);
-        }
+        this.sessions = await loadLedgers(this.directory);
     }
     /** Replace one session using all billing events through the opening snapshot cut.
      *
-     * Sampling is replayed, but a charge that an earlier scan already decided keeps its recorded
-     * `priceId` and `amount`, so editing `prices.json` only affects requests decided afterwards.
+     * The fold is the projection: every sample is decided again with the table loaded now, so a
+     * corrected table reaches history on the next scan and a request no table covered yet is priced
+     * as soon as one does. Only the totals are kept, and the cut and engine keep an older scan from
+     * replacing a newer one.
      * @param sessionId - Host session identity.
      * @param cut - Opening cursor, preventing a stale scan from overwriting a newer scan.
      * @param events - Minimal events returned by `costRecords`, across all history pages.
+     * @param now - Clock that names the calendar day the day bucket covers.
      */
-    async replace(sessionId, cut, events) {
+    async replace(sessionId, cut, events, now = Date.now()) {
         const current = this.sessions.get(sessionId);
         if ((current?.cut ?? -2) > cut)
             return;
-        const previous = new Map((current?.charges ?? []).map(charge => [charge.key, charge]));
-        const charges = foldSamples(events).map(sample => decide(this.prices, sample, previous.get(sample.key)));
-        const saved = { version: 2, sessionId, cut, charges };
+        const day = costDay(now);
+        const total = { amount: 0, unknown: 0, records: 0 };
+        const today = { day, amount: 0, unknown: 0, records: 0 };
+        const unpriced = new Set();
+        for (const sample of foldSamples(events)) {
+            const decision = chargeFor(this.prices, sample.provider, sample.model, sample.time, sample.usage);
+            // A request belongs to the day it settled on, so the day bucket only counts the requests of
+            // the calendar day this scan is running on; another day reads as nothing spent today. A request
+            // with no settlement time belongs to no day, so it is counted as unknown wherever it is read.
+            const buckets = sample.time === undefined || costDay(sample.time) === day ? [total, today] : [total];
+            for (const bucket of buckets) {
+                bucket.records++;
+                if (decision.amount === undefined)
+                    bucket.unknown++;
+                else
+                    bucket.amount += decision.amount;
+            }
+            if (decision.amount === undefined && unpriced.size < UNPRICED_LIMIT)
+                unpriced.add(`${sample.provider}/${sample.model}: ${decision.reason}`);
+        }
+        const saved = { version: 3, sessionId, cut, engine: PRICING_ENGINE_VERSION, catalog: this.catalog,
+            total, day: today, unpriced: [...unpriced] };
         // Another process may have persisted a newer cut of this session since it was last read.
         if (this.directory && !await saveLedger(this.directory, saved))
             return;
@@ -71,61 +83,59 @@ export class CostLedger {
         this.totals.clear();
     }
     /** Count the retained ledger so a memory sample can separate it from the transcript window.
-     * @returns Sessions and charges currently held, and how many charges carry no amount.
+     * @returns Sessions, requests and unpriced requests currently held.
      */
     summary() {
-        let charges = 0, unpriced = 0;
+        let records = 0, unpriced = 0;
         for (const session of this.sessions.values()) {
-            charges += session.charges.length;
-            unpriced += session.charges.filter(charge => charge.amount === undefined).length;
+            records += session.total.records;
+            unpriced += session.total.unknown;
         }
-        return { sessions: this.sessions.size, charges, unpriced };
+        return { sessions: this.sessions.size, records, unpriced };
     }
     /** Whether this session has a complete cached scan.
-     * @param sessionId - Selected session identity.
-     * @returns True when a complete scan is available.
+     * @param sessionId - Selected session identity, which may be unset before one is picked.
+     * @returns True when a complete scan is available, narrowing the identity to a string.
      */
     hasSession(sessionId) { return sessionId !== undefined && this.sessions.has(sessionId); }
     /** Describe unpriced model/usage combinations without exposing conversation content.
      * @returns Unique reasons across cached sessions.
      */
-    missing() {
-        return [...new Set([...this.sessions.values()].flatMap(s => s.charges.filter(c => c.amount === undefined).map(c => `${c.provider}/${c.model}: ${c.reason}`)))];
+    missing() { return [...new Set([...this.sessions.values()].flatMap(s => s.unpriced))]; }
+    /** One session's stored totals.
+     * @param sessionId - Session identity to report.
+     * @returns The total a scan folded for it, or zeros when no scan has covered it.
+     */
+    total(sessionId) {
+        const cached = this.totals.get(`s:${sessionId}`);
+        if (cached)
+            return cached;
+        const session = this.sessions.get(sessionId);
+        const result = session === undefined ? { amount: 0, unknown: 0, records: 0 } : { ...session.total };
+        this.totals.set(`s:${sessionId}`, result);
+        return result;
     }
-    /** Summarize recorded requests across one session or Beijing calendar days.
-     * @param sessionId - Optional session restriction.
-     * @param days - Today or today plus the preceding two calendar days.
-     * @param now - Clock used for date attribution.
-     * @returns Known subtotal, unpriceable count, and estimated count; an estimated record always
-     *   names an amount, but a dated range only adds the records it can place inside that range.
+    /** 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.
+     * @param now - Clock that names the day to report.
+     * @returns The day's total across cached sessions.
      */
-    total(sessionId, days, now = Date.now()) {
-        const cacheKey = JSON.stringify([sessionId, days, days ? costDay(now) : '']);
-        const cached = this.totals.get(cacheKey);
+    today(now = Date.now()) {
+        const day = costDay(now);
+        const cached = this.totals.get(`d:${day}`);
         if (cached)
             return cached;
-        const result = { amount: 0, unknown: 0, estimated: 0, records: 0 };
-        const end = costDay(now);
-        const start = costDay(now - ((days ?? 1) - 1) * 86400_000);
+        const result = { amount: 0, unknown: 0, records: 0 };
         for (const session of this.sessions.values()) {
-            if (sessionId !== undefined && session.sessionId !== sessionId)
+            if (session.day.day !== day)
                 continue;
-            for (const charge of session.charges) {
-                if (days && charge.time !== undefined && (costDay(charge.time) < start || costDay(charge.time) > end))
-                    continue;
-                result.records++;
-                if (charge.amount === undefined) {
-                    result.unknown++;
-                    continue;
-                }
-                const dated = days === undefined || charge.time !== undefined;
-                if (charge.estimated === true || !dated)
-                    result.estimated++;
-                if (dated)
-                    result.amount += charge.amount;
-            }
+            result.amount += session.day.amount;
+            result.unknown += session.day.unknown;
+            result.records += session.day.records;
         }
-        this.totals.set(cacheKey, result);
+        this.totals.set(`d:${day}`, result);
         return result;
     }
 }
@@ -133,4 +143,4 @@ export class CostLedger {
  * @param total - Summary from the ledger.
  * @returns Yuan amount and incompleteness marker.
  */
-export function costText(total) { return `~¥${total.amount.toFixed(4)}${total.unknown || total.estimated ? '*' : ''}`; }
+export function costText(total) { return `~¥${total.amount.toFixed(4)}${total.unknown ? '*' : ''}`; }

package/dist/cost/pricing.d.ts

@@ -1,48 +1,86 @@
 import { type PriceDecision, type PriceVersion, type Rates, type Usage } from './types.ts';
 export declare const DEFAULT_PRICES: PriceVersion[];
+/** Revision of the pricing decision rules, recorded with the totals they decided.
+ *
+ * Bump it whenever the rules change what an amount would be — the matching of a model name, the
+ * token buckets an amount covers, or the timestamp it is priced at — so a stored total can be traced
+ * to the rules that produced it. Version 1 matched a model by the substring `pro` and priced a
+ * request with no settlement time at the cheapest off-peak rate.
+ */
+export declare const PRICING_ENGINE_VERSION = 2;
+/** Revision of the shipped table, recorded beside a seeded file so a correction can replace it. */
+export declare const PRICES_REVISION = "2026-09-12";
+/** Whether a table is the seed an earlier revision wrote, which a corrected ship must replace.
+ *
+ * `prices.json` overrides the shipped table, so an install seeded before the Flash rates were
+ * corrected keeps charging 1.5x for input and 2.5x for cache reads for as long as that file lives.
+ * Only an exact match to the superseded revision qualifies, so a rate the user chose is never rewritten.
+ * @param prices - Table loaded from the configuration file.
+ * @returns True when every entry carries the superseded revision's rates.
+ */
+export declare function isUncorrectedSeed(prices: readonly PriceVersion[]): boolean;
 /** Validate user-maintained price versions, rejecting ambiguous overlapping intervals.
  * @param value - Parsed prices.json array.
  * @returns Price versions with validated rates and schedules.
  */
 export declare function pricesFrom(value: unknown): PriceVersion[];
-/** Return the calendar date used by both daily and three-calendar-day summaries.
+/** Return the Beijing calendar date a request is attributed to.
  * @param time - Epoch milliseconds.
  * @returns Beijing calendar date, YYYY-MM-DD.
  */
 export declare function costDay(time: number): string;
-/** Select a price by event time, applying half-open local peak windows.
+/** Canonical form of a model name before matching.
+ *
+ * The host reports names that differ from the published table by width, case, surrounding space, or
+ * the CJK full stop a display path can substitute for a period. Normalizing here keeps the table
+ * readable and keeps a name variant from silently missing its entry. NFKC does not fold the CJK
+ * stops, so they are mapped explicitly.
+ * @param model - Model name exactly as the recorded request reported it.
+ * @returns The name in the form the table is matched against.
+ */
+export declare function canonicalModel(model: string): string;
+/** Candidate versions for one request, in the order the table is searched: the exact model, then
+ * the aliases a version declares. A name the table does not cover stays unpriced rather than
+ * falling back to a family guess, because guessing a rate is indistinguishable from a wrong one.
  * @param prices - Validated versions.
  * @param provider - Provider identity from the recorded request.
- * @param model - Recorded model name; official DeepSeek aliases fall back to Pro when containing pro, otherwise Flash.
- * @param time - Recorded settlement timestamp used as a billing-time estimate.
- * @returns Matching price version and per-million-token rates, if known.
+ * @param model - Recorded model name.
+ * @returns Matching versions, each with the rule that matched it.
  */
-export declare function priceAt(prices: PriceVersion[], provider: string, model: string, time: number): {
+export declare function candidates(prices: PriceVersion[], provider: string, model: string): {
     price: PriceVersion;
-    rates: Rates;
-} | undefined;
-/** Select a rate without a settlement time, so an unattributable request still enters the total.
- * The cheapest candidate off-peak rate is a floor: it never overstates, and the charge stays
- * marked as estimated.
+    matchedBy: 'exact' | 'alias';
+}[];
+/** Stable identity of a loaded price table.
+ *
+ * The identity a price version carries can be edited in place while keeping its `id` — which is how
+ * a corrected table once kept charging superseded rates under one id — so a stored total records a
+ * digest of the whole table it was decided from, not only the version names.
+ * @param prices - Price versions loaded for this process.
+ * @returns Short digest of the table.
+ */
+export declare function pricesDigest(prices: readonly PriceVersion[]): string;
+/** Select a price by event time, applying half-open local peak windows.
  * @param prices - Validated versions.
  * @param provider - Provider identity from the recorded request.
  * @param model - Recorded model name.
- * @returns The candidate version with the lowest off-peak input rate and its rates, if any.
+ * @param time - Recorded settlement timestamp used as the billing instant.
+ * @returns Matching price version, the rule that matched it, and its per-million-token rates.
  */
-export declare function lowestPrice(prices: PriceVersion[], provider: string, model: string): {
+export declare function priceAt(prices: PriceVersion[], provider: string, model: string, time: number): {
     price: PriceVersion;
     rates: Rates;
+    matchedBy: 'exact' | 'alias';
 } | undefined;
 /** Decide the amount for one request sample using the table loaded at decision time.
  *
- * The returned decision is recorded once and never revisited: a later `prices.json` change must
- * not move a historical amount. Only a sample with no usable usage (`missing usage`) is left
- * undecided, because its request has not finished reporting tokens yet.
+ * A decision is a number or a reason; nothing about the rates that produced it is kept, because the
+ * ledger stores totals rather than requests and the next scan decides the sample again.
  * @param prices - Validated versions currently loaded.
  * @param provider - Provider identity from the recorded request.
  * @param model - Recorded model name.
  * @param time - Recorded settlement timestamp, when the host logged one.
  * @param usage - Disjoint token buckets, when the host reported valid counts.
- * @returns The selected price identity, the amount, and the reason when no amount exists.
+ * @returns The amount, or the reason no amount exists.
  */
 export declare function chargeFor(prices: PriceVersion[], provider: string, model: string, time: number | undefined, usage: Usage | undefined): PriceDecision;