tokentrace 0.21.0 → 0.21.2

package/CHANGELOG.md

@@ -4,6 +4,28 @@ All notable changes to TokenTrace are documented here.
 
 ## Unreleased
 
+## [0.21.2] - 2026-06-26
+
+### Fixed
+
+- **ProjScan circular-import warnings removed.** Shared scan-health, analytics,
+  evidence, review-queue, project-signal, session-comparison, and unknown-cost
+  repair contracts now live in leaf type modules so the import graph stays
+  acyclic. Added a regression test for these architecture boundaries.
+
+### Changed
+
+- **Low-risk dependency refresh.** Updated patch and minor dependencies within
+  the existing major-version ranges after audit and package-security checks.
+
+## [0.21.1] - 2026-06-26
+
+### Changed
+
+- **README and website handoff now match the simplified product.** Refreshed the
+  public docs around preflight, Today, Evidence, Fix Data, and current
+  Playwright-captured `0.21.0` dashboard screenshots.
+
 ## [0.21.0] - 2026-06-26
 
 ### Added

package/README.md

@@ -4,13 +4,26 @@
 
 # TokenTrace CLI
 
-Local-first AI CLI usage analytics. TokenTrace scans local CLI logs and local usage databases, normalizes token usage, estimates missing counts with confidence labels, and shows cost, model, project, session, repair, and evidence analytics in a browser dashboard.
+Local-first AI CLI usage analytics for developers and coding agents.
+
+TokenTrace answers one practical question before the next expensive AI CLI run:
+is your local usage evidence ready to trust? It scans local Claude Code, Codex,
+structured usage logs, and usage-shaped local databases, then labels token and
+cost data as exact, estimated, unknown, cached, or non-cache. The dashboard
+opens on **Today**, with direct paths into Sessions, Evidence, and Fix Data.
 
 TokenTrace is designed for local development machines first, with macOS-oriented defaults. It does not require a cloud account and does not send telemetry or logs anywhere.
 
 [Website](https://www.baseframelabs.com/apps/tokentrace) · [Source](https://github.com/abhiyoheswaran1/tokentrace)
 
-![TokenTrace overview dashboard](docs/assets/overview-0.12.0.png)
+![TokenTrace Today dashboard](docs/assets/today-0.21.0.png)
+
+## What TokenTrace Helps You Do
+
+- Check readiness before another coding-agent run with `tokentrace preflight --json` or MCP `get_preflight`.
+- See today’s local cost, tokens, sessions, confidence, anomalies, and repair signals in one first screen.
+- Trace every important number back to local files, parser state, sessions, model rates, and confidence labels.
+- Fix missing cost data through a guided repair queue without uploading prompts or message bodies.
 
 ## Start In Seconds
 
@@ -133,8 +146,7 @@ explicit scan tool. It does not scan files on startup, and its scan tool require
 `confirmLocalScan=true` before reading local usage files or writing the local
 database.
 
-Before starting another long coding-agent run, use the read-only preflight
-surface:
+Before starting another long coding-agent run, use preflight:
 
 ```bash
 tokentrace preflight --json
@@ -195,13 +207,17 @@ tokentrace roadmap --json
                     # Inspect roadmap handoff, action recipes, and release status
 ```
 
-## Local Sources And Trust
+## Daily Loop And Trust
 
-TokenTrace 0.12.0 bundles local source expansion, evidence exports, scan
-scheduling, scoped guardrails, parser profile preview, saved reports, and
-agent-readable release status.
+TokenTrace now organizes the product around the daily loop:
 
-New trust surfaces include:
+1. **Preflight**: decide whether local evidence is ready before another agent run.
+2. **Today**: review cost, token, session, confidence, anomaly, and repair signals.
+3. **Evidence**: trace numbers back to source files, parser confidence, sessions, and model-rate state.
+4. **Fix Data**: resolve unknown cost, parser review, and model-rate gaps.
+5. **Advanced**: inspect Scan Health, Discovery, Parsers, Raw Data, Query, and Model Rates when you need the full diagnostic surface.
+
+Trust surfaces include:
 
 - native structured usage log and Cursor-style chat export ingestion
 - Source Coverage in Scan Health for native, profile-assisted, fallback, and
@@ -214,11 +230,6 @@ New trust surfaces include:
   cost, high-cost sessions, and confidence trends
 - operating metadata export without raw usage records
 
-The 0.12.0 dashboard also tightens the daily operator path: setup buttons now
-open the exact Settings section, scan results show what changed and where to go
-next, and Evidence explains when it is being opened as a contextual drill-down
-rather than a sidebar destination.
-
 ## Accuracy And Evidence
 
 TokenTrace labels the trust level behind imported numbers:
@@ -270,10 +281,13 @@ Default discovery checks these locations when present:
 - TokenTrace wrapper logs in the local app-data directory
 - Any custom folders configured in Settings
 
-Use **Settings** in the dashboard to add custom folders, toggle raw message storage, and trigger scans. Use **Scan Health**, **Discovery**, **Parsers**, and **Raw Data** to inspect discovered files, parser decisions, warnings, failures, extracted metadata, and confidence levels.
+Use **Settings** to add custom folders, toggle raw message storage, and trigger
+scans. Use **Scan Health**, **Discovery**, **Parsers**, and **Raw Data** to
+inspect discovered files, parser decisions, warnings, failures, extracted
+metadata, and confidence levels.
 
 Settings also supports optional local monthly usage guardrails. Set a cost
-limit, token limit, or both, and Overview will show month-to-date progress from
+limit, token limit, or both, and Today will show month-to-date progress from
 imported local CLI usage.
 
 Sessions includes built-in and local saved views for recurring review paths:
@@ -362,13 +376,13 @@ Codex CLI status-line integration is intentionally deferred until its status-lin
 
 Dashboard views:
 
-![TokenTrace overview dashboard](docs/assets/overview-0.12.0.png)
+![TokenTrace Today dashboard](docs/assets/today-0.21.0.png)
 
-![TokenTrace processed tokens evidence trail](docs/assets/evidence-0.12.0.png)
+![TokenTrace unknown cost evidence trail](docs/assets/evidence-0.21.0.png)
 
-![TokenTrace unknown cost repair queue](docs/assets/repair-0.12.0.png)
+![TokenTrace Fix Data queue](docs/assets/fix-data-0.21.0.png)
 
-![TokenTrace Scan Health parser review](docs/assets/scan-health-0.12.0.png)
+![TokenTrace Scan Health parser review](docs/assets/scan-health-0.21.0.png)
 
 CLI startup and help:
 
@@ -403,6 +417,7 @@ Stop the server with `Ctrl+C` in the terminal where `tokentrace` is running.
 - `npm run security:ioc` scans lockfiles, workflows, and local Claude/VS Code hook files for high-signal supply-chain compromise indicators.
 - Public npm publishing is configured through GitHub Actions Trusted Publishing and provenance from version tags.
 - Socket GitHub checks and ProjScan are used as release guardrails, alongside `npm audit --audit-level=moderate`.
+- `npm run release:check` fails when a gate command exits non-zero. The import graph is expected to remain free of circular dependencies; `tests/import-boundaries.test.ts` protects shared type/helper modules from importing higher-level orchestration barrels.
 - Release notes are published directly in GitHub Releases from the relevant changelog section, not as a link-only summary.
 
 See [SECURITY.md](SECURITY.md) for the full security and privacy model.

package/TOKENTRACE_AGENT.md

@@ -3,6 +3,11 @@
 TokenTrace is a local-first CLI and dashboard for AI coding-agent token, cost,
 session, parser, and evidence analytics.
 
+The current product loop is: run preflight, review Today, inspect Sessions or
+Evidence, then use Fix Data when model rates or parser confidence block trusted
+costs. Advanced pages remain available for diagnostics, but agents should start
+from preflight before long runs.
+
 ## Start Here
 
 Use the read-only discovery manifest before running any other TokenTrace command:
@@ -101,19 +106,22 @@ curl http://127.0.0.1:3030/api/roadmap
    tokentrace preflight --json
    ```
 
-4. Refresh local data when the human expects current usage:
+4. Follow the preflight decision. Use Today for the human-facing status, Evidence
+   for numeric claims, and Fix Data for unknown-cost work.
+
+5. Refresh local data when the human expects current usage:
 
    ```bash
    tokentrace scan --json
    ```
 
-5. Check trust before making claims:
+6. Check trust before making claims:
 
    ```bash
    tokentrace doctor --json
    ```
 
-6. Explain totals with evidence:
+7. Explain totals with evidence:
 
    ```bash
    tokentrace evidence --json

package/docs/agent-adoption.md

@@ -5,6 +5,9 @@ session, parser, and repair questions. The goal is not to make agents guess from
 terminal history. The goal is to make them check local TokenTrace data first,
 then report with confidence labels and evidence.
 
+The current workflow is short: preflight first, Today for status, Evidence for
+numbers, and Fix Data for unknown-cost or parser-confidence repairs.
+
 ## MCP Install
 
 MCP registry name:

package/llms.txt

@@ -2,6 +2,10 @@
 
 > Local-first analytics for AI CLI usage, focused on coding-agent tokens, costs, sessions, parser confidence, and evidence trails.
 
+Current product loop: preflight before long runs, Today for local readiness and
+daily usage, Sessions for conversation detail, Evidence for numeric claims, and
+Fix Data for unknown cost or parser-confidence work.
+
 ## Agent Entry Point
 
 Start with:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokentrace",
-  "version": "0.21.0",
+  "version": "0.21.2",
   "mcpName": "io.github.abhiyoheswaran1/tokentrace",
   "description": "Local-first dashboard for AI CLI token, cost, and session analytics.",
   "author": {

package/server.json

@@ -8,12 +8,12 @@
     "url": "https://github.com/abhiyoheswaran1/tokentrace",
     "source": "github"
   },
-  "version": "0.21.0",
+  "version": "0.21.2",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "tokentrace",
-      "version": "0.21.0",
+      "version": "0.21.2",
       "runtimeHint": "npx",
       "packageArguments": [
         {

package/src/lib/analytics-types.ts

@@ -1,10 +1,7 @@
 import type { DataConfidenceGrade, DataConfidenceScore } from "@/src/lib/data-confidence";
-import type { EvidenceMetric } from "@/src/lib/evidence-trail";
+import type { EvidenceMetric } from "@/src/lib/evidence/metrics";
 import type { LocalRecommendation } from "@/src/lib/recommendations";
-import type { ProjectSignalRow } from "@/src/lib/project-signals";
-import type { ReviewQueueItem } from "@/src/lib/review-queue";
-import type { ScanConfidenceSummary, ScanHealth } from "@/src/lib/scan-health";
-import type { SessionComparisonRow } from "@/src/lib/session-comparison";
+import type { ScanConfidenceSummary, ScanHealth } from "@/src/lib/scan-health-types";
 import type { UsageGuardrailProgress } from "@/src/lib/usage-guardrails";
 
 export type TrendPoint = {
@@ -172,6 +169,60 @@ export type ModelAliasSuggestion = {
   parserHref: string;
 };
 
+export type ReviewQueueCategory =
+  | "guardrail"
+  | "cost-repair"
+  | "session"
+  | "project"
+  | "model"
+  | "cache"
+  | "baseline";
+
+export type ReviewQueueItem = {
+  id: string;
+  severity: "high" | "medium" | "low";
+  category: ReviewQueueCategory;
+  title: string;
+  evidence: string;
+  action: string;
+  href: string;
+  impactLabel: string;
+  impactValue: string;
+};
+
+export type SessionComparisonRow = {
+  sessionId: string;
+  title: string;
+  project: string;
+  tool: string;
+  models: string;
+  totalTokens: number;
+  cost: number | null;
+  peerSessions: number;
+  peerMedianTokens: number;
+  peerMedianCost: number | null;
+  tokenMultiple: number;
+  costMultiple: number | null;
+  severity: "high" | "medium" | "low";
+  flag: "token outlier" | "cost outlier";
+  evidence: string;
+  action: string;
+  href: string;
+};
+
+export type ProjectSignalRow = {
+  id: string;
+  severity: "high" | "medium" | "low";
+  project: string;
+  path: string;
+  signal: "dominant usage" | "unknown cost" | "estimated tokens" | "model concentration";
+  evidence: string;
+  action: string;
+  href: string;
+  metricLabel: string;
+  metricValue: string;
+};
+
 export type DebugScanFile = {
   id: string;
   scanRunId: string;

package/src/lib/evidence/query.ts

@@ -1,5 +1,5 @@
 import { sqlite } from "@/src/db/client";
-import type { AnalyticsFilters } from "@/src/lib/analytics";
+import type { AnalyticsFilters } from "@/src/lib/analytics-types";
 import type { EvidenceMetric } from "@/src/lib/evidence/metrics";
 
 export type EvidenceSessionRow = {

package/src/lib/evidence-trail.ts

@@ -1,4 +1,4 @@
-import type { AnalyticsFilters } from "@/src/lib/analytics";
+import type { AnalyticsFilters } from "@/src/lib/analytics-types";
 import type { EvidenceMetric } from "@/src/lib/evidence/metrics";
 import {
   mapEvidenceTrail,

package/src/lib/project-signals.ts

@@ -1,18 +1,7 @@
-import type { ProjectAnalyticsRow, SessionRow } from "@/src/lib/analytics";
+import type { ProjectAnalyticsRow, ProjectSignalRow, SessionRow } from "@/src/lib/analytics-types";
 import { formatTokens } from "@/src/lib/format";
 
-export type ProjectSignalRow = {
-  id: string;
-  severity: "high" | "medium" | "low";
-  project: string;
-  path: string;
-  signal: "dominant usage" | "unknown cost" | "estimated tokens" | "model concentration";
-  evidence: string;
-  action: string;
-  href: string;
-  metricLabel: string;
-  metricValue: string;
-};
+export type { ProjectSignalRow } from "@/src/lib/analytics-types";
 
 type ProjectSignalInput = {
   totalTokens: number;

package/src/lib/review-queue.ts

@@ -2,33 +2,16 @@ import { formatCurrency, formatTokens } from "@/src/lib/format";
 import type {
   ModelAnalyticsRow,
   ProjectAnalyticsRow,
+  ReviewQueueCategory,
+  ReviewQueueItem,
   SessionRow,
   SummaryMetrics,
   ToolComparisonRow,
   UnknownCostQueueRow
-} from "@/src/lib/analytics";
+} from "@/src/lib/analytics-types";
 import type { UsageGuardrailProgress, UsageGuardrailMetric } from "@/src/lib/usage-guardrails";
 
-export type ReviewQueueCategory =
-  | "guardrail"
-  | "cost-repair"
-  | "session"
-  | "project"
-  | "model"
-  | "cache"
-  | "baseline";
-
-export type ReviewQueueItem = {
-  id: string;
-  severity: "high" | "medium" | "low";
-  category: ReviewQueueCategory;
-  title: string;
-  evidence: string;
-  action: string;
-  href: string;
-  impactLabel: string;
-  impactValue: string;
-};
+export type { ReviewQueueCategory, ReviewQueueItem } from "@/src/lib/analytics-types";
 
 type ReviewQueueInput = {
   summary: Pick<SummaryMetrics, "totalTokens" | "totalCost" | "inputTokens" | "cachedTokens" | "unknownCostInteractions">;

package/src/lib/scan-health-rules.ts

@@ -6,7 +6,7 @@ import type {
   ScanHealthNoteGroup,
   ScanHealthRun,
   SupplyChainHealth
-} from "@/src/lib/scan-health";
+} from "@/src/lib/scan-health-types";
 
 export function incrementCount(target: Record<string, number>, key: string, amount = 1) {
   target[key] = (target[key] ?? 0) + amount;

package/src/lib/scan-health-types.ts

@@ -0,0 +1,104 @@
+export type ScanHealthRun = {
+  id: string;
+  startedAt: number;
+  completedAt: number | null;
+  filesScanned: number;
+  recordsImported: number;
+  warnings: string[];
+  errors: string[];
+};
+
+export type ScanHealthFile = {
+  id: string;
+  scanRunId: string;
+  path: string;
+  modifiedTime: number | null;
+  sizeBytes: number;
+  parser: string | null;
+  status: string;
+  recordsImported: number;
+  warnings: string[];
+  errors: string[];
+  rawMetadata: Record<string, unknown>;
+};
+
+export type ScanConfidenceSummary = {
+  interactions: number;
+  exactTokenInteractions: number;
+  tokenizerEstimateInteractions?: number;
+  simpleEstimateInteractions?: number;
+  highConfidenceTokenInteractions: number;
+  lowConfidenceTokenInteractions: number;
+  unknownTokenInteractions: number;
+  estimatedTokenInteractions: number;
+  exactCostInteractions: number;
+  estimatedCostInteractions: number;
+  unknownCostInteractions: number;
+  unknownCostCauses: {
+    missingModelName: number;
+    missingPricing: number;
+    missingTokenCount: number;
+    other: number;
+  };
+};
+
+export type ScanHealthAction = {
+  label: string;
+  href: string;
+  reason: string;
+  tone: "default" | "warning" | "destructive";
+};
+
+export type SupplyChainHealth = {
+  status: "passed" | "failed" | "not-run";
+  checkedAt: number | null;
+  findings: number;
+  summary: string;
+};
+
+export type ScanHealthNoteGroup = {
+  severity: "warning" | "error";
+  message: string;
+  count: number;
+  examples: string[];
+};
+
+export type ScanHealth = {
+  latestRun: ScanHealthRun | null;
+  lastSuccessfulRun: ScanHealthRun | null;
+  latestFiles: ScanHealthFile[];
+  headline: string;
+  description: string;
+  tone: "success" | "warning" | "destructive" | "secondary";
+  latestStatusCounts: Record<string, number>;
+  parserCounts: Record<string, number>;
+  latestWarnings: string[];
+  latestErrors: string[];
+  latestNoteGroups: ScanHealthNoteGroup[];
+  freshness: {
+    state: "no-scan" | "no-successful-scan" | "fresh" | "stale";
+    lastSuccessfulCompletedAt: number | null;
+    staleAfterMs: number;
+    description: string;
+  };
+  tokenCoverage: {
+    exact: number;
+    tokenizerEstimate: number;
+    simpleEstimate: number;
+    highConfidenceEstimate: number;
+    lowConfidenceEstimate: number;
+    unknown: number;
+    estimated: number;
+    total: number;
+  };
+  costCoverage: {
+    priced: number;
+    exact: number;
+    estimated: number;
+    unknown: number;
+    unknownCauses: ScanConfidenceSummary["unknownCostCauses"];
+    total: number;
+  };
+  supplyChain: SupplyChainHealth;
+  actions: ScanHealthAction[];
+};

package/src/lib/scan-health.ts

@@ -8,111 +8,23 @@ import {
   uniqueMessages,
   type ScanHealthRuleStats
 } from "@/src/lib/scan-health-rules";
+import type {
+  ScanConfidenceSummary,
+  ScanHealth,
+  ScanHealthFile,
+  ScanHealthRun,
+  SupplyChainHealth
+} from "@/src/lib/scan-health-types";
 
-export type ScanHealthRun = {
-  id: string;
-  startedAt: number;
-  completedAt: number | null;
-  filesScanned: number;
-  recordsImported: number;
-  warnings: string[];
-  errors: string[];
-};
-
-export type ScanHealthFile = {
-  id: string;
-  scanRunId: string;
-  path: string;
-  modifiedTime: number | null;
-  sizeBytes: number;
-  parser: string | null;
-  status: string;
-  recordsImported: number;
-  warnings: string[];
-  errors: string[];
-  rawMetadata: Record<string, unknown>;
-};
-
-export type ScanConfidenceSummary = {
-  interactions: number;
-  exactTokenInteractions: number;
-  tokenizerEstimateInteractions?: number;
-  simpleEstimateInteractions?: number;
-  highConfidenceTokenInteractions: number;
-  lowConfidenceTokenInteractions: number;
-  unknownTokenInteractions: number;
-  estimatedTokenInteractions: number;
-  exactCostInteractions: number;
-  estimatedCostInteractions: number;
-  unknownCostInteractions: number;
-  unknownCostCauses: {
-    missingModelName: number;
-    missingPricing: number;
-    missingTokenCount: number;
-    other: number;
-  };
-};
-
-export type ScanHealthAction = {
-  label: string;
-  href: string;
-  reason: string;
-  tone: "default" | "warning" | "destructive";
-};
-
-export type SupplyChainHealth = {
-  status: "passed" | "failed" | "not-run";
-  checkedAt: number | null;
-  findings: number;
-  summary: string;
-};
-
-export type ScanHealthNoteGroup = {
-  severity: "warning" | "error";
-  message: string;
-  count: number;
-  examples: string[];
-};
-
-export type ScanHealth = {
-  latestRun: ScanHealthRun | null;
-  lastSuccessfulRun: ScanHealthRun | null;
-  latestFiles: ScanHealthFile[];
-  headline: string;
-  description: string;
-  tone: "success" | "warning" | "destructive" | "secondary";
-  latestStatusCounts: Record<string, number>;
-  parserCounts: Record<string, number>;
-  latestWarnings: string[];
-  latestErrors: string[];
-  latestNoteGroups: ScanHealthNoteGroup[];
-  freshness: {
-    state: "no-scan" | "no-successful-scan" | "fresh" | "stale";
-    lastSuccessfulCompletedAt: number | null;
-    staleAfterMs: number;
-    description: string;
-  };
-  tokenCoverage: {
-    exact: number;
-    tokenizerEstimate: number;
-    simpleEstimate: number;
-    highConfidenceEstimate: number;
-    lowConfidenceEstimate: number;
-    unknown: number;
-    estimated: number;
-    total: number;
-  };
-  costCoverage: {
-    priced: number;
-    exact: number;
-    estimated: number;
-    unknown: number;
-    unknownCauses: ScanConfidenceSummary["unknownCostCauses"];
-    total: number;
-  };
-  supplyChain: SupplyChainHealth;
-  actions: ScanHealthAction[];
-};
+export type {
+  ScanConfidenceSummary,
+  ScanHealth,
+  ScanHealthAction,
+  ScanHealthFile,
+  ScanHealthNoteGroup,
+  ScanHealthRun,
+  SupplyChainHealth
+} from "@/src/lib/scan-health-types";
 
 export function buildScanHealth({
   scanRuns,

package/src/lib/session-comparison.ts

@@ -1,25 +1,7 @@
-import type { SessionRow } from "@/src/lib/analytics";
+import type { SessionComparisonRow, SessionRow } from "@/src/lib/analytics-types";
 import { formatCurrency, formatTokens } from "@/src/lib/format";
 
-export type SessionComparisonRow = {
-  sessionId: string;
-  title: string;
-  project: string;
-  tool: string;
-  models: string;
-  totalTokens: number;
-  cost: number | null;
-  peerSessions: number;
-  peerMedianTokens: number;
-  peerMedianCost: number | null;
-  tokenMultiple: number;
-  costMultiple: number | null;
-  severity: "high" | "medium" | "low";
-  flag: "token outlier" | "cost outlier";
-  evidence: string;
-  action: string;
-  href: string;
-};
+export type { SessionComparisonRow } from "@/src/lib/analytics-types";
 
 function median(values: number[]) {
   if (!values.length) return 0;

package/src/lib/unknown-cost-repair/auto-classify.ts

@@ -1,46 +1,21 @@
 import { prepareCached } from "@/src/db/prepared";
 import { modelNameCandidates } from "@/src/lib/model-aliases";
-import type { UnknownCostRepairWorkbenchGroup } from "@/src/lib/unknown-cost-repair/types";
-
-export type AutoClassificationRule = "exact-model" | "family-fragment" | "parser-source" | "none";
-
-export type AutoClassification = {
-  suggestedModel: string | null;
-  suggestedProvider: string | null;
-  confidence: number;
-  rule: AutoClassificationRule;
-  evidence: {
-    matchedRows: number;
-    sampleSourceFile: string | null;
-  };
-};
-
-export type ClassifyInput = {
-  cause: UnknownCostRepairWorkbenchGroup["cause"];
-  providerId: string;
-  model: string;
-  sourceFile: string;
-};
-
-export type PricedModelRow = {
-  providerId: string;
-  providerName: string;
-  modelName: string;
-  usageCount: number;
-};
-
-export type SourcePricedRow = {
-  sourceFile: string;
-  providerId: string;
-  providerName: string;
-  modelName: string;
-  usageCount: number;
-};
-
-export type ClassificationLookups = {
-  pricedByProvider: Map<string, PricedModelRow[]>;
-  pricedBySource: Map<string, SourcePricedRow>;
-};
+import type {
+  AutoClassification,
+  ClassificationLookups,
+  ClassifyInput,
+  PricedModelRow,
+  SourcePricedRow
+} from "@/src/lib/unknown-cost-repair/classification-types";
+
+export type {
+  AutoClassification,
+  AutoClassificationRule,
+  ClassificationLookups,
+  ClassifyInput,
+  PricedModelRow,
+  SourcePricedRow
+} from "@/src/lib/unknown-cost-repair/classification-types";
 
 export function buildClassificationLookups(): ClassificationLookups {
   const pricedRows = prepareCached(

package/src/lib/unknown-cost-repair/classification-types.ts

@@ -0,0 +1,41 @@
+import type { UnknownCostRepairCause } from "@/src/lib/repair-actions";
+
+export type AutoClassificationRule = "exact-model" | "family-fragment" | "parser-source" | "none";
+
+export type AutoClassification = {
+  suggestedModel: string | null;
+  suggestedProvider: string | null;
+  confidence: number;
+  rule: AutoClassificationRule;
+  evidence: {
+    matchedRows: number;
+    sampleSourceFile: string | null;
+  };
+};
+
+export type ClassifyInput = {
+  cause: UnknownCostRepairCause;
+  providerId: string;
+  model: string;
+  sourceFile: string;
+};
+
+export type PricedModelRow = {
+  providerId: string;
+  providerName: string;
+  modelName: string;
+  usageCount: number;
+};
+
+export type SourcePricedRow = {
+  sourceFile: string;
+  providerId: string;
+  providerName: string;
+  modelName: string;
+  usageCount: number;
+};
+
+export type ClassificationLookups = {
+  pricedByProvider: Map<string, PricedModelRow[]>;
+  pricedBySource: Map<string, SourcePricedRow>;
+};

package/src/lib/unknown-cost-repair/types.ts

@@ -1,4 +1,4 @@
-import type { AutoClassification } from "@/src/lib/unknown-cost-repair/auto-classify";
+import type { AutoClassification } from "@/src/lib/unknown-cost-repair/classification-types";
 import type { UnknownCostRepairAction, UnknownCostRepairCause } from "@/src/lib/repair-actions";
 
 export type UnknownCostRepairStatus = "unresolved" | "ignored" | "resolved" | "needs-parser-review";