metergraph-cli 0.2.1 → 0.2.3

package/src/pricing-args.js

@@ -0,0 +1,163 @@
+import { DEFAULT_ORIGIN } from "./constants.js";
+import { parseOrigin } from "./origin.js";
+export const PRICING_ACTIONS = ["models", "lookup", "calculate", "cost", "history", "market"];
+const SELECTORS = ["model", "provider", "channel", "region"];
+export const TOKEN_KEYS = [
+  "input_tokens",
+  "output_tokens",
+  "cache_read_tokens",
+  "cache_write_tokens",
+  "cache_write_5m_tokens",
+  "cache_write_1h_tokens",
+];
+export const PRICING_OPTIONS = [
+  "--url",
+  "--api",
+  "--trace-format",
+  "--timeout-ms",
+  "--format",
+  "--at",
+  "--limit",
+  ...SELECTORS.map((k) => `--${k}`),
+  ...TOKEN_KEYS.map((k) => `--${k.replaceAll("_", "-")}`),
+];
+export function validDate(v) {
+  return (
+    typeof v === "string" &&
+    !v.startsWith("0000-") &&
+    /^\d{4}-\d{2}-\d{2}$/.test(v) &&
+    Number.isFinite(Date.parse(v)) &&
+    new Date(v).toISOString().slice(0, 10) === v
+  );
+}
+export function parsePricing(action, values, flags, json, fail) {
+  if (!action)
+    return fail("missing_subcommand", "pricing requires models, lookup, calculate, cost, history or market.");
+  const origin = parseOrigin(values["--url"] ?? DEFAULT_ORIGIN);
+  if (!origin) return fail("invalid_url", "--url requires a bare HTTPS origin, or HTTP on loopback.");
+  const api = values["--api"] ?? "public";
+  if (!["public", "reference"].includes(api)) return fail("invalid_pricing_api", "--api must be public or reference.");
+  if (api === "reference" && !["127.0.0.1", "localhost", "[::1]"].includes(new URL(origin).hostname))
+    return fail(
+      "reference_requires_loopback",
+      "The reference pricing API is local development tooling; use a loopback --url.",
+    );
+  const cost = action === "cost" || action === "calculate";
+  if (api === "reference" && ["models", "calculate"].includes(action))
+    return fail(
+      "reference_action_unsupported",
+      "The reference adapter supports lookup, cost, history and market.",
+      "unsupported",
+    );
+  const format = values["--format"] ?? (action === "history" ? "chart" : "table");
+  if (
+    !["table", "chart", "html"].includes(format) ||
+    (format !== "table" && action !== "history") ||
+    (json && values["--format"] !== undefined)
+  ) {
+    return fail("invalid_format", "Use table, or chart/html for history. --json cannot be combined with --format.");
+  }
+  const query = {};
+  for (const k of SELECTORS) {
+    const v = values[`--${k}`];
+    if (v !== undefined) {
+      if (!/^[a-zA-Z0-9][a-zA-Z0-9._/:+-]{0,199}$/.test(v))
+        return fail("invalid_selector", "Pricing selectors require 1 to 200 identifier characters.");
+      query[k] = k === "model" ? v : v.toLowerCase();
+    }
+  }
+  if (!["market", "models"].includes(action) && !query.model) return fail("missing_model", "--model is required.");
+  if (query.provider && query.channel)
+    return fail("conflicting_selector", "Choose --provider or --channel; channel selects the exact billing route.");
+  if (action === "market" && (query.model || query.provider || !query.channel))
+    return fail(
+      "invalid_market_selector",
+      "market requires --channel and accepts --region; use lookup for a model or provider.",
+    );
+  if (action === "history" && !query.channel)
+    return fail("missing_channel", "history requires --channel to keep one billing route per chart.");
+  if (values["--at"] !== undefined || api === "reference")
+    query.at = values["--at"] ?? new Date().toISOString().slice(0, 10);
+  if (query.at !== undefined && !validDate(query.at))
+    return fail("invalid_date", "--at must be a real UTC date, YYYY-MM-DD.");
+  if (["history", "market"].includes(action)) query.region ??= "global";
+  if (values["--limit"] !== undefined && !["models", "market"].includes(action))
+    return fail("unexpected_limit", "--limit is supported only by models and market.");
+  if (["market", "models"].includes(action)) {
+    const v = values["--limit"] ?? "20";
+    if (!/^[1-9]\d?$|^100$/.test(v)) return fail("invalid_limit", "--limit must be 1 to 100.");
+    query.limit = Number(v);
+  }
+  for (const k of TOKEN_KEYS) {
+    const v = values[`--${k.replaceAll("_", "-")}`];
+    if (v !== undefined) {
+      if (!cost || !/^(0|[1-9]\d{0,11})$/.test(v))
+        return fail(
+          "invalid_usage",
+          "Token counts are supported only by cost and must be whole numbers from 0 to 999999999999.",
+        );
+      query[k] = Number(v);
+    }
+  }
+  if (flags.has("--batch")) {
+    if (!cost) return fail("invalid_usage", "--batch is supported only by cost.");
+    query.batch = true;
+  }
+  if (
+    query.cache_write_tokens !== undefined &&
+    (query.cache_write_5m_tokens !== undefined || query.cache_write_1h_tokens !== undefined)
+  )
+    return fail("conflicting_usage", "Use an aggregate cache-write count or duration-specific counts, not both.");
+  if (action === "models" && query.at !== undefined)
+    return fail(
+      "models_date_unsupported",
+      "models returns current discovery data; --at is not supported.",
+      "unsupported",
+    );
+  const traceFormat =
+    values["--trace-format"] ??
+    (query.provider === "anthropic" || query.channel === "anthropic-api"
+      ? "anthropic.messages"
+      : query.provider === "openai" || query.channel === "openai-api"
+        ? "openai.responses"
+        : "otel.gen_ai");
+  if (values["--trace-format"] !== undefined && (!cost || api !== "public"))
+    return fail("unexpected_trace_format", "--trace-format is supported only by public calculate/cost.");
+  if (!["openai.responses", "openai.chat_completions", "anthropic.messages", "otel.gen_ai"].includes(traceFormat))
+    return fail(
+      "invalid_trace_format",
+      "Use openai.responses, openai.chat_completions, anthropic.messages or otel.gen_ai.",
+    );
+  if (api === "public" && cost) {
+    if (
+      (traceFormat.startsWith("openai.") || query.provider === "openai" || query.channel === "openai-api") &&
+      query.cache_read_tokens !== undefined &&
+      (query.input_tokens === undefined || query.cache_read_tokens > query.input_tokens)
+    )
+      return fail("invalid_cached_input", "OpenAI cached input must not exceed the supplied total input tokens.");
+    if (
+      traceFormat !== "anthropic.messages" &&
+      TOKEN_KEYS.filter((k) => k.startsWith("cache_write")).some((k) => query[k] !== undefined)
+    )
+      return fail(
+        "cache_write_format_unsupported",
+        "Use --trace-format anthropic.messages for cache-write counts; other mappings are not verified.",
+        "unsupported",
+      );
+  }
+  const raw = values["--timeout-ms"] ?? "10000";
+  if (!/^\d+$/.test(raw) || Number(raw) < 100 || Number(raw) > 30000)
+    return fail("invalid_timeout", "--timeout-ms must be 100 to 30000.");
+  return {
+    ok: true,
+    command: "pricing",
+    action,
+    origin,
+    query,
+    format,
+    api,
+    traceFormat,
+    timeoutMs: Number(raw),
+    json,
+  };
+}

package/src/pricing-output.js

@@ -0,0 +1,206 @@
+// All terminal text arrives through the bounded pricing validator. HTML escapes
+// every dynamic label; no scripts, remote fonts, analytics or external assets.
+const money = (v) => (v === null ? "unknown" : Number(v).toLocaleString("en-US", { maximumFractionDigits: 8 }));
+const escape = (s) =>
+  String(s).replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
+function movement(s) {
+  const points = s.points;
+  const now = points.at(-1),
+    before = points.at(-2);
+  if (
+    !before ||
+    Date.parse(before.effective_to) !== Date.parse(now.effective_from) ||
+    before.input_per_mtok === null ||
+    now.input_per_mtok === null ||
+    Number(before.input_per_mtok) === 0
+  )
+    return "n/a";
+  const delta = (Number(now.input_per_mtok) / Number(before.input_per_mtok) - 1) * 100;
+  return `${delta > 0 ? "+" : ""}${delta.toFixed(1)}%`;
+}
+function spark(points) {
+  const nums = points.map((p) => (p.input_per_mtok === null ? null : Number(p.input_per_mtok)));
+  const known = nums.filter((n) => n !== null);
+  const min = Math.min(...known),
+    max = Math.max(...known);
+  return nums
+    .map((n) => (n === null ? "?" : "▁▂▃▄▅▆▇█"[max === min ? 3 : Math.round(((n - min) / (max - min)) * 7)]))
+    .join("");
+}
+function provenance(d) {
+  if (d.api === "public")
+    return d.catalog
+      ? `Catalog ${d.catalog.version} · verified ${d.catalog.pricing_verified_at} · discovery as of ${d.as_of}\n${d.action === "market" ? "Rates were obtained through separate lookups; public history is unavailable." : "Discovery lists supported dimensions, not numeric rates. Use pricing lookup."}\n`
+      : "Public pricing result. The API does not report catalog version or verification time on this response.\nCatalog list rates, not your invoice.\n";
+  return `Catalog ${d.catalog.version} · verified ${d.catalog.pricing_verified_at} · served ${d.catalog.served_at}\nCatalog list rates, not your invoice. Base rates exclude conditional rules; use pricing cost.\n`;
+}
+export function pricingText(e, format, style) {
+  if (!e.ok) return `Pricing unavailable\n${e.error.message}\nReason: ${e.error.reason}\n`;
+  const d = e.data,
+    r = d.result;
+  let lines = [
+    style.bold(`METERGRAPH / PRICING ${d.action.toUpperCase()}`),
+    d.request.at ? `As of ${d.request.at} UTC` : `Effective time: ${r.effective_at ?? d.as_of}`,
+    "",
+  ];
+  if (d.action === "models") {
+    lines.push(
+      `Canonical models: ${r.total_models}; matching: ${r.matched}; showing: ${r.models.length}${r.truncated ? " (raise --limit for more)" : ""}`,
+      `Formats: ${d.formats.join(", ")}`,
+      "",
+      "MODEL                                  PUBLISHER       CHANNELS",
+    );
+    for (const m of r.models)
+      lines.push(
+        `${m.model_id.padEnd(38)} ${m.publisher.padEnd(15)} ${[...new Set(m.prices.map((p) => p.channel))].join(", ")}`,
+      );
+    lines.push("", "Filters are applied locally to current discovery metadata. Numeric rates require pricing lookup.");
+  } else if (d.action === "market" && d.api === "public") {
+    lines.push("MODEL                                  STATUS    CCY      INPUT     OUTPUT");
+    for (const item of r.items) {
+      const p = item.price;
+      lines.push(
+        `${(item.model_id ?? item.requested_model).padEnd(38)} ${item.status.padEnd(9)} ${(item.currency ?? "---").padEnd(3)} ${money(p?.input_per_mtok ?? null).padStart(10)} ${money(p?.output_per_mtok ?? null).padStart(10)}`,
+      );
+      if (item.missing_dimensions.length) lines.push(`  Missing: ${item.missing_dimensions.join(", ")}`);
+      if (p && d.request.region !== p.region)
+        lines.push(`  Requested region: ${d.request.region} · resolved region: ${p.region} (fallback)`);
+    }
+    lines.push(
+      "",
+      `${d.request.channel} / ${d.request.region} · base rates per million tokens`,
+      `Showing ${r.items.length} of ${r.matched} matching current models${r.truncated ? " · raise --limit for more" : ""}`,
+      "Current discovery plus bounded lookups, not an atomic price snapshot. History, returns and sparklines are unavailable from the public API.",
+    );
+  } else if (d.action === "market") {
+    lines.push("MODEL                                  CCY     INPUT     OUTPUT    LAST INPUT CHANGE   HISTORY");
+    for (const s of r.series) {
+      const p = s.points.at(-1);
+      lines.push(
+        `${s.model_id.padEnd(38)} ${s.currency} ${money(p.input_per_mtok).padStart(8)} ${money(p.output_per_mtok).padStart(10)} ${movement(s).padStart(12)}      ${spark(s.points)}`,
+      );
+    }
+    lines.push(
+      "",
+      `${d.request.channel} / ${d.request.region} · rates per million tokens`,
+      `Showing ${r.series.length} of ${r.matched} models${r.truncated ? " · raise --limit for more" : ""}`,
+      "Change is between the last two contiguous catalog windows, not a 24h return. Sparklines show events, not elapsed time.",
+    );
+  } else if (d.action === "history") {
+    const s = r.series[0];
+    if (!s) lines.push("No catalog history for this exact model/channel/region.");
+    else {
+      lines.push(`${s.model_id} · ${s.channel} / ${s.region} · ${s.currency} per million tokens`);
+      if (format === "chart") lines.push(...terminalChart(s, d.request.at));
+      lines.push("", "EFFECTIVE FROM             INPUT       OUTPUT       UNTIL");
+      for (const p of s.points)
+        lines.push(
+          `${p.effective_from.slice(0, 19)}   ${money(p.input_per_mtok).padStart(10)}   ${money(p.output_per_mtok).padStart(10)}   ${p.effective_to ?? "open"}`,
+        );
+      lines.push("", `Last input change: ${movement(s)} · effective windows; gaps mean unknown pricing.`);
+    }
+  } else {
+    lines.push(
+      `Status: ${r.status}${r.missing_dimensions.length ? ` · missing ${r.missing_dimensions.join(", ")}` : ""}`,
+    );
+    if (r.price)
+      lines.push(
+        `${r.model_id} · ${r.price.channel} / ${r.price.region}`,
+        `Input ${money(r.price.input_per_mtok)} · Output ${money(r.price.output_per_mtok)} ${r.price.currency}/million tokens`,
+        `Source: ${r.price.source_url}`,
+        ...(d.request.region && d.request.region !== r.price.region
+          ? [`Requested region: ${d.request.region} · resolved price region: ${r.price.region} (fallback)`]
+          : []),
+      );
+    if (["cost", "calculate"].includes(d.action))
+      lines.push(
+        `Cost: ${r.cost ?? "unknown"} ${r.currency ?? ""}${r.status === "partial" ? " (known subtotal)" : ""}`,
+        ...(r.components ? Object.entries(r.components).map(([k, v]) => `  ${k}: ${v}`) : []),
+        `Reasons: ${r.reasons?.join(", ") || (d.api === "public" ? "not reported" : "none")}`,
+      );
+  }
+  return `${lines.join("\n")}\n\n${provenance(d)}`;
+}
+function domain(s, at) {
+  const end = Date.parse(`${at}T00:00:00Z`);
+  const start = Math.min(Date.parse(s.points[0].effective_from), end - 86400000);
+  return {
+    start,
+    end,
+    max: Math.max(
+      0.00000001,
+      ...s.points
+        .flatMap((p) => [p.input_per_mtok, p.output_per_mtok])
+        .filter((v) => v !== null)
+        .map(Number),
+    ),
+  };
+}
+function terminalChart(s, at) {
+  const { start, end, max } = domain(s, at);
+  const grid = Array.from({ length: 9 }, () => Array(55).fill(" "));
+  for (let x = 0; x < 55; x++) {
+    const t = start + ((end - start) * x) / 54;
+    const p = s.points.find(
+      (p) => Date.parse(p.effective_from) <= t && (p.effective_to === null || Date.parse(p.effective_to) > t),
+    );
+    if (!p) continue;
+    for (const [key, glyph] of [
+      ["output_per_mtok", "o"],
+      ["input_per_mtok", "i"],
+    ]) {
+      if (p[key] === null) continue;
+      const y = 8 - Math.round((Number(p[key]) / max) * 8);
+      grid[y][x] = grid[y][x] === " " ? glyph : "*";
+    }
+  }
+  return [
+    "",
+    ...grid.map((row, i) => `${money((max * (8 - i)) / 8).padStart(10)} │${row.join("")}`),
+    `           └${"─".repeat(55)}`,
+    `            ${new Date(start).toISOString().slice(0, 10)}${" ".repeat(35)}${at}`,
+    "            i input · o output · * overlap (linear UTC time)",
+  ];
+}
+export function pricingHtml(d) {
+  const s = d.result.series[0];
+  if (!s)
+    return "<!doctype html><meta charset=utf-8><title>Pricing history</title><p>No matching catalog history.</p>\n";
+  const { start, end, max } = domain(s, d.request.at),
+    x = (t) => 70 + ((Date.parse(t) - start) / (end - start)) * 850,
+    y = (v) => 330 - (Number(v) / max) * 250;
+  const paths = [];
+  for (const [key, color] of [
+    ["input_per_mtok", "#46e3bb"],
+    ["output_per_mtok", "#aaa4ff"],
+  ]) {
+    for (const [index, p] of s.points.entries()) {
+      if (p[key] === null) continue;
+      const until = Math.min(end, p.effective_to ? Date.parse(p.effective_to) : end);
+      if (until < Date.parse(p.effective_from)) continue;
+      const next = s.points[index + 1];
+      const join =
+        next && Date.parse(p.effective_to) === Date.parse(next.effective_from) && next[key] !== null
+          ? `V${y(next[key])}`
+          : "";
+      paths.push(
+        `<path d="M${x(p.effective_from)},${y(p[key])}H${70 + ((until - start) / (end - start)) * 850}${join}" stroke="${color}" stroke-width="3" fill="none"/><circle cx="${x(p.effective_from)}" cy="${y(p[key])}" r="3" fill="${color}"><title>${escape(p.effective_from)}: ${money(p[key])}</title></circle>`,
+      );
+    }
+  }
+  const last = s.points.at(-1);
+  const rows = s.points
+    .map(
+      (p) =>
+        `<tr><td>${escape(p.effective_from)}</td><td>${escape(p.effective_to ?? "open")}</td><td>${money(p.input_per_mtok)}</td><td>${money(p.output_per_mtok)}</td><td><a href="${escape(p.source_url)}">Provider source</a></td></tr>`,
+    )
+    .join("");
+  return `<!doctype html><html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width"><title>${escape(s.model_id)} · Metergraph price history</title>
+<style>body{margin:0;background:#10151e;color:#eef2f8;font:16px system-ui}main{max-width:1050px;margin:55px auto;padding:24px}header,section{border-bottom:1px solid #303847;padding:24px 0}small,p{color:#acb8ca}h1{font-size:40px;margin:14px 0}strong{font-size:32px}svg{width:100%;height:auto} .table-scroll{overflow-x:auto}table{width:100%;text-align:left;border-collapse:collapse}td,th{padding:12px;border-bottom:1px solid #303847}a{color:#46e3bb}.metrics{display:flex;gap:50px;flex-wrap:wrap}.input{color:#46e3bb}.output{color:#aaa4ff}</style>
+<main><header><small>METERGRAPH / MODEL PRICE HISTORY · ${escape(d.request.at)} UTC</small><h1>${escape(s.model_id)}</h1><p>${escape(s.channel)} / ${escape(s.region)} · ${escape(s.currency)} per million tokens</p></header>
+<section class="metrics"><div class="input">Last recorded input<br><strong>${money(last.input_per_mtok)}</strong></div><div class="output">Last recorded output<br><strong>${money(last.output_per_mtok)}</strong></div><div>Last input change<br><strong>${movement(s)}</strong></div></section>
+<svg role="img" aria-labelledby="title desc" viewBox="0 0 1000 400"><title id="title">Effective-dated input and output base rates</title><desc id="desc">Horizontal segments cover known pricing windows. Gaps are unknown. Exact values and sources follow in the table.</desc><g fill="#acb8ca" font-family="system-ui" font-size="14"><text x="10" y="85">${money(max)}</text><text x="45" y="335">0</text><text x="70" y="370">${new Date(start).toISOString().slice(0, 10)}</text><text x="840" y="370">${escape(d.request.at)}</text></g><path d="M70 80V330H920" stroke="#435064" fill="none"/>${paths.join("")}</svg>
+<p><span class="input">━ Input</span> &nbsp; <span class="output">━ Output</span> · Linear UTC time; effective windows, not daily observations. Gaps mean unknown.</p>
+<div class="table-scroll"><table><caption>Catalog price windows and provider sources</caption><thead><tr><th>From (UTC)</th><th>Until (exclusive)</th><th>Input</th><th>Output</th><th>Source</th></tr></thead><tbody>${rows}</tbody></table></div>
+<p>${escape(provenance(d))}</p><footer>Explore your application's actual model costs with <a href="https://www.metergraph.dev/">Metergraph</a>. Free pricing queries require no account.</footer></main></html>\n`;
+}

package/src/pricing-reference.js

@@ -0,0 +1,195 @@
+import { send } from "./transport.js";
+import { parseJsonObject } from "./http.js";
+import { validDate } from "./pricing-args.js";
+export const PRICING_SCHEMA = "metergraph.pricing/v1";
+const fail = (outcome, reason) => ({
+  outcome,
+  reason,
+  message: "Pricing could not be read. Check the reason and the pricing service contract.",
+});
+const text = (v) =>
+  typeof v === "string" &&
+  v.length > 0 &&
+  v.length <= 500 &&
+  !/[\x00-\x1f\x7f-\x9f\u202a-\u202e\u2066-\u2069]/u.test(v);
+const currency = (v) => typeof v === "string" && /^[A-Z]{3}$/.test(v);
+const decimal = (v) =>
+  v === null || (typeof v === "string" && /^(0|[1-9]\d{0,14})(\.\d{1,16})?$/.test(v) && Number.isFinite(Number(v)));
+const instant = (v) =>
+  typeof v === "string" &&
+  /^\d{4}-\d{2}-\d{2}T(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d{1,6})?(?:Z|\+00:00)$/.test(v) &&
+  validDate(v.slice(0, 10)) &&
+  Number.isFinite(Date.parse(v));
+const source = (v) => {
+  if (!text(v)) return false;
+  try {
+    const u = new URL(v);
+    return u.protocol === "https:" && !u.username && !u.password;
+  } catch {
+    return false;
+  }
+};
+export const RATE_KEYS = [
+  "input_per_mtok",
+  "output_per_mtok",
+  "cache_read_per_mtok",
+  "cache_write_5m_per_mtok",
+  "cache_write_1h_per_mtok",
+  "batch_input_per_mtok",
+  "batch_output_per_mtok",
+  "request_fee_per_1k",
+];
+function price(p) {
+  return (
+    p &&
+    ["id", "model_id", "channel", "region"].every((k) => text(p[k])) &&
+    currency(p.currency) &&
+    instant(p.effective_from) &&
+    (p.effective_to === null ||
+      (instant(p.effective_to) && Date.parse(p.effective_to) > Date.parse(p.effective_from))) &&
+    source(p.source_url) &&
+    RATE_KEYS.every((k) => decimal(p[k])) &&
+    p.rules &&
+    typeof p.rules === "object" &&
+    !Array.isArray(p.rules)
+  );
+}
+function series(s, q) {
+  if (
+    !s ||
+    !["model_id", "channel", "region"].every((k) => text(s[k])) ||
+    s.channel !== q.channel ||
+    s.region !== q.region ||
+    !currency(s.currency) ||
+    !Array.isArray(s.points) ||
+    s.points.length < 1 ||
+    s.points.length > 1000
+  )
+    return false;
+  return s.points.every(
+    (p, i) =>
+      price(p) &&
+      p.model_id === s.model_id &&
+      p.channel === s.channel &&
+      p.region === s.region &&
+      p.currency === s.currency &&
+      Date.parse(p.effective_from) <= Date.parse(`${q.at}T00:00:00Z`) &&
+      (i === 0 ||
+        (Date.parse(s.points[i - 1].effective_from) < Date.parse(p.effective_from) &&
+          s.points[i - 1].effective_to !== null &&
+          Date.parse(s.points[i - 1].effective_to) <= Date.parse(p.effective_from))),
+  );
+}
+export function validatePricing(d, action, q) {
+  if (
+    !d ||
+    d.schema_version !== PRICING_SCHEMA ||
+    d.action !== action ||
+    !d.request ||
+    JSON.stringify(Object.keys(d.request).sort()) !== JSON.stringify(Object.keys(q).sort()) ||
+    !Object.keys(q).every((k) => d.request[k] === q[k]) ||
+    !d.catalog ||
+    !text(d.catalog.version) ||
+    typeof d.catalog.content_hash !== "string" ||
+    !/^[a-f0-9]{64}$/.test(d.catalog.content_hash) ||
+    !validDate(d.catalog.pricing_verified_at) ||
+    !instant(d.catalog.served_at) ||
+    !text(d.catalog.core_version)
+  )
+    return false;
+  const r = d.result;
+  if (!r) return false;
+  if (action === "market" || action === "history") {
+    if (
+      !Array.isArray(r.series) ||
+      r.series.length > (action === "history" ? 1 : q.limit) ||
+      !r.series.every((s) => series(s, q)) ||
+      typeof r.truncated !== "boolean" ||
+      !Number.isSafeInteger(r.matched) ||
+      r.matched < r.series.length ||
+      r.truncated !== r.matched > r.series.length ||
+      (action === "history" && r.truncated)
+    )
+      return false;
+    if (
+      action === "market" &&
+      r.series.some(
+        (s) =>
+          s.points.at(-1).effective_to !== null &&
+          Date.parse(s.points.at(-1).effective_to) <= Date.parse(`${q.at}T00:00:00Z`),
+      )
+    )
+      return false;
+    const ids = r.series.map((s) => `${s.model_id}|${s.channel}|${s.region}`);
+    return new Set(ids).size === ids.length;
+  }
+  if (
+    !["priced", "partial", "unpriced"].includes(r.status) ||
+    !Array.isArray(r.missing_dimensions) ||
+    new Set(r.missing_dimensions).size !== r.missing_dimensions.length ||
+    !r.missing_dimensions.every((k) => ["region", "channel", "input_tokens", "output_tokens"].includes(k)) ||
+    !instant(r.effective_at) ||
+    Date.parse(r.effective_at) !== Date.parse(`${q.at}T00:00:00Z`)
+  )
+    return false;
+  if (r.status === "unpriced") {
+    if (r.price !== null || r.model_id !== null) return false;
+  } else if (
+    !price(r.price) ||
+    r.model_id !== r.price.model_id ||
+    (q.channel && r.price.channel !== q.channel) ||
+    (q.region && ![q.region, "global", "*"].includes(r.price.region)) ||
+    Date.parse(r.price.effective_from) > Date.parse(r.effective_at) ||
+    (r.price.effective_to !== null && Date.parse(r.price.effective_to) <= Date.parse(r.effective_at))
+  )
+    return false;
+  if (r.status === "priced" && r.missing_dimensions.length) return false;
+  if (action === "cost") {
+    if (!decimal(r.cost) || !Array.isArray(r.reasons) || !r.reasons.every(text)) return false;
+    if (r.status === "priced" && r.reasons.length) return false;
+    if (
+      r.status !== "unpriced" &&
+      ["input_tokens", "output_tokens"].some((k) => !Object.hasOwn(q, k) && !r.missing_dimensions.includes(k))
+    )
+      return false;
+    if (r.status === "unpriced") return r.cost === null && r.components === null && r.currency === null;
+    if (
+      r.cost === null ||
+      r.currency !== r.price.currency ||
+      !r.components ||
+      !["input", "output", "cache_read", "cache_write", "request"].every(
+        (k) => r.components[k] !== null && decimal(r.components[k]),
+      )
+    )
+      return false;
+    // Validate the engine's rounded breakdown using integer decimal arithmetic.
+    const units = (value) => {
+      const [whole, fraction = ""] = value.split(".");
+      return BigInt(whole) * 10n ** 16n + BigInt(fraction.padEnd(16, "0"));
+    };
+    if (
+      Object.keys(r.components).sort().join() !== "cache_read,cache_write,input,output,request" ||
+      Object.values(r.components).reduce((sum, v) => sum + units(v), 0n) !== units(r.cost)
+    )
+      return false;
+  }
+  return true;
+}
+export async function runReferencePricing(o) {
+  const query = new URLSearchParams(Object.entries(o.query).map(([k, v]) => [k, String(v)]));
+  const res = await send(o.origin, `/v1/pricing/${o.action}`, {
+    query,
+    maxBytes: 1024 * 1024,
+    signal: AbortSignal.timeout(o.timeoutMs),
+  });
+  if (res.kind === "error") return fail("connection_failed", res.reason);
+  if (res.status >= 300 && res.status < 400) return fail("redirect_rejected", "pricing_redirect_rejected");
+  if (res.status === 429) return fail("rate_limited", "pricing_rate_limited");
+  if (res.status >= 500) return fail("unhealthy", "pricing_service_unhealthy");
+  if ([401, 403, 404, 405].includes(res.status)) return fail("unsupported", "public_pricing_unavailable");
+  if (res.tooLarge) return fail("unsupported", "pricing_response_too_large");
+  if (res.status !== 200) return fail("unsupported", "pricing_response_unsupported");
+  const data = parseJsonObject(res);
+  if (!validatePricing(data, o.action, o.query)) return fail("verification_failed", "pricing_contract_mismatch");
+  return { outcome: "ok", data };
+}