@itookit/dsht 0.3.2 → 0.3.3

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;

package/dist/cost/pricing.js

@@ -1,8 +1,9 @@
 /** Versioned CNY price tables and the price decision taken for one request sample. */
+import { createHash } from 'node:crypto';
 import { object } from "../transport/wire.js";
-import { MISSING_USAGE } from "./types.js";
+import { MISSING_TIME, MISSING_USAGE, UNSUPPORTED_USAGE } from "./types.js";
 const clocks = new Map();
-/** Published rates verified on 2026-09-10; preceding dates require historical configuration.
+/** Published rates verified on 2026-09-12; preceding dates require historical configuration.
  * Flash and Pro are priced independently, and a separate cache write uses the cache-miss input rate.
  */
 const OFFICIAL_PRICING = 'https://api-docs.deepseek.com/zh-cn/quick_start/pricing/';
@@ -12,17 +13,63 @@ const FLASH_RATES = { peak: { input: 2, cacheRead: 0.04, cacheWrite: 2, output:
 const PRO_RATES = { peak: { input: 9, cacheRead: 0.3, cacheWrite: 9, output: 27 },
     offPeak: { input: 4.5, cacheRead: 0.15, cacheWrite: 4.5, output: 13.5 } };
 export const DEFAULT_PRICES = [
+    // The published table states that superseded Flash names stay callable and are served by
+    // V4.1-Flash at Flash rates, so every name the host can report is listed instead of guessed at.
     { id: 'deepseek-2026-09-10-flash', provider: 'deepseek-official', model: 'deepseek-flash',
+        aliases: ['deepseek-v4-flash', 'deepseek-v4-flash-vision-exp', 'deepseek-v4-flash*', 'deepseek-v4.1-flash*', 'deepseek-v4.1-flash'],
         from: '2026-09-10T00:00:00+08:00', currency: 'CNY', source: OFFICIAL_PRICING, timezone: 'Asia/Shanghai',
         ...PEAK_SCHEDULE, ...FLASH_RATES },
+    // The published table keeps V4 Pro available after 2026-09-14 at these rates, so the interval
+    // stays open until a later page names an end.
     { id: 'deepseek-2026-09-10-pro', provider: 'deepseek-official', model: 'deepseek-v4-pro',
-        from: '2026-09-10T00:00:00+08:00', until: '2026-09-14T12:00:00+08:00', currency: 'CNY',
-        source: OFFICIAL_PRICING, timezone: 'Asia/Shanghai', ...PEAK_SCHEDULE, ...PRO_RATES },
-    // The provider bills `deepseek-v4-pro` requests at Flash rates once V4 Pro is retired.
-    { id: 'deepseek-2026-09-14-pro-served-by-flash', provider: 'deepseek-official', model: 'deepseek-v4-pro',
-        from: '2026-09-14T12:00:00+08:00', currency: 'CNY', source: OFFICIAL_PRICING, timezone: 'Asia/Shanghai',
-        ...PEAK_SCHEDULE, ...FLASH_RATES },
+        // No `deepseek-pro*`: a prefix that broad would also claim `deepseek-proxy-*` or `deepseek-prompt-*`.
+        aliases: ['deepseek-v4-pro', 'deepseek-v4-pro*', 'deepseek-v4.1-pro*'],
+        from: '2026-09-10T00:00:00+08:00', currency: 'CNY', source: OFFICIAL_PRICING, timezone: 'Asia/Shanghai',
+        ...PEAK_SCHEDULE, ...PRO_RATES },
 ];
+/** 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 const PRICING_ENGINE_VERSION = 2;
+/** Revision of the shipped table, recorded beside a seeded file so a correction can replace it. */
+export const PRICES_REVISION = '2026-09-12';
+/** Rates the first published revision charged, rebuilt with the same arithmetic so the values compare equal.
+ * It only recognizes that seed; it never prices a request.
+ */
+const UNCORRECTED_SEED_RATES = Object.fromEntries(['deepseek-v4-flash', 'deepseek-v4-pro', 'deepseek-v4-flash-vision-exp'].map(model => {
+    const scale = model === 'deepseek-v4-pro' ? 3 : 1;
+    return [`deepseek-2026-09-10-${model}`, {
+            peak: { input: 3 * scale, cacheRead: 0.1 * scale, cacheWrite: 3 * scale, output: 9 * scale },
+            offPeak: { input: 1.5 * scale, cacheRead: 0.05 * scale, cacheWrite: 1.5 * scale, output: 4.5 * scale },
+        }];
+}));
+/** 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 function isUncorrectedSeed(prices) {
+    const superseded = Object.keys(UNCORRECTED_SEED_RATES);
+    return prices.length === superseded.length && prices.every(price => {
+        const legacy = UNCORRECTED_SEED_RATES[price.id];
+        return legacy !== undefined && sameRates(price.peak, legacy.peak) && sameRates(price.offPeak, legacy.offPeak);
+    });
+}
+/** Compare two rate sets, allowing the representation error a JSON round trip can introduce.
+ * @param a - One rate set.
+ * @param b - The other rate set.
+ * @returns True when every rate agrees.
+ */
+function sameRates(a, b) {
+    return ['input', 'cacheRead', 'cacheWrite', 'output'].every(bucket => Math.abs(a[bucket] - b[bucket]) < 1e-9);
+}
 /** Validate user-maintained price versions, rejecting ambiguous overlapping intervals.
  * @param value - Parsed prices.json array.
  * @returns Price versions with validated rates and schedules.
@@ -39,6 +86,8 @@ export function pricesFrom(value) {
         if (ids.has(String(p.id)))
             throw new Error('Duplicate price id');
         ids.add(String(p.id));
+        if (p.aliases !== undefined && (!Array.isArray(p.aliases) || p.aliases.some(alias => typeof alias !== 'string' || alias === '')))
+            throw new Error('Invalid price aliases');
         const from = Date.parse(String(p.from));
         const until = p.until === undefined ? Infinity : Date.parse(String(p.until));
         if (!Number.isFinite(from) || !(until > from) || p.currency !== 'CNY')
@@ -63,31 +112,72 @@ export function pricesFrom(value) {
         }
     return prices;
 }
-/** 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 function costDay(time) { return new Date(time + 8 * 3600_000).toISOString().slice(0, 10); }
-/** Price family used when a recorded model name has no exact entry. */
-function priceFamily(model) { return model.toLowerCase().includes('pro') ? 'deepseek-v4-pro' : 'deepseek-flash'; }
-/** Candidate versions for one request: its exact model first, then the official model family. */
-function candidates(prices, provider, model) {
-    const exact = prices.filter(p => p.provider === provider && p.model === model);
+/** 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 function canonicalModel(model) {
+    return model.normalize('NFKC').replace(/[\u3002\uff0e\uff61]/g, '.').trim().toLowerCase();
+}
+/** Whether an alias matches a canonical model name, treating a trailing `*` as a prefix.
+ * @param alias - Alias declared by a price version.
+ * @param model - Canonical model name.
+ * @returns True when the alias covers the name.
+ */
+function aliasMatches(alias, model) {
+    const canonical = canonicalModel(alias);
+    return canonical.endsWith('*') ? model.startsWith(canonical.slice(0, -1)) : model === canonical;
+}
+/** 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.
+ * @returns Matching versions, each with the rule that matched it.
+ */
+export function candidates(prices, provider, model) {
+    const canonical = canonicalModel(model);
+    const exact = prices.filter(p => p.provider === provider && canonicalModel(p.model) === canonical);
     if (exact.length)
-        return exact;
-    return provider === 'deepseek-official' ? prices.filter(p => p.model === priceFamily(model)) : [];
+        return exact.map(price => ({ price, matchedBy: 'exact' }));
+    return prices.filter(p => p.provider === provider && (p.aliases ?? []).some(alias => aliasMatches(alias, canonical)))
+        .map(price => ({ price, matchedBy: '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 function pricesDigest(prices) {
+    return createHash('sha256').update(JSON.stringify(prices)).digest('hex').slice(0, 12);
 }
 /** 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; 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.
+ * @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 function priceAt(prices, provider, model, time) {
-    const price = candidates(prices, provider, model).find(p => Date.parse(p.from) <= time && (p.until === undefined || time < Date.parse(p.until)));
-    if (!price)
+    const candidate = candidates(prices, provider, model)
+        .find(({ price }) => Date.parse(price.from) <= time && (price.until === undefined || time < Date.parse(price.until)));
+    if (candidate === undefined)
         return;
+    const { price, matchedBy } = candidate;
     let clock = clocks.get(price.timezone);
     if (!clock) {
         clock = new Intl.DateTimeFormat('en-US', { timeZone: price.timezone, weekday: 'short', hour: '2-digit', minute: '2-digit', hourCycle: 'h23' });
@@ -97,45 +187,37 @@ export function priceAt(prices, provider, model, time) {
     const part = (name) => parts.find(p => p.type === name).value;
     const day = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'].indexOf(part('weekday'));
     const minute = Number(part('hour')) * 60 + Number(part('minute'));
-    return { price, rates: price.weekdays.includes(day) && price.windows.some(([a, b]) => minute >= a && minute < b) ? price.peak : price.offPeak };
-}
-/** 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.
- * @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.
- */
-export function lowestPrice(prices, provider, model) {
-    let best;
-    for (const price of candidates(prices, provider, model)) {
-        if (best === undefined || price.offPeak.input < best.rates.input)
-            best = { price, rates: price.offPeak };
-    }
-    return best;
+    return { price, matchedBy, rates: price.weekdays.includes(day) && price.windows.some(([a, b]) => minute >= a && minute < b) ? price.peak : price.offPeak };
 }
 /** 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 function chargeFor(prices, provider, model, time, usage) {
     if (!usage)
         return { reason: MISSING_USAGE };
-    const selected = time === undefined ? lowestPrice(prices, provider, model) : priceAt(prices, provider, model, time);
+    // The published DeepSeek table prices cache hits, cache misses and output; a fourth bucket means
+    // the usage mapping is wrong, and inventing a rate for it would hide that.
+    if (provider === 'deepseek-official' && usage.cacheWrite !== 0)
+        return { reason: UNSUPPORTED_USAGE };
+    // No settlement time means the host did not say when the request was billed, and the two peak
+    // bands differ by a factor of two: a floor amount would enter the total while belonging to no day,
+    // so the request is reported unresolved instead of guessed.
+    if (time === undefined)
+        return { reason: MISSING_TIME };
+    const selected = priceAt(prices, provider, model, time);
     if (!selected)
         return { reason: 'no price version' };
     const amount = (usage.input * selected.rates.input + usage.output * selected.rates.output
         + usage.cacheRead * selected.rates.cacheRead + usage.cacheWrite * selected.rates.cacheWrite) / 1e6;
     if (!Number.isFinite(amount))
         return { reason: 'invalid estimate' };
-    return { priceId: selected.price.id, amount, ...(time === undefined ? { estimated: true } : {}) };
+    return { amount };
 }

package/dist/cost/records.js

@@ -1,19 +1,31 @@
 /** Fold host history records into per-request samples; conversation text never enters the ledger. */
 import { array, object } from "../transport/wire.js";
-/** Host event types that carry billing-relevant usage or route context. */
-const BILLING_EVENTS = new Set(['request/context', 'assistant/message', 'assistant/attempt', 'llm/retry-started', 'session/end-seed']);
+/** Host event types that carry billing-relevant usage or route context.
+ *
+ * `compaction/summary` is a provider request like any other — it reads the whole context to write the
+ * summary — and it records its own provider, model and usage instead of appearing as an assistant
+ * message, so a fold without it under-reports the most expensive requests in a session.
+ */
+const BILLING_EVENTS = new Set(['request/context', 'assistant/message', 'assistant/attempt', 'llm/retry-started', 'session/end-seed', 'compaction/summary']);
 /** Keep only billing-relevant fields; prompts, tool bodies, cookies and keys never enter the ledger.
  * @param records - One HTTP history page's records.
  * @returns Minimal durable events for a deterministic usage fold.
  */
 export function costRecords(records) {
-    return array(records).map(raw => object(object(raw).event)).filter(e => BILLING_EVENTS.has(String(e.type))).map(e => {
+    return array(records).map(raw => object(object(raw).event)).filter(e => BILLING_EVENTS.has(String(e.type)))
+        // A summary written without a model call — an unmarked template or remote summarizer — has no
+        // usage and no cost, so it is not a billable sample at all.
+        .filter(e => e.type !== 'compaction/summary' || object(e.data).usage !== undefined).map(e => {
         const d = object(e.data);
         const m = object(d.message ?? {});
         const stream = array(d.stream ?? []).map(r => object(object(r).chunk ?? {})).filter(c => c.type === 'usage');
+        // A summary names its own provider and model, and carries no turn or step to fold against, so
+        // its route travels as the source a message would carry rather than as folded context.
+        const source = e.type === 'compaction/summary' ? { provider: d.provider ?? null, model: d.model ?? null } : m.source ?? null;
         return { seq: e.seq ?? null, time: e.time ?? null, type: e.type, data: {
-                inherited: d.inherited ?? false, turn: d.turn ?? null, step: d.step ?? null, provider: d.provider ?? null, model: d.model ?? null,
-                source: m.source ?? null, usage: d.usage ?? stream.at(-1)?.usage ?? null,
+                inherited: d.inherited ?? false, turn: d.turn ?? null, step: d.step ?? null,
+                provider: d.provider ?? null, model: d.model ?? null,
+                source, usage: d.usage ?? stream.at(-1)?.usage ?? null,
             } };
     });
 }
@@ -43,6 +55,7 @@ export function foldSamples(events) {
                 last = undefined;
             continue;
         }
+        // A message or summary carries its own route; only the remaining events inherit the folded one.
         const source = object(d.source ?? {});
         const provider = String(source.provider ?? route.provider ?? '');
         const model = String(source.model ?? route.model ?? '');

package/dist/cost/types.d.ts

@@ -11,6 +11,8 @@ export interface PriceVersion {
     id: string;
     provider: string;
     model: string;
+    /** Further model names this version prices; a trailing `*` matches a prefix. Never a guess. */
+    aliases?: string[];
     from: string;
     until?: string;
     currency: 'CNY';
@@ -28,7 +30,7 @@ export interface Usage {
     cacheRead: number;
     cacheWrite: number;
 }
-/** One folded request sample before a price decision is attached. */
+/** One folded request sample: the attempt identity and the facts a price decision needs. */
 export interface ChargeSample {
     key: string;
     time?: number;
@@ -36,34 +38,48 @@ export interface ChargeSample {
     model: string;
     usage?: Usage;
 }
-/** The price decision recorded the first time a request sample was evaluated. */
+/** What the table decides for one request sample: an amount, or the reason it has none. */
 export interface PriceDecision {
-    priceId?: string;
     amount?: number;
-    estimated?: true;
     reason?: string;
 }
-/** One ledger entry: a request sample plus the price decision that seals it. */
-export interface Charge extends ChargeSample, PriceDecision {
-}
-/** One session's persisted ledger slice. */
-export interface SavedCost {
-    version: 2;
-    sessionId: string;
-    cut: number;
-    charges: Charge[];
-}
-/** Summary retains the known subtotal, the records it could not price, and the coarse estimates.
- * `unknown` counts records with no amount at all; `estimated` counts records that only have a
- * floor amount, including dated requests whose timestamp cannot place them inside the range.
+/** Summary retains the known subtotal and the records it could not price.
+ * `unknown` counts records with no amount; `records` counts every request the range covers, so a
+ * subtotal is never read as complete without them.
  */
 export interface CostTotal {
     amount: number;
     unknown: number;
-    estimated: number;
     records: number;
 }
+/** One Beijing calendar day's requests, kept only for the day a scan ran on. */
+export interface DayTotal extends CostTotal {
+    day: string;
+}
+/** One session's persisted ledger slice.
+ *
+ * The host log and the loaded price table are the only inputs, so the slice stores the totals one
+ * scan folded them into and no per-request detail: the next scan reads the session's history again
+ * and decides every sample with the table loaded then. `engine` and `catalog` name the decision
+ * rules and the table behind these totals, so a process holding an older one cannot overwrite them.
+ */
+export interface SavedCost {
+    version: 3;
+    sessionId: string;
+    /** Durable sequence the fold reached; a scan that opened an older cut may not replace this slice. */
+    cut: number;
+    engine: number;
+    catalog: string;
+    total: CostTotal;
+    day: DayTotal;
+    /** Distinct reasons an amount is missing, bounded, so a panel can say what makes a total inexact. */
+    unpriced: string[];
+}
 /** How much of the visible history the cached ledger currently covers. */
 export type Coverage = 'complete' | 'scanning' | 'partial';
 /** Reason recorded when a sample carries no usable token counts. */
 export declare const MISSING_USAGE = "missing usage";
+/** Reason recorded when the host reported a cache-write bucket the published table does not price. */
+export declare const UNSUPPORTED_USAGE = "unsupported usage";
+/** Reason recorded when the request has no settlement time to place it in a peak band or a day. */
+export declare const MISSING_TIME = "missing time";

package/dist/cost/types.js

@@ -1,3 +1,7 @@
 /** Cost-domain types shared by pricing, record folding, storage and the in-memory ledger. */
 /** Reason recorded when a sample carries no usable token counts. */
 export const MISSING_USAGE = 'missing usage';
+/** Reason recorded when the host reported a cache-write bucket the published table does not price. */
+export const UNSUPPORTED_USAGE = 'unsupported usage';
+/** Reason recorded when the request has no settlement time to place it in a peak band or a day. */
+export const MISSING_TIME = 'missing time';

package/dist/session/navigation.d.ts

@@ -9,3 +9,29 @@ export declare function navigationCommand(value: string): {
 export declare function sessionLabel(session: ObjectValue): string;
 /** Match an exact ID or name before a unique ID prefix; never choose an ambiguous target. */
 export declare function resolveTarget(items: ObjectValue[], query: string, id: string, names: (item: ObjectValue) => string[]): ObjectValue;
+/** Activity a session summary reports on its own, without loading that session's history. */
+export type SessionState = 'running' | 'idle' | 'blank';
+/** Classify one session from the host's list summary; nothing is inferred from silence.
+ * @param session - Session summary from `session/list`.
+ * @returns Running while its agent works, blank before its first turn, otherwise idle.
+ */
+export declare function sessionState(session: ObjectValue): SessionState;
+/** Leading marker per state: a working clock, a filled idle dot, and an empty unused circle. */
+export declare const SESSION_MARKERS: Record<SessionState, string>;
+/** Coarse age of a session's last activity, so the column stays steady between list refreshes.
+ * @param time - Epoch milliseconds of the last activity, when the summary reported one.
+ * @param now - Current epoch milliseconds.
+ * @returns `now`, minutes, hours or days.
+ */
+export declare function activityAge(time: number | undefined, now: number): string;
+/** Status cell for one session row: its state marker and the age of its last activity.
+ * @param session - Session summary from `session/list`.
+ * @param now - Current epoch milliseconds.
+ * @returns Marker with an optional age, without a trailing space when unknown.
+ */
+export declare function sessionStatus(session: ObjectValue, now: number): string;
+/** Count the sessions of one workspace by the state each reports.
+ * @param sessions - Sessions whose `sessionIds` belong to the workspace.
+ * @returns One `marker count` cell per state that occurs, running first, or an empty string.
+ */
+export declare function workspaceStatus(sessions: readonly ObjectValue[]): string;

package/dist/session/navigation.js

@@ -34,3 +34,51 @@ export function resolveTarget(items, query, id, names) {
         throw new Error(`Ambiguous target: ${target}. Use a full ID.`);
     throw new Error(`Target not found: ${target}`);
 }
+/** Classify one session from the host's list summary; nothing is inferred from silence.
+ * @param session - Session summary from `session/list`.
+ * @returns Running while its agent works, blank before its first turn, otherwise idle.
+ */
+export function sessionState(session) {
+    if (session.running === true)
+        return 'running';
+    return session.blank === true ? 'blank' : 'idle';
+}
+/** Leading marker per state: a working clock, a filled idle dot, and an empty unused circle. */
+export const SESSION_MARKERS = { running: '◐', idle: '●', blank: '○' };
+/** Coarse age of a session's last activity, so the column stays steady between list refreshes.
+ * @param time - Epoch milliseconds of the last activity, when the summary reported one.
+ * @param now - Current epoch milliseconds.
+ * @returns `now`, minutes, hours or days.
+ */
+export function activityAge(time, now) {
+    if (time === undefined || !Number.isFinite(time))
+        return '';
+    const seconds = Math.max(0, Math.floor((now - time) / 1000));
+    if (seconds < 60)
+        return 'now';
+    const minutes = Math.floor(seconds / 60);
+    if (minutes < 60)
+        return `${minutes}m`;
+    const hours = Math.floor(minutes / 60);
+    return hours < 24 ? `${hours}h` : `${Math.floor(hours / 24)}d`;
+}
+/** Status cell for one session row: its state marker and the age of its last activity.
+ * @param session - Session summary from `session/list`.
+ * @param now - Current epoch milliseconds.
+ * @returns Marker with an optional age, without a trailing space when unknown.
+ */
+export function sessionStatus(session, now) {
+    const age = activityAge(typeof session.updatedAt === 'number' ? session.updatedAt : undefined, now);
+    return `${SESSION_MARKERS[sessionState(session)]}${age === '' ? '' : ` ${age}`}`;
+}
+/** Count the sessions of one workspace by the state each reports.
+ * @param sessions - Sessions whose `sessionIds` belong to the workspace.
+ * @returns One `marker count` cell per state that occurs, running first, or an empty string.
+ */
+export function workspaceStatus(sessions) {
+    const counts = { running: 0, idle: 0, blank: 0 };
+    for (const session of sessions)
+        counts[sessionState(session)] += 1;
+    return ['running', 'idle', 'blank'].filter(state => counts[state] > 0)
+        .map(state => `${SESSION_MARKERS[state]} ${counts[state]}`).join('  ');
+}