@dzhechkov/harness-core 0.3.146 → 0.3.147

package/src/cost-scoring.ts

@@ -78,6 +78,23 @@ const FALLBACK_PRICING = priced(3 / 1e6, 15 / 1e6);
  * Resolve a model id to its pricing by longest-prefix match.
  * `bedrock/anthropic.claude-3-opus...` → strips a leading `provider/` segment.
  */
+/**
+ * Whether {@link pricingFor} will find a REAL entry for this model id, or silently fall back to
+ * {@link FALLBACK_PRICING} (sonnet-class).
+ *
+ * Exists so a cost surface can REPORT the fallback instead of hiding it: `claude-fable-*` has no
+ * entry in {@link MODEL_PRICES} and is the default model of every recorded feature-adr run, so its
+ * dollar figures are priced at a fallback rate (feature `cost-ledger`, ADR-003).
+ */
+export function hasKnownPricing(modelId: string): boolean {
+  if (typeof modelId !== 'string' || modelId.length === 0) return false;
+  const id = modelId.toLowerCase().replace(/^[a-z0-9-]+\//, '');
+  for (const key of Object.keys(MODEL_PRICES)) {
+    if (id.startsWith(key)) return true;
+  }
+  return false;
+}
+
 export function pricingFor(modelId: string): ModelPricing {
   // Strip a leading `provider/` segment (e.g. `bedrock/`, `us-east-1/`).
   const id = modelId.toLowerCase().replace(/^[a-z0-9-]+\//, '');

package/src/index.ts

@@ -263,6 +263,7 @@ export type { RiskScore, RiskThresholds } from './risk-scoring.js';
 export {
   MODEL_PRICES,
   pricingFor,
+  hasKnownPricing,
   normalizeUsage,
   usageCost,
   invocationCost,
@@ -342,6 +343,43 @@ export {
   readUsageLimits,
   weeklyWindowFor,
 } from './usage.js';
+export { claudeProjectsRoot, rawTokenMixOf, weightedTokensOf } from './usage.js';
+export type { RawTokenMix } from './usage.js';
+// Per-stage cost ledger + reconciliation invariant (feature cost-ledger, ADR-001/002/003).
+export {
+  COST_LEDGER_SCOPE,
+  COST_LEDGER_DEFECT_KINDS,
+  COST_LEDGER_VERDICTS,
+  DEFAULT_COST_LEDGER_EPSILON,
+  extractCostSamples,
+  parseWorkflowRunRecord,
+  buildCostLedger,
+  verifyCostLedgerReport,
+  stageCostAggregates,
+  renderCostLedger,
+  costLedgerJsonl,
+  listCostLedgerRuns,
+  deriveCostLedger,
+  deriveStageCostAggregates,
+  writeCostLedgerJsonl,
+} from './cost-ledger.js';
+export type {
+  CostLedgerDefect,
+  CostLedgerDefectKind,
+  CostLedgerIoOptions,
+  CostLedgerReconciliation,
+  CostLedgerReport,
+  CostLedgerRow,
+  CostLedgerRunRef,
+  CostLedgerSample,
+  CostLedgerVerdict,
+  BuildCostLedgerInput,
+  DeriveCostLedgerOptions,
+  StageCostAggregate,
+  StageSampleSet,
+  WorkflowRunRecord,
+  WorkflowStageEntry,
+} from './cost-ledger.js';
 export type {
   ClaudeUsageModel,
   UsageCalibrationChange,

package/src/usage.ts

@@ -45,6 +45,77 @@ const MTIME_SLACK_MS = HOUR_MS;
  */
 export const TOKEN_WEIGHTS = { input: 1, cacheWrite: 1.25, cacheWrite1h: 2, cacheRead: 0.1, output: 5 } as const;
 
+/** The four raw token buckets of one `message.usage` record, after clamping. */
+export interface RawTokenMix {
+  readonly input: number;
+  /** Cache-CREATION tokens, already priced at their TTL rate inside {@link weightedTokensOf}. */
+  readonly cacheWrite: number;
+  readonly cacheRead: number;
+  readonly output: number;
+}
+
+function positiveFinite(v: unknown): number {
+  return typeof v === 'number' && isFinite(v) && v > 0 ? v : 0;
+}
+
+/**
+ * The raw token buckets of an Anthropic `message.usage` object, clamped to finite non-negatives.
+ * `cacheWrite` prefers the TTL breakdown (`cache_creation.ephemeral_*`) and falls back to the flat
+ * `cache_creation_input_tokens` — reading only the flat field scored a nested-only record as ZERO.
+ */
+export function rawTokenMixOf(usage: unknown): RawTokenMix {
+  if (typeof usage !== 'object' || usage === null) {
+    return { input: 0, cacheWrite: 0, cacheRead: 0, output: 0 };
+  }
+  const u = usage as Record<string, unknown>;
+  const cc = (typeof u['cache_creation'] === 'object' && u['cache_creation'] !== null
+    ? (u['cache_creation'] as Record<string, unknown>)
+    : {}) as Record<string, unknown>;
+  const c5 = positiveFinite(cc['ephemeral_5m_input_tokens']);
+  const c1h = positiveFinite(cc['ephemeral_1h_input_tokens']);
+  const cacheWrite = c5 + c1h > 0 ? c5 + c1h : positiveFinite(u['cache_creation_input_tokens']);
+  return {
+    input: positiveFinite(u['input_tokens']),
+    cacheWrite,
+    cacheRead: positiveFinite(u['cache_read_input_tokens']),
+    output: positiveFinite(u['output_tokens']),
+  };
+}
+
+/**
+ * THE estimator — cost-weighted "input-equivalent" tokens for one `message.usage` object.
+ *
+ * A flat token sum is 89-99.7% `cache_read` on this machine, which tracks CONVERSATION LENGTH
+ * rather than work done. {@link TOKEN_WEIGHTS} are the published per-token price ratios relative to
+ * base input, so the result tracks consumption instead of context size.
+ *
+ * Extracted verbatim from `computeUsage`'s per-sample arithmetic so that `dz usage` and the
+ * per-stage cost ledger measure the same quantity (feature `cost-ledger`, ADR-002 — the invariant
+ * only means something if both sides use ONE estimator). The return value is UNROUNDED; callers
+ * that need exact integer identities round once at their own extraction point.
+ */
+export function weightedTokensOf(usage: unknown): number {
+  if (typeof usage !== 'object' || usage === null) return 0;
+  const mix = rawTokenMixOf(usage);
+  const u = usage as Record<string, unknown>;
+  const cc =
+    typeof u['cache_creation'] === 'object' && u['cache_creation'] !== null
+      ? (u['cache_creation'] as Record<string, unknown>)
+      : {};
+  const c5 = positiveFinite(cc['ephemeral_5m_input_tokens']);
+  const c1h = positiveFinite(cc['ephemeral_1h_input_tokens']);
+  const cacheWriteCost =
+    c5 + c1h > 0
+      ? c5 * TOKEN_WEIGHTS.cacheWrite + c1h * TOKEN_WEIGHTS.cacheWrite1h
+      : mix.cacheWrite * TOKEN_WEIGHTS.cacheWrite;
+  return (
+    mix.input * TOKEN_WEIGHTS.input +
+    cacheWriteCost +
+    mix.cacheRead * TOKEN_WEIGHTS.cacheRead +
+    mix.output * TOKEN_WEIGHTS.output
+  );
+}
+
 export const CLAUDE_USAGE_MODELS = ['fable', 'opus', 'sonnet', 'haiku'] as const;
 export type ClaudeUsageModel = (typeof CLAUDE_USAGE_MODELS)[number];
 
@@ -230,7 +301,7 @@ export function normalizeClaudeUsageModelKey(raw: unknown): ClaudeUsageModel | n
  * The `~/.claude/projects` root (the account-wide transcript store). Overridable via
  * `DZ_CLAUDE_PROJECTS_ROOT` — used by tests to point at a temp tree. Never throws.
  */
-function claudeProjectsRoot(): string {
+export function claudeProjectsRoot(): string {
   const override = process.env['DZ_CLAUDE_PROJECTS_ROOT'];
   if (typeof override === 'string' && override.length > 0) return override;
   return join(homedir(), '.claude', 'projects');
@@ -414,17 +485,8 @@ function extractSamples(path: string, scanCutoff: number, into: Sample[], seen:
     // tokens": a quantity that tracks consumption instead of context size.
     // Prefer the TTL breakdown when present (5m 1.25x / 1h 2x); fall back to the flat field at the
     // 5m rate. Reading only the flat field scored a nested-only record as ZERO.
-    const c5 = n(usage.cache_creation?.ephemeral_5m_input_tokens);
-    const c1h = n(usage.cache_creation?.ephemeral_1h_input_tokens);
-    const cacheWriteCost =
-      c5 + c1h > 0
-        ? c5 * TOKEN_WEIGHTS.cacheWrite + c1h * TOKEN_WEIGHTS.cacheWrite1h
-        : n(usage.cache_creation_input_tokens) * TOKEN_WEIGHTS.cacheWrite;
-    const tokens =
-      n(usage.input_tokens) * TOKEN_WEIGHTS.input +
-      cacheWriteCost +
-      n(usage.cache_read_input_tokens) * TOKEN_WEIGHTS.cacheRead +
-      n(usage.output_tokens) * TOKEN_WEIGHTS.output;
+    // ONE estimator, shared with the per-stage cost ledger (feature `cost-ledger`, ADR-002).
+    const tokens = weightedTokensOf(usage);
     if (tokens <= 0) continue;
     // Dedup: streamed assistant messages repeat their usage object across chunks.
     const id = typeof rec.message?.id === 'string' ? rec.message.id : '';