segreant 0.1.0 → 0.2.0

package/dist/store/realization.js

@@ -17,10 +17,12 @@
  */
 import { runScript } from './schema.js';
 import { pricingEvidenceFromRecord } from './rows.js';
+import { formatMoneyAmount, money } from '../economics/money.js';
 import { requestEconomicEventId } from '../economics/request.js';
 import { priceCorrectionEvent } from '../economics/corrections.js';
 import { economicAttributionFromRows, economicAttributionNumber } from '../economics/attribution.js';
 import { canonicalModelAttribution } from './economicReadModel.js';
+import { evidenceMatcher, modelSpendFromRows, parseScopeEvidence } from './scopeEvidence.js';
 export function saveReceipt(db, r) {
     db
         .prepare(`INSERT INTO receipts (unit, project, ts_epoch_ms, realized, receipt_json)
@@ -90,13 +92,25 @@ export function realizationProjects(db) {
 }
 /** Every row priced with a fallback/family-match rate — the reprice candidates. */
 export function estimatedRequestRows(db) {
-    return db
+    const rows = db
         .prepare(`SELECT request_id AS requestId, provider, model,
                 input_tokens AS inputTokens, output_tokens AS outputTokens,
                 cache_write_tokens AS cacheWriteTokens, cache_read_tokens AS cacheReadTokens,
-                cost_usd AS costUsd
-         FROM requests WHERE estimated = 1`)
+                CASE WHEN cache_write_ttl IN ('5m', '1h') THEN cache_write_ttl END AS cacheWriteTtl,
+                cost_usd AS costUsd,
+                -- An unpriced row with no token counts has no captured usage to
+                -- price (a response cut off at the resource limit): repricing it
+                -- wrote a confirmed $0 list price over an unknown cost
+                -- (independent review, 2026-10-18). It stays in the report as an
+                -- untouched estimate; only the write plan skips it (PR #150
+                -- review). An unpriced row WITH token counts stays repriceable.
+                CASE WHEN cost_basis = 'unpriced'
+                      AND input_tokens + output_tokens + cache_write_tokens + cache_read_tokens = 0
+                     THEN 0 ELSE 1 END AS usageCaptured
+         FROM requests
+         WHERE estimated = 1 AND cost_basis <> 'not_sent'`)
         .all();
+    return rows.map((r) => ({ ...r, usageCaptured: r.usageCaptured === 1 }));
 }
 /**
  * Re-cost estimated rows in one transaction and retain the previous
@@ -113,10 +127,15 @@ export function estimatedRequestRows(db) {
  * left marked stale for disclosure instead of being recomputed on a guess.
  */
 export function applyRepricedCosts(db, deps, updates, appliedAtMs) {
-    const prior = db.prepare(`SELECT cost_usd AS costUsd, estimated, ts_epoch_ms AS tsEpochMs, project,
-              cost_basis AS CostBasis, rate_card_sha256 AS RateCardSha256,
-              rate_card_source_kind AS RateCardSourceKind, rate_match_kind AS RateMatchKind,
-              rate_match_provider AS RateMatchProvider, rate_match_model AS RateMatchModel
+    const prior = db.prepare(
+    // camelCase, which is what pricingEvidenceFromRecord reads with no prefix.
+    // These were aliased CostBasis/RateCardSha256/..., so every reprice event
+    // recorded legacy_unknown as the provenance it replaced (independent review,
+    // 2026-10-18).
+    `SELECT cost_usd AS costUsd, estimated, ts_epoch_ms AS tsEpochMs, project,
+              cost_basis AS costBasis, rate_card_sha256 AS rateCardSha256,
+              rate_card_source_kind AS rateCardSourceKind, rate_match_kind AS rateMatchKind,
+              rate_match_provider AS rateMatchProvider, rate_match_model AS rateMatchModel
        FROM requests WHERE request_id = ?`);
     const update = db.prepare(`UPDATE requests
        SET cost_usd = ?, estimated = 0,
@@ -131,6 +150,9 @@ export function applyRepricedCosts(db, deps, updates, appliedAtMs) {
          new_rate_card_source_kind, new_rate_match_kind, new_rate_match_provider, new_rate_match_model
        ) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)`);
     const touched = [];
+    // Which requests this transaction actually rewrote, so a caller reports
+    // those and not its plan (PR #146 review).
+    const writtenRequestIds = [];
     runScript(db, 'BEGIN');
     try {
         for (const u of updates) {
@@ -143,11 +165,22 @@ export function applyRepricedCosts(db, deps, updates, appliedAtMs) {
                     throw new Error(`exact reprice for request ${u.requestId} requires an exact replacement amount`);
                 }
                 const recordedAt = new Date(appliedAtMs).toISOString();
+                // A correction keeps its source's basis: the economic ledger never
+                // moves an amount from one kind of evidence to another. An estimate
+                // repriced at a list rate is recorded as that estimate, corrected to the
+                // exact figure; the request row itself says which rate priced it. Without
+                // this, every fallback row on an exact ledger refused to reprice
+                // (PR #146 review). Re-labelling the other way would claim more
+                // certainty than the source event carries.
+                const source = exactSource.amount;
+                const nextAmount = u.economicAmount.basis === source.basis
+                    ? u.economicAmount
+                    : money(formatMoneyAmount(u.economicAmount), u.economicAmount.currency, source.basis);
                 const correction = priceCorrectionEvent({
                     id: `economic:request:${u.requestId}:price-corrected`,
                     source: exactSource,
-                    previousAmount: exactSource.amount,
-                    nextAmount: u.economicAmount,
+                    previousAmount: source,
+                    nextAmount,
                     recordedAt,
                 });
                 deps.economicLedger.appendWithinTransaction(correction);
@@ -158,10 +191,11 @@ export function applyRepricedCosts(db, deps, updates, appliedAtMs) {
                 continue;
             event.run(u.requestId, 'reprice', appliedAtMs, Number(old.costUsd), Boolean(old.estimated) ? 1 : 0, oldPricing.costBasis, oldPricing.rateCardSha256, oldPricing.rateCardSourceKind, oldPricing.rateMatchKind, oldPricing.rateMatchProvider, oldPricing.rateMatchModel, u.costUsd, 0, u.pricing.costBasis, u.pricing.rateCardSha256, u.pricing.rateCardSourceKind, u.pricing.rateMatchKind, u.pricing.rateMatchProvider, u.pricing.rateMatchModel);
             touched.push({ tsEpochMs: Number(old.tsEpochMs), project: String(old.project) });
+            writtenRequestIds.push(u.requestId);
         }
         const sync = syncRealizationCosts(db, deps, touched);
         runScript(db, 'COMMIT');
-        return sync;
+        return { ...sync, writtenRequestIds };
     }
     catch (e) {
         runScript(db, 'ROLLBACK');
@@ -234,7 +268,11 @@ function syncRealizationCosts(db, deps, repriced) {
         if (scope === 'synthetic_demo')
             continue;
         const unitProject = canon(row.project);
-        const affected = priced.some((p) => p.tsEpochMs >= startMs && p.tsEpochMs < endMs && (scope !== 'project' || p.project === unitProject));
+        const evidence = scope === 'project' ? parseScopeEvidence(unit.spendScope) : undefined;
+        // A unit scoped by evidence also absorbed linked sessions' and folders' spend
+        // under other labels, so any repriced request in its window may touch it.
+        const affected = priced.some((p) => p.tsEpochMs >= startMs && p.tsEpochMs < endMs
+            && (scope !== 'project' || evidence !== undefined || p.project === unitProject));
         if (!affected)
             continue;
         out.markedStale += 1;
@@ -243,10 +281,36 @@ function syncRealizationCosts(db, deps, repriced) {
             out.unresolvable += 1;
             continue;
         }
+        if (evidence !== undefined && deps.requestsInRange === undefined) {
+            // The rule that produced these dollars cannot be re-run here: disclose.
+            markStale.run(row.commitHash);
+            out.unresolvable += 1;
+            continue;
+        }
         const scoped = scope === 'project' ? row.project : undefined;
-        const spend = deps.summary(startMs, endMs, scoped);
-        const modelSpend = deps.byModel(startMs, endMs, scoped);
-        const economicRows = deps.economicRequestRows?.(startMs, endMs, scoped);
+        let spend;
+        let modelSpend;
+        let economicRows;
+        if (evidence !== undefined) {
+            const linked = evidenceMatcher(evidence);
+            const rows = deps.requestsInRange(startMs, endMs)
+                .filter((r) => canon(r.projectCanonical ?? r.project) === unitProject || linked(r));
+            const ids = new Set(rows.map((r) => r.requestId));
+            spend = {
+                label: row.project,
+                costUsd: rows.reduce((s, r) => s + r.costUsd, 0),
+                requests: rows.length,
+                inputTokens: rows.reduce((s, r) => s + r.inputTokens, 0),
+                outputTokens: rows.reduce((s, r) => s + r.outputTokens, 0),
+            };
+            modelSpend = modelSpendFromRows(rows);
+            economicRows = deps.economicRequestRows?.(startMs, endMs, undefined).filter((r) => ids.has(r.requestId));
+        }
+        else {
+            spend = deps.summary(startMs, endMs, scoped);
+            modelSpend = deps.byModel(startMs, endMs, scoped);
+            economicRows = deps.economicRequestRows?.(startMs, endMs, scoped);
+        }
         const economic = economicRows === undefined ? undefined : economicAttributionFromRows(economicRows);
         const modelAuthority = economicRows === undefined ? undefined : canonicalModelAttribution(economicRows);
         const totalLines = Number(unit.linesAdded ?? 0) + Number(unit.linesDeleted ?? 0);

package/dist/store/schema.js

@@ -59,7 +59,8 @@ CREATE TABLE IF NOT EXISTS requests (
   scope_capture_status TEXT NOT NULL DEFAULT 'legacy_unknown',
   provider_scope_declaration_id TEXT,
   attribution_basis TEXT NOT NULL DEFAULT 'legacy_unknown',
-  capture_coverage TEXT NOT NULL DEFAULT 'legacy_unknown'
+  capture_coverage TEXT NOT NULL DEFAULT 'legacy_unknown',
+  cache_write_ttl   TEXT NOT NULL DEFAULT 'legacy_unknown'
 );
 
 CREATE INDEX IF NOT EXISTS idx_requests_ts      ON requests(ts_epoch_ms);
@@ -236,10 +237,46 @@ CREATE TABLE IF NOT EXISTS import_file_cursors (
   mtime_ms INTEGER NOT NULL,
   truncated_lines INTEGER NOT NULL DEFAULT 0,
   truncated_rows  INTEGER NOT NULL DEFAULT 0,
+  reader_version  INTEGER NOT NULL DEFAULT 1,
   at_ms    INTEGER NOT NULL,
   PRIMARY KEY (source, path)
 );
 
+-- A git commit an agent session reported making, read from the session's own
+-- log (git prints "[branch sha] subject" when it creates a commit). This is an
+-- observation, not yet a fact about any repository: realization accepts it only
+-- when the sha exists in the repo, the subject matches and the times agree.
+CREATE TABLE IF NOT EXISTS observed_commits (
+  source      TEXT NOT NULL,
+  session_id  TEXT NOT NULL,
+  short_sha   TEXT NOT NULL,
+  branch      TEXT NOT NULL,
+  subject     TEXT NOT NULL,
+  ts_epoch_ms INTEGER NOT NULL,
+  cwd         TEXT,
+  -- How the line was recognised. NULL rows came from a reader that matched a
+  -- commit line anywhere, code fixtures included. The migration drops them, and
+  -- the next import re-reads every log under the strict rule.
+  extraction  TEXT,
+  PRIMARY KEY (source, session_id, short_sha)
+);
+CREATE INDEX IF NOT EXISTS idx_observed_commits_sha ON observed_commits(short_sha);
+
+-- The vendors' own usage meters, as their tools log them (src/quota/limits.ts):
+-- Codex's rate-limit percentages when they change, Claude's limit messages.
+-- Evidence of what the vendor said, kept apart from Segreant's own count.
+CREATE TABLE IF NOT EXISTS quota_events (
+  source         TEXT NOT NULL,
+  kind           TEXT NOT NULL,
+  ts_epoch_ms    INTEGER NOT NULL,
+  used_percent   REAL,
+  window_minutes INTEGER,
+  resets_at_ms   INTEGER,
+  detail         TEXT,
+  PRIMARY KEY (source, kind, ts_epoch_ms)
+);
+CREATE INDEX IF NOT EXISTS idx_quota_events_ts ON quota_events(ts_epoch_ms);
+
 -- What retention deleted, so an absence can be told from a deletion.
 --
 -- prune used to run one DELETE, print a count, and leave nothing behind. A
@@ -1116,10 +1153,25 @@ function validateAppendOnlyTriggerAuthority(db) {
 }
 /** Idempotent schema migrations for DBs created before a column existed. */
 function migrate(db) {
+    // Commit observations made by the loose reader cannot be re-judged: the line
+    // around each match was not kept. They are dropped once, and IMPORT_READER_
+    // VERSION 4 makes the next import read every log again under the strict rule.
+    const observedCols = db.prepare('PRAGMA table_info(observed_commits)').all();
+    if (observedCols.length > 0 && !observedCols.some((c) => c.name === 'extraction')) {
+        db.prepare('ALTER TABLE observed_commits ADD COLUMN extraction TEXT').run();
+        db.prepare('DELETE FROM observed_commits WHERE extraction IS NULL').run();
+    }
     const cols = db.prepare('PRAGMA table_info(requests)').all();
     if (!cols.some((c) => c.name === 'user')) {
         db.prepare('ALTER TABLE requests ADD COLUMN user TEXT').run();
     }
+    if (!cols.some((c) => c.name === 'cache_write_ttl')) {
+        // The cache-write duration ('5m' or '1h') a request was priced with;
+        // 'not_recorded' when its source did not say. No backfill: an older row
+        // reads 'legacy_unknown', and a reprice says how many rows it priced at the
+        // 5-minute rate for that reason (PR #146 review).
+        db.prepare("ALTER TABLE requests ADD COLUMN cache_write_ttl TEXT NOT NULL DEFAULT 'legacy_unknown'").run();
+    }
     if (!cols.some((c) => c.name === 'source')) {
         db.prepare('ALTER TABLE requests ADD COLUMN source TEXT').run();
     }
@@ -1219,6 +1271,12 @@ function migrate(db) {
         // column exists to prevent. Unknown stays unknown.
         db.prepare("ALTER TABLE openai_cost_observation_runs ADD COLUMN source_kind TEXT NOT NULL DEFAULT 'legacy_unknown'").run();
     }
+    const cursorCols = db.prepare('PRAGMA table_info(import_file_cursors)').all();
+    if (cursorCols.length > 0 && !cursorCols.some((c) => c.name === 'reader_version')) {
+        // Cursors written before readers learned to capture commits: version 1, so
+        // their files are read once more by the current reader.
+        db.prepare('ALTER TABLE import_file_cursors ADD COLUMN reader_version INTEGER NOT NULL DEFAULT 1').run();
+    }
     const signalCols = db.prepare('PRAGMA table_info(gate_signals)').all();
     if (!signalCols.some((c) => c.name === 'evidence_source')) {
         db.prepare("ALTER TABLE gate_signals ADD COLUMN evidence_source TEXT NOT NULL DEFAULT 'manual'").run();

package/dist/store/scopeEvidence.js

@@ -0,0 +1,67 @@
+/**
+ * The evidence a value snapshot's dollars were scoped by beyond its project
+ * label: the agent sessions and the folders that verifiably made commits in the
+ * repository (see git/repoScope.ts for how that evidence is accepted).
+ *
+ * A snapshot records the evidence its own window used (`unit.spendScope`), so a
+ * later reprice re-sums exactly the same rows by exactly the same rule instead
+ * of falling back to the label and quietly dropping the linked spend. Pure: no
+ * git, no I/O, so the store layer can apply it.
+ */
+import { resolve } from 'node:path';
+/** Normalize a path for prefix comparison (Windows paths compare case-insensitively). */
+export function normPath(p) {
+    const r = resolve(p).replace(/[\\/]+/g, '/').replace(/\/$/, '');
+    return process.platform === 'win32' ? r.toLowerCase() : r;
+}
+export function pathUnder(path, root) {
+    return path === root || path.startsWith(root + '/');
+}
+/** A matcher for rows the evidence covers (the label is checked by the caller). */
+export function evidenceMatcher(ev) {
+    const sessions = new Set(ev.sessions);
+    const roots = ev.folders.map(normPath);
+    return (row) => {
+        if (row.sessionId !== null && sessions.has(row.sessionId))
+            return true;
+        if (row.cwd) {
+            const c = normPath(row.cwd);
+            if (roots.some((root) => pathUnder(c, root)))
+                return true;
+        }
+        return false;
+    };
+}
+/** Read evidence back from a persisted snapshot; anything malformed is absent. */
+export function parseScopeEvidence(value) {
+    if (value === null || typeof value !== 'object')
+        return undefined;
+    const v = value;
+    const strings = (x) => Array.isArray(x) && x.every((s) => typeof s === 'string') ? x : null;
+    const sessions = strings(v.sessions);
+    const folders = strings(v.folders);
+    if (sessions === null || folders === null)
+        return undefined;
+    if (sessions.length === 0 && folders.length === 0)
+        return undefined;
+    return { sessions, folders };
+}
+/** The `byModel` shape, grouped from already-scoped rows (same order: cost, descending). */
+export function modelSpendFromRows(rows) {
+    const groups = new Map();
+    for (const r of rows) {
+        const key = `${r.provider}\0${r.model}`;
+        const g = groups.get(key) ?? {
+            provider: r.provider, label: r.model, costUsd: 0, requests: 0, inputTokens: 0, outputTokens: 0,
+            cacheReadTokens: 0, cacheWriteTokens: 0,
+        };
+        g.costUsd += r.costUsd;
+        g.requests += 1;
+        g.inputTokens += r.inputTokens;
+        g.outputTokens += r.outputTokens;
+        g.cacheReadTokens += r.cacheReadTokens;
+        g.cacheWriteTokens += r.cacheWriteTokens;
+        groups.set(key, g);
+    }
+    return [...groups.values()].sort((a, b) => b.costUsd - a.costUsd);
+}

package/dist/util/pool.js

@@ -0,0 +1,19 @@
+/**
+ * Map over items with at most `limit` calls in flight, keeping input order.
+ *
+ * Most of what the value stage does per repository is waiting on a git child
+ * process, so a few at once finish far sooner than one after another, and a
+ * bound keeps a machine with fifty repositories from spawning fifty gits.
+ */
+export async function mapLimit(items, limit, fn) {
+    const out = new Array(items.length);
+    let next = 0;
+    const lane = async () => {
+        while (next < items.length) {
+            const i = next++;
+            out[i] = await fn(items[i], i);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.max(1, Math.min(limit, items.length)) }, lane));
+    return out;
+}

package/dist/util/time.js

@@ -0,0 +1,7 @@
+/** Recorded evidence timestamps use zero as an unknown sentinel, never epoch. */
+export function recordedTime(ms, dayOnly = false) {
+    if (typeof ms !== 'number' || !Number.isFinite(ms) || ms <= 0 || ms > 8.64e15)
+        return 'unknown';
+    const iso = new Date(ms).toISOString();
+    return dayOnly ? iso.slice(0, 10) : iso;
+}