segreant 0.1.0 → 0.2.0

package/dist/cost/pricing.js

@@ -14,9 +14,12 @@ import { readFileSync, writeFileSync, mkdirSync, existsSync, renameSync, unlinkS
 import { createHash } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 import { egressFetch, EgressError } from '../egress/transport.js';
+import { DEFAULT_PRICE_LIST_URL } from '../egress/policy.js';
 import { dirname, join } from 'node:path';
 import { segreantHome } from '../config.js';
 import { computeExactCost, validateExactModelRate } from './exactPricing.js';
+import { activePriceOverrides, priceOverrideFor } from './overrides.js';
+import { money } from '../economics/money.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 /** The rate card shipped inside the package — always present, works offline. */
 const BUNDLED_PRICING_PATH = join(__dirname, '..', '..', 'pricing', 'models.json');
@@ -52,12 +55,14 @@ export const COST_BASES = [
     'tool_reported_unverified',
     'synthetic_demo',
     'unpriced',
+    'not_sent',
+    'user_declared_price',
     'legacy_unknown',
 ];
 /** Source of an attached rate-card hash. `none` is deliberately explicit for
  * tool-reported and unpriced rows, so a null hash is never mistaken for a lost
  * local rate card. */
-export const RATE_CARD_SOURCE_KINDS = ['manual', 'native_manifest', 'litellm_transformed', 'bundled', 'legacy_unknown', 'none'];
+export const RATE_CARD_SOURCE_KINDS = ['manual', 'native_manifest', 'litellm_transformed', 'bundled', 'legacy_unknown', 'none', 'user_declaration'];
 /** How the observed model was resolved against a local rate card, if any. */
 export const RATE_MATCH_KINDS = [
     'exact_provider',
@@ -67,6 +72,9 @@ export const RATE_MATCH_KINDS = [
     'fallback',
     'reported',
     'unpriced',
+    'not_sent',
+    'user_declared',
+    'user_declared_free',
     'legacy_unknown',
 ];
 export const MAX_PRICING_MANIFEST_BYTES = 5 * 1024 * 1024;
@@ -75,8 +83,17 @@ let cachedSource = 'bundled';
 function sha256(text) {
     return createHash('sha256').update(text, 'utf8').digest('hex');
 }
+// Every priced request carries its card's hash, and an import prices tens of
+// thousands of them against one card. A loaded card is replaced, never mutated,
+// when pricing is refreshed, so the hash is remembered per card object.
+const cardHashes = new WeakMap();
 function pricingCardHash(file) {
-    return sha256(JSON.stringify(file));
+    let hash = cardHashes.get(file);
+    if (hash === undefined) {
+        hash = sha256(JSON.stringify(file));
+        cardHashes.set(file, hash);
+    }
+    return hash;
 }
 function redactedUrl(raw) {
     try {
@@ -299,15 +316,33 @@ export function loadPricing(force = false) {
  * scraping provider pricing pages (brittle HTML that needs a parser which
  * itself rots). The GET fetches a public file and sends nothing about the user.
  */
-export const DEFAULT_MANIFEST_URL = 'https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json';
-/** LiteLLM providers we carry, mapped onto our table's provider keys. */
+export const DEFAULT_MANIFEST_URL = DEFAULT_PRICE_LIST_URL;
+/**
+ * First-party model makers, mapped onto our table's provider keys. Hosts and
+ * resellers are excluded: their rates price the host's route, which a bare
+ * model name cannot identify.
+ */
 const LITELLM_PROVIDER_MAP = {
     anthropic: 'anthropic',
     openai: 'openai',
     gemini: 'google',
+    cohere_chat: 'cohere',
+    dashscope: 'dashscope',
+    deepseek: 'deepseek',
+    mistral: 'mistral',
+    perplexity: 'perplexity',
+    xai: 'xai',
+    zai: 'zai',
 };
 /** Fewer matched models than this means the feed shape changed — refuse, keep the current table. */
 const MIN_TRANSFORMED_MODELS = 10;
+/** A per-1M rate as a plain decimal string, never exponent notation (1e-7 is "0.0000001"). */
+function plainDecimal(n) {
+    const s = String(n);
+    if (!/e/i.test(s))
+        return s;
+    return n.toFixed(20).replace(/0+$/, '').replace(/\.$/, '');
+}
 /** Per-token → per-1M, trimmed of float noise (3e-6/token → 3 $/1M exactly). */
 function perMillion(perToken) {
     return Number((perToken * 1e6).toPrecision(10));
@@ -315,7 +350,7 @@ function perMillion(perToken) {
 /**
  * Convert a LiteLLM price file into our manifest schema. Pure and total: bad
  * input yields `{ ok: false }`, never a throw. Only chat-capable entries from
- * providers we meter are carried; `verified` is false because the rates are
+ * first-party makers are carried; `verified` is false because the rates are
  * community-maintained; the conservative `unknown` fallback comes from the
  * CURRENT table, so a feed can never weaken it.
  */
@@ -360,18 +395,39 @@ export function transformLiteLLMManifest(rawText) {
         if (typeof e.cache_read_input_token_cost === 'number' && e.cache_read_input_token_cost > 0) {
             rate.cache_read = perMillion(e.cache_read_input_token_cost);
         }
+        // The decimal companion, so a model learned from the feed reprices to an
+        // exact amount: without it `reprice --apply` refused a first-sight model
+        // that had been recorded against the bundled card's exact fallback (PR #146 review).
+        const exact = {
+            input: plainDecimal(rate.input),
+            output: plainDecimal(rate.output),
+        };
+        if (rate.cache_write_5m !== undefined)
+            exact.cache_write_5m = plainDecimal(rate.cache_write_5m);
+        if (rate.cache_read !== undefined)
+            exact.cache_read = plainDecimal(rate.cache_read);
+        rate.exact = exact;
         bucket.models[name] = rate;
     }
     const total = Object.values(providers).reduce((n, p) => n + Object.keys(p.models).length, 0);
     if (total < MIN_TRANSFORMED_MODELS) {
         return { ok: false, error: `feed shape not recognized (only ${total} usable models found) — keeping the current table` };
     }
+    // Cross-provider lookups use insertion order: keep the big three ahead of
+    // other makers on name collisions, regardless of the upstream key order.
+    const primaryProviders = ['anthropic', 'openai', 'google'];
+    const providerOrder = [
+        ...primaryProviders,
+        ...Object.keys(providers).filter((provider) => !primaryProviders.includes(provider)).sort(),
+    ];
     const file = {
         schema_version: 1,
         updated: new Date().toISOString().slice(0, 10),
         currency: 'USD',
         unit: 'per_million_tokens',
-        providers,
+        providers: Object.fromEntries(providerOrder
+            .filter((provider) => providers[provider] !== undefined)
+            .map((provider) => [provider, providers[provider]])),
         fallbacks: loadPricing().fallbacks,
     };
     return { ok: true, file };
@@ -666,17 +722,29 @@ function heuristicMatch(models, model) {
 function activeRateCardSourceKind() {
     return cachedSource === 'bundled' ? 'bundled' : cachedProvenance?.sourceKind ?? 'legacy_unknown';
 }
-function resolved(rate, rateMatchKind, rateMatchProvider, rateMatchModel) {
+function resolved(rate, rateMatchKind, rateMatchProvider, rateMatchModel, declarationSha256 = null) {
     // rateFor always loads the active card first, so the card identity and source
     // describe this exact local computation rather than a later refresh.
     const card = loadPricing();
+    const declared = rateMatchKind === 'user_declared' || rateMatchKind === 'user_declared_free';
+    // A rate or free declaration is priced by the declaration alone: stamping it
+    // with the active card's hash made a card refresh look like a price change
+    // for requests whose price had not moved (PR #146 review). Only `like`
+    // depends on the card, and it names the card model it follows.
+    const fromCard = !declared || rateMatchProvider !== null;
     return {
         rate,
-        estimated: rateMatchKind !== 'exact_provider' && rateMatchKind !== 'exact_cross_provider',
+        // A declared price is resolved, not guessed: it is the price the user said
+        // this model costs. It keeps its own basis so it is never shown as list price.
+        estimated: rateMatchKind !== 'exact_provider' && rateMatchKind !== 'exact_cross_provider' && !declared,
         pricing: {
-            costBasis: rateMatchKind === 'fallback' ? 'fallback_estimate' : 'local_list_price',
-            rateCardSha256: pricingCardHash(card),
-            rateCardSourceKind: activeRateCardSourceKind(),
+            costBasis: rateMatchKind === 'fallback' ? 'fallback_estimate' : declared ? 'user_declared_price' : 'local_list_price',
+            // A rate or free declaration carries a revision of the declaration itself,
+            // labelled as the user's, never the card's: a changed price is then a new
+            // revision that value comparisons see, and a card refresh is not
+            // (PR #146 review).
+            rateCardSha256: fromCard ? pricingCardHash(card) : declarationSha256,
+            rateCardSourceKind: fromCard ? activeRateCardSourceKind() : declarationSha256 ? 'user_declaration' : 'none',
             rateMatchKind,
             rateMatchProvider,
             rateMatchModel,
@@ -705,6 +773,22 @@ export function unpricedPricingEvidence() {
         rateMatchModel: null,
     };
 }
+/**
+ * A request Segreant refused before it reached the provider (a budget block, an
+ * egress refusal). Its cost is not unknown: nothing was sent, so nothing was
+ * charged. Recording it as `unpriced` made every cap refusal read as a missing
+ * price ("1 of 835 requests in this window are unpriced").
+ */
+export function notSentPricingEvidence() {
+    return {
+        costBasis: 'not_sent',
+        rateCardSha256: null,
+        rateCardSourceKind: 'none',
+        rateMatchKind: 'not_sent',
+        rateMatchProvider: null,
+        rateMatchModel: null,
+    };
+}
 /** The only default for records created before per-request pricing lineage existed. */
 export function legacyPricingEvidence() {
     return {
@@ -720,9 +804,117 @@ export function legacyPricingEvidence() {
 export function syntheticPricingEvidence(cost) {
     return { ...cost.pricing, costBasis: 'synthetic_demo' };
 }
+/** The rate-card rate a `like` declaration points at: exact matches only, never another guess. */
+function exactCardRate(pricing, model) {
+    for (const p of Object.keys(pricing.providers)) {
+        const r = pricing.providers[p]?.models[model];
+        if (r)
+            return { provider: p, rate: r };
+    }
+    return null;
+}
+/** USD per 1M tokens as a decimal string, back to the card's number form. */
+function declaredRate(o) {
+    const exact = {
+        input: o.input,
+        output: o.output,
+        ...(o.cacheRead === undefined ? {} : { cache_read: o.cacheRead }),
+        // cacheWrite prices both TTLs unless cacheWrite1h names the 1-hour price
+        // (the engine and the usage record already tell the two apart).
+        ...(o.cacheWrite === undefined ? {} : { cache_write_5m: o.cacheWrite, cache_write_1h: o.cacheWrite }),
+        ...(o.cacheWrite1h === undefined ? {} : { cache_write_1h: o.cacheWrite1h }),
+    };
+    return {
+        input: Number(o.input),
+        output: Number(o.output),
+        ...(o.cacheRead === undefined ? {} : { cache_read: Number(o.cacheRead) }),
+        ...(o.cacheWrite === undefined ? {} : { cache_write_5m: Number(o.cacheWrite), cache_write_1h: Number(o.cacheWrite) }),
+        ...(o.cacheWrite1h === undefined ? {} : { cache_write_1h: Number(o.cacheWrite1h) }),
+        exact,
+    };
+}
+/** A stable revision of what was declared (the prices, not when): the same price declared again is the same revision. */
+function declarationRevision(o) {
+    const { declaredAt: _when, ...price } = o;
+    const canonical = JSON.stringify(Object.keys(price).sort().map((k) => [k, price[k]]));
+    return createHash('sha256').update('segreant-declaration:v1\n' + canonical).digest('hex');
+}
+/** The rate with decimal companions for any it lacks, written from its own numbers. */
+function withExactCompanion(rate) {
+    if (rate.exact !== undefined)
+        return rate;
+    const exact = {
+        input: plainDecimal(rate.input),
+        output: plainDecimal(rate.output),
+    };
+    if (rate.cache_write_5m !== undefined)
+        exact.cache_write_5m = plainDecimal(rate.cache_write_5m);
+    if (rate.cache_write_1h !== undefined)
+        exact.cache_write_1h = plainDecimal(rate.cache_write_1h);
+    if (rate.cache_read !== undefined)
+        exact.cache_read = plainDecimal(rate.cache_read);
+    return { ...rate, exact };
+}
+/** A free (local) model: every rate is zero, cache rates included. */
+/** Where rateFor reads declarations; null reads the file (re-read when it changes). */
+let declarationSource = null;
+function withDeclarationSource(source, fn) {
+    const previous = declarationSource;
+    declarationSource = source;
+    try {
+        return fn();
+    }
+    finally {
+        declarationSource = previous;
+    }
+}
+/**
+ * Run `fn` pricing from the card alone. The demo is fixed sample data: a real
+ * declaration (say, gpt-4o marked free) must not change its spend, evidence or
+ * comparisons (PR #146 review).
+ */
+export function withoutDeclaredPrices(fn) {
+    return withDeclarationSource(() => null, fn);
+}
+/**
+ * Run `fn` against one read of the declarations. A plan priced row by row
+ * re-read the file at each row, so a `pricing set` from another process midway
+ * gave earlier and later rows of the same model different prices in one
+ * correction (PR #146 review). The card needs no snapshot: it is cached for
+ * the life of the process and changes only by a refresh in this process,
+ * which cannot run inside a synchronous plan.
+ */
+/** Run `fn` against declarations read earlier (a proxied request keeps the ones it was checked against). */
+export function withDeclarations(models, fn) {
+    return withDeclarationSource((model) => models[model] ?? null, fn);
+}
+export function withPricingSnapshot(fn) {
+    if (declarationSource !== null)
+        return fn();
+    const models = activePriceOverrides();
+    return withDeclarationSource((model) => models[model] ?? null, fn);
+}
+const FREE_RATE = Object.freeze({ input: 0, output: 0, cache_read: 0, cache_write_5m: 0, cache_write_1h: 0 });
 export function rateFor(provider, model) {
     const pricing = loadPricing();
     const here = pricing.providers[provider]?.models;
+    // 0) A price the user declared for this exact model name wins: it is the one
+    //    place a private, fine-tuned or local model can get a real price. A `like`
+    //    that no longer resolves exactly on the card is ignored, so the request
+    //    falls to the ordinary ladder rather than to a guess built on a guess.
+    const declared = declarationSource ? declarationSource(model) : priceOverrideFor(model);
+    if (declared?.kind === 'free')
+        return resolved(FREE_RATE, 'user_declared_free', null, model, declarationRevision(declared));
+    if (declared?.kind === 'rate')
+        return resolved(declaredRate(declared), 'user_declared', null, model, declarationRevision(declared));
+    if (declared?.kind === 'like') {
+        const target = exactCardRate(pricing, declared.like);
+        // A card entry without decimal companions (a hand-written manifest may omit
+        // them) would leave a reprice with no exact replacement and roll it back
+        // (PR #146 review); the companion is the card's own stated numbers.
+        if (target)
+            return resolved(withExactCompanion(target.rate), 'user_declared', target.provider, declared.like);
+    }
     // 1) Exact id in the named provider — the price we're surest about.
     const exact = here?.[model];
     if (exact)
@@ -755,11 +947,29 @@ export function rateFor(provider, model) {
 export function exactRateFromModelRate(rate) {
     return rate.exact === undefined ? null : validateExactModelRate(rate.exact);
 }
+function zeroExactCost() {
+    const zero = money('0', 'USD', 'estimated');
+    return Object.freeze({ total: zero, components: Object.freeze({ input: zero, output: zero, cacheWrite: zero, cacheRead: zero }) });
+}
 function per(tokens, rate) {
     if (!tokens || !rate)
         return 0;
     return (tokens / 1_000_000) * rate;
 }
+/**
+ * The duration a cache write is priced at, and whether the source reported a
+ * breakdown. No breakdown: no duration (priced at the standard 5-minute rate,
+ * recorded as not recorded). One duration only: that one. Both: the larger
+ * share, which is what the request is priced with, and the ledger records it
+ * so a later reprice prices it the same way (PR #150 review). A missing
+ * breakdown used to be stored as '1h' by the Claude Code import and '5m' by
+ * the proxy, each as if it were seen (independent review, 2026-10-18).
+ */
+export function cacheWriteDuration(ephemeral5m, ephemeral1h) {
+    if (ephemeral5m <= 0 && ephemeral1h <= 0)
+        return { observed: false };
+    return { ttl: ephemeral1h > ephemeral5m ? '1h' : '5m', observed: true };
+}
 export function computeCost(provider, model, usage) {
     const { rate, estimated, pricing } = rateFor(provider, model);
     // Cache-write rate: prefer the TTL-specific rate, else default to 1.25x input
@@ -776,9 +986,12 @@ export function computeCost(provider, model, usage) {
         cacheRead: per(usage.cacheReadTokens, readRate),
     };
     const costUsd = components.input + components.output + components.cacheWrite + components.cacheRead;
-    const exactRate = exactRateFromModelRate(rate);
-    const exact = exactRate === null
-        ? undefined
-        : computeExactCost(exactRate, usage, estimated ? 'estimated' : 'list');
+    const declared = pricing.rateMatchKind === 'user_declared' || pricing.rateMatchKind === 'user_declared_free';
+    const exactRate = rate === FREE_RATE ? null : exactRateFromModelRate(rate);
+    const exact = rate === FREE_RATE
+        ? zeroExactCost()
+        : exactRate === null
+            ? undefined
+            : computeExactCost(exactRate, usage, estimated || declared ? 'estimated' : 'list');
     return { costUsd, estimated, pricing, rate, components, ...(exact === undefined ? {} : { exact }) };
 }

package/dist/cost/reprice.js

@@ -0,0 +1,130 @@
+import { computeCost, withPricingSnapshot } from './pricing.js';
+import { requestEconomicEventId } from '../economics/request.js';
+/**
+ * What priced the replacement amounts, from every row that will change: a
+ * report built from the first row alone claimed "local rate card only" for a
+ * batch that also held prices the user typed (PR #146 review).
+ */
+function repriceEvidence(updates) {
+    if (updates.length === 0)
+        return null;
+    const sources = new Map();
+    for (const u of updates) {
+        const key = JSON.stringify([u.pricing.costBasis, u.pricing.rateCardSha256, u.pricing.rateCardSourceKind]);
+        const s = sources.get(key) ?? { costBasis: u.pricing.costBasis, rateCardSha256: u.pricing.rateCardSha256, rateCardSourceKind: u.pricing.rateCardSourceKind, rows: 0 };
+        s.rows += 1;
+        sources.set(key, s);
+    }
+    const list = [...sources.values()].sort((a, b) => b.rows - a.rows);
+    const declaredRows = list.filter((s) => s.costBasis === 'user_declared_price').reduce((n, s) => n + s.rows, 0);
+    const cards = [...new Set(list.filter((s) => s.rateCardSha256 !== null).map((s) => `${s.rateCardSourceKind} ${s.rateCardSha256}`))];
+    const onlyCard = declaredRows === 0 && cards.length === 1 ? list.find((s) => s.rateCardSha256 !== null) : null;
+    return {
+        localRateCardOnly: declaredRows === 0,
+        cardSha256: onlyCard?.rateCardSha256 ?? null,
+        sourceKind: onlyCard?.rateCardSourceKind ?? (declaredRows === updates.length ? 'none' : 'mixed'),
+        declaredRows,
+        sources: list,
+        note: declaredRows === 0
+            ? 'Local list-price estimate only; never provider invoice, discount, tax, credit, or reconciliation.'
+            : `${declaredRows} of ${updates.length} rows take a price you set (your price, not a list price); the rest are local list prices. None is a provider invoice, discount, tax, credit, or reconciliation.`,
+    };
+}
+export function previewReprice(store) {
+    // Every row of one plan is priced from the same declarations.
+    return withPricingSnapshot(() => planReprice(store));
+}
+function planReprice(store) {
+    const rows = store.estimatedRequestRows();
+    const updates = [];
+    const meta = new Map();
+    let stillEstimated = 0;
+    // Rows with cache writes whose duration was never recorded (before Segreant
+    // kept it): priced at the 5-minute rate, as they were first priced, and
+    // counted so the preview says so (PR #146 review).
+    let cacheDurationUnknown = 0;
+    for (const r of rows) {
+        // No captured usage: nothing to price it from, so it stays an estimate.
+        if (!r.usageCaptured) {
+            stillEstimated++;
+            continue;
+        }
+        const c = computeCost(r.provider, r.model, {
+            inputTokens: r.inputTokens, outputTokens: r.outputTokens,
+            cacheWriteTokens: r.cacheWriteTokens, cacheReadTokens: r.cacheReadTokens,
+            ...(r.cacheWriteTtl === null ? {} : { cacheWriteTtl: r.cacheWriteTtl }),
+        });
+        if (c.estimated) {
+            stillEstimated++;
+            continue;
+        }
+        // A row with an exact economic event can only be corrected by an exact
+        // amount. A custom card may omit the decimal companions, and the plan used
+        // to promise such a row, then --apply refused it and rolled back the whole
+        // batch (PR #146 review). It stays an estimate until a card can price it exactly.
+        if (c.exact === undefined && store.economic().read(requestEconomicEventId(r.requestId)) !== null) {
+            stillEstimated++;
+            continue;
+        }
+        // Counted only for rows the plan will rewrite, so the preview never says a
+        // row's writes are priced at the 5-minute rate when it is left untouched.
+        if (r.cacheWriteTokens > 0 && r.cacheWriteTtl === null)
+            cacheDurationUnknown++;
+        updates.push({ requestId: r.requestId, costUsd: c.costUsd, pricing: c.pricing, ...(c.exact === undefined ? {} : { economicAmount: c.exact.total }) });
+        meta.set(r.requestId, {
+            provider: r.provider, model: r.model, beforeUsd: r.costUsd,
+            cacheDurationUnknown: r.cacheWriteTokens > 0 && r.cacheWriteTtl === null,
+        });
+    }
+    return { ...summarize(updates, meta, 0), estimatedRows: rows.length, stillEstimated, cacheDurationUnknown, meta };
+}
+/** Totals, models and evidence for exactly these updates: the plan, or the rows a write touched. */
+function summarize(updates, meta, alreadyRepriced) {
+    const byModel = new Map();
+    for (const u of updates) {
+        const r = meta.get(u.requestId);
+        const key = JSON.stringify([r.provider, r.model]);
+        const agg = byModel.get(key) ?? {
+            provider: r.provider, model: r.model, rows: 0, beforeUsd: 0, afterUsd: 0,
+            afterBasis: u.pricing.rateMatchKind === 'user_declared' || u.pricing.rateMatchKind === 'user_declared_free' ? 'your price' : 'list price',
+        };
+        agg.rows++;
+        agg.beforeUsd += r.beforeUsd;
+        agg.afterUsd += u.costUsd;
+        byModel.set(key, agg);
+    }
+    return {
+        applied: false, repriceable: updates.length,
+        /** Planned rows another reprice had already rewritten by the time this one wrote: left alone, not counted. */
+        alreadyRepriced,
+        totalBeforeUsd: [...byModel.values()].reduce((a, v) => a + v.beforeUsd, 0),
+        totalAfterUsd: [...byModel.values()].reduce((a, v) => a + v.afterUsd, 0),
+        priceEvidence: repriceEvidence(updates),
+        byModel: [...byModel.values()],
+        // Internal write plan; never expose the exact bigint money objects on the JSON wire.
+        updates,
+        realizationSync: null,
+    };
+}
+/**
+ * Compute once, write that plan through the Store's audited transaction, and
+ * report only the rows the transaction wrote. Another process may reprice the
+ * same rows between the plan and the write; the store skips a row that is no
+ * longer an estimate, and the result used to claim it anyway (PR #146 review).
+ */
+export function applyReprice(store) {
+    const preview = previewReprice(store);
+    if (preview.updates.length === 0)
+        return { ...preview, applied: true };
+    const { writtenRequestIds, ...realizationSync } = store.applyRepricedCosts(preview.updates);
+    const written = new Set(writtenRequestIds);
+    const done = preview.updates.filter((u) => written.has(u.requestId));
+    const cacheDurationUnknown = done.filter((u) => preview.meta.get(u.requestId).cacheDurationUnknown).length;
+    return {
+        ...preview,
+        ...summarize(done, preview.meta, preview.updates.length - done.length),
+        cacheDurationUnknown,
+        applied: true,
+        realizationSync,
+    };
+}

package/dist/dashboard/claim-support.js

@@ -52,6 +52,7 @@
  * conflict lands on `coverage`, and the difference is the point rather than an
  * inconsistency.
  */
+import { recordedTime } from '../util/time.js';
 /**
  * The seven axes that do not vary, and why stating them is the point.
  *
@@ -136,7 +137,7 @@ export function meteredClaimSupport(input) {
         notes.push('no priced spend in this window, so pricing coverage is unevidenced rather than complete');
     if (truncated) {
         const removed = input.retention.rowsRemoved === 1 ? '1 request row' : `${input.retention.rowsRemoved} request rows`;
-        notes.push(`retention deleted ${removed} from before ${new Date(input.retention.prunedBeforeMs ?? 0).toISOString()}, `
+        notes.push(`retention deleted ${removed} from before ${recordedTime(input.retention.prunedBeforeMs)}, `
             + 'so this window covers what survived rather than everything metered in it');
     }
     return claimSupportPayload({
@@ -189,8 +190,8 @@ export function billedClaimSupport(input) {
     // deleted by retention bounds nothing either, for a different reason -- the
     // local total is a known undercount by an unknown amount. Both are "this
     // residual establishes no bound", which is what this variable feeds.
-    const boundsNothing = input.latest?.offPathBound === 'none_local_estimate_exceeds_provider'
-        || input.latest?.offPathBound === 'unknown_local_total_truncated_by_retention';
+    const truncatedByRetention = input.latest?.offPathBound === 'unknown_local_total_truncated_by_retention';
+    const residualBoundsNothing = input.latest?.offPathBound === 'none_local_estimate_exceeds_provider';
     return claimSupportPayload({
         ...PRODUCT_CLAIM_AXES,
         epistemic: unstable ? 'conflicted' : 'supported',
@@ -198,16 +199,18 @@ export function billedClaimSupport(input) {
         // immutable and identified by the digest of the result it describes, so it
         // cannot outlive a change to that result.
         integrity: 'verified',
-        coverage: boundsNothing ? 'partial' : 'complete',
+        coverage: truncatedByRetention || residualBoundsNothing ? 'partial' : 'complete',
         monetaryBasis: 'billed',
     }, 
     // An evidence claim about whether a comparison happened, not a second cost
     // figure. The band carries no dollar in any branch.
     'not_a_money_claim', unstable
         ? `provider snapshots disagreed on ${days.length} day(s) of this scope`
-        : boundsNothing
-            ? 'the local estimate exceeds the provider total, so the residual bounds no off-path spend'
-            : undefined);
+        : truncatedByRetention
+            ? 'retention deleted local request rows in this period, so the residual bounds no off-path spend'
+            : residualBoundsNothing
+                ? 'the local estimate exceeds the provider total, so the residual bounds no off-path spend'
+                : undefined);
 }
 /**
  * Allocation is showback: the claim is whose cost it is, not how much, so the
@@ -263,6 +266,6 @@ export function realizedClaimSupport(input) {
     }, !supported ? 'withheld_unsupported' : input.valued ? 'shown' : 'withheld_uncosted', conflicted.length > 0
         ? `${conflictedUnits} mature unit(s) hold contradicted gate evidence at ${conflicted
             .map(([gate]) => gate)
-            .join(', ')} and are unadjudicated rather than refuted`
+            .join(', ')}; the conflict is unresolved, not a fail`
         : undefined);
 }

package/dist/dashboard/contracts.js

@@ -18,9 +18,19 @@ export const DASHBOARD_API_CONTRACTS = [
     { id: 'scan', path: '/api/scan', methods: ['GET', 'POST'], localOnly: ['POST'], responseType: 'ScanPayload', browserBinding: ['modern-api', 'classic'] },
     { id: 'overview', path: '/api/overview', methods: ['GET', 'HEAD'], localOnly: [], responseType: 'Overview', browserBinding: ['modern-api', 'classic'] },
     { id: 'billing', path: '/api/billing', methods: ['GET'], localOnly: [], responseType: 'BillingPayload', browserBinding: ['modern-api', 'classic'] },
+    { id: 'statement', path: '/api/statement', methods: ['GET', 'HEAD'], localOnly: [], responseType: 'StatementPayload', browserBinding: ['modern-api'] },
+    { id: 'sessions', path: '/api/sessions', methods: ['GET', 'HEAD'], localOnly: [], responseType: 'SessionsPayload', browserBinding: ['modern-api'] },
+    { id: 'statement-csv', path: '/api/statement.csv', methods: ['GET', 'HEAD'], localOnly: [], responseType: 'text/csv', browserBinding: ['modern-api'] },
     { id: 'allocation', path: '/api/allocation', methods: ['GET'], localOnly: [], responseType: 'AllocationPayload', browserBinding: ['modern-api', 'classic'] },
+    { id: 'allocation-write', path: '/api/allocation/write', methods: ['POST'], localOnly: ['POST'], responseType: 'AllocationWritePayload', browserBinding: ['modern-api'] },
+    { id: 'allocation-run-csv', path: '/api/allocation/run.csv', methods: ['GET', 'HEAD'], localOnly: [], responseType: 'text/csv', browserBinding: ['modern-api'] },
+    { id: 'billing-write', path: '/api/billing/write', methods: ['POST'], localOnly: ['POST'], responseType: 'BillingWritePayload', browserBinding: ['modern-api'] },
     { id: 'economic', path: '/api/economic', methods: ['GET', 'HEAD'], localOnly: [], responseType: 'EconomicPayload', browserBinding: ['modern-api'] },
     { id: 'pricing', path: '/api/pricing', methods: ['GET', 'HEAD'], localOnly: [], responseType: 'PricingPayload', browserBinding: [] },
+    { id: 'pricing-unknown', path: '/api/pricing/unknown', methods: ['GET'], localOnly: [], responseType: 'UnknownPricingPayload', browserBinding: ['modern-api'] },
+    { id: 'pricing-declare', path: '/api/pricing/declare', methods: ['POST'], localOnly: ['POST'], responseType: 'PricingDeclarePayload', browserBinding: ['modern-api'] },
+    { id: 'pricing-unset', path: '/api/pricing/unset', methods: ['POST'], localOnly: ['POST'], responseType: 'PricingUnsetPayload', browserBinding: ['modern-api'] },
+    { id: 'reprice', path: '/api/reprice', methods: ['POST'], localOnly: ['POST'], responseType: 'RepricePayload', browserBinding: ['modern-api'] },
     { id: 'export-csv', path: '/api/export.csv', methods: ['GET', 'HEAD'], localOnly: [], responseType: 'text/csv', browserBinding: ['classic', 'actions'] },
     { id: 'realization', path: '/api/realization', methods: ['GET', 'HEAD'], localOnly: [], responseType: 'RealizationPayload', browserBinding: [] },
     { id: 'guide', path: '/api/guide', methods: ['GET', 'HEAD'], localOnly: [], responseType: 'GuidePayload', browserBinding: ['modern-api', 'classic'] },
@@ -59,21 +69,31 @@ export const DASHBOARD_PAYLOAD_CONTRACTS = [
     { routeId: 'scan', method: 'GET', contentType: 'json', responseType: 'ScanPayload', required: [field('ok', 'boolean'), field('tools', 'array'), field('otherApps', 'array'), field('roots', 'array'), field('repoCount', 'number'), field('reposWithSpend', 'number'), field('hitBudget', 'boolean'), field('dirsVisited', 'number'), field('unreadableDirs', 'number'), field('diff', 'object')] },
     { routeId: 'scan', method: 'POST', contentType: 'json', responseType: 'ScanSetupPayload', required: [field('ok', 'boolean'), field('totalNew', 'number'), field('imported', 'object'), field('correlated', 'number'), field('discovered', 'array')] },
     { routeId: 'overview', method: 'GET', contentType: 'json', responseType: 'Overview', required: [field('claimSupport', 'object'), field('range', 'string'), field('demo', 'boolean'), field('generatedAt', 'string'), field('budget', 'object'), field('summary', 'object'), field('pricing', 'object'), field('byModel', 'array'), field('byProject', 'array'), field('attributionEvidence', 'array'), field('byUser', 'array'), field('bySource', 'array'), field('characterization', 'object'), field('dimensions', 'array'), field('series', 'array'), field('recent', 'array'), field('alerts', 'array'), field('alertCoverage', 'object')] },
+    { routeId: 'statement', method: 'GET', contentType: 'json', responseType: 'StatementPayload', required: [field('demo', 'boolean'), field('generatedAt', 'string'), field('month', 'string'), field('period', 'object'), field('metered', 'object'), field('billed', 'object'), field('allocated', 'object'), field('realized', 'object'), field('close', 'object')] },
+    { routeId: 'sessions', method: 'GET', contentType: 'json', responseType: 'SessionsPayload', required: [field('demo', 'boolean'), field('generatedAt', 'string'), field('range', 'string'), field('window', 'object'), field('totals', 'object'), field('models', 'array'), field('buckets', 'array'), field('sessions', 'array'), field('sessionLimit', 'number'), field('sessionsOmitted', 'number'), field('outcomes', 'object')] },
     { routeId: 'billing', method: 'GET', contentType: 'json', responseType: 'BillingPayload', required: [field('claimSupport', 'object'), field('demo', 'boolean'), field('generatedAt', 'string'), field('evidence', 'object'), field('summary', 'object'), field('imports', 'array'), field('kernel', 'object'), field('readiness', 'object'), field('mapping', 'object'), field('directOpenAiCosts', 'object'), field('reconciliation', 'object')] },
     { routeId: 'allocation', method: 'GET', contentType: 'json', responseType: 'AllocationPayload', required: [field('claimSupport', 'object'), field('demo', 'boolean'), field('generatedAt', 'string'), field('kind', 'string'), field('trust', 'string'), field('basis', 'string'), field('excludedFrom', 'array'), field('costCentres', 'array'), field('rules', 'array'), field('runs', 'array'), field('reconciliation', 'object')] },
+    { routeId: 'allocation-write', method: 'POST', contentType: 'json', responseType: 'AllocationWritePayload', required: [field('ok', 'boolean'), field('op', 'string'), field('applied', 'boolean')] },
+    { routeId: 'billing-write', method: 'POST', contentType: 'json', responseType: 'BillingWritePayload', required: [field('ok', 'boolean'), field('op', 'string'), field('applied', 'boolean')] },
     { routeId: 'economic', method: 'GET', contentType: 'json', responseType: 'EconomicPayload', required: [field('kind', 'string'), field('schemaVersion', 'number'), field('demo', 'boolean'), field('window', 'object'), field('translation', 'object', true), field('projection', 'object'), field('periodClose', 'object')] },
     { routeId: 'pricing', method: 'GET', contentType: 'json', responseType: 'PricingPayload', required: [field('demo', 'boolean'), field('generatedAt', 'string'), field('window', 'object'), field('activeRateCard', 'object'), field('total', 'object'), field('provenance', 'array'), field('boundary', 'string')] },
+    { routeId: 'pricing-unknown', method: 'GET', contentType: 'json', responseType: 'UnknownPricingPayload', required: [field('models', 'array'), field('boundary', 'string'), field('demo', 'boolean')] },
+    { routeId: 'pricing-declare', method: 'POST', contentType: 'json', responseType: 'PricingDeclarePayload', required: [field('ok', 'boolean'), field('model', 'string'), field('price', 'object')] },
+    { routeId: 'pricing-unset', method: 'POST', contentType: 'json', responseType: 'PricingUnsetPayload', required: [field('ok', 'boolean'), field('model', 'string'), field('removed', 'boolean')] },
+    { routeId: 'reprice', method: 'POST', contentType: 'json', responseType: 'RepricePayload', required: [field('applied', 'boolean'), field('demo', 'boolean'), field('estimatedRows', 'number'), field('repriceable', 'number'), field('stillEstimated', 'number'), field('totalBeforeUsd', 'number'), field('totalAfterUsd', 'number'), field('byModel', 'array'), field('realizationSync', 'object', true)] },
     { routeId: 'export-csv', method: 'GET', contentType: 'text', responseType: 'text/csv', required: [] },
+    { routeId: 'statement-csv', method: 'GET', contentType: 'text', responseType: 'text/csv', required: [] },
+    { routeId: 'allocation-run-csv', method: 'GET', contentType: 'text', responseType: 'text/csv', required: [] },
     { routeId: 'realization', method: 'GET', contentType: 'json', responseType: 'RealizationPayload', required: [field('available', 'boolean'), field('repo', 'string')] },
     { routeId: 'guide', method: 'GET', contentType: 'json', responseType: 'GuidePayload', required: [field('stage', 'string'), field('headline', 'string'), field('steps', 'array'), field('next', 'object'), field('hint', 'object', true)] },
     { routeId: 'judge', method: 'POST', contentType: 'json', responseType: 'JudgePayload', required: [] },
     { routeId: 'kernel', method: 'GET', contentType: 'json', responseType: 'KernelNodePayload', required: [field('found', 'boolean'), field('id', 'string'), field('asOf', 'string', true), field('node', 'object', true)] },
-    { routeId: 'value', method: 'GET', contentType: 'json', responseType: 'ValuePayload', required: [field('claimSupport', 'object'), field('demo', 'boolean'), field('gitRepo', 'boolean'), field('valueSource', 'string', true), field('repo', 'string'), field('generatedAt', 'string'), field('realization', 'object', true), field('roi', 'object', true), field('frontier', 'object', true), field('budget', 'object', true), field('allocation', 'object', true), field('projects', 'array'), field('projectAllocation', 'object', true), field('usage', 'object', true), field('selfReported', 'object'), field('team', 'object', true), field('drift', 'object', true), field('reclaimed', 'object', true)] },
+    { routeId: 'value', method: 'GET', contentType: 'json', responseType: 'ValuePayload', required: [field('claimSupport', 'object'), field('demo', 'boolean'), field('gitRepo', 'boolean'), field('valueSource', 'string', true), field('repo', 'string'), field('generatedAt', 'string'), field('realization', 'object', true), field('roi', 'object', true), field('frontier', 'object', true), field('budget', 'object', true), field('allocation', 'object', true), field('projects', 'array', true), field('projectAllocation', 'object', true), field('usage', 'object', true), field('selfReported', 'object'), field('team', 'object', true), field('drift', 'object', true), field('reclaimed', 'object', true)] },
     { routeId: 'market', method: 'GET', contentType: 'json', responseType: 'MarketPayload', required: [field('status', 'string'), field('categories', 'array'), field('boundary', 'array'), field('cacheErrors', 'array')] },
     { routeId: 'outcome-record', method: 'POST', contentType: 'json', responseType: 'OutcomeRecordPayload', required: [field('apply', 'boolean'), field('basis', 'string'), field('event', 'object'), field('matchedRequests', 'number'), field('matchedCostUsd', 'number', true), field('linkStatus', 'string')] },
     { routeId: 'causal', method: 'GET', contentType: 'json', responseType: 'CausalPayload', required: [field('demo', 'boolean'), field('generatedAt', 'string'), field('studies', 'array'), field('study', 'object', true), field('causalEvidence', 'string'), field('boundary', 'string')] },
-    { routeId: 'settings', method: 'GET', contentType: 'json', responseType: 'SettingsSnapshot', required: [field('version', 'string'), field('home', 'string'), field('configPath', 'string'), field('dbPath', 'string'), field('proxyPort', 'number'), field('dashboardPort', 'number'), field('retentionDays', 'number'), field('proposalRetentionDays', 'number'), field('metadataOnly', 'boolean'), field('features', 'object'), field('budget', 'object'), field('enforcement', 'object'), field('egress', 'object'), field('connections', 'array')] },
-    { routeId: 'settings-update', method: 'POST', contentType: 'json', responseType: 'SettingsSnapshot', required: [field('version', 'string'), field('home', 'string'), field('configPath', 'string'), field('dbPath', 'string'), field('proxyPort', 'number'), field('dashboardPort', 'number'), field('retentionDays', 'number'), field('proposalRetentionDays', 'number'), field('metadataOnly', 'boolean'), field('features', 'object'), field('budget', 'object'), field('enforcement', 'object'), field('egress', 'object'), field('connections', 'array')] },
+    { routeId: 'settings', method: 'GET', contentType: 'json', responseType: 'SettingsSnapshot', required: [field('version', 'string'), field('home', 'string'), field('configPath', 'string'), field('dbPath', 'string'), field('proxyPort', 'number'), field('dashboardPort', 'number'), field('retentionDays', 'number'), field('proposalRetentionDays', 'number'), field('metadataOnly', 'boolean'), field('demo', 'boolean'), field('features', 'object'), field('budget', 'object'), field('enforcement', 'object'), field('egress', 'object'), field('connections', 'array')] },
+    { routeId: 'settings-update', method: 'POST', contentType: 'json', responseType: 'SettingsSnapshot', required: [field('version', 'string'), field('home', 'string'), field('configPath', 'string'), field('dbPath', 'string'), field('proxyPort', 'number'), field('dashboardPort', 'number'), field('retentionDays', 'number'), field('proposalRetentionDays', 'number'), field('metadataOnly', 'boolean'), field('demo', 'boolean'), field('features', 'object'), field('budget', 'object'), field('enforcement', 'object'), field('egress', 'object'), field('connections', 'array')] },
     { routeId: 'clear-proposals', method: 'POST', contentType: 'json', responseType: 'ClearProposalsPayload', required: [field('ok', 'boolean'), field('removed', 'number')] },
 ];
 export function dashboardPayloadContract(routeId, method) {