cleargate 0.8.2 → 0.11.0

package/dist/lib/ledger.cjs

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/lib/ledger.ts
+var ledger_exports = {};
+__export(ledger_exports, {
+  sumDeltas: () => sumDeltas
+});
+module.exports = __toCommonJS(ledger_exports);
+function isTokenCounts(v) {
+  if (typeof v !== "object" || v === null) return false;
+  const obj = v;
+  return typeof obj["input"] === "number" && typeof obj["output"] === "number" && typeof obj["cache_creation"] === "number" && typeof obj["cache_read"] === "number";
+}
+function hasDelta(row) {
+  return isTokenCounts(row["delta"]);
+}
+function zeroCounts() {
+  return { input: 0, output: 0, cache_creation: 0, cache_read: 0 };
+}
+function addCounts(a, b) {
+  return {
+    input: a.input + b.input,
+    output: a.output + b.output,
+    cache_creation: a.cache_creation + b.cache_creation,
+    cache_read: a.cache_read + b.cache_read
+  };
+}
+function lastRowTrickForFlatRows(rows) {
+  const sessionMap = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    const sessionId = typeof row["session_id"] === "string" ? row["session_id"] : "(unknown)";
+    const existing = sessionMap.get(sessionId);
+    if (!existing) {
+      sessionMap.set(sessionId, row);
+    } else {
+      const existingTs = typeof existing["ts"] === "string" ? existing["ts"] : "";
+      const rowTs = typeof row["ts"] === "string" ? row["ts"] : "";
+      if (rowTs > existingTs) {
+        sessionMap.set(sessionId, row);
+      }
+    }
+  }
+  let totals = zeroCounts();
+  for (const row of sessionMap.values()) {
+    totals = addCounts(totals, {
+      input: typeof row["input"] === "number" ? row["input"] : 0,
+      output: typeof row["output"] === "number" ? row["output"] : 0,
+      cache_creation: typeof row["cache_creation"] === "number" ? row["cache_creation"] : 0,
+      cache_read: typeof row["cache_read"] === "number" ? row["cache_read"] : 0
+    });
+  }
+  return totals;
+}
+function sumDeltas(rows) {
+  const validRows = [];
+  for (const raw of rows) {
+    if (typeof raw === "object" && raw !== null && !Array.isArray(raw)) {
+      validRows.push(raw);
+    } else {
+      console.warn("[ledger.ts] sumDeltas: skipping malformed row (not an object):", raw);
+    }
+  }
+  if (validRows.length === 0) {
+    return { totals: zeroCounts(), format: "delta" };
+  }
+  const deltaRows = validRows.filter(hasDelta);
+  const flatRows = validRows.filter((r) => !hasDelta(r));
+  if (flatRows.length === 0) {
+    let totals2 = zeroCounts();
+    for (const row of deltaRows) {
+      const d = row["delta"];
+      totals2 = addCounts(totals2, d);
+    }
+    return { totals: totals2, format: "delta" };
+  }
+  if (deltaRows.length === 0) {
+    const totals2 = lastRowTrickForFlatRows(flatRows);
+    return {
+      totals: totals2,
+      format: "pre-0.9.0",
+      pre_v2_caveat: "**Ledger format note:** This sprint's token-ledger.jsonl uses pre-0.9.0 flat-field rows; cost is computed via the last-row-per-session trick (reconciliation accuracy \xB1N \xD7 real-cost where N = SubagentStop fires per session)."
+    };
+  }
+  let totals = zeroCounts();
+  for (const row of deltaRows) {
+    const d = row["delta"];
+    totals = addCounts(totals, d);
+  }
+  const flatTotals = lastRowTrickForFlatRows(flatRows);
+  totals = addCounts(totals, flatTotals);
+  const caveat = `Mixed format ledger: ${deltaRows.length} delta rows + ${flatRows.length} pre-0.9.0 rows; flat segment uses last-row trick.`;
+  return {
+    totals,
+    format: "mixed",
+    pre_v2_caveat: caveat
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  sumDeltas
+});
+//# sourceMappingURL=ledger.cjs.map

package/dist/lib/ledger.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/lib/ledger.ts"],"sourcesContent":["/**\n * ledger.ts — CR-018\n *\n * Sprint-wide cost math: parses token-ledger.jsonl rows and sums delta tokens\n * for the Reporter agent. Distinct from ledger-reader.ts (per-work-item\n * attribution lookup); this file provides sumDeltas() for sprint-total cost.\n *\n * Format detection handles three cases:\n *   'delta'     — all rows carry delta.* blocks (post-0.9.0)\n *   'pre-0.9.0' — all rows use flat input/output/cache_* fields (pre-0.9.0)\n *   'mixed'     — some rows have delta, others don't (SPRINT-15 cutover window)\n */\n\n// ─── Public types ─────────────────────────────────────────────────────────────\n\n/** Token counts block (used in both delta and session_total). */\nexport interface TokenCounts {\n  input: number;\n  output: number;\n  cache_creation: number;\n  cache_read: number;\n}\n\n/** Full post-0.9.0 ledger row shape. */\nexport interface LedgerRowV2 {\n  ts: string;\n  sprint_id: string;\n  story_id: string;\n  work_item_id: string;\n  agent_type: string;\n  session_id: string;\n  transcript?: string;\n  sentinel_started_at?: string;\n  delta_from_turn?: number;\n  delta: TokenCounts;\n  session_total: TokenCounts;\n  model: string;\n  turns: number;\n}\n\n/** Result returned by sumDeltas(). */\nexport interface SumResult {\n  /** Aggregated token totals across all rows (using appropriate format). */\n  totals: TokenCounts;\n  /** How the totals were computed. */\n  format: 'delta' | 'pre-0.9.0' | 'mixed';\n  /**\n   * Present when format is 'pre-0.9.0' or 'mixed'.\n   * Reporter should paste this verbatim into REPORT.md §3.\n   */\n  pre_v2_caveat?: string;\n}\n\n// ─── Internal helpers ─────────────────────────────────────────────────────────\n\nfunction isTokenCounts(v: unknown): v is TokenCounts {\n  if (typeof v !== 'object' || v === null) return false;\n  const obj = v as Record<string, unknown>;\n  return (\n    typeof obj['input'] === 'number' &&\n    typeof obj['output'] === 'number' &&\n    typeof obj['cache_creation'] === 'number' &&\n    typeof obj['cache_read'] === 'number'\n  );\n}\n\nfunction hasDelta(row: Record<string, unknown>): boolean {\n  return isTokenCounts(row['delta']);\n}\n\nfunction zeroCounts(): TokenCounts {\n  return { input: 0, output: 0, cache_creation: 0, cache_read: 0 };\n}\n\nfunction addCounts(a: TokenCounts, b: TokenCounts): TokenCounts {\n  return {\n    input: a.input + b.input,\n    output: a.output + b.output,\n    cache_creation: a.cache_creation + b.cache_creation,\n    cache_read: a.cache_read + b.cache_read,\n  };\n}\n\n/**\n * Last-row-per-session trick for pre-0.9.0 flat-field rows.\n * Groups rows by session_id, takes the row with max ts per group,\n * and sums the flat input/output/cache_* fields across those last rows.\n */\nfunction lastRowTrickForFlatRows(rows: Record<string, unknown>[]): TokenCounts {\n  const sessionMap = new Map<string, Record<string, unknown>>();\n\n  for (const row of rows) {\n    const sessionId = typeof row['session_id'] === 'string' ? row['session_id'] : '(unknown)';\n    const existing = sessionMap.get(sessionId);\n    if (!existing) {\n      sessionMap.set(sessionId, row);\n    } else {\n      const existingTs = typeof existing['ts'] === 'string' ? existing['ts'] : '';\n      const rowTs = typeof row['ts'] === 'string' ? row['ts'] : '';\n      if (rowTs > existingTs) {\n        sessionMap.set(sessionId, row);\n      }\n    }\n  }\n\n  let totals = zeroCounts();\n  for (const row of sessionMap.values()) {\n    totals = addCounts(totals, {\n      input: typeof row['input'] === 'number' ? row['input'] : 0,\n      output: typeof row['output'] === 'number' ? row['output'] : 0,\n      cache_creation: typeof row['cache_creation'] === 'number' ? row['cache_creation'] : 0,\n      cache_read: typeof row['cache_read'] === 'number' ? row['cache_read'] : 0,\n    });\n  }\n  return totals;\n}\n\n// ─── Public API ───────────────────────────────────────────────────────────────\n\n/**\n * Compute sprint-wide token totals from an array of raw ledger rows (parsed JSONL).\n *\n * Format-detection algorithm (mandatory):\n *   1. Classify each row: has `delta` object with 4 numeric fields → v2; else → flat/legacy.\n *   2. All v2       → format='delta',    sum delta.* directly.\n *   3. All flat     → format='pre-0.9.0', group by session_id, last-row-per-session trick.\n *   4. Mixed        → format='mixed',    delta rows contribute delta.*; flat rows within\n *                     each session use last-row trick scoped to flat rows only.\n *\n * Malformed or unrecognisable rows are skipped with a console.warn.\n *\n * @param rows  Array of parsed JSON objects (unknown type for defensive parsing).\n */\nexport function sumDeltas(rows: unknown[]): SumResult {\n  // Filter to recognisable objects; skip malformed rows.\n  const validRows: Record<string, unknown>[] = [];\n  for (const raw of rows) {\n    if (typeof raw === 'object' && raw !== null && !Array.isArray(raw)) {\n      validRows.push(raw as Record<string, unknown>);\n    } else {\n      console.warn('[ledger.ts] sumDeltas: skipping malformed row (not an object):', raw);\n    }\n  }\n\n  if (validRows.length === 0) {\n    return { totals: zeroCounts(), format: 'delta' };\n  }\n\n  const deltaRows = validRows.filter(hasDelta);\n  const flatRows = validRows.filter((r) => !hasDelta(r));\n\n  // All rows are v2 (delta) format\n  if (flatRows.length === 0) {\n    let totals = zeroCounts();\n    for (const row of deltaRows) {\n      const d = row['delta'] as TokenCounts;\n      totals = addCounts(totals, d);\n    }\n    return { totals, format: 'delta' };\n  }\n\n  // All rows are pre-0.9.0 flat format\n  if (deltaRows.length === 0) {\n    const totals = lastRowTrickForFlatRows(flatRows);\n    return {\n      totals,\n      format: 'pre-0.9.0',\n      pre_v2_caveat:\n        '**Ledger format note:** This sprint\\'s token-ledger.jsonl uses pre-0.9.0 flat-field rows; ' +\n        'cost is computed via the last-row-per-session trick ' +\n        '(reconciliation accuracy ±N × real-cost where N = SubagentStop fires per session).',\n    };\n  }\n\n  // Mixed format: both delta rows and flat rows in same ledger (e.g. SPRINT-15 cutover)\n  // Delta rows → sum delta.*\n  // Flat rows  → group by session_id, last-row trick (scoped to flat rows only)\n  let totals = zeroCounts();\n\n  // Sum delta rows directly\n  for (const row of deltaRows) {\n    const d = row['delta'] as TokenCounts;\n    totals = addCounts(totals, d);\n  }\n\n  // Apply last-row trick to flat rows\n  const flatTotals = lastRowTrickForFlatRows(flatRows);\n  totals = addCounts(totals, flatTotals);\n\n  const caveat =\n    `Mixed format ledger: ${deltaRows.length} delta rows + ${flatRows.length} pre-0.9.0 rows; ` +\n    `flat segment uses last-row trick.`;\n\n  return {\n    totals,\n    format: 'mixed',\n    pre_v2_caveat: caveat,\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAuDA,SAAS,cAAc,GAA8B;AACnD,MAAI,OAAO,MAAM,YAAY,MAAM,KAAM,QAAO;AAChD,QAAM,MAAM;AACZ,SACE,OAAO,IAAI,OAAO,MAAM,YACxB,OAAO,IAAI,QAAQ,MAAM,YACzB,OAAO,IAAI,gBAAgB,MAAM,YACjC,OAAO,IAAI,YAAY,MAAM;AAEjC;AAEA,SAAS,SAAS,KAAuC;AACvD,SAAO,cAAc,IAAI,OAAO,CAAC;AACnC;AAEA,SAAS,aAA0B;AACjC,SAAO,EAAE,OAAO,GAAG,QAAQ,GAAG,gBAAgB,GAAG,YAAY,EAAE;AACjE;AAEA,SAAS,UAAU,GAAgB,GAA6B;AAC9D,SAAO;AAAA,IACL,OAAO,EAAE,QAAQ,EAAE;AAAA,IACnB,QAAQ,EAAE,SAAS,EAAE;AAAA,IACrB,gBAAgB,EAAE,iBAAiB,EAAE;AAAA,IACrC,YAAY,EAAE,aAAa,EAAE;AAAA,EAC/B;AACF;AAOA,SAAS,wBAAwB,MAA8C;AAC7E,QAAM,aAAa,oBAAI,IAAqC;AAE5D,aAAW,OAAO,MAAM;AACtB,UAAM,YAAY,OAAO,IAAI,YAAY,MAAM,WAAW,IAAI,YAAY,IAAI;AAC9E,UAAM,WAAW,WAAW,IAAI,SAAS;AACzC,QAAI,CAAC,UAAU;AACb,iBAAW,IAAI,WAAW,GAAG;AAAA,IAC/B,OAAO;AACL,YAAM,aAAa,OAAO,SAAS,IAAI,MAAM,WAAW,SAAS,IAAI,IAAI;AACzE,YAAM,QAAQ,OAAO,IAAI,IAAI,MAAM,WAAW,IAAI,IAAI,IAAI;AAC1D,UAAI,QAAQ,YAAY;AACtB,mBAAW,IAAI,WAAW,GAAG;AAAA,MAC/B;AAAA,IACF;AAAA,EACF;AAEA,MAAI,SAAS,WAAW;AACxB,aAAW,OAAO,WAAW,OAAO,GAAG;AACrC,aAAS,UAAU,QAAQ;AAAA,MACzB,OAAO,OAAO,IAAI,OAAO,MAAM,WAAW,IAAI,OAAO,IAAI;AAAA,MACzD,QAAQ,OAAO,IAAI,QAAQ,MAAM,WAAW,IAAI,QAAQ,IAAI;AAAA,MAC5D,gBAAgB,OAAO,IAAI,gBAAgB,MAAM,WAAW,IAAI,gBAAgB,IAAI;AAAA,MACpF,YAAY,OAAO,IAAI,YAAY,MAAM,WAAW,IAAI,YAAY,IAAI;AAAA,IAC1E,CAAC;AAAA,EACH;AACA,SAAO;AACT;AAkBO,SAAS,UAAU,MAA4B;AAEpD,QAAM,YAAuC,CAAC;AAC9C,aAAW,OAAO,MAAM;AACtB,QAAI,OAAO,QAAQ,YAAY,QAAQ,QAAQ,CAAC,MAAM,QAAQ,GAAG,GAAG;AAClE,gBAAU,KAAK,GAA8B;AAAA,IAC/C,OAAO;AACL,cAAQ,KAAK,kEAAkE,GAAG;AAAA,IACpF;AAAA,EACF;AAEA,MAAI,UAAU,WAAW,GAAG;AAC1B,WAAO,EAAE,QAAQ,WAAW,GAAG,QAAQ,QAAQ;AAAA,EACjD;AAEA,QAAM,YAAY,UAAU,OAAO,QAAQ;AAC3C,QAAM,WAAW,UAAU,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;AAGrD,MAAI,SAAS,WAAW,GAAG;AACzB,QAAIA,UAAS,WAAW;AACxB,eAAW,OAAO,WAAW;AAC3B,YAAM,IAAI,IAAI,OAAO;AACrB,MAAAA,UAAS,UAAUA,SAAQ,CAAC;AAAA,IAC9B;AACA,WAAO,EAAE,QAAAA,SAAQ,QAAQ,QAAQ;AAAA,EACnC;AAGA,MAAI,UAAU,WAAW,GAAG;AAC1B,UAAMA,UAAS,wBAAwB,QAAQ;AAC/C,WAAO;AAAA,MACL,QAAAA;AAAA,MACA,QAAQ;AAAA,MACR,eACE;AAAA,IAGJ;AAAA,EACF;AAKA,MAAI,SAAS,WAAW;AAGxB,aAAW,OAAO,WAAW;AAC3B,UAAM,IAAI,IAAI,OAAO;AACrB,aAAS,UAAU,QAAQ,CAAC;AAAA,EAC9B;AAGA,QAAM,aAAa,wBAAwB,QAAQ;AACnD,WAAS,UAAU,QAAQ,UAAU;AAErC,QAAM,SACJ,wBAAwB,UAAU,MAAM,iBAAiB,SAAS,MAAM;AAG1E,SAAO;AAAA,IACL;AAAA,IACA,QAAQ;AAAA,IACR,eAAe;AAAA,EACjB;AACF;","names":["totals"]}

package/dist/lib/ledger.d.cts

@@ -0,0 +1,64 @@
+/**
+ * ledger.ts — CR-018
+ *
+ * Sprint-wide cost math: parses token-ledger.jsonl rows and sums delta tokens
+ * for the Reporter agent. Distinct from ledger-reader.ts (per-work-item
+ * attribution lookup); this file provides sumDeltas() for sprint-total cost.
+ *
+ * Format detection handles three cases:
+ *   'delta'     — all rows carry delta.* blocks (post-0.9.0)
+ *   'pre-0.9.0' — all rows use flat input/output/cache_* fields (pre-0.9.0)
+ *   'mixed'     — some rows have delta, others don't (SPRINT-15 cutover window)
+ */
+/** Token counts block (used in both delta and session_total). */
+interface TokenCounts {
+    input: number;
+    output: number;
+    cache_creation: number;
+    cache_read: number;
+}
+/** Full post-0.9.0 ledger row shape. */
+interface LedgerRowV2 {
+    ts: string;
+    sprint_id: string;
+    story_id: string;
+    work_item_id: string;
+    agent_type: string;
+    session_id: string;
+    transcript?: string;
+    sentinel_started_at?: string;
+    delta_from_turn?: number;
+    delta: TokenCounts;
+    session_total: TokenCounts;
+    model: string;
+    turns: number;
+}
+/** Result returned by sumDeltas(). */
+interface SumResult {
+    /** Aggregated token totals across all rows (using appropriate format). */
+    totals: TokenCounts;
+    /** How the totals were computed. */
+    format: 'delta' | 'pre-0.9.0' | 'mixed';
+    /**
+     * Present when format is 'pre-0.9.0' or 'mixed'.
+     * Reporter should paste this verbatim into REPORT.md §3.
+     */
+    pre_v2_caveat?: string;
+}
+/**
+ * Compute sprint-wide token totals from an array of raw ledger rows (parsed JSONL).
+ *
+ * Format-detection algorithm (mandatory):
+ *   1. Classify each row: has `delta` object with 4 numeric fields → v2; else → flat/legacy.
+ *   2. All v2       → format='delta',    sum delta.* directly.
+ *   3. All flat     → format='pre-0.9.0', group by session_id, last-row-per-session trick.
+ *   4. Mixed        → format='mixed',    delta rows contribute delta.*; flat rows within
+ *                     each session use last-row trick scoped to flat rows only.
+ *
+ * Malformed or unrecognisable rows are skipped with a console.warn.
+ *
+ * @param rows  Array of parsed JSON objects (unknown type for defensive parsing).
+ */
+declare function sumDeltas(rows: unknown[]): SumResult;
+
+export { type LedgerRowV2, type SumResult, type TokenCounts, sumDeltas };

package/dist/lib/ledger.d.ts

@@ -0,0 +1,64 @@
+/**
+ * ledger.ts — CR-018
+ *
+ * Sprint-wide cost math: parses token-ledger.jsonl rows and sums delta tokens
+ * for the Reporter agent. Distinct from ledger-reader.ts (per-work-item
+ * attribution lookup); this file provides sumDeltas() for sprint-total cost.
+ *
+ * Format detection handles three cases:
+ *   'delta'     — all rows carry delta.* blocks (post-0.9.0)
+ *   'pre-0.9.0' — all rows use flat input/output/cache_* fields (pre-0.9.0)
+ *   'mixed'     — some rows have delta, others don't (SPRINT-15 cutover window)
+ */
+/** Token counts block (used in both delta and session_total). */
+interface TokenCounts {
+    input: number;
+    output: number;
+    cache_creation: number;
+    cache_read: number;
+}
+/** Full post-0.9.0 ledger row shape. */
+interface LedgerRowV2 {
+    ts: string;
+    sprint_id: string;
+    story_id: string;
+    work_item_id: string;
+    agent_type: string;
+    session_id: string;
+    transcript?: string;
+    sentinel_started_at?: string;
+    delta_from_turn?: number;
+    delta: TokenCounts;
+    session_total: TokenCounts;
+    model: string;
+    turns: number;
+}
+/** Result returned by sumDeltas(). */
+interface SumResult {
+    /** Aggregated token totals across all rows (using appropriate format). */
+    totals: TokenCounts;
+    /** How the totals were computed. */
+    format: 'delta' | 'pre-0.9.0' | 'mixed';
+    /**
+     * Present when format is 'pre-0.9.0' or 'mixed'.
+     * Reporter should paste this verbatim into REPORT.md §3.
+     */
+    pre_v2_caveat?: string;
+}
+/**
+ * Compute sprint-wide token totals from an array of raw ledger rows (parsed JSONL).
+ *
+ * Format-detection algorithm (mandatory):
+ *   1. Classify each row: has `delta` object with 4 numeric fields → v2; else → flat/legacy.
+ *   2. All v2       → format='delta',    sum delta.* directly.
+ *   3. All flat     → format='pre-0.9.0', group by session_id, last-row-per-session trick.
+ *   4. Mixed        → format='mixed',    delta rows contribute delta.*; flat rows within
+ *                     each session use last-row trick scoped to flat rows only.
+ *
+ * Malformed or unrecognisable rows are skipped with a console.warn.
+ *
+ * @param rows  Array of parsed JSON objects (unknown type for defensive parsing).
+ */
+declare function sumDeltas(rows: unknown[]): SumResult;
+
+export { type LedgerRowV2, type SumResult, type TokenCounts, sumDeltas };

package/dist/lib/ledger.js

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+
+// src/lib/ledger.ts
+function isTokenCounts(v) {
+  if (typeof v !== "object" || v === null) return false;
+  const obj = v;
+  return typeof obj["input"] === "number" && typeof obj["output"] === "number" && typeof obj["cache_creation"] === "number" && typeof obj["cache_read"] === "number";
+}
+function hasDelta(row) {
+  return isTokenCounts(row["delta"]);
+}
+function zeroCounts() {
+  return { input: 0, output: 0, cache_creation: 0, cache_read: 0 };
+}
+function addCounts(a, b) {
+  return {
+    input: a.input + b.input,
+    output: a.output + b.output,
+    cache_creation: a.cache_creation + b.cache_creation,
+    cache_read: a.cache_read + b.cache_read
+  };
+}
+function lastRowTrickForFlatRows(rows) {
+  const sessionMap = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    const sessionId = typeof row["session_id"] === "string" ? row["session_id"] : "(unknown)";
+    const existing = sessionMap.get(sessionId);
+    if (!existing) {
+      sessionMap.set(sessionId, row);
+    } else {
+      const existingTs = typeof existing["ts"] === "string" ? existing["ts"] : "";
+      const rowTs = typeof row["ts"] === "string" ? row["ts"] : "";
+      if (rowTs > existingTs) {
+        sessionMap.set(sessionId, row);
+      }
+    }
+  }
+  let totals = zeroCounts();
+  for (const row of sessionMap.values()) {
+    totals = addCounts(totals, {
+      input: typeof row["input"] === "number" ? row["input"] : 0,
+      output: typeof row["output"] === "number" ? row["output"] : 0,
+      cache_creation: typeof row["cache_creation"] === "number" ? row["cache_creation"] : 0,
+      cache_read: typeof row["cache_read"] === "number" ? row["cache_read"] : 0
+    });
+  }
+  return totals;
+}
+function sumDeltas(rows) {
+  const validRows = [];
+  for (const raw of rows) {
+    if (typeof raw === "object" && raw !== null && !Array.isArray(raw)) {
+      validRows.push(raw);
+    } else {
+      console.warn("[ledger.ts] sumDeltas: skipping malformed row (not an object):", raw);
+    }
+  }
+  if (validRows.length === 0) {
+    return { totals: zeroCounts(), format: "delta" };
+  }
+  const deltaRows = validRows.filter(hasDelta);
+  const flatRows = validRows.filter((r) => !hasDelta(r));
+  if (flatRows.length === 0) {
+    let totals2 = zeroCounts();
+    for (const row of deltaRows) {
+      const d = row["delta"];
+      totals2 = addCounts(totals2, d);
+    }
+    return { totals: totals2, format: "delta" };
+  }
+  if (deltaRows.length === 0) {
+    const totals2 = lastRowTrickForFlatRows(flatRows);
+    return {
+      totals: totals2,
+      format: "pre-0.9.0",
+      pre_v2_caveat: "**Ledger format note:** This sprint's token-ledger.jsonl uses pre-0.9.0 flat-field rows; cost is computed via the last-row-per-session trick (reconciliation accuracy \xB1N \xD7 real-cost where N = SubagentStop fires per session)."
+    };
+  }
+  let totals = zeroCounts();
+  for (const row of deltaRows) {
+    const d = row["delta"];
+    totals = addCounts(totals, d);
+  }
+  const flatTotals = lastRowTrickForFlatRows(flatRows);
+  totals = addCounts(totals, flatTotals);
+  const caveat = `Mixed format ledger: ${deltaRows.length} delta rows + ${flatRows.length} pre-0.9.0 rows; flat segment uses last-row trick.`;
+  return {
+    totals,
+    format: "mixed",
+    pre_v2_caveat: caveat
+  };
+}
+export {
+  sumDeltas
+};
+//# sourceMappingURL=ledger.js.map

package/dist/lib/ledger.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/lib/ledger.ts"],"sourcesContent":["/**\n * ledger.ts — CR-018\n *\n * Sprint-wide cost math: parses token-ledger.jsonl rows and sums delta tokens\n * for the Reporter agent. Distinct from ledger-reader.ts (per-work-item\n * attribution lookup); this file provides sumDeltas() for sprint-total cost.\n *\n * Format detection handles three cases:\n *   'delta'     — all rows carry delta.* blocks (post-0.9.0)\n *   'pre-0.9.0' — all rows use flat input/output/cache_* fields (pre-0.9.0)\n *   'mixed'     — some rows have delta, others don't (SPRINT-15 cutover window)\n */\n\n// ─── Public types ─────────────────────────────────────────────────────────────\n\n/** Token counts block (used in both delta and session_total). */\nexport interface TokenCounts {\n  input: number;\n  output: number;\n  cache_creation: number;\n  cache_read: number;\n}\n\n/** Full post-0.9.0 ledger row shape. */\nexport interface LedgerRowV2 {\n  ts: string;\n  sprint_id: string;\n  story_id: string;\n  work_item_id: string;\n  agent_type: string;\n  session_id: string;\n  transcript?: string;\n  sentinel_started_at?: string;\n  delta_from_turn?: number;\n  delta: TokenCounts;\n  session_total: TokenCounts;\n  model: string;\n  turns: number;\n}\n\n/** Result returned by sumDeltas(). */\nexport interface SumResult {\n  /** Aggregated token totals across all rows (using appropriate format). */\n  totals: TokenCounts;\n  /** How the totals were computed. */\n  format: 'delta' | 'pre-0.9.0' | 'mixed';\n  /**\n   * Present when format is 'pre-0.9.0' or 'mixed'.\n   * Reporter should paste this verbatim into REPORT.md §3.\n   */\n  pre_v2_caveat?: string;\n}\n\n// ─── Internal helpers ─────────────────────────────────────────────────────────\n\nfunction isTokenCounts(v: unknown): v is TokenCounts {\n  if (typeof v !== 'object' || v === null) return false;\n  const obj = v as Record<string, unknown>;\n  return (\n    typeof obj['input'] === 'number' &&\n    typeof obj['output'] === 'number' &&\n    typeof obj['cache_creation'] === 'number' &&\n    typeof obj['cache_read'] === 'number'\n  );\n}\n\nfunction hasDelta(row: Record<string, unknown>): boolean {\n  return isTokenCounts(row['delta']);\n}\n\nfunction zeroCounts(): TokenCounts {\n  return { input: 0, output: 0, cache_creation: 0, cache_read: 0 };\n}\n\nfunction addCounts(a: TokenCounts, b: TokenCounts): TokenCounts {\n  return {\n    input: a.input + b.input,\n    output: a.output + b.output,\n    cache_creation: a.cache_creation + b.cache_creation,\n    cache_read: a.cache_read + b.cache_read,\n  };\n}\n\n/**\n * Last-row-per-session trick for pre-0.9.0 flat-field rows.\n * Groups rows by session_id, takes the row with max ts per group,\n * and sums the flat input/output/cache_* fields across those last rows.\n */\nfunction lastRowTrickForFlatRows(rows: Record<string, unknown>[]): TokenCounts {\n  const sessionMap = new Map<string, Record<string, unknown>>();\n\n  for (const row of rows) {\n    const sessionId = typeof row['session_id'] === 'string' ? row['session_id'] : '(unknown)';\n    const existing = sessionMap.get(sessionId);\n    if (!existing) {\n      sessionMap.set(sessionId, row);\n    } else {\n      const existingTs = typeof existing['ts'] === 'string' ? existing['ts'] : '';\n      const rowTs = typeof row['ts'] === 'string' ? row['ts'] : '';\n      if (rowTs > existingTs) {\n        sessionMap.set(sessionId, row);\n      }\n    }\n  }\n\n  let totals = zeroCounts();\n  for (const row of sessionMap.values()) {\n    totals = addCounts(totals, {\n      input: typeof row['input'] === 'number' ? row['input'] : 0,\n      output: typeof row['output'] === 'number' ? row['output'] : 0,\n      cache_creation: typeof row['cache_creation'] === 'number' ? row['cache_creation'] : 0,\n      cache_read: typeof row['cache_read'] === 'number' ? row['cache_read'] : 0,\n    });\n  }\n  return totals;\n}\n\n// ─── Public API ───────────────────────────────────────────────────────────────\n\n/**\n * Compute sprint-wide token totals from an array of raw ledger rows (parsed JSONL).\n *\n * Format-detection algorithm (mandatory):\n *   1. Classify each row: has `delta` object with 4 numeric fields → v2; else → flat/legacy.\n *   2. All v2       → format='delta',    sum delta.* directly.\n *   3. All flat     → format='pre-0.9.0', group by session_id, last-row-per-session trick.\n *   4. Mixed        → format='mixed',    delta rows contribute delta.*; flat rows within\n *                     each session use last-row trick scoped to flat rows only.\n *\n * Malformed or unrecognisable rows are skipped with a console.warn.\n *\n * @param rows  Array of parsed JSON objects (unknown type for defensive parsing).\n */\nexport function sumDeltas(rows: unknown[]): SumResult {\n  // Filter to recognisable objects; skip malformed rows.\n  const validRows: Record<string, unknown>[] = [];\n  for (const raw of rows) {\n    if (typeof raw === 'object' && raw !== null && !Array.isArray(raw)) {\n      validRows.push(raw as Record<string, unknown>);\n    } else {\n      console.warn('[ledger.ts] sumDeltas: skipping malformed row (not an object):', raw);\n    }\n  }\n\n  if (validRows.length === 0) {\n    return { totals: zeroCounts(), format: 'delta' };\n  }\n\n  const deltaRows = validRows.filter(hasDelta);\n  const flatRows = validRows.filter((r) => !hasDelta(r));\n\n  // All rows are v2 (delta) format\n  if (flatRows.length === 0) {\n    let totals = zeroCounts();\n    for (const row of deltaRows) {\n      const d = row['delta'] as TokenCounts;\n      totals = addCounts(totals, d);\n    }\n    return { totals, format: 'delta' };\n  }\n\n  // All rows are pre-0.9.0 flat format\n  if (deltaRows.length === 0) {\n    const totals = lastRowTrickForFlatRows(flatRows);\n    return {\n      totals,\n      format: 'pre-0.9.0',\n      pre_v2_caveat:\n        '**Ledger format note:** This sprint\\'s token-ledger.jsonl uses pre-0.9.0 flat-field rows; ' +\n        'cost is computed via the last-row-per-session trick ' +\n        '(reconciliation accuracy ±N × real-cost where N = SubagentStop fires per session).',\n    };\n  }\n\n  // Mixed format: both delta rows and flat rows in same ledger (e.g. SPRINT-15 cutover)\n  // Delta rows → sum delta.*\n  // Flat rows  → group by session_id, last-row trick (scoped to flat rows only)\n  let totals = zeroCounts();\n\n  // Sum delta rows directly\n  for (const row of deltaRows) {\n    const d = row['delta'] as TokenCounts;\n    totals = addCounts(totals, d);\n  }\n\n  // Apply last-row trick to flat rows\n  const flatTotals = lastRowTrickForFlatRows(flatRows);\n  totals = addCounts(totals, flatTotals);\n\n  const caveat =\n    `Mixed format ledger: ${deltaRows.length} delta rows + ${flatRows.length} pre-0.9.0 rows; ` +\n    `flat segment uses last-row trick.`;\n\n  return {\n    totals,\n    format: 'mixed',\n    pre_v2_caveat: caveat,\n  };\n}\n"],"mappings":"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","names":["totals"]}