segreant 0.1.0 → 0.2.0

package/dist/store/allocation.js

@@ -179,6 +179,20 @@ export function allocationRuns(db, limit) {
         result: JSON.parse(String(row.resultJson)),
     }));
 }
+/** One recorded run, exactly as stored, or null when no run has that id. */
+export function allocationRunById(db, allocationRunId) {
+    const row = db
+        .prepare(`SELECT allocation_run_id AS allocationRunId, computed_at_ms AS computedAtMs, result_json AS resultJson
+         FROM allocation_runs WHERE allocation_run_id = ?`)
+        .get(allocationRunId);
+    if (row === undefined)
+        return null;
+    return {
+        allocationRunId: String(row.allocationRunId),
+        computedAtMs: Number(row.computedAtMs),
+        result: JSON.parse(String(row.resultJson)),
+    };
+}
 function exactRunId(serialized) {
     return `economic:allocation:${serialized.digest.slice('sha256:'.length)}`;
 }

package/dist/store/db.js

@@ -27,6 +27,7 @@ import { canonicalJson } from '../epistemic/serialization.js';
 import { RESOURCE_LIMITS } from '../util/resource-limits.js';
 import { transact, writeBatch } from '../util/transaction.js';
 import { ATTRIBUTION_BASES } from '../value/characterization.js';
+import { isOnDeclaredRoute, quantizeLocalDays } from '../billing/reconcile.js';
 import { buildExactAllocationKernelIssuance } from '../alloc/epistemic.js';
 import { bindCodingRealizationSuccessor, buildCodingRealizationKernelIssuance, codingRealizationKernelEligible } from '../value/epistemic.js';
 import * as allocation from './allocation.js';
@@ -58,10 +59,31 @@ const EXACT_SPEND_CACHE_KEYS = 64;
  * "+275760-...", which sorts BEFORE every ordinary timestamp.
  */
 const MAX_DATE_MS = Date.UTC(9999, 11, 31, 23, 59, 59, 999);
+/** Every RequestRow column, alias-canonical label included; callers add WHERE and ORDER BY. */
+const REQUEST_ROW_SELECT = `SELECT request_id AS requestId, session_id AS sessionId, ts_epoch_ms AS tsEpochMs,
+                provider, model, r.project AS project,
+                COALESCE(a.canonical, r.project) AS projectCanonical, task_weight AS taskWeight,
+                input_tokens AS inputTokens, output_tokens AS outputTokens,
+                cache_write_tokens AS cacheWriteTokens, cache_read_tokens AS cacheReadTokens,
+                reasoning_tokens AS reasoningTokens, cost_usd AS costUsd,
+                estimated, streamed, status_code AS statusCode, duration_ms AS durationMs, user, source, cwd, via,
+                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,
+                scope_capture_status AS scopeCaptureStatus,
+                provider_scope_declaration_id AS providerScopeDeclarationId,
+                attribution_basis AS attributionBasis,
+                capture_coverage AS captureCoverage, cache_write_ttl AS cacheWriteTtlRecorded
+         FROM requests r LEFT JOIN project_aliases a ON a.alias = r.project`;
 /**
  * Merge a few new ids into an already sorted list, in the same order
  * `Array.prototype.sort()` gives strings. Re-sorting the whole list on every
  * extension made each proxied request cost O(n log n) in the day's events.
+ *
+ * Cost note: the merge still copies the whole cached id list on every extension,
+ * so the memory copied per append grows with the events a projection retains.
+ * That growth is not O(1) and is not asserted as such; it is measured separately.
+ * The work counters in exactSpendWorkCounters() count rows read, not bytes copied.
  */
 function mergeSortedIds(sorted, added) {
     if (added.length === 0)
@@ -83,10 +105,15 @@ function mergeSortedIds(sorted, added) {
 const REQUEST_CHARGE_KINDS = new Set(['charge_estimated', 'provider_charge_observed', 'bill_observed']);
 const SCOPE_CAPTURE_STATUSES = ['legacy_unknown', 'unscoped', 'declared_unverified', 'not_observed'];
 const CAPTURE_COVERAGES = ['complete', 'truncated', 'unknown', 'legacy_unknown'];
+const CACHE_WRITE_TTLS = ['5m', '1h', 'not_recorded', 'legacy_unknown'];
 function requestRowFromRecord(record) {
-    const { costBasis, rateCardSha256, rateCardSourceKind, rateMatchKind, rateMatchProvider, rateMatchModel, ...row } = record;
+    const { costBasis, rateCardSha256, rateCardSourceKind, rateMatchKind, rateMatchProvider, rateMatchModel, cacheWriteTtlRecorded, ...row } = record;
+    // 'not_recorded' and 'legacy_unknown' read as absent; any other string is
+    // damage (D-251) and refuses rather than passing through.
+    const ttl = vocabularyValue(cacheWriteTtlRecorded, CACHE_WRITE_TTLS, 'cacheWriteTtl', 'legacy_unknown');
     return {
         ...row,
+        ...(ttl === '5m' || ttl === '1h' ? { cacheWriteTtl: ttl } : {}),
         estimated: Boolean(record.estimated),
         streamed: Boolean(record.streamed),
         pricing: pricingEvidenceFromRecord(record),
@@ -149,6 +176,8 @@ export class Store {
     epistemicLedger;
     economicLedger;
     exactSpendCache = new Map();
+    /** Diagnostic work counters for the exact-spend readers; see exactSpendWorkCounters(). */
+    exactSpendWork = { fullProjections: 0, incrementalRowsVisited: 0 };
     requestMarks = null;
     migrationBackupEvidence = null;
     constructor(path) {
@@ -298,14 +327,47 @@ export class Store {
     activeBatch = null;
     /** The size and mtime a tool log file had when it was last imported completely. */
     importFileCursor(source, path) {
-        const row = prepared(this.db, 'SELECT size, mtime_ms AS mtimeMs, truncated_lines AS truncatedLines, truncated_rows AS truncatedRows FROM import_file_cursors WHERE source = ? AND path = ?').get(source, path);
+        const row = prepared(this.db, 'SELECT size, mtime_ms AS mtimeMs, truncated_lines AS truncatedLines, truncated_rows AS truncatedRows, reader_version AS readerVersion FROM import_file_cursors WHERE source = ? AND path = ?').get(source, path);
         return row ?? null;
     }
     /** Record that every row of this file, at this size and mtime, is in the ledger. */
     saveImportFileCursor(source, path, cursor) {
-        prepared(this.db, `INSERT INTO import_file_cursors (source, path, size, mtime_ms, truncated_lines, truncated_rows, at_ms) VALUES (?,?,?,?,?,?,?)
+        prepared(this.db, `INSERT INTO import_file_cursors (source, path, size, mtime_ms, truncated_lines, truncated_rows, reader_version, at_ms) VALUES (?,?,?,?,?,?,?,?)
        ON CONFLICT(source, path) DO UPDATE SET size = excluded.size, mtime_ms = excluded.mtime_ms,
-         truncated_lines = excluded.truncated_lines, truncated_rows = excluded.truncated_rows, at_ms = excluded.at_ms`).run(source, path, cursor.size, Math.trunc(cursor.mtimeMs), cursor.truncatedLines, cursor.truncatedRows, Date.now());
+         truncated_lines = excluded.truncated_lines, truncated_rows = excluded.truncated_rows,
+         reader_version = excluded.reader_version, at_ms = excluded.at_ms`).run(source, path, cursor.size, Math.trunc(cursor.mtimeMs), cursor.truncatedLines, cursor.truncatedRows, cursor.readerVersion, Date.now());
+    }
+    /** Record that a session reported making a commit. The first observation of a sha in a session stands. */
+    recordObservedCommit(o) {
+        prepared(this.db, `INSERT INTO observed_commits (source, session_id, short_sha, branch, subject, ts_epoch_ms, cwd, extraction) VALUES (?,?,?,?,?,?,?,'output_start')
+       ON CONFLICT(source, session_id, short_sha) DO NOTHING`).run(o.source, o.sessionId, o.shortSha, o.branch, o.subject, Math.trunc(o.tsEpochMs), o.cwd);
+        this.activeBatch?.tick();
+    }
+    /** Record what a vendor's meter said at an instant. The first record of an instant stands. */
+    recordQuotaEvent(e) {
+        prepared(this.db, `INSERT INTO quota_events (source, kind, ts_epoch_ms, used_percent, window_minutes, resets_at_ms, detail)
+       VALUES (?,?,?,?,?,?,?) ON CONFLICT(source, kind, ts_epoch_ms) DO NOTHING`).run(e.source, e.kind, Math.trunc(e.tsEpochMs), e.usedPercent, e.windowMinutes, e.resetsAtMs === null ? null : Math.trunc(e.resetsAtMs), e.detail);
+        this.activeBatch?.tick();
+    }
+    /** List cost the ledger holds for one source (tool) in [startMs, endMs). */
+    sourceCostBetween(source, startMs, endMs) {
+        const row = prepared(this.db, 'SELECT COALESCE(SUM(cost_usd),0) AS c FROM requests WHERE source = ? AND ts_epoch_ms >= ? AND ts_epoch_ms < ?').get(source, Math.trunc(startMs), Math.trunc(endMs));
+        return row.c;
+    }
+    /** The newest reading of one meter, or null. */
+    latestQuotaEvent(source, kind) {
+        const row = prepared(this.db, `SELECT source, kind, ts_epoch_ms AS tsEpochMs, used_percent AS usedPercent, window_minutes AS windowMinutes,
+              resets_at_ms AS resetsAtMs, detail FROM quota_events WHERE source = ? AND kind = ? ORDER BY ts_epoch_ms DESC LIMIT 1`).get(source, kind);
+        return row === undefined ? null : { ...row };
+    }
+    /** Vendor meter events at or after `sinceMs`, oldest first. */
+    quotaEvents(sinceMs = 0) {
+        return prepared(this.db, `SELECT source, kind, ts_epoch_ms AS tsEpochMs, used_percent AS usedPercent, window_minutes AS windowMinutes,
+              resets_at_ms AS resetsAtMs, detail FROM quota_events WHERE ts_epoch_ms >= ? ORDER BY ts_epoch_ms`).all(sinceMs).map((row) => ({ ...row }));
+    }
+    /** Every commit observation on record (one row per session and sha). */
+    observedCommits() {
+        return prepared(this.db, 'SELECT source, session_id AS sessionId, short_sha AS shortSha, branch, subject, ts_epoch_ms AS tsEpochMs, cwd FROM observed_commits ORDER BY ts_epoch_ms').all().map((row) => ({ ...row }));
     }
     /**
      * The numeric request column remains a compatibility projection while an
@@ -349,9 +411,9 @@ export class Store {
             task_weight, input_tokens, output_tokens, cache_write_tokens, cache_read_tokens,
             reasoning_tokens, cost_usd, estimated, streamed, status_code, duration_ms, user, source, cwd, via,
             cost_basis, rate_card_sha256, rate_card_source_kind, rate_match_kind, rate_match_provider, rate_match_model,
-            scope_capture_status, provider_scope_declaration_id, attribution_basis, capture_coverage
-         ) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)${idempotent ? ' ON CONFLICT(request_id) DO NOTHING' : ''}`;
-            const info = prepared(this.db, sql).run(row.requestId, row.sessionId, new Date(row.tsEpochMs).toISOString(), row.tsEpochMs, row.provider, row.model, row.project, row.taskWeight, row.inputTokens, row.outputTokens, row.cacheWriteTokens, row.cacheReadTokens, row.reasoningTokens, costUsd, row.estimated ? 1 : 0, row.streamed ? 1 : 0, row.statusCode, row.durationMs, row.user ?? null, row.source ?? null, row.cwd ?? null, row.via ?? 'proxy', pricing.costBasis, pricing.rateCardSha256, pricing.rateCardSourceKind, pricing.rateMatchKind, pricing.rateMatchProvider, pricing.rateMatchModel, scope.status, scope.declarationId, row.attributionBasis ?? 'legacy_unknown', row.captureCoverage ?? 'complete');
+            scope_capture_status, provider_scope_declaration_id, attribution_basis, capture_coverage, cache_write_ttl
+         ) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)${idempotent ? ' ON CONFLICT(request_id) DO NOTHING' : ''}`;
+            const info = prepared(this.db, sql).run(row.requestId, row.sessionId, new Date(row.tsEpochMs).toISOString(), row.tsEpochMs, row.provider, row.model, row.project, row.taskWeight, row.inputTokens, row.outputTokens, row.cacheWriteTokens, row.cacheReadTokens, row.reasoningTokens, costUsd, row.estimated ? 1 : 0, row.streamed ? 1 : 0, row.statusCode, row.durationMs, row.user ?? null, row.source ?? null, row.cwd ?? null, row.via ?? 'proxy', pricing.costBasis, pricing.rateCardSha256, pricing.rateCardSourceKind, pricing.rateMatchKind, pricing.rateMatchProvider, pricing.rateMatchModel, scope.status, scope.declarationId, row.attributionBasis ?? 'legacy_unknown', row.captureCoverage ?? 'complete', row.cacheWriteTokens > 0 && (row.cacheWriteTtl === '5m' || row.cacheWriteTtl === '1h') ? row.cacheWriteTtl : 'not_recorded');
             const inserted = Number(info.changes ?? 0) > 0;
             if (row.economicAmount !== undefined) {
                 if (inserted) {
@@ -418,6 +480,7 @@ export class Store {
             byModel: (startMs, endMs, project) => this.byModel(startMs, endMs, project),
             economicRequestRows: (startMs, endMs, project) => this.economicRequestRowsInRange(startMs, endMs, { project }),
             economicModelUnits: (startMs, endMs, project) => this.economicModelUnits(startMs, endMs, project),
+            requestsInRange: (startMs, endMs) => this.requestsInRange(startMs, endMs),
             economicLedger: this.economicLedger,
         };
     }
@@ -615,6 +678,14 @@ export class Store {
     // the traffic a cap can actually BLOCK. Imported subscription spend is sunk cost
     // observed after the fact; counting it toward enforcement froze live traffic in
     // dogfooding. Legacy NULL via reads as proxy (the conservative direction).
+    /**
+     * Requests Segreant refused before they reached the provider cost nothing and
+     * are not spend, so the exact projection neither counts them nor treats them
+     * as unresolved.
+     */
+    sentClause(alias = '') {
+        return ` AND COALESCE(${alias}cost_basis, '') <> 'not_sent'`;
+    }
     viaClause(liveOnly) {
         return liveOnly ? ` AND COALESCE(via,'proxy') = 'proxy'` : '';
     }
@@ -744,6 +815,30 @@ export class Store {
         this.requestMarks ??= new AppendMark(this.db, 'requests');
         return this.requestMarks.read();
     }
+    /**
+     * Change marks for every ledger table the value report reads: the highest
+     * rowid and the exact row count. Any append, removal or in-place replacement
+     * (a replaced row takes a new rowid) moves a mark, so a cached value report
+     * keyed on these marks cannot survive a change to what it was computed from.
+     * Exact counts, not AppendMark's bounded estimate, because a cache hit must
+     * never be served across a deletion; the cost is a few milliseconds, against
+     * the realization work it avoids.
+     */
+    valueChangeMarks() {
+        const mark = (table) => {
+            const row = prepared(this.db, `SELECT COALESCE(MAX(rowid), 0) AS rowid, COUNT(*) AS count FROM ${table}`)
+                .get();
+            return { rowid: Number(row.rowid), count: Number(row.count) };
+        };
+        return {
+            requests: mark('requests'),
+            request_price_events: mark('request_price_events'),
+            gate_signals: mark('gate_signals'),
+            realization_units: mark('realization_units'),
+            economic_events: mark('economic_events'),
+            project_aliases: mark('project_aliases'),
+        };
+    }
     /**
      * Add the rows and charge events appended since `cached` to its projection,
      * or return null when that would not equal a full re-projection: rows removed
@@ -761,12 +856,14 @@ export class Store {
             .all(cached.requestMark.rowid);
         if (requestMark.count - cached.requestMark.count !== appendedIds.length)
             return null;
+        this.exactSpendWork.incrementalRowsVisited += appendedIds.length;
         const newRequestIds = new Set(appendedIds.map((row) => row.requestId));
         // A window projection reads events occurring inside the window; a session
         // has no fixed window, so every appended event is read. That is at least
         // as inclusive as the full session projection, and only new events are read.
         const [startMs, endMs] = scope.kind === 'window' ? [scope.startMs, scope.endMs] : [0, MAX_DATE_MS];
         const events = this.economicLedger.eventsAppendedAfterInOccurrenceRange(cached.eventMark.rowid, startMs, endMs);
+        this.exactSpendWork.incrementalRowsVisited += events.length;
         for (const event of events) {
             const metadata = event.metadata;
             const requestId = metadata !== null && typeof metadata === 'object' && !Array.isArray(metadata)
@@ -780,11 +877,12 @@ export class Store {
             // NOT INDEXED keeps this a rowid range over the rows appended since the
             // mark; left to itself the planner walks the whole window's index.
             `SELECT request_id AS requestId, ts_epoch_ms AS tsEpochMs, via
-           FROM requests NOT INDEXED WHERE rowid > ? AND ts_epoch_ms >= ? AND ts_epoch_ms < ?` + this.viaClause(liveOnly) + `
+           FROM requests NOT INDEXED WHERE rowid > ? AND ts_epoch_ms >= ? AND ts_epoch_ms < ?` + this.viaClause(liveOnly) + this.sentClause() + `
            ORDER BY ts_epoch_ms ASC, request_id ASC`).all(cached.requestMark.rowid, startMs, endMs)
             : prepared(this.db, `SELECT request_id AS requestId, ts_epoch_ms AS tsEpochMs, via
-           FROM requests WHERE rowid > ? AND session_id = ?` + this.viaClause(liveOnly) + `
+           FROM requests WHERE rowid > ? AND session_id = ?` + this.viaClause(liveOnly) + this.sentClause() + `
            ORDER BY ts_epoch_ms ASC, request_id ASC`).all(cached.requestMark.rowid, scope.sessionId));
+        this.exactSpendWork.incrementalRowsVisited += rows.length;
         const delta = this.exactSpendFromRows(rows, startMs, endMs, liveOnly, events);
         const sourceBases = new Set([...cached.projection.sourceBases, ...delta.sourceBases]);
         return Object.freeze({
@@ -795,9 +893,25 @@ export class Store {
             unresolvedRequests: cached.projection.unresolvedRequests + delta.unresolvedRequests,
         });
     }
+    /**
+     * Diagnostic seam for tests, not an input to any figure. `fullProjections`
+     * counts whole-window or whole-session re-projections (cache misses, expiry,
+     * invalidation, and short sliding windows). `incrementalRowsVisited` counts
+     * the request ids, request rows and charge events that cache extensions read.
+     * Returns a copy; pair with resetExactSpendWorkCounters().
+     */
+    exactSpendWorkCounters() {
+        return { ...this.exactSpendWork };
+    }
+    /** Diagnostic seam for tests: zero the exact-spend work counters. */
+    resetExactSpendWorkCounters() {
+        this.exactSpendWork.fullProjections = 0;
+        this.exactSpendWork.incrementalRowsVisited = 0;
+    }
     exactSpendBetweenFull(startMs, endMs, liveOnly) {
+        this.exactSpendWork.fullProjections += 1;
         const rows = prepared(this.db, `SELECT request_id AS requestId, ts_epoch_ms AS tsEpochMs, via
-         FROM requests WHERE ts_epoch_ms >= ? AND ts_epoch_ms < ?` + this.viaClause(liveOnly) + `
+         FROM requests WHERE ts_epoch_ms >= ? AND ts_epoch_ms < ?` + this.viaClause(liveOnly) + this.sentClause() + `
          ORDER BY ts_epoch_ms ASC, request_id ASC`).all(startMs, endMs);
         return this.exactSpendFromRows(rows, startMs, endMs, liveOnly);
     }
@@ -812,7 +926,7 @@ export class Store {
         const rows = prepared(this.db, `SELECT r.request_id AS requestId, r.ts_epoch_ms AS tsEpochMs, r.via
          FROM requests r
         WHERE r.ts_epoch_ms >= ? AND r.ts_epoch_ms < ?
-          AND ${fam.sql}` + this.viaClause(liveOnly) + `
+          AND ${fam.sql}` + this.viaClause(liveOnly) + this.sentClause('r.') + `
         ORDER BY r.ts_epoch_ms ASC, r.request_id ASC`).all(startMs, endMs, ...fam.args);
         return this.exactSpendFromRows(rows, startMs, endMs, liveOnly);
     }
@@ -826,8 +940,9 @@ export class Store {
         return this.cachedExactSpend(`session:${liveOnly ? 'live' : 'all'}:${sessionId}`, { kind: 'session', sessionId }, liveOnly, () => this.exactSpendForSessionFull(sessionId, liveOnly));
     }
     exactSpendForSessionFull(sessionId, liveOnly) {
+        this.exactSpendWork.fullProjections += 1;
         const rows = prepared(this.db, `SELECT request_id AS requestId, ts_epoch_ms AS tsEpochMs, via
-         FROM requests WHERE session_id = ?` + this.viaClause(liveOnly) + `
+         FROM requests WHERE session_id = ?` + this.viaClause(liveOnly) + this.sentClause() + `
          ORDER BY ts_epoch_ms ASC, request_id ASC`).all(sessionId);
         if (rows.length === 0) {
             return Object.freeze({ amount: money('0', 'USD', 'effective'), eventIds: Object.freeze([]), sourceBases: Object.freeze([]), requestCount: 0, unresolvedRequests: 0 });
@@ -852,10 +967,13 @@ export class Store {
         const row = this.db
             .prepare(`SELECT COALESCE(SUM(CASE WHEN status_code = 429 THEN 1 ELSE 0 END),0) AS blocked,
                 COALESCE(SUM(CASE WHEN estimated = 1 THEN cost_usd ELSE 0 END),0) AS estCost,
+                COALESCE(SUM(CASE WHEN estimated = 0 AND cost_basis = 'user_declared_price' THEN cost_usd ELSE 0 END),0) AS declaredCost,
                 COALESCE(SUM(cost_usd),0) AS total
          FROM requests WHERE ts_epoch_ms >= ? AND ts_epoch_ms < ?`)
             .get(startMs, endMs);
-        return { blocked: row.blocked, estimatedCostUsd: row.estCost, totalCostUsd: row.total };
+        // A declared price is resolved (so `estimated` is 0 and a reprice can write
+        // it) but it is not a list price; claim support counts it apart (PR #146 review).
+        return { blocked: row.blocked, estimatedCostUsd: row.estCost, declaredCostUsd: row.declaredCost, totalCostUsd: row.total };
     }
     /**
      * Local rate-card lineage grouped strictly by the evidence captured when each
@@ -1087,7 +1205,7 @@ export class Store {
         if (fam)
             args.push(...fam.args);
         const rows = this.db
-            .prepare(`SELECT DISTINCT cost_basis AS costBasis, rate_card_sha256 AS rateCardSha256
+            .prepare(`SELECT DISTINCT cost_basis AS costBasis, rate_card_sha256 AS rateCardSha256, rate_match_model AS rateMatchModel
          FROM requests
          WHERE ts_epoch_ms >= ? AND ts_epoch_ms < ? AND model = ?` +
             (provider !== undefined ? ` AND provider = ?` : ``) +
@@ -1099,8 +1217,10 @@ export class Store {
             bases.add(r.costBasis);
             // A null card is not a distinct revision — plenty of bases (tool-reported,
             // unpriced) legitimately have none. Only real revisions count as a span.
+            // A declared `like` follows the card under the model it names, so a new
+            // target on the same card is a new price revision (PR #146 review).
             if (r.rateCardSha256)
-                cards.add(r.rateCardSha256);
+                cards.add(r.costBasis === 'user_declared_price' && r.rateMatchModel ? `${r.rateCardSha256}:${r.rateMatchModel}` : r.rateCardSha256);
         }
         return { costBases: [...bases].sort(), rateCardShas: [...cards].sort() };
     }
@@ -1241,37 +1361,98 @@ export class Store {
     requestsInRange(startMs, endMs) {
         // Carry the alias-canonical label alongside the raw one so an export totals
         // the same way `byProject` does without rewriting the recorded row.
-        const rows = this.db
-            .prepare(`SELECT request_id AS requestId, session_id AS sessionId, ts_epoch_ms AS tsEpochMs,
-                provider, model, r.project AS project,
-                COALESCE(a.canonical, r.project) AS projectCanonical, task_weight AS taskWeight,
-                input_tokens AS inputTokens, output_tokens AS outputTokens,
-                cache_write_tokens AS cacheWriteTokens, cache_read_tokens AS cacheReadTokens,
-                reasoning_tokens AS reasoningTokens, cost_usd AS costUsd,
-                estimated, streamed, status_code AS statusCode, duration_ms AS durationMs, user, source, cwd, via,
-                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,
-                 scope_capture_status AS scopeCaptureStatus,
-                 provider_scope_declaration_id AS providerScopeDeclarationId,
-                 attribution_basis AS attributionBasis,
-                 capture_coverage AS captureCoverage
-         FROM requests r LEFT JOIN project_aliases a ON a.alias = r.project
-         WHERE ts_epoch_ms >= ? AND ts_epoch_ms < ? ORDER BY ts_epoch_ms ASC`)
-            .all(startMs, endMs);
+        // Streamed and mapped one record at a time: `.all()` held every raw record
+        // alongside its mapped row, which put a 100,000-row month at 455 MiB RSS.
+        const out = [];
+        const stmt = this.db.prepare(`${REQUEST_ROW_SELECT} WHERE ts_epoch_ms >= ? AND ts_epoch_ms < ? ORDER BY ts_epoch_ms ASC`);
+        for (const record of stmt.iterate(startMs, endMs))
+            out.push(requestRowFromRecord(record));
+        return out;
+    }
+    /**
+     * The rows `requestsInRange(0, endMs)` would return that one self-reported
+     * spend link names: one request, one session, or one tool over [fromMs, toMs).
+     * Same columns, same order, read through an index instead of the whole
+     * ledger. Matching by filtering every request ever recorded took the value
+     * report from 320 MiB of heap to 864 MiB on a 300,000-request ledger.
+     */
+    requestsForSpendLink(link, endMs) {
+        const range = 'ts_epoch_ms >= 0 AND ts_epoch_ms < ?';
+        const order = 'ORDER BY ts_epoch_ms ASC';
+        const rows = (link.type === 'request'
+            ? this.db.prepare(`${REQUEST_ROW_SELECT} WHERE request_id = ? AND ${range} ${order}`).all(link.requestId, endMs)
+            : link.type === 'session'
+                ? this.db.prepare(`${REQUEST_ROW_SELECT} WHERE session_id = ? AND ${range} ${order}`).all(link.sessionId, endMs)
+                : this.db.prepare(`${REQUEST_ROW_SELECT} WHERE source = ? AND ts_epoch_ms >= ? AND ts_epoch_ms < ? AND ${range} ${order}`)
+                    .all(link.tool, link.fromMs, link.toMs, endMs));
         return rows.map(requestRowFromRecord);
     }
+    /**
+     * The effective (exact-Money) rows for request rows the caller already holds.
+     * Row by row, so it equals `economicRequestRowsInRange` over the same rows; a
+     * caller slicing one read into many windows uses it instead of re-querying.
+     */
+    economicRowsOf(rows) {
+        return effectiveRequestRows(rows, this.economicLedger);
+    }
     /** Exact-safe request export rows with original/effective Money and lineage. */
     economicRequestsInRange(startMs, endMs, options = {}) {
-        return buildEconomicRequestExportRows(this.requestsInRange(startMs, endMs), this.economicLedger, options);
+        // A request refused before it was sent cost nothing and has no economic
+        // event; exporting it would print it as legacy_unknown with
+        // no_exact_economic_event. Same rule as the economic read model (PR #143 review).
+        const rows = this.requestsInRange(startMs, endMs).filter((row) => row.pricing?.costBasis !== 'not_sent');
+        return buildEconomicRequestExportRows(rows, this.economicLedger, options);
     }
     /**
      * Exact request-level economic rows for value consumers. The optional project
      * filter follows the alias family used by `summary()`; `liveOnly` preserves
      * the budget distinction between proxy traffic and imported observations.
      */
+    /**
+     * Run `work` with identical economic row reads served once. The value report
+     * read the same 30-day window three times (usage, cohort, self-reported),
+     * each mapping every row through the economic ledger; on a real ledger that
+     * was most of a 9-12 s dashboard read. The snapshot also makes the three
+     * agree with each other, since a write landing mid-report no longer splits
+     * them. Nested calls share the outer snapshot.
+     */
+    async withReadSnapshot(work) {
+        if (this.readSnapshot !== null)
+            return work();
+        this.readSnapshot = new Map();
+        try {
+            return await work();
+        }
+        finally {
+            this.readSnapshot = null;
+        }
+    }
+    readSnapshot = null;
     economicRequestRowsInRange(startMs, endMs, options = {}) {
+        const key = this.readSnapshot === null ? null : JSON.stringify([
+            startMs, endMs, options.project ?? null, options.liveOnly === true,
+            options.asOf ?? null, options.targetUnit ?? null, options.effectiveAt ?? null,
+        ]);
+        const hit = key === null ? undefined : this.readSnapshot.get(key);
+        if (hit !== undefined)
+            return hit.slice();
+        // Inside a snapshot, proxy-only rows are the full read filtered, so the
+        // full read is done once and both questions are answered from it.
+        const out = key !== null && options.liveOnly === true
+            ? this.economicRequestRowsInRange(startMs, endMs, { ...options, liveOnly: false }).filter((row) => row.via === 'proxy')
+            : this.economicRequestRowsInRangeUncached(startMs, endMs, options);
+        if (key !== null)
+            this.readSnapshot.set(key, out.slice());
+        return out;
+    }
+    economicRequestRowsInRangeUncached(startMs, endMs, options) {
         const rows = this.requestsInRange(startMs, endMs).filter((row) => {
+            // A request refused before it was sent has no economic event because it
+            // cost nothing; reading it here marked it no_exact_economic_event and made
+            // attribution partial (PR #143 review). It is not spend, so it is skipped,
+            // as the exact spend projection skips it.
+            if (row.pricing?.costBasis === 'not_sent')
+                return false;
             if (options.project !== undefined && row.projectCanonical !== this.canonicalProject(options.project))
                 return false;
             if (options.liveOnly === true && (row.via ?? 'proxy') !== 'proxy')
@@ -1643,6 +1824,20 @@ export class Store {
     realizationProjects() {
         return realization.realizationProjects(this.db);
     }
+    /**
+     * Recorded guesses, grouped by historical match evidence, costliest first.
+     * Current resolution belongs to the caller: a new card or declaration must
+     * not reinterpret the evidence retained on these requests.
+     */
+    unresolvedModels() {
+        return this.db.prepare(`SELECT provider, model, COUNT(*) AS requests, COALESCE(SUM(cost_usd),0) AS costUsd,
+              rate_match_kind AS rateMatchKind
+       FROM requests
+       WHERE cost_basis != 'not_sent'
+         AND (cost_basis = 'fallback_estimate' OR rate_match_kind IN ('family_provider', 'family_cross_provider'))
+       GROUP BY provider, model, rate_match_kind
+       ORDER BY costUsd DESC, provider, model, rate_match_kind`).all();
+    }
     /** Every row priced with a fallback/family-match rate — the reprice candidates. */
     estimatedRequestRows() {
         return realization.estimatedRequestRows(this.db);
@@ -1998,6 +2193,33 @@ export class Store {
         // (D-173).
         this.retentionFloor().requestsPrunedBeforeMs);
     }
+    /**
+     * Everything Segreant metered in [startMs, endMs), every provider and route,
+     * under the reconciliation's own day quantization, so a comparison's local
+     * figure can be stated as a share of it without the two rounding apart.
+     * Null when an amount cannot be quantized (a non-USD exact amount).
+     */
+    meteredMicrosLikeReconciliation(startMs, endMs, declaredScopeId) {
+        // Both figures from one read of the ledger as it is now. The on-route part
+        // is what the comparison recorded as its local figure; when it no longer
+        // matches the record, the ledger has moved (a prune, a repricing) and a
+        // share of the live total would mix two snapshots (PR #142 review).
+        const rows = this.reconciliationRequestsInRange(startMs, endMs);
+        const inPeriod = (row) => row.tsEpochMs >= startMs && row.tsEpochMs < endMs;
+        const all = quantizeLocalDays(rows, inPeriod);
+        const onRoute = quantizeLocalDays(rows, (row) => inPeriod(row) && isOnDeclaredRoute(row, declaredScopeId));
+        if ('refusal' in all || 'refusal' in onRoute)
+            return null;
+        const sum = (q) => {
+            if ('refusal' in q)
+                return 0;
+            let total = 0;
+            for (const day of q.localByDay.values())
+                total += day.micros;
+            return total;
+        };
+        return { allMicros: sum(all), onRouteMicros: sum(onRoute) };
+    }
     /** Persist a computed reconciliation as an immutable derived record. */
     saveReconciliationRun(result, computedAtMs = Date.now()) {
         return billing.saveReconciliationRun(this.db, result, computedAtMs);
@@ -2118,6 +2340,9 @@ export class Store {
     allocationRuns(limit = 20) {
         return allocation.allocationRuns(this.db, limit);
     }
+    allocationRunById(allocationRunId) {
+        return allocation.allocationRunById(this.db, allocationRunId);
+    }
     /** Recorded reconciliation runs, newest first. */
     reconciliationRuns(limit = 20) {
         return billing.reconciliationRuns(this.db, limit);