ai-lcr 0.5.6 → 0.6.0

package/CHANGELOG.md

@@ -4,6 +4,50 @@ All notable changes to `ai-lcr` are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/), and the project adheres to
 [Semantic Versioning](https://semver.org/).
 
+## [0.6.0] — 2026-06-10
+
+Media billing contract v2: **rank by the reference, bill by actual usage.**
+The 0.5 media router used one number for both jobs — the price normalized to a
+reference output (1080p image / 5-second clip) ranked routes *and* estimated
+costs, multiplied by an untyped `units` count. That mispriced off-reference
+outputs (an 8s clip billed as 5s) and made the baseline duration-blind, and the
+bare `units` invited a seconds-as-count 8× overcharge. 0.6 separates the two.
+
+### Added
+
+- **Typed usage (`MediaUsage`).** Adapter results (`MediaGenerateResult`,
+  `MediaStatusResult`) carry `usage: { seconds?, outputs?, megapixels? }` —
+  explicitly named dimensions that cannot be confused. The bundled adapters
+  report it (Kunavo video now safely reports the real `duration_seconds`).
+  The legacy bare `units` field is still honored as an output count.
+- **Settle-time billing.** Cost estimates price the route's actual unit on
+  actual usage: per-second SKUs bill `usage.seconds` → `input.duration`
+  (numbers or `"8s"`-style strings) → the reference (last resort); per-image /
+  per-call SKUs bill output count; per-megapixel SKUs bill measured megapixels.
+  New public helpers: `billableUnits`, `priceCents`, `durationFromInput`.
+- **Usage-aware savings baseline.** `baselineUsd` is now priced at settle time
+  against the same usage as the cost — an 8-second clip is baselined at 8
+  seconds of the official rate, not the 5-second reference. Off-reference calls
+  can no longer produce negative or understated savings.
+- **`CallRecord` provenance fields** (all optional, backward compatible):
+  `modality` ("image" | "video"), `usage`, `baselineKind`
+  ("official" | "priciest-route" | "last-leg" — the text router now stamps
+  "last-leg"), `officialUsd` (the official price for this call's usage), and
+  `estCostUsd` (the price-table prediction; `costUsd − estCostUsd` on
+  provider-reported rows is price-table drift).
+- **Cost-outlier guard.** A provider-reported cost ≥25× off the table
+  prediction (the classic USD-vs-cents slip is exactly 100×) raises `onError`
+  with both numbers; the reported bill still stands.
+- `MediaRunResult` and the terminal `MediaPollResult` expose the `usage` that
+  backed the bill.
+
+### Changed
+
+- `MediaJobHandle` now carries the serving route's `pricing` and the resolved
+  savings `baseline` so settle-time billing works across processes. Handles
+  serialized by 0.5.x still poll fine: they settle with the legacy
+  reference-price estimate and the submit-time baseline.
+
 ## [0.5.6] — 2026-06-07
 
 All additions are optional and backward compatible. The sync `createMediaLCR`

package/README.md

@@ -293,7 +293,9 @@ USD per second, as of 2026-05 — verify current rates. Video billing differs by
 
 ## Image & video routing (`createMediaLCR`)
 
-Image and video are a separate, self-contained side of `ai-lcr` (file outputs, mixed pricing units, async jobs) — see [`src/media.ts`](src/media.ts). You give it a registry (each model's provider routes + per-unit price) and a set of adapters; it routes cheapest-first, fails over, and reports real/normalized cost through the same `onCall` sink as text.
+Image and video are a separate, self-contained side of `ai-lcr` (file outputs, mixed pricing units, async jobs) — see [`src/media.ts`](src/media.ts). You give it a registry (each model's provider routes + per-unit price) and a set of adapters; it routes cheapest-first, fails over, and reports real cost through the same `onCall` sink as text.
+
+Two prices, two jobs: routes are **ranked** by their price normalized to one reference output (a 1080p image / a 5-second clip) so mixed units are comparable, but each settled call is **billed** on its actual usage — an 8-second clip on a per-second SKU costs 8 × the per-second rate, and its savings baseline is the official price for those same 8 seconds. Adapters report typed usage (`usage: { seconds, outputs, megapixels }`); when a provider returns its own bill, that wins, and a bill wildly off the price table (the classic USD-vs-cents slip is exactly 100×) raises `onError` so the table gets fixed.
 
 ```ts
 import { createMediaLCR, createKunavoMediaAdapter, createFalMediaAdapter } from 'ai-lcr'

package/dist/index.cjs

@@ -23,6 +23,7 @@ __export(index_exports, {
   DEFAULT_REFERENCE: () => DEFAULT_REFERENCE,
   MEDIA_PRICING: () => MEDIA_PRICING,
   OFFICIAL_PRICES: () => OFFICIAL_PRICES,
+  billableUnits: () => billableUnits,
   cheapestRoute: () => cheapestRoute,
   classifyError: () => classifyError,
   classifyErrorKind: () => classifyErrorKind,
@@ -33,11 +34,13 @@ __export(index_exports, {
   createLCR: () => createLCR,
   createMediaLCR: () => createMediaLCR,
   createRunwareMediaAdapter: () => createRunwareMediaAdapter,
+  durationFromInput: () => durationFromInput,
   formatCallRecord: () => formatCallRecord,
   isAbortError: () => isAbortError,
   isNetworkError: () => isNetworkError,
   isRetryableError: () => isRetryableError,
   normalizedCents: () => normalizedCents,
+  priceCents: () => priceCents,
   rankRoutes: () => rankRoutes,
   referenceMegapixels: () => referenceMegapixels,
   shouldFailover: () => shouldFailover
@@ -364,6 +367,7 @@ var LcrFallbackModel = class {
     const cachedSavingUsd = provider.cost ? cacheSavingForUsage(provider.cost, inputTokens, cacheReadTokens) : 0;
     const usageMissing = inputTokens === 0 && outputTokens === 0;
     const emptyCompletion = inputTokens > 0 && outputTokens === 0;
+    const baselineUsd = this.baselineUsd(inputTokens, outputTokens, cacheReadTokens);
     this.emitCost({
       model: this.opts.modelName,
       provider: provider.label,
@@ -384,7 +388,7 @@ var LcrFallbackModel = class {
       outputTokens,
       ...cacheReadTokens > 0 ? { cachedInputTokens: cacheReadTokens } : {},
       costUsd,
-      baselineUsd: this.baselineUsd(inputTokens, outputTokens, cacheReadTokens),
+      ...baselineUsd !== void 0 ? { baselineUsd, baselineKind: "last-leg" } : {},
       ...cachedSavingUsd > 0 ? { cachedSavingUsd } : {},
       ...ctx.requestId ? { requestId: ctx.requestId } : {},
       ...usageMissing ? { usageMissing: true } : {},
@@ -715,6 +719,40 @@ function normalizedCents(pricing, ref = DEFAULT_REFERENCE) {
       return pricing.cents * ref.videoSeconds;
   }
 }
+function durationFromInput(input) {
+  const raw = input?.["duration"];
+  if (typeof raw === "number" && Number.isFinite(raw) && raw > 0) return raw;
+  if (typeof raw === "string") {
+    const m = /^(\d+(?:\.\d+)?)\s*s?$/i.exec(raw.trim());
+    if (m) {
+      const n = Number(m[1]);
+      if (Number.isFinite(n) && n > 0) return n;
+    }
+  }
+  return void 0;
+}
+function billableUnits(unit, ctx) {
+  const ref = ctx.reference ?? DEFAULT_REFERENCE;
+  const positive = (n) => typeof n === "number" && Number.isFinite(n) && n > 0 ? n : void 0;
+  switch (unit) {
+    case "second": {
+      const measured = positive(ctx.usage?.seconds) ?? durationFromInput(ctx.input);
+      return measured !== void 0 ? { value: measured, assumed: false } : { value: ref.videoSeconds, assumed: true };
+    }
+    case "megapixel": {
+      const measured = positive(ctx.usage?.megapixels);
+      return measured !== void 0 ? { value: measured, assumed: false } : { value: referenceMegapixels(ref), assumed: true };
+    }
+    case "image":
+    case "call": {
+      const measured = positive(ctx.usage?.outputs) ?? positive(ctx.outputCount) ?? positive(ctx.units);
+      return measured !== void 0 ? { value: measured, assumed: false } : { value: 1, assumed: true };
+    }
+  }
+}
+function priceCents(pricing, ctx) {
+  return pricing.cents * billableUnits(pricing.unit, ctx).value;
+}
 function rankRoutes(def, ref = DEFAULT_REFERENCE) {
   return def.routes.map((r) => ({ ...r, refCents: normalizedCents(r.pricing, ref) })).sort((a, b) => a.refCents - b.refCents);
 }
@@ -780,38 +818,91 @@ function createMediaLCR(config) {
     }
     const ranked = rankRoutes(def, reference);
     const official = def.official ?? officialPrices[modelId];
-    const baselineUsd = official !== void 0 ? normalizedCents(official, reference) / 100 : ranked.length > 0 ? Math.max(...ranked.map((r) => r.refCents)) / 100 : 0;
-    return { ranked, baselineUsd };
+    const baseline = official !== void 0 ? { pricing: official, kind: "official" } : ranked.length > 0 ? { pricing: ranked[ranked.length - 1].pricing, kind: "priciest-route" } : void 0;
+    return { def, ranked, baseline };
   }
-  const costFor = (refCents, result) => result.costCents === void 0 ? refCents * (result.units ?? 1) : result.costCents;
-  const emitFail = (modelId, attempts, baselineUsd, startedAt) => safeCall({
-    id: newMediaCallId(),
-    model: modelId,
-    attempts,
-    winner: void 0,
-    ok: false,
-    failedOver: attempts.length > 1,
-    latencyMs: Date.now() - startedAt,
-    inputTokens: 0,
-    outputTokens: 0,
-    costUsd: 0,
-    baselineUsd
-  });
-  const emitOk = (modelId, provider, attempts, costCents, baselineUsd, startedAt) => safeCall({
-    id: newMediaCallId(),
-    model: modelId,
-    attempts,
-    winner: provider,
-    ok: true,
-    failedOver: attempts.length > 1,
-    latencyMs: Date.now() - startedAt,
-    inputTokens: 0,
-    outputTokens: 0,
-    costUsd: costCents / 100,
-    baselineUsd
-  });
+  const refBaselineUsd = (baseline) => baseline ? normalizedCents(baseline.pricing, reference) / 100 : 0;
+  function settle(pricing, refCents, result, input) {
+    const ctx = {
+      ...result.usage ? { usage: result.usage } : {},
+      ...result.units !== void 0 ? { units: result.units } : {},
+      ...result.outputs ? { outputCount: result.outputs.length } : {},
+      ...input ? { input } : {},
+      reference
+    };
+    const estCents = pricing ? priceCents(pricing, ctx) : refCents * billableUnits("call", ctx).value;
+    const estimated = result.costCents === void 0;
+    const costCents = result.costCents ?? estCents;
+    const usage = { ...result.usage ?? {} };
+    if (usage.outputs === void 0 && (result.outputs?.length ?? 0) > 0) {
+      usage.outputs = result.outputs.length;
+    }
+    if (usage.seconds === void 0 && pricing?.unit === "second") {
+      const s = billableUnits("second", ctx);
+      if (!s.assumed) usage.seconds = s.value;
+    }
+    return {
+      costCents,
+      estCents,
+      estimated,
+      ...Object.keys(usage).length > 0 ? { usage } : {},
+      ctx
+    };
+  }
+  const DRIFT_RATIO = 25;
+  const warnDrift = (modelId, provider, s) => {
+    if (s.estimated || s.estCents <= 0 || s.costCents <= 0) return;
+    const ratio = s.costCents / s.estCents;
+    if (ratio >= DRIFT_RATIO || ratio <= 1 / DRIFT_RATIO) {
+      safeError(
+        new Error(
+          `ai-lcr: ${provider} reported ${s.costCents}\xA2 for "${modelId}" but the price table predicts ${s.estCents}\xA2 (${ratio.toFixed(1)}\xD7) \u2014 check the route's pricing units (USD vs cents) or refresh the registry price`
+        ),
+        provider
+      );
+    }
+  };
+  const emitFail = (modelId, attempts, baselineUsd, startedAt) => {
+    const modality = registry[modelId]?.modality;
+    safeCall({
+      id: newMediaCallId(),
+      model: modelId,
+      attempts,
+      winner: void 0,
+      ok: false,
+      failedOver: attempts.length > 1,
+      latencyMs: Date.now() - startedAt,
+      inputTokens: 0,
+      outputTokens: 0,
+      costUsd: 0,
+      baselineUsd,
+      ...modality ? { modality } : {}
+    });
+  };
+  const emitOk = (args) => {
+    const { settled, baseline } = args;
+    const baselineUsd = baseline ? priceCents(baseline.pricing, settled.ctx) / 100 : args.legacyBaselineUsd ?? 0;
+    safeCall({
+      id: newMediaCallId(),
+      model: args.modelId,
+      attempts: args.attempts,
+      winner: args.provider,
+      ok: true,
+      failedOver: args.attempts.length > 1,
+      latencyMs: Date.now() - args.startedAt,
+      inputTokens: 0,
+      outputTokens: 0,
+      costUsd: settled.costCents / 100,
+      baselineUsd,
+      ...baseline ? { baselineKind: baseline.kind } : {},
+      ...baseline?.kind === "official" ? { officialUsd: baselineUsd } : {},
+      modality: args.modality,
+      ...settled.usage ? { usage: settled.usage } : {},
+      estCostUsd: settled.estCents / 100
+    });
+  };
   const generate = async function generate2(modelId, input) {
-    const { ranked, baselineUsd } = resolve(modelId);
+    const { def, ranked, baseline } = resolve(modelId);
     const startedAt = Date.now();
     const attempts = [];
     let lastErr;
@@ -821,12 +912,31 @@ function createMediaLCR(config) {
       const attemptStart = Date.now();
       try {
         const result = await adapter.run({ externalId: route.externalId, input });
-        const estimated = result.costCents === void 0;
-        const costCents = costFor(route.refCents, result);
+        const settled = settle(route.pricing, route.refCents, result, input);
         attempts.push({ provider: route.provider, ok: true, latencyMs: Date.now() - attemptStart });
-        safeCost({ modelId, provider: route.provider, costCents, estimated });
-        emitOk(modelId, route.provider, attempts, costCents, baselineUsd, startedAt);
-        return { outputs: result.outputs, provider: route.provider, costCents, estimated };
+        warnDrift(modelId, route.provider, settled);
+        safeCost({
+          modelId,
+          provider: route.provider,
+          costCents: settled.costCents,
+          estimated: settled.estimated
+        });
+        emitOk({
+          modelId,
+          modality: def.modality,
+          provider: route.provider,
+          attempts,
+          settled,
+          baseline,
+          startedAt
+        });
+        return {
+          outputs: result.outputs,
+          provider: route.provider,
+          costCents: settled.costCents,
+          estimated: settled.estimated,
+          ...settled.usage ? { usage: settled.usage } : {}
+        };
       } catch (err) {
         lastErr = err;
         attempts.push({
@@ -837,19 +947,19 @@ function createMediaLCR(config) {
         });
         safeError(err, route.provider);
         if (!isRetryableError(err)) {
-          emitFail(modelId, attempts, baselineUsd, startedAt);
+          emitFail(modelId, attempts, refBaselineUsd(baseline), startedAt);
           throw err;
         }
       }
     }
-    emitFail(modelId, attempts, baselineUsd, startedAt);
+    emitFail(modelId, attempts, refBaselineUsd(baseline), startedAt);
     throw lastErr instanceof Error ? lastErr : new Error(`ai-lcr: no provider could serve media model "${modelId}"`);
   };
   const asyncRanked = (modelId) => {
     const { ranked } = resolve(modelId);
     return ranked.filter((r) => typeof adapters[r.provider]?.submit === "function");
   };
-  async function submitFrom(modelId, routes, input, metadata, baselineUsd, startedAt, attempts) {
+  async function submitFrom(modelId, routes, input, metadata, baseline, startedAt, attempts) {
     let lastErr;
     for (let i = 0; i < routes.length; i++) {
       const route = routes[i];
@@ -864,10 +974,12 @@ function createMediaLCR(config) {
           externalId: route.externalId,
           requestId,
           refCents: route.refCents,
+          pricing: route.pricing,
+          ...baseline ? { baseline } : {},
           fallbacks: routes.slice(i + 1).map((r) => ({ provider: r.provider, externalId: r.externalId, refCents: r.refCents })),
           input,
           ...metadata ? { metadata } : {},
-          baselineUsd,
+          baselineUsd: refBaselineUsd(baseline),
           startedAt,
           attemptStart,
           attempts
@@ -884,18 +996,18 @@ function createMediaLCR(config) {
         if (!isRetryableError(err)) break;
       }
     }
-    emitFail(modelId, attempts, baselineUsd, startedAt);
+    emitFail(modelId, attempts, refBaselineUsd(baseline), startedAt);
     throw lastErr instanceof Error ? lastErr : new Error(`ai-lcr: no async provider could submit media model "${modelId}"`);
   }
   generate.submit = async function submit(modelId, input, options) {
-    const { ranked, baselineUsd } = resolve(modelId);
+    const { ranked, baseline } = resolve(modelId);
     const usable = ranked.filter((r) => typeof adapters[r.provider]?.submit === "function");
     if (usable.length === 0) {
       throw new Error(
         `ai-lcr: no provider for media model "${modelId}" supports async submit (need an adapter with submit/checkStatus)`
       );
     }
-    return submitFrom(modelId, usable, input, options?.metadata, baselineUsd, Date.now(), []);
+    return submitFrom(modelId, usable, input, options?.metadata, baseline, Date.now(), []);
   };
   generate.poll = async function poll(handle) {
     const adapter = adapters[handle.provider];
@@ -905,6 +1017,7 @@ function createMediaLCR(config) {
       );
     }
     const failover = async (attempts) => {
+      const { baseline } = resolve(handle.modelId);
       const next = asyncRanked(handle.modelId).filter(
         (r) => handle.fallbacks.some((f) => f.provider === r.provider && f.externalId === r.externalId)
       );
@@ -913,7 +1026,7 @@ function createMediaLCR(config) {
         next,
         handle.input,
         handle.metadata,
-        handle.baselineUsd,
+        handle.baseline ?? baseline,
         handle.startedAt,
         attempts
       );
@@ -953,15 +1066,37 @@ function createMediaLCR(config) {
           true
         );
       }
-      const estimated = status.costCents === void 0;
-      const costCents = costFor(handle.refCents, status);
+      const settled = settle(handle.pricing, handle.refCents, { ...status, outputs }, handle.input);
       const attempts = [
         ...handle.attempts,
         { provider: handle.provider, ok: true, latencyMs: Date.now() - handle.attemptStart }
       ];
-      safeCost({ modelId: handle.modelId, provider: handle.provider, costCents, estimated });
-      emitOk(handle.modelId, handle.provider, attempts, costCents, handle.baselineUsd, handle.startedAt);
-      return { done: true, status: "done", outputs, provider: handle.provider, costCents, estimated };
+      warnDrift(handle.modelId, handle.provider, settled);
+      safeCost({
+        modelId: handle.modelId,
+        provider: handle.provider,
+        costCents: settled.costCents,
+        estimated: settled.estimated
+      });
+      emitOk({
+        modelId: handle.modelId,
+        modality: registry[handle.modelId]?.modality ?? outputs[0].type,
+        provider: handle.provider,
+        attempts,
+        settled,
+        baseline: handle.baseline,
+        legacyBaselineUsd: handle.baselineUsd,
+        startedAt: handle.startedAt
+      });
+      return {
+        done: true,
+        status: "done",
+        outputs,
+        provider: handle.provider,
+        costCents: settled.costCents,
+        estimated: settled.estimated,
+        ...settled.usage ? { usage: settled.usage } : {}
+      };
     }
     return onLegFailure(new Error(status.error ?? `ai-lcr: ${handle.provider} job failed`), true);
   };
@@ -1152,9 +1287,12 @@ function createKunavoMediaAdapter(config) {
       if (urls.length === 0) {
         return { status: "error", error: `Kunavo video job ${req.requestId} completed with no URL` };
       }
+      const durationSeconds = body.output?.duration_seconds;
+      const seconds = typeof durationSeconds === "number" && Number.isFinite(durationSeconds) && durationSeconds > 0 ? durationSeconds : void 0;
       return {
         status: "done",
-        outputs: urls.map((url) => ({ url, type: "video" }))
+        outputs: urls.map((url) => ({ url, type: "video" })),
+        usage: { outputs: urls.length, ...seconds !== void 0 ? { seconds } : {} }
       };
     }
     if (status === "failed" || status === "error") {
@@ -1312,6 +1450,7 @@ function createRunwareMediaAdapter(config) {
       return {
         outputs,
         units: images.length,
+        usage: { outputs: images.length },
         ...cents !== void 0 ? { costCents: cents } : {}
       };
     },
@@ -1342,6 +1481,7 @@ function createRunwareMediaAdapter(config) {
         return {
           status: "done",
           outputs: [{ url, type: "video" }],
+          usage: { outputs: 1 },
           ...cents !== void 0 ? { costCents: cents } : {}
         };
       }
@@ -1433,7 +1573,7 @@ function createFalMediaAdapter(config) {
     if (outputs.length === 0) {
       return { status: "error", error: `fal job ${req.requestId} completed with no media URL` };
     }
-    return { status: "done", outputs, units: outputs.length };
+    return { status: "done", outputs, units: outputs.length, usage: { outputs: outputs.length } };
   }
   return {
     provider: "fal",
@@ -1485,7 +1625,7 @@ function createFalMediaAdapter(config) {
       if (outputs.length === 0) {
         throw new Error(`ai-lcr: fal returned no media URL for "${req.externalId}"`);
       }
-      return { outputs, units: outputs.length };
+      return { outputs, units: outputs.length, usage: { outputs: outputs.length } };
     }
   };
 }
@@ -1571,6 +1711,7 @@ function createLCR(config) {
   DEFAULT_REFERENCE,
   MEDIA_PRICING,
   OFFICIAL_PRICES,
+  billableUnits,
   cheapestRoute,
   classifyError,
   classifyErrorKind,
@@ -1581,11 +1722,13 @@ function createLCR(config) {
   createLCR,
   createMediaLCR,
   createRunwareMediaAdapter,
+  durationFromInput,
   formatCallRecord,
   isAbortError,
   isNetworkError,
   isRetryableError,
   normalizedCents,
+  priceCents,
   rankRoutes,
   referenceMegapixels,
   shouldFailover

package/dist/index.d.cts

@@ -127,6 +127,47 @@ interface CallRecord {
      * when no provider was priced.
      */
     baselineUsd?: number;
+    /**
+     * How `baselineUsd` was derived, so a dashboard can qualify the savings
+     * number instead of treating every baseline as equally authoritative:
+     *   - "last-leg":        text router — the always-on fallback leg's list price.
+     *   - "official":        media router — the model maker's first-party price.
+     *   - "priciest-route":  media router with no official price — the most
+     *                        expensive configured route (self-referential; honest
+     *                        about cross-provider spread, but not a market price).
+     * Undefined when `baselineUsd` is undefined.
+     */
+    baselineKind?: "last-leg" | "official" | "priciest-route";
+    /**
+     * Media only: "image" | "video". Lets the dashboard split media traffic from
+     * token-billed text (whose records leave this unset) without inferring from
+     * zero token counts.
+     */
+    modality?: "image" | "video";
+    /**
+     * Media only: the actual billable quantity behind `costUsd` — seconds of
+     * video, output count, or megapixels — so per-unit economics ($/second,
+     * $/image) are derivable downstream. Absent when nothing was measured.
+     */
+    usage?: {
+        seconds?: number;
+        outputs?: number;
+        megapixels?: number;
+    };
+    /**
+     * Media only: the model maker's official first-party price for THIS call's
+     * usage (USD). Present only when an official price is known; equals
+     * `baselineUsd` when `baselineKind` is "official".
+     */
+    officialUsd?: number;
+    /**
+     * What the configured price table PREDICTED this call would cost (USD), on
+     * the same usage. When the provider reports an actual cost, `costUsd −
+     * estCostUsd` is the price-table drift — the signal that a registry price is
+     * stale or mis-entered. When no provider cost is reported the two are equal
+     * (the estimate IS the cost), so drift is only meaningful on reported rows.
+     */
+    estCostUsd?: number;
     /**
      * The slice of `costUsd` that prompt-cache reads saved versus paying the full
      * input rate for those same tokens (`cachedTokens × (input − cacheRead)`).
@@ -366,6 +407,41 @@ declare function referenceMegapixels(ref: ReferenceSpec): number;
  * This is the single normalization that makes providers comparable.
  */
 declare function normalizedCents(pricing: MediaPricing, ref?: ReferenceSpec): number;
+/**
+ * Parse a duration in seconds out of a canonical media input. Accepts a number
+ * or a numeric-ish string (Veo-style `"8s"`, `"8"`). Returns undefined when the
+ * input carries no usable duration.
+ */
+declare function durationFromInput(input: Record<string, unknown> | undefined): number | undefined;
+/** What `billableUnits` can draw on to resolve the actual billed quantity. */
+interface BillableContext {
+    /** Typed usage the adapter measured on the settled result. Highest priority. */
+    usage?: MediaUsage;
+    /** Legacy bare count from older adapters — OUTPUT COUNT only. */
+    units?: number;
+    /** Settled output count (`outputs.length`), when available. */
+    outputCount?: number;
+    /** The canonical request input — `duration` is read for per-second pricing. */
+    input?: Record<string, unknown>;
+    /** Reference spec, the last-resort assumption when nothing was measured. */
+    reference?: ReferenceSpec;
+}
+/**
+ * Resolve the actual billable quantity for a pricing unit, with provenance:
+ * `assumed: true` means nothing was measured and the reference spec filled in
+ * (so the resulting cost is a guess of last resort, not a measurement).
+ *
+ * Resolution order per unit:
+ *   - "second":     usage.seconds → input.duration → reference.videoSeconds (assumed)
+ *   - "megapixel":  usage.megapixels → reference image MP (assumed)
+ *   - "image"/"call": usage.outputs → outputCount → legacy units → 1 (assumed)
+ */
+declare function billableUnits(unit: MediaUnit, ctx: BillableContext): {
+    value: number;
+    assumed: boolean;
+};
+/** Price a settled generation on `pricing`, from its actual usage (cents). */
+declare function priceCents(pricing: MediaPricing, ctx: BillableContext): number;
 interface RankedRoute extends MediaRoute {
     /** Normalized cost (cents per reference output) used for ordering. */
     refCents: number;
@@ -398,11 +474,31 @@ interface MediaOutput {
     url: string;
     type: MediaModality;
 }
+/**
+ * Actual measured usage for one settled generation — the typed billing
+ * quantities. Adapters report whichever dimensions they can observe:
+ *   - `seconds`:    video length actually produced (per-second pricing bills this)
+ *   - `outputs`:    output count — images or clips (per-image / per-call pricing)
+ *   - `megapixels`: total output megapixels (per-megapixel pricing)
+ * Dimensions are EXPLICITLY named so a seconds value can never be mistaken for
+ * an output count (the bug class the old bare `units` number invited: a flat
+ * per-call price × 8 "units" of an 8-second clip = an 8× overcharge).
+ */
+interface MediaUsage {
+    seconds?: number;
+    outputs?: number;
+    megapixels?: number;
+}
 interface MediaGenerateResult {
     outputs: MediaOutput[];
     /** Provider-reported actual cost in cents, when the API returns it. */
     costCents?: number;
-    /** Units actually billed (images, or seconds of video) — for cost fallback. */
+    /** Typed actual usage (seconds / outputs / megapixels) — drives cost estimation. */
+    usage?: MediaUsage;
+    /**
+     * @deprecated Legacy bare count, meaning OUTPUT COUNT only (never seconds).
+     * Prefer `usage: { outputs }`. Still honored for backward compatibility.
+     */
     units?: number;
 }
 interface MediaSubmitRequest {
@@ -429,7 +525,12 @@ interface MediaStatusResult {
     outputs?: MediaOutput[];
     /** Provider-reported actual cost in cents, when the API returns it (`done`). */
     costCents?: number;
-    /** Units billed (e.g. seconds of video) — cost fallback when `costCents` is absent. */
+    /** Typed actual usage (seconds / outputs / megapixels) — drives cost estimation. */
+    usage?: MediaUsage;
+    /**
+     * @deprecated Legacy bare count, meaning OUTPUT COUNT only (never seconds).
+     * Prefer `usage: { outputs }` (or `usage: { seconds }` for per-second SKUs).
+     */
     units?: number;
     /** Human-readable reason on `error`. */
     error?: string;
@@ -486,6 +587,8 @@ interface MediaRunResult {
     provider: string;
     costCents: number;
     estimated: boolean;
+    /** Actual usage behind `costCents` (seconds / outputs / megapixels), when known. */
+    usage?: MediaUsage;
 }
 interface MediaSubmitOptions {
     /** Opaque caller metadata forwarded to the provider's `submit`. */
@@ -514,8 +617,24 @@ interface MediaJobHandle {
     externalId: string;
     /** Provider-native job id from `submit`. */
     requestId: string;
-    /** Normalized cost (cents/ref output) of the serving route — used to estimate cost. */
+    /** Normalized cost (cents/ref output) of the serving route — ranking metadata. */
     refCents: number;
+    /**
+     * The serving route's pricing — settle-time billing prices ACTUAL usage on
+     * this (`priceCents`), not the reference estimate. Optional only so handles
+     * serialized by pre-0.6 versions still poll; those fall back to `refCents`.
+     */
+    pricing?: MediaPricing;
+    /**
+     * Savings baseline carried across processes: the official first-party price
+     * when known, else the priciest configured route. Priced against the SAME
+     * actual usage as the cost at settle time. Absent on pre-0.6 handles (those
+     * settle with the submit-time `baselineUsd` estimate below).
+     */
+    baseline?: {
+        pricing: MediaPricing;
+        kind: "official" | "priciest-route";
+    };
     /** Not-yet-tried routes, cheapest-first, for poll-time re-submit failover. */
     fallbacks: {
         provider: string;
@@ -551,6 +670,8 @@ type MediaPollResult = {
     provider: string;
     costCents: number;
     estimated: boolean;
+    /** Actual usage behind `costCents` (seconds / outputs / megapixels), when known. */
+    usage?: MediaUsage;
 };
 /**
  * The router returned by {@link createMediaLCR}: a callable (the sync `run`
@@ -791,4 +912,4 @@ type LCRRouter = (modelName: string) => LanguageModelV3;
  */
 declare function createLCR(config: LCRConfig): LCRRouter;
 
-export { type CallRecord, type CostEvent, DEFAULT_REFERENCE, type ErrorKind, type FormatOptions, type HttpSinkOptions, type LCRConfig, type LCRRouter, MEDIA_PRICING, type MediaAdapter, type MediaCostEvent, type MediaGenerateRequest, type MediaGenerateResult, type MediaJobHandle, type MediaJobStatus, type MediaLCR, type MediaLCRConfig, type MediaModality, type MediaModelDef, type MediaOutput, type MediaPollResult, type MediaPricing, type MediaRegistry, type MediaRoute, type MediaRunResult, type MediaStatusRequest, type MediaStatusResult, type MediaSubmitOptions, type MediaSubmitRequest, type MediaSubmitResult, type MediaUnit, OFFICIAL_PRICES, type PriceComparisonRow, type ProviderCost, type ProviderEntry, type RankedRoute, type ReferenceSpec, type RouteAttempt, cheapestRoute, classifyError, classifyErrorKind, comparePrices, createFalMediaAdapter, createHttpSink, createKunavoMediaAdapter, createLCR, createMediaLCR, createRunwareMediaAdapter, formatCallRecord, isAbortError, isNetworkError, isRetryableError, normalizedCents, rankRoutes, referenceMegapixels, shouldFailover };
+export { type BillableContext, type CallRecord, type CostEvent, DEFAULT_REFERENCE, type ErrorKind, type FormatOptions, type HttpSinkOptions, type LCRConfig, type LCRRouter, MEDIA_PRICING, type MediaAdapter, type MediaCostEvent, type MediaGenerateRequest, type MediaGenerateResult, type MediaJobHandle, type MediaJobStatus, type MediaLCR, type MediaLCRConfig, type MediaModality, type MediaModelDef, type MediaOutput, type MediaPollResult, type MediaPricing, type MediaRegistry, type MediaRoute, type MediaRunResult, type MediaStatusRequest, type MediaStatusResult, type MediaSubmitOptions, type MediaSubmitRequest, type MediaSubmitResult, type MediaUnit, type MediaUsage, OFFICIAL_PRICES, type PriceComparisonRow, type ProviderCost, type ProviderEntry, type RankedRoute, type ReferenceSpec, type RouteAttempt, billableUnits, cheapestRoute, classifyError, classifyErrorKind, comparePrices, createFalMediaAdapter, createHttpSink, createKunavoMediaAdapter, createLCR, createMediaLCR, createRunwareMediaAdapter, durationFromInput, formatCallRecord, isAbortError, isNetworkError, isRetryableError, normalizedCents, priceCents, rankRoutes, referenceMegapixels, shouldFailover };

package/dist/index.d.ts

@@ -127,6 +127,47 @@ interface CallRecord {
      * when no provider was priced.
      */
     baselineUsd?: number;
+    /**
+     * How `baselineUsd` was derived, so a dashboard can qualify the savings
+     * number instead of treating every baseline as equally authoritative:
+     *   - "last-leg":        text router — the always-on fallback leg's list price.
+     *   - "official":        media router — the model maker's first-party price.
+     *   - "priciest-route":  media router with no official price — the most
+     *                        expensive configured route (self-referential; honest
+     *                        about cross-provider spread, but not a market price).
+     * Undefined when `baselineUsd` is undefined.
+     */
+    baselineKind?: "last-leg" | "official" | "priciest-route";
+    /**
+     * Media only: "image" | "video". Lets the dashboard split media traffic from
+     * token-billed text (whose records leave this unset) without inferring from
+     * zero token counts.
+     */
+    modality?: "image" | "video";
+    /**
+     * Media only: the actual billable quantity behind `costUsd` — seconds of
+     * video, output count, or megapixels — so per-unit economics ($/second,
+     * $/image) are derivable downstream. Absent when nothing was measured.
+     */
+    usage?: {
+        seconds?: number;
+        outputs?: number;
+        megapixels?: number;
+    };
+    /**
+     * Media only: the model maker's official first-party price for THIS call's
+     * usage (USD). Present only when an official price is known; equals
+     * `baselineUsd` when `baselineKind` is "official".
+     */
+    officialUsd?: number;
+    /**
+     * What the configured price table PREDICTED this call would cost (USD), on
+     * the same usage. When the provider reports an actual cost, `costUsd −
+     * estCostUsd` is the price-table drift — the signal that a registry price is
+     * stale or mis-entered. When no provider cost is reported the two are equal
+     * (the estimate IS the cost), so drift is only meaningful on reported rows.
+     */
+    estCostUsd?: number;
     /**
      * The slice of `costUsd` that prompt-cache reads saved versus paying the full
      * input rate for those same tokens (`cachedTokens × (input − cacheRead)`).
@@ -366,6 +407,41 @@ declare function referenceMegapixels(ref: ReferenceSpec): number;
  * This is the single normalization that makes providers comparable.
  */
 declare function normalizedCents(pricing: MediaPricing, ref?: ReferenceSpec): number;
+/**
+ * Parse a duration in seconds out of a canonical media input. Accepts a number
+ * or a numeric-ish string (Veo-style `"8s"`, `"8"`). Returns undefined when the
+ * input carries no usable duration.
+ */
+declare function durationFromInput(input: Record<string, unknown> | undefined): number | undefined;
+/** What `billableUnits` can draw on to resolve the actual billed quantity. */
+interface BillableContext {
+    /** Typed usage the adapter measured on the settled result. Highest priority. */
+    usage?: MediaUsage;
+    /** Legacy bare count from older adapters — OUTPUT COUNT only. */
+    units?: number;
+    /** Settled output count (`outputs.length`), when available. */
+    outputCount?: number;
+    /** The canonical request input — `duration` is read for per-second pricing. */
+    input?: Record<string, unknown>;
+    /** Reference spec, the last-resort assumption when nothing was measured. */
+    reference?: ReferenceSpec;
+}
+/**
+ * Resolve the actual billable quantity for a pricing unit, with provenance:
+ * `assumed: true` means nothing was measured and the reference spec filled in
+ * (so the resulting cost is a guess of last resort, not a measurement).
+ *
+ * Resolution order per unit:
+ *   - "second":     usage.seconds → input.duration → reference.videoSeconds (assumed)
+ *   - "megapixel":  usage.megapixels → reference image MP (assumed)
+ *   - "image"/"call": usage.outputs → outputCount → legacy units → 1 (assumed)
+ */
+declare function billableUnits(unit: MediaUnit, ctx: BillableContext): {
+    value: number;
+    assumed: boolean;
+};
+/** Price a settled generation on `pricing`, from its actual usage (cents). */
+declare function priceCents(pricing: MediaPricing, ctx: BillableContext): number;
 interface RankedRoute extends MediaRoute {
     /** Normalized cost (cents per reference output) used for ordering. */
     refCents: number;
@@ -398,11 +474,31 @@ interface MediaOutput {
     url: string;
     type: MediaModality;
 }
+/**
+ * Actual measured usage for one settled generation — the typed billing
+ * quantities. Adapters report whichever dimensions they can observe:
+ *   - `seconds`:    video length actually produced (per-second pricing bills this)
+ *   - `outputs`:    output count — images or clips (per-image / per-call pricing)
+ *   - `megapixels`: total output megapixels (per-megapixel pricing)
+ * Dimensions are EXPLICITLY named so a seconds value can never be mistaken for
+ * an output count (the bug class the old bare `units` number invited: a flat
+ * per-call price × 8 "units" of an 8-second clip = an 8× overcharge).
+ */
+interface MediaUsage {
+    seconds?: number;
+    outputs?: number;
+    megapixels?: number;
+}
 interface MediaGenerateResult {
     outputs: MediaOutput[];
     /** Provider-reported actual cost in cents, when the API returns it. */
     costCents?: number;
-    /** Units actually billed (images, or seconds of video) — for cost fallback. */
+    /** Typed actual usage (seconds / outputs / megapixels) — drives cost estimation. */
+    usage?: MediaUsage;
+    /**
+     * @deprecated Legacy bare count, meaning OUTPUT COUNT only (never seconds).
+     * Prefer `usage: { outputs }`. Still honored for backward compatibility.
+     */
     units?: number;
 }
 interface MediaSubmitRequest {
@@ -429,7 +525,12 @@ interface MediaStatusResult {
     outputs?: MediaOutput[];
     /** Provider-reported actual cost in cents, when the API returns it (`done`). */
     costCents?: number;
-    /** Units billed (e.g. seconds of video) — cost fallback when `costCents` is absent. */
+    /** Typed actual usage (seconds / outputs / megapixels) — drives cost estimation. */
+    usage?: MediaUsage;
+    /**
+     * @deprecated Legacy bare count, meaning OUTPUT COUNT only (never seconds).
+     * Prefer `usage: { outputs }` (or `usage: { seconds }` for per-second SKUs).
+     */
     units?: number;
     /** Human-readable reason on `error`. */
     error?: string;
@@ -486,6 +587,8 @@ interface MediaRunResult {
     provider: string;
     costCents: number;
     estimated: boolean;
+    /** Actual usage behind `costCents` (seconds / outputs / megapixels), when known. */
+    usage?: MediaUsage;
 }
 interface MediaSubmitOptions {
     /** Opaque caller metadata forwarded to the provider's `submit`. */
@@ -514,8 +617,24 @@ interface MediaJobHandle {
     externalId: string;
     /** Provider-native job id from `submit`. */
     requestId: string;
-    /** Normalized cost (cents/ref output) of the serving route — used to estimate cost. */
+    /** Normalized cost (cents/ref output) of the serving route — ranking metadata. */
     refCents: number;
+    /**
+     * The serving route's pricing — settle-time billing prices ACTUAL usage on
+     * this (`priceCents`), not the reference estimate. Optional only so handles
+     * serialized by pre-0.6 versions still poll; those fall back to `refCents`.
+     */
+    pricing?: MediaPricing;
+    /**
+     * Savings baseline carried across processes: the official first-party price
+     * when known, else the priciest configured route. Priced against the SAME
+     * actual usage as the cost at settle time. Absent on pre-0.6 handles (those
+     * settle with the submit-time `baselineUsd` estimate below).
+     */
+    baseline?: {
+        pricing: MediaPricing;
+        kind: "official" | "priciest-route";
+    };
     /** Not-yet-tried routes, cheapest-first, for poll-time re-submit failover. */
     fallbacks: {
         provider: string;
@@ -551,6 +670,8 @@ type MediaPollResult = {
     provider: string;
     costCents: number;
     estimated: boolean;
+    /** Actual usage behind `costCents` (seconds / outputs / megapixels), when known. */
+    usage?: MediaUsage;
 };
 /**
  * The router returned by {@link createMediaLCR}: a callable (the sync `run`
@@ -791,4 +912,4 @@ type LCRRouter = (modelName: string) => LanguageModelV3;
  */
 declare function createLCR(config: LCRConfig): LCRRouter;
 
-export { type CallRecord, type CostEvent, DEFAULT_REFERENCE, type ErrorKind, type FormatOptions, type HttpSinkOptions, type LCRConfig, type LCRRouter, MEDIA_PRICING, type MediaAdapter, type MediaCostEvent, type MediaGenerateRequest, type MediaGenerateResult, type MediaJobHandle, type MediaJobStatus, type MediaLCR, type MediaLCRConfig, type MediaModality, type MediaModelDef, type MediaOutput, type MediaPollResult, type MediaPricing, type MediaRegistry, type MediaRoute, type MediaRunResult, type MediaStatusRequest, type MediaStatusResult, type MediaSubmitOptions, type MediaSubmitRequest, type MediaSubmitResult, type MediaUnit, OFFICIAL_PRICES, type PriceComparisonRow, type ProviderCost, type ProviderEntry, type RankedRoute, type ReferenceSpec, type RouteAttempt, cheapestRoute, classifyError, classifyErrorKind, comparePrices, createFalMediaAdapter, createHttpSink, createKunavoMediaAdapter, createLCR, createMediaLCR, createRunwareMediaAdapter, formatCallRecord, isAbortError, isNetworkError, isRetryableError, normalizedCents, rankRoutes, referenceMegapixels, shouldFailover };
+export { type BillableContext, type CallRecord, type CostEvent, DEFAULT_REFERENCE, type ErrorKind, type FormatOptions, type HttpSinkOptions, type LCRConfig, type LCRRouter, MEDIA_PRICING, type MediaAdapter, type MediaCostEvent, type MediaGenerateRequest, type MediaGenerateResult, type MediaJobHandle, type MediaJobStatus, type MediaLCR, type MediaLCRConfig, type MediaModality, type MediaModelDef, type MediaOutput, type MediaPollResult, type MediaPricing, type MediaRegistry, type MediaRoute, type MediaRunResult, type MediaStatusRequest, type MediaStatusResult, type MediaSubmitOptions, type MediaSubmitRequest, type MediaSubmitResult, type MediaUnit, type MediaUsage, OFFICIAL_PRICES, type PriceComparisonRow, type ProviderCost, type ProviderEntry, type RankedRoute, type ReferenceSpec, type RouteAttempt, billableUnits, cheapestRoute, classifyError, classifyErrorKind, comparePrices, createFalMediaAdapter, createHttpSink, createKunavoMediaAdapter, createLCR, createMediaLCR, createRunwareMediaAdapter, durationFromInput, formatCallRecord, isAbortError, isNetworkError, isRetryableError, normalizedCents, priceCents, rankRoutes, referenceMegapixels, shouldFailover };

package/dist/index.js

@@ -318,6 +318,7 @@ var LcrFallbackModel = class {
     const cachedSavingUsd = provider.cost ? cacheSavingForUsage(provider.cost, inputTokens, cacheReadTokens) : 0;
     const usageMissing = inputTokens === 0 && outputTokens === 0;
     const emptyCompletion = inputTokens > 0 && outputTokens === 0;
+    const baselineUsd = this.baselineUsd(inputTokens, outputTokens, cacheReadTokens);
     this.emitCost({
       model: this.opts.modelName,
       provider: provider.label,
@@ -338,7 +339,7 @@ var LcrFallbackModel = class {
       outputTokens,
       ...cacheReadTokens > 0 ? { cachedInputTokens: cacheReadTokens } : {},
       costUsd,
-      baselineUsd: this.baselineUsd(inputTokens, outputTokens, cacheReadTokens),
+      ...baselineUsd !== void 0 ? { baselineUsd, baselineKind: "last-leg" } : {},
       ...cachedSavingUsd > 0 ? { cachedSavingUsd } : {},
       ...ctx.requestId ? { requestId: ctx.requestId } : {},
       ...usageMissing ? { usageMissing: true } : {},
@@ -669,6 +670,40 @@ function normalizedCents(pricing, ref = DEFAULT_REFERENCE) {
       return pricing.cents * ref.videoSeconds;
   }
 }
+function durationFromInput(input) {
+  const raw = input?.["duration"];
+  if (typeof raw === "number" && Number.isFinite(raw) && raw > 0) return raw;
+  if (typeof raw === "string") {
+    const m = /^(\d+(?:\.\d+)?)\s*s?$/i.exec(raw.trim());
+    if (m) {
+      const n = Number(m[1]);
+      if (Number.isFinite(n) && n > 0) return n;
+    }
+  }
+  return void 0;
+}
+function billableUnits(unit, ctx) {
+  const ref = ctx.reference ?? DEFAULT_REFERENCE;
+  const positive = (n) => typeof n === "number" && Number.isFinite(n) && n > 0 ? n : void 0;
+  switch (unit) {
+    case "second": {
+      const measured = positive(ctx.usage?.seconds) ?? durationFromInput(ctx.input);
+      return measured !== void 0 ? { value: measured, assumed: false } : { value: ref.videoSeconds, assumed: true };
+    }
+    case "megapixel": {
+      const measured = positive(ctx.usage?.megapixels);
+      return measured !== void 0 ? { value: measured, assumed: false } : { value: referenceMegapixels(ref), assumed: true };
+    }
+    case "image":
+    case "call": {
+      const measured = positive(ctx.usage?.outputs) ?? positive(ctx.outputCount) ?? positive(ctx.units);
+      return measured !== void 0 ? { value: measured, assumed: false } : { value: 1, assumed: true };
+    }
+  }
+}
+function priceCents(pricing, ctx) {
+  return pricing.cents * billableUnits(pricing.unit, ctx).value;
+}
 function rankRoutes(def, ref = DEFAULT_REFERENCE) {
   return def.routes.map((r) => ({ ...r, refCents: normalizedCents(r.pricing, ref) })).sort((a, b) => a.refCents - b.refCents);
 }
@@ -734,38 +769,91 @@ function createMediaLCR(config) {
     }
     const ranked = rankRoutes(def, reference);
     const official = def.official ?? officialPrices[modelId];
-    const baselineUsd = official !== void 0 ? normalizedCents(official, reference) / 100 : ranked.length > 0 ? Math.max(...ranked.map((r) => r.refCents)) / 100 : 0;
-    return { ranked, baselineUsd };
+    const baseline = official !== void 0 ? { pricing: official, kind: "official" } : ranked.length > 0 ? { pricing: ranked[ranked.length - 1].pricing, kind: "priciest-route" } : void 0;
+    return { def, ranked, baseline };
   }
-  const costFor = (refCents, result) => result.costCents === void 0 ? refCents * (result.units ?? 1) : result.costCents;
-  const emitFail = (modelId, attempts, baselineUsd, startedAt) => safeCall({
-    id: newMediaCallId(),
-    model: modelId,
-    attempts,
-    winner: void 0,
-    ok: false,
-    failedOver: attempts.length > 1,
-    latencyMs: Date.now() - startedAt,
-    inputTokens: 0,
-    outputTokens: 0,
-    costUsd: 0,
-    baselineUsd
-  });
-  const emitOk = (modelId, provider, attempts, costCents, baselineUsd, startedAt) => safeCall({
-    id: newMediaCallId(),
-    model: modelId,
-    attempts,
-    winner: provider,
-    ok: true,
-    failedOver: attempts.length > 1,
-    latencyMs: Date.now() - startedAt,
-    inputTokens: 0,
-    outputTokens: 0,
-    costUsd: costCents / 100,
-    baselineUsd
-  });
+  const refBaselineUsd = (baseline) => baseline ? normalizedCents(baseline.pricing, reference) / 100 : 0;
+  function settle(pricing, refCents, result, input) {
+    const ctx = {
+      ...result.usage ? { usage: result.usage } : {},
+      ...result.units !== void 0 ? { units: result.units } : {},
+      ...result.outputs ? { outputCount: result.outputs.length } : {},
+      ...input ? { input } : {},
+      reference
+    };
+    const estCents = pricing ? priceCents(pricing, ctx) : refCents * billableUnits("call", ctx).value;
+    const estimated = result.costCents === void 0;
+    const costCents = result.costCents ?? estCents;
+    const usage = { ...result.usage ?? {} };
+    if (usage.outputs === void 0 && (result.outputs?.length ?? 0) > 0) {
+      usage.outputs = result.outputs.length;
+    }
+    if (usage.seconds === void 0 && pricing?.unit === "second") {
+      const s = billableUnits("second", ctx);
+      if (!s.assumed) usage.seconds = s.value;
+    }
+    return {
+      costCents,
+      estCents,
+      estimated,
+      ...Object.keys(usage).length > 0 ? { usage } : {},
+      ctx
+    };
+  }
+  const DRIFT_RATIO = 25;
+  const warnDrift = (modelId, provider, s) => {
+    if (s.estimated || s.estCents <= 0 || s.costCents <= 0) return;
+    const ratio = s.costCents / s.estCents;
+    if (ratio >= DRIFT_RATIO || ratio <= 1 / DRIFT_RATIO) {
+      safeError(
+        new Error(
+          `ai-lcr: ${provider} reported ${s.costCents}\xA2 for "${modelId}" but the price table predicts ${s.estCents}\xA2 (${ratio.toFixed(1)}\xD7) \u2014 check the route's pricing units (USD vs cents) or refresh the registry price`
+        ),
+        provider
+      );
+    }
+  };
+  const emitFail = (modelId, attempts, baselineUsd, startedAt) => {
+    const modality = registry[modelId]?.modality;
+    safeCall({
+      id: newMediaCallId(),
+      model: modelId,
+      attempts,
+      winner: void 0,
+      ok: false,
+      failedOver: attempts.length > 1,
+      latencyMs: Date.now() - startedAt,
+      inputTokens: 0,
+      outputTokens: 0,
+      costUsd: 0,
+      baselineUsd,
+      ...modality ? { modality } : {}
+    });
+  };
+  const emitOk = (args) => {
+    const { settled, baseline } = args;
+    const baselineUsd = baseline ? priceCents(baseline.pricing, settled.ctx) / 100 : args.legacyBaselineUsd ?? 0;
+    safeCall({
+      id: newMediaCallId(),
+      model: args.modelId,
+      attempts: args.attempts,
+      winner: args.provider,
+      ok: true,
+      failedOver: args.attempts.length > 1,
+      latencyMs: Date.now() - args.startedAt,
+      inputTokens: 0,
+      outputTokens: 0,
+      costUsd: settled.costCents / 100,
+      baselineUsd,
+      ...baseline ? { baselineKind: baseline.kind } : {},
+      ...baseline?.kind === "official" ? { officialUsd: baselineUsd } : {},
+      modality: args.modality,
+      ...settled.usage ? { usage: settled.usage } : {},
+      estCostUsd: settled.estCents / 100
+    });
+  };
   const generate = async function generate2(modelId, input) {
-    const { ranked, baselineUsd } = resolve(modelId);
+    const { def, ranked, baseline } = resolve(modelId);
     const startedAt = Date.now();
     const attempts = [];
     let lastErr;
@@ -775,12 +863,31 @@ function createMediaLCR(config) {
       const attemptStart = Date.now();
       try {
         const result = await adapter.run({ externalId: route.externalId, input });
-        const estimated = result.costCents === void 0;
-        const costCents = costFor(route.refCents, result);
+        const settled = settle(route.pricing, route.refCents, result, input);
         attempts.push({ provider: route.provider, ok: true, latencyMs: Date.now() - attemptStart });
-        safeCost({ modelId, provider: route.provider, costCents, estimated });
-        emitOk(modelId, route.provider, attempts, costCents, baselineUsd, startedAt);
-        return { outputs: result.outputs, provider: route.provider, costCents, estimated };
+        warnDrift(modelId, route.provider, settled);
+        safeCost({
+          modelId,
+          provider: route.provider,
+          costCents: settled.costCents,
+          estimated: settled.estimated
+        });
+        emitOk({
+          modelId,
+          modality: def.modality,
+          provider: route.provider,
+          attempts,
+          settled,
+          baseline,
+          startedAt
+        });
+        return {
+          outputs: result.outputs,
+          provider: route.provider,
+          costCents: settled.costCents,
+          estimated: settled.estimated,
+          ...settled.usage ? { usage: settled.usage } : {}
+        };
       } catch (err) {
         lastErr = err;
         attempts.push({
@@ -791,19 +898,19 @@ function createMediaLCR(config) {
         });
         safeError(err, route.provider);
         if (!isRetryableError(err)) {
-          emitFail(modelId, attempts, baselineUsd, startedAt);
+          emitFail(modelId, attempts, refBaselineUsd(baseline), startedAt);
           throw err;
         }
       }
     }
-    emitFail(modelId, attempts, baselineUsd, startedAt);
+    emitFail(modelId, attempts, refBaselineUsd(baseline), startedAt);
     throw lastErr instanceof Error ? lastErr : new Error(`ai-lcr: no provider could serve media model "${modelId}"`);
   };
   const asyncRanked = (modelId) => {
     const { ranked } = resolve(modelId);
     return ranked.filter((r) => typeof adapters[r.provider]?.submit === "function");
   };
-  async function submitFrom(modelId, routes, input, metadata, baselineUsd, startedAt, attempts) {
+  async function submitFrom(modelId, routes, input, metadata, baseline, startedAt, attempts) {
     let lastErr;
     for (let i = 0; i < routes.length; i++) {
       const route = routes[i];
@@ -818,10 +925,12 @@ function createMediaLCR(config) {
           externalId: route.externalId,
           requestId,
           refCents: route.refCents,
+          pricing: route.pricing,
+          ...baseline ? { baseline } : {},
           fallbacks: routes.slice(i + 1).map((r) => ({ provider: r.provider, externalId: r.externalId, refCents: r.refCents })),
           input,
           ...metadata ? { metadata } : {},
-          baselineUsd,
+          baselineUsd: refBaselineUsd(baseline),
           startedAt,
           attemptStart,
           attempts
@@ -838,18 +947,18 @@ function createMediaLCR(config) {
         if (!isRetryableError(err)) break;
       }
     }
-    emitFail(modelId, attempts, baselineUsd, startedAt);
+    emitFail(modelId, attempts, refBaselineUsd(baseline), startedAt);
     throw lastErr instanceof Error ? lastErr : new Error(`ai-lcr: no async provider could submit media model "${modelId}"`);
   }
   generate.submit = async function submit(modelId, input, options) {
-    const { ranked, baselineUsd } = resolve(modelId);
+    const { ranked, baseline } = resolve(modelId);
     const usable = ranked.filter((r) => typeof adapters[r.provider]?.submit === "function");
     if (usable.length === 0) {
       throw new Error(
         `ai-lcr: no provider for media model "${modelId}" supports async submit (need an adapter with submit/checkStatus)`
       );
     }
-    return submitFrom(modelId, usable, input, options?.metadata, baselineUsd, Date.now(), []);
+    return submitFrom(modelId, usable, input, options?.metadata, baseline, Date.now(), []);
   };
   generate.poll = async function poll(handle) {
     const adapter = adapters[handle.provider];
@@ -859,6 +968,7 @@ function createMediaLCR(config) {
       );
     }
     const failover = async (attempts) => {
+      const { baseline } = resolve(handle.modelId);
       const next = asyncRanked(handle.modelId).filter(
         (r) => handle.fallbacks.some((f) => f.provider === r.provider && f.externalId === r.externalId)
       );
@@ -867,7 +977,7 @@ function createMediaLCR(config) {
         next,
         handle.input,
         handle.metadata,
-        handle.baselineUsd,
+        handle.baseline ?? baseline,
         handle.startedAt,
         attempts
       );
@@ -907,15 +1017,37 @@ function createMediaLCR(config) {
           true
         );
       }
-      const estimated = status.costCents === void 0;
-      const costCents = costFor(handle.refCents, status);
+      const settled = settle(handle.pricing, handle.refCents, { ...status, outputs }, handle.input);
       const attempts = [
         ...handle.attempts,
         { provider: handle.provider, ok: true, latencyMs: Date.now() - handle.attemptStart }
       ];
-      safeCost({ modelId: handle.modelId, provider: handle.provider, costCents, estimated });
-      emitOk(handle.modelId, handle.provider, attempts, costCents, handle.baselineUsd, handle.startedAt);
-      return { done: true, status: "done", outputs, provider: handle.provider, costCents, estimated };
+      warnDrift(handle.modelId, handle.provider, settled);
+      safeCost({
+        modelId: handle.modelId,
+        provider: handle.provider,
+        costCents: settled.costCents,
+        estimated: settled.estimated
+      });
+      emitOk({
+        modelId: handle.modelId,
+        modality: registry[handle.modelId]?.modality ?? outputs[0].type,
+        provider: handle.provider,
+        attempts,
+        settled,
+        baseline: handle.baseline,
+        legacyBaselineUsd: handle.baselineUsd,
+        startedAt: handle.startedAt
+      });
+      return {
+        done: true,
+        status: "done",
+        outputs,
+        provider: handle.provider,
+        costCents: settled.costCents,
+        estimated: settled.estimated,
+        ...settled.usage ? { usage: settled.usage } : {}
+      };
     }
     return onLegFailure(new Error(status.error ?? `ai-lcr: ${handle.provider} job failed`), true);
   };
@@ -1106,9 +1238,12 @@ function createKunavoMediaAdapter(config) {
       if (urls.length === 0) {
         return { status: "error", error: `Kunavo video job ${req.requestId} completed with no URL` };
       }
+      const durationSeconds = body.output?.duration_seconds;
+      const seconds = typeof durationSeconds === "number" && Number.isFinite(durationSeconds) && durationSeconds > 0 ? durationSeconds : void 0;
       return {
         status: "done",
-        outputs: urls.map((url) => ({ url, type: "video" }))
+        outputs: urls.map((url) => ({ url, type: "video" })),
+        usage: { outputs: urls.length, ...seconds !== void 0 ? { seconds } : {} }
       };
     }
     if (status === "failed" || status === "error") {
@@ -1266,6 +1401,7 @@ function createRunwareMediaAdapter(config) {
       return {
         outputs,
         units: images.length,
+        usage: { outputs: images.length },
         ...cents !== void 0 ? { costCents: cents } : {}
       };
     },
@@ -1296,6 +1432,7 @@ function createRunwareMediaAdapter(config) {
         return {
           status: "done",
           outputs: [{ url, type: "video" }],
+          usage: { outputs: 1 },
           ...cents !== void 0 ? { costCents: cents } : {}
         };
       }
@@ -1387,7 +1524,7 @@ function createFalMediaAdapter(config) {
     if (outputs.length === 0) {
       return { status: "error", error: `fal job ${req.requestId} completed with no media URL` };
     }
-    return { status: "done", outputs, units: outputs.length };
+    return { status: "done", outputs, units: outputs.length, usage: { outputs: outputs.length } };
   }
   return {
     provider: "fal",
@@ -1439,7 +1576,7 @@ function createFalMediaAdapter(config) {
       if (outputs.length === 0) {
         throw new Error(`ai-lcr: fal returned no media URL for "${req.externalId}"`);
       }
-      return { outputs, units: outputs.length };
+      return { outputs, units: outputs.length, usage: { outputs: outputs.length } };
     }
   };
 }
@@ -1524,6 +1661,7 @@ export {
   DEFAULT_REFERENCE,
   MEDIA_PRICING,
   OFFICIAL_PRICES,
+  billableUnits,
   cheapestRoute,
   classifyError,
   classifyErrorKind,
@@ -1534,11 +1672,13 @@ export {
   createLCR,
   createMediaLCR,
   createRunwareMediaAdapter,
+  durationFromInput,
   formatCallRecord,
   isAbortError,
   isNetworkError,
   isRetryableError,
   normalizedCents,
+  priceCents,
   rankRoutes,
   referenceMegapixels,
   shouldFailover

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-lcr",
-  "version": "0.5.6",
+  "version": "0.6.0",
   "description": "Least Cost Routing for LLMs — route every model call to the cheapest available provider, fall back automatically, and track real cost. Built for the Vercel AI SDK.",
   "keywords": [
     "ai",
@@ -19,11 +19,11 @@
   "author": "Victor",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/victorzhrn/ai-lcr.git"
+    "url": "git+https://github.com/ai-lcr/ai-lcr.git"
   },
-  "homepage": "https://github.com/victorzhrn/ai-lcr#readme",
+  "homepage": "https://github.com/ai-lcr/ai-lcr#readme",
   "bugs": {
-    "url": "https://github.com/victorzhrn/ai-lcr/issues"
+    "url": "https://github.com/ai-lcr/ai-lcr/issues"
   },
   "type": "module",
   "main": "./dist/index.cjs",