session-orchestrator 5.9.0 → 5.11.0

package/scripts/lib/session-schema/validator.mjs

@@ -26,6 +26,17 @@ import {
 /** Valid values for the optional `expected_cost_tier` field (ADR-364). */
 const EXPECTED_COST_TIERS = Object.freeze(['quick', 'standard', 'deep']);
 
+/**
+ * Valid values for the optional `cost_basis` field (#1470 Pkt 4). Must contain
+ * `COST_BASIS` from scripts/lib/telemetry/pricing.mjs — the value emit-session
+ * writes beside `total_cost_usd`. There is deliberately no payment value: no
+ * writer can see what was actually billed.
+ */
+const COST_BASES = Object.freeze(['api-list-equivalent']);
+
+/** `pricing_table_date` (#1470 Pkt 6): a calendar date, `YYYY-MM-DD`. */
+const ISO_DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+
 /**
  * Valid values for the optional `status` field (Epic #724 C1).
  * `completed`  — record written by a normal /close flow.
@@ -456,6 +467,28 @@ function _validateOptionalFields(entry) {
     );
   }
 
+  // #1470 Pkt 4/6 — what the cost figure is and which price table produced it.
+  if (entry.cost_basis !== undefined && entry.cost_basis !== null) {
+    if (!COST_BASES.includes(entry.cost_basis)) {
+      throw new ValidationError(
+        `cost_basis must be one of ${COST_BASES.join('|')} or null, got: ${entry.cost_basis}`
+      );
+    }
+  }
+  if (entry.pricing_table_date !== undefined && entry.pricing_table_date !== null) {
+    if (
+      typeof entry.pricing_table_date !== 'string' ||
+      !ISO_DATE_RE.test(entry.pricing_table_date) ||
+      // Round-trip, not Date.parse alone: V8 rolls 2026-02-30 over to March.
+      Number.isNaN(Date.parse(`${entry.pricing_table_date}T00:00:00Z`)) ||
+      new Date(`${entry.pricing_table_date}T00:00:00Z`).toISOString().slice(0, 10) !== entry.pricing_table_date
+    ) {
+      throw new ValidationError(
+        `pricing_table_date must be an ISO date (YYYY-MM-DD) or null, got: ${entry.pricing_table_date}`
+      );
+    }
+  }
+
   // Epic #724 C1 — SessionEnd close-through backfill provenance fields.
   // All additive-optional; null/absent passes without further checks so that
   // pre-#724 records (and every normally-closed record) validate cleanly.

package/scripts/lib/subagents-schema.mjs

@@ -55,6 +55,8 @@
  *   total_cost_usd    number  | null — native total cost in USD (#624, fractional,
  *                                      best-effort: null when the harness does not
  *                                      expose it; no rate table is applied)
+ *   cost_basis        'api-list-equivalent' | null — explicitly supplied cost
+ *                                      provenance; null means unknown (#1543)
  *
  * OTel aliases (optional, stop-only, additive — #411, schema_version=1 backwards-compat):
  *   gen_ai.usage.input_tokens   integer | null — RAW UNCACHED prompt tokens (OTel
@@ -69,6 +71,7 @@
 import { readFile, appendFile, mkdir } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import path from 'node:path';
+import { COST_BASIS } from './telemetry/pricing.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -267,6 +270,11 @@ export function validateSubagent(entry, options = {}) {
     }
   }
 
+  // #1543 additive: never infer provenance from a native dollar value.
+  if (entry.cost_basis !== undefined && entry.cost_basis !== null && entry.cost_basis !== COST_BASIS) {
+    throw new ValidationError(`cost_basis must be ${COST_BASIS} or null`, 'cost_basis');
+  }
+
   // OTel alias — #411 additive, schema_version=1 backwards-compat
   const otelInputTokens = entry['gen_ai.usage.input_tokens'];
   if (otelInputTokens !== undefined && otelInputTokens !== null) {
@@ -334,6 +342,7 @@ export function normalizeSubagent(entry) {
     model: entry.model ?? null,
     // total_cost_usd — #624 additive, best-effort native cost (null when absent)
     total_cost_usd: entry.total_cost_usd ?? null,
+    cost_basis: entry.cost_basis ?? null,
     // OTel alias — #411 additive, schema_version=1 backwards-compat
     'gen_ai.usage.input_tokens': entry['gen_ai.usage.input_tokens'] ?? null,
     'gen_ai.usage.cache_read_input_tokens': entry['gen_ai.usage.cache_read_input_tokens'] ?? null,

package/scripts/lib/telemetry/pricing.mjs

@@ -62,6 +62,17 @@
  */
 export const PRICING_TABLE_DATE = '2026-09-29';
 
+/**
+ * What a dollar figure computed from this table IS (#1470 Pkt 4): the API
+ * list-price equivalent of the metered tokens — never a payment. Subscription
+ * quota, purchased credits and what was actually billed are not visible to
+ * this module, so a consumer must not present the figure as any of them.
+ * Written beside every persisted cost as `cost_basis`; the session validator's
+ * `COST_BASES` must contain it (pinned by tests/scripts/emit-session.test.mjs).
+ * @type {'api-list-equivalent'}
+ */
+export const COST_BASIS = 'api-list-equivalent';
+
 /**
  * @typedef {Object} PricingRow
  * @property {number} input           - USD per 1M uncached prompt tokens.