@aixle/insights 0.1.0

package/dist/lib/project-resolver.d.ts

@@ -0,0 +1,48 @@
+export interface ProjectResolution {
+    projectId: string | null;
+    source: "flag" | "config" | "auto-detect" | "auto-detect-not-found" | "none";
+}
+export interface LookupResult {
+    project_id: string;
+    name: string;
+}
+export declare function resolveProjectId(flagValue: string | undefined, configValue: string | undefined, host: string, token: string, verbose: boolean): Promise<ProjectResolution>;
+export declare function resolveProjectIdForRepoPath(repoPath: string, host: string, token: string, verbose: boolean): Promise<ProjectResolution>;
+export declare function getGitRemote(verbose: boolean): string | null;
+export declare function getGitRemoteForPath(repoPath: string, verbose: boolean): string | null;
+/**
+ * `git remote get-url origin` returns the literal host from the URL, which may
+ * be an SSH host alias from the user's ~/.ssh/config (e.g. `git@github-work:...`
+ * where `github-work` maps to `github.com`). DB90 stores the real host, so the
+ * server-side normalized URLs never match. Resolve the alias to its real
+ * hostname via `ssh -G` before lookup so the remote is canonical at the source.
+ * Non-SSH remotes and unresolvable hosts are returned unchanged.
+ */
+export declare function canonicalizeGitRemote(remote: string, verbose: boolean): string;
+/**
+ * Cursor `recentCommit.repoName` is typically `owner/repo` (GitHub-style slug), not a full
+ * git remote. Expand to remotes the API lookup understands (`Project.normalize_git_remote`).
+ */
+export declare function repoNameToGitRemoteCandidates(repoName: string): string[];
+export declare function lookupProjectByRepoName(repoName: string, host: string, token: string, verbose: boolean): Promise<LookupResult | "not-found" | null>;
+/** Payload shape shared by db90-cursor and telemetry-mcp commit mappers. */
+export interface CommitAttributionPayload {
+    event_type?: string;
+    project_id?: string;
+    metadata?: {
+        source?: string;
+        repo_name?: string;
+    };
+}
+/**
+ * For recent-commit events, prefer DB90 project lookup from Cursor's `metadata.repo_name`
+ * unless the user set `--project-id` or config `project_id` (explicit attribution).
+ * Daily stats / legacy rows keep batch (CWD) attribution only.
+ */
+export declare function enrichCommitProjectAttribution(payloads: CommitAttributionPayload[], options: {
+    projectIdSource?: ProjectResolution["source"];
+    host: string;
+    token: string;
+    verbose?: boolean;
+}): Promise<void>;
+export declare function lookupProjectByRemote(gitRemote: string, host: string, token: string, verbose: boolean): Promise<LookupResult | "not-found" | null>;

package/dist/lib/project-resolver.js

@@ -0,0 +1,203 @@
+import { execFileSync } from "node:child_process";
+/** Coerce empty string to undefined so "" is treated as "not set" */
+function coerce(val) {
+    return val === "" ? undefined : val;
+}
+export async function resolveProjectId(flagValue, configValue, host, token, verbose) {
+    const flag = coerce(flagValue);
+    const config = coerce(configValue);
+    if (flag !== undefined)
+        return { projectId: flag, source: "flag" };
+    if (config !== undefined)
+        return { projectId: config, source: "config" };
+    const gitRemote = getGitRemote(verbose);
+    if (gitRemote === null)
+        return { projectId: null, source: "none" };
+    const result = await lookupProjectByRemote(gitRemote, host, token, verbose);
+    if (result === "not-found")
+        return { projectId: null, source: "auto-detect-not-found" };
+    if (result !== null)
+        return { projectId: result.project_id, source: "auto-detect" };
+    return { projectId: null, source: "none" };
+}
+export async function resolveProjectIdForRepoPath(repoPath, host, token, verbose) {
+    const gitRemote = getGitRemoteForPath(repoPath, verbose);
+    if (gitRemote === null)
+        return { projectId: null, source: "none" };
+    const result = await lookupProjectByRemote(gitRemote, host, token, verbose);
+    if (result === "not-found")
+        return { projectId: null, source: "auto-detect-not-found" };
+    if (result !== null)
+        return { projectId: result.project_id, source: "auto-detect" };
+    return { projectId: null, source: "none" };
+}
+export function getGitRemote(verbose) {
+    try {
+        const out = execFileSync("git", ["remote", "get-url", "origin"], {
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "pipe"],
+            timeout: 5000,
+        }).trim();
+        return out ? canonicalizeGitRemote(out, verbose) : null;
+    }
+    catch {
+        if (verbose)
+            console.log("[verbose] Could not determine git remote");
+        return null;
+    }
+}
+export function getGitRemoteForPath(repoPath, verbose) {
+    try {
+        const out = execFileSync("git", ["-C", repoPath, "remote", "get-url", "origin"], {
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "pipe"],
+            timeout: 5000,
+        }).trim();
+        return out ? canonicalizeGitRemote(out, verbose) : null;
+    }
+    catch {
+        if (verbose)
+            console.log(`[verbose] Could not determine git remote for path: ${repoPath}`);
+        return null;
+    }
+}
+/**
+ * `git remote get-url origin` returns the literal host from the URL, which may
+ * be an SSH host alias from the user's ~/.ssh/config (e.g. `git@github-work:...`
+ * where `github-work` maps to `github.com`). DB90 stores the real host, so the
+ * server-side normalized URLs never match. Resolve the alias to its real
+ * hostname via `ssh -G` before lookup so the remote is canonical at the source.
+ * Non-SSH remotes and unresolvable hosts are returned unchanged.
+ */
+export function canonicalizeGitRemote(remote, verbose) {
+    const trimmed = remote.trim();
+    if (!trimmed)
+        return remote;
+    const scp = trimmed.match(/^([\w.-]+)@([^:/]+):(.+)$/);
+    const sshUrl = trimmed.match(/^ssh:\/\/(?:([\w.-]+)@)?([^:/]+)(?::\d+)?\/(.+)$/i);
+    const host = scp?.[2] ?? sshUrl?.[2];
+    if (!host)
+        return trimmed;
+    const resolved = resolveSshHostName(host, verbose);
+    if (!resolved || resolved.toLowerCase() === host.toLowerCase())
+        return trimmed;
+    if (verbose)
+        console.log(`[verbose] Resolved SSH host alias ${host} -> ${resolved}`);
+    if (scp)
+        return `${scp[1]}@${resolved}:${scp[3]}`;
+    const user = sshUrl?.[1] ? `${sshUrl[1]}@` : "";
+    return `ssh://${user}${resolved}/${sshUrl[3]}`;
+}
+function resolveSshHostName(host, verbose) {
+    try {
+        const out = execFileSync("ssh", ["-G", host], {
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "pipe"],
+            timeout: 5000,
+        });
+        for (const line of out.split("\n")) {
+            const m = line.match(/^hostname\s+(.+)$/i);
+            if (m)
+                return m[1].trim();
+        }
+        return null;
+    }
+    catch {
+        if (verbose)
+            console.log(`[verbose] Could not resolve SSH host alias: ${host}`);
+        return null;
+    }
+}
+function isLookupResponse(body) {
+    if (typeof body !== "object" || body === null)
+        return false;
+    const d = body.data;
+    if (typeof d !== "object" || d === null)
+        return false;
+    const data = d;
+    return typeof data.project_id === "string" && typeof data.name === "string";
+}
+/**
+ * Cursor `recentCommit.repoName` is typically `owner/repo` (GitHub-style slug), not a full
+ * git remote. Expand to remotes the API lookup understands (`Project.normalize_git_remote`).
+ */
+export function repoNameToGitRemoteCandidates(repoName) {
+    const trimmed = repoName.trim();
+    if (!trimmed)
+        return [];
+    if (trimmed.includes("://") || trimmed.includes("@")) {
+        return [trimmed];
+    }
+    if (/^[\w.-]+\/[\w.-]+(\/[\w.-]+)*$/.test(trimmed)) {
+        return [`https://github.com/${trimmed}`, `git@github.com:${trimmed}.git`];
+    }
+    return [];
+}
+export async function lookupProjectByRepoName(repoName, host, token, verbose) {
+    const candidates = repoNameToGitRemoteCandidates(repoName);
+    if (candidates.length === 0) {
+        if (verbose)
+            console.log(`[verbose] Cannot derive git remote from repo_name: ${repoName}`);
+        return "not-found";
+    }
+    for (const candidate of candidates) {
+        const result = await lookupProjectByRemote(candidate, host, token, verbose);
+        if (result === "not-found")
+            continue;
+        return result;
+    }
+    return "not-found";
+}
+/**
+ * For recent-commit events, prefer DB90 project lookup from Cursor's `metadata.repo_name`
+ * unless the user set `--project-id` or config `project_id` (explicit attribution).
+ * Daily stats / legacy rows keep batch (CWD) attribution only.
+ */
+export async function enrichCommitProjectAttribution(payloads, options) {
+    const explicit = options.projectIdSource === "flag" || options.projectIdSource === "config";
+    if (explicit)
+        return;
+    for (const payload of payloads) {
+        if (payload.event_type !== "commit" && payload.metadata?.source !== "recent_commit") {
+            continue;
+        }
+        const repoName = payload.metadata?.repo_name;
+        if (!repoName)
+            continue;
+        const result = await lookupProjectByRepoName(repoName, options.host, options.token, options.verbose ?? false);
+        if (result && typeof result === "object" && "project_id" in result) {
+            payload.project_id = result.project_id;
+            if (options.verbose) {
+                console.log(`[verbose] Commit project attribution from metadata.repo_name=${repoName}: ${result.project_id}`);
+            }
+        }
+    }
+}
+export async function lookupProjectByRemote(gitRemote, host, token, verbose) {
+    const url = `${host.replace(/\/$/, "")}/api/v1/projects/lookup?git_remote=${encodeURIComponent(gitRemote)}`;
+    try {
+        const res = await fetch(url, { headers: { Authorization: `Bearer ${token}` } });
+        if (res.status === 404) {
+            if (verbose)
+                console.log(`[verbose] No project found for git remote: ${gitRemote}`);
+            return "not-found";
+        }
+        if (!res.ok) {
+            if (verbose)
+                console.log(`[verbose] Project lookup failed: HTTP ${res.status}`);
+            return null;
+        }
+        const body = await res.json();
+        if (!isLookupResponse(body)) {
+            if (verbose)
+                console.log("[verbose] Unexpected response shape from project lookup");
+            return null;
+        }
+        return body.data;
+    }
+    catch {
+        if (verbose)
+            console.log("[verbose] Project lookup network error — proceeding without project attribution");
+        return null;
+    }
+}

package/dist/lock.d.ts

@@ -0,0 +1,9 @@
+export interface SyncLock {
+    acquired: boolean;
+    release: () => void;
+}
+/**
+ * Advisory lock file under the MCP app directory. Prevents overlapping sync runs
+ * across timer ticks, manual tool calls, and separate MCP processes.
+ */
+export declare function acquireSyncLock(appDir: string, staleMs?: number): SyncLock;

package/dist/lock.js

@@ -0,0 +1,84 @@
+import { closeSync, fstatSync, mkdirSync, openSync, readFileSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+const LOCK_FILE = "state.lock";
+/** Stale lock TTL — longer than a normal transcript sync run. */
+const DEFAULT_STALE_MS = 30 * 60 * 1000;
+function lockOwnerIsAlive(owner) {
+    const pid = Number.parseInt(owner.split(":")[0] ?? "", 10);
+    if (!Number.isFinite(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Advisory lock file under the MCP app directory. Prevents overlapping sync runs
+ * across timer ticks, manual tool calls, and separate MCP processes.
+ */
+export function acquireSyncLock(appDir, staleMs = DEFAULT_STALE_MS) {
+    mkdirSync(appDir, { recursive: true });
+    const lockPath = join(appDir, LOCK_FILE);
+    const owner = `${process.pid}:${randomUUID()}`;
+    const tryAcquire = () => {
+        try {
+            const fd = openSync(lockPath, "wx");
+            closeSync(fd);
+            writeFileSync(lockPath, owner, "utf-8");
+            return true;
+        }
+        catch (err) {
+            const code = err?.code;
+            if (code !== "EEXIST")
+                throw err;
+            let fd = null;
+            try {
+                fd = openSync(lockPath, "r");
+                const st = fstatSync(fd);
+                if (Date.now() - st.mtimeMs > staleMs) {
+                    try {
+                        const existingOwner = readFileSync(lockPath, "utf-8");
+                        if (lockOwnerIsAlive(existingOwner))
+                            return false;
+                        const current = statSync(lockPath);
+                        if (current.dev === st.dev && current.ino === st.ino) {
+                            unlinkSync(lockPath);
+                        }
+                    }
+                    catch {
+                        // another winner removed it — fall through to retry
+                    }
+                    return tryAcquire();
+                }
+            }
+            catch {
+                // stat/unlink race — treat as not acquired
+            }
+            finally {
+                if (fd !== null)
+                    closeSync(fd);
+            }
+            return false;
+        }
+    };
+    const acquired = tryAcquire();
+    return {
+        acquired,
+        release: () => {
+            if (!acquired)
+                return;
+            try {
+                if (readFileSync(lockPath, "utf-8") !== owner)
+                    return;
+                unlinkSync(lockPath);
+            }
+            catch {
+                // best-effort
+            }
+        },
+    };
+}

package/dist/log.d.ts

@@ -0,0 +1,14 @@
+/** Active log file is capped; overflow rotates to `mcp.log.1`. */
+export declare const MCP_LOG_MAX_BYTES: number;
+export declare function getMcpLogPath(appDir?: string): string;
+/**
+ * Append one UTF-8 line to `mcp.log` under the app dir (`AIXLE_INSIGHTS_HOME` or `~/.aixle-insights`).
+ * Rotates when the file would exceed {@link MCP_LOG_MAX_BYTES}.
+ */
+export declare function appendMcpLogLine(line: string, appDir?: string): void;
+/** Structured MCP operational log (file + optional stderr mirror for operators). */
+export declare const mcpLog: {
+    info(event: string, fields?: Record<string, unknown>, mirrorToConsole?: boolean): void;
+    warn(event: string, fields?: Record<string, unknown>, mirrorToConsole?: boolean): void;
+    error(event: string, fields?: Record<string, unknown>, mirrorToConsole?: boolean): void;
+};

package/dist/log.js

@@ -0,0 +1,81 @@
+import { appendFileSync, existsSync, mkdirSync, renameSync, statSync, unlinkSync, } from "node:fs";
+import { dirname, join } from "node:path";
+import { getAppDir } from "./state.js";
+/** Active log file is capped; overflow rotates to `mcp.log.1`. */
+export const MCP_LOG_MAX_BYTES = 5 * 1024 * 1024;
+const LOG_BASENAME = "mcp.log";
+const ROTATED_BASENAME = "mcp.log.1";
+export function getMcpLogPath(appDir) {
+    return join(appDir ?? getAppDir(), LOG_BASENAME);
+}
+function formatLine(level, event, fields) {
+    const base = {
+        ts: new Date().toISOString(),
+        level,
+        event,
+    };
+    if (fields && Object.keys(fields).length > 0) {
+        base["data"] = fields;
+    }
+    return JSON.stringify(base);
+}
+function rotateIfNeeded(logPath, incomingByteLength) {
+    if (!existsSync(logPath))
+        return;
+    const size = statSync(logPath).size;
+    if (size + incomingByteLength <= MCP_LOG_MAX_BYTES)
+        return;
+    const rotated = join(dirname(logPath), ROTATED_BASENAME);
+    if (existsSync(rotated)) {
+        unlinkSync(rotated);
+    }
+    renameSync(logPath, rotated);
+}
+/**
+ * Append one UTF-8 line to `mcp.log` under the app dir (`AIXLE_INSIGHTS_HOME` or `~/.aixle-insights`).
+ * Rotates when the file would exceed {@link MCP_LOG_MAX_BYTES}.
+ */
+export function appendMcpLogLine(line, appDir) {
+    const dir = appDir ?? getAppDir();
+    mkdirSync(dir, { recursive: true });
+    const logPath = join(dir, LOG_BASENAME);
+    const raw = Buffer.from(`${line}\n`, "utf8");
+    const buf = raw.length > MCP_LOG_MAX_BYTES
+        ? Buffer.concat([raw.subarray(0, MCP_LOG_MAX_BYTES - 1), Buffer.from("\n")])
+        : raw;
+    rotateIfNeeded(logPath, buf.length);
+    appendFileSync(logPath, buf);
+}
+function emit(level, event, fields, mirrorToConsole) {
+    const line = formatLine(level, event, fields);
+    try {
+        appendMcpLogLine(line);
+    }
+    catch (err) {
+        /* best-effort — never break sync for logging */
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`[aixle-insights] failed to append mcp.log: ${msg}`);
+    }
+    if (mirrorToConsole) {
+        const suffix = fields ? ` ${JSON.stringify(fields)}` : "";
+        const prefix = `[aixle-insights][${level}] ${event}`;
+        if (level === "info")
+            console.log(prefix + suffix);
+        else if (level === "warn")
+            console.warn(prefix + suffix);
+        else
+            console.error(prefix + suffix);
+    }
+}
+/** Structured MCP operational log (file + optional stderr mirror for operators). */
+export const mcpLog = {
+    info(event, fields, mirrorToConsole = false) {
+        emit("info", event, fields, mirrorToConsole);
+    },
+    warn(event, fields, mirrorToConsole = true) {
+        emit("warn", event, fields, mirrorToConsole);
+    },
+    error(event, fields, mirrorToConsole = true) {
+        emit("error", event, fields, mirrorToConsole);
+    },
+};

package/dist/pricing.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Model pricing table and cost calculation for @aixle/insights.
+ *
+ * Default rates source: https://platform.claude.com/docs/en/about-claude/pricing
+ * Rates last verified: 2026-05-04
+ */
+export interface ModelPricing {
+    input_per_mtok: number;
+    output_per_mtok: number;
+    cache_write_per_mtok: number;
+    cache_read_per_mtok: number;
+}
+export type PricingTable = Record<string, ModelPricing>;
+/**
+ * Default pricing table (USD per million tokens).
+ * Covers the Claude model IDs most commonly seen in Claude Code transcripts.
+ *
+ * NOTE: Sessions may use multiple models but SessionAggregate stores only
+ * the last-seen model. Cost is calculated as if all tokens in the session
+ * used that model. This is a known approximation; per-model-per-session
+ * breakdown is a future improvement.
+ */
+export declare const DEFAULT_PRICING: PricingTable;
+/**
+ * Deep-merges user-supplied overrides on top of base, per model.
+ *
+ * - For models already in base: any subset of the four rate fields may be
+ *   supplied; missing fields fall back to the base value for that model.
+ * - For NEW model IDs not in base: all four *_per_mtok fields are required.
+ *   If any rate is missing or non-finite after merge, calculateCost will
+ *   return null rather than produce NaN. getCostWarning will explain why.
+ * - Returns a new table object so mutations never affect DEFAULT_PRICING.
+ */
+export declare function mergePricing(base: PricingTable, overrides: PricingTable): PricingTable;
+export declare function calculateCost(model: string | null, baseInputTokens: number, outputTokens: number, cacheWriteTokens: number, cacheReadTokens: number, pricing: PricingTable): number | null;
+/**
+ * Returns a human-readable warning string explaining why cost could not be
+ * computed, or null if cost should be calculable (no warning needed).
+ */
+export declare function getCostWarning(model: string | null, pricing: PricingTable): string | null;

package/dist/pricing.js

@@ -0,0 +1,149 @@
+/**
+ * Model pricing table and cost calculation for @aixle/insights.
+ *
+ * Default rates source: https://platform.claude.com/docs/en/about-claude/pricing
+ * Rates last verified: 2026-05-04
+ */
+/**
+ * Default pricing table (USD per million tokens).
+ * Covers the Claude model IDs most commonly seen in Claude Code transcripts.
+ *
+ * NOTE: Sessions may use multiple models but SessionAggregate stores only
+ * the last-seen model. Cost is calculated as if all tokens in the session
+ * used that model. This is a known approximation; per-model-per-session
+ * breakdown is a future improvement.
+ */
+export const DEFAULT_PRICING = {
+    // Opus 4.7/4.6/4.5 — $5 input / $25 output
+    "claude-opus-4-7": {
+        input_per_mtok: 5.0,
+        output_per_mtok: 25.0,
+        cache_write_per_mtok: 6.25,
+        cache_read_per_mtok: 0.5,
+    },
+    "claude-opus-4-6": {
+        input_per_mtok: 5.0,
+        output_per_mtok: 25.0,
+        cache_write_per_mtok: 6.25,
+        cache_read_per_mtok: 0.5,
+    },
+    "claude-opus-4-5": {
+        input_per_mtok: 5.0,
+        output_per_mtok: 25.0,
+        cache_write_per_mtok: 6.25,
+        cache_read_per_mtok: 0.5,
+    },
+    // Opus 4.1/4 — $15 input / $75 output
+    "claude-opus-4-1": {
+        input_per_mtok: 15.0,
+        output_per_mtok: 75.0,
+        cache_write_per_mtok: 18.75,
+        cache_read_per_mtok: 1.5,
+    },
+    "claude-opus-4": {
+        input_per_mtok: 15.0,
+        output_per_mtok: 75.0,
+        cache_write_per_mtok: 18.75,
+        cache_read_per_mtok: 1.5,
+    },
+    // Sonnet 4.x family — $3 input / $15 output
+    "claude-sonnet-4": {
+        input_per_mtok: 3.0,
+        output_per_mtok: 15.0,
+        cache_write_per_mtok: 3.75,
+        cache_read_per_mtok: 0.3,
+    },
+    "claude-sonnet-4-6": {
+        input_per_mtok: 3.0,
+        output_per_mtok: 15.0,
+        cache_write_per_mtok: 3.75,
+        cache_read_per_mtok: 0.3,
+    },
+    "claude-sonnet-4-5-20251001": {
+        input_per_mtok: 3.0,
+        output_per_mtok: 15.0,
+        cache_write_per_mtok: 3.75,
+        cache_read_per_mtok: 0.3,
+    },
+    // Haiku 4.5 — $1 input / $5 output
+    "claude-haiku-4-5-20251001": {
+        input_per_mtok: 1.0,
+        output_per_mtok: 5.0,
+        cache_write_per_mtok: 1.25,
+        cache_read_per_mtok: 0.1,
+    },
+    // Legacy Claude 3.x models
+    "claude-3-5-sonnet-20241022": {
+        input_per_mtok: 3.0,
+        output_per_mtok: 15.0,
+        cache_write_per_mtok: 3.75,
+        cache_read_per_mtok: 0.3,
+    },
+    "claude-3-5-haiku-20241022": {
+        input_per_mtok: 0.8,
+        output_per_mtok: 4.0,
+        cache_write_per_mtok: 1.0,
+        cache_read_per_mtok: 0.08,
+    },
+    "claude-3-opus-20240229": {
+        input_per_mtok: 15.0,
+        output_per_mtok: 75.0,
+        cache_write_per_mtok: 18.75,
+        cache_read_per_mtok: 1.5,
+    },
+};
+/**
+ * Deep-merges user-supplied overrides on top of base, per model.
+ *
+ * - For models already in base: any subset of the four rate fields may be
+ *   supplied; missing fields fall back to the base value for that model.
+ * - For NEW model IDs not in base: all four *_per_mtok fields are required.
+ *   If any rate is missing or non-finite after merge, calculateCost will
+ *   return null rather than produce NaN. getCostWarning will explain why.
+ * - Returns a new table object so mutations never affect DEFAULT_PRICING.
+ */
+export function mergePricing(base, overrides) {
+    const result = { ...base };
+    for (const [model, rates] of Object.entries(overrides)) {
+        const merged = { ...(base[model] ?? {}), ...rates };
+        result[model] = merged;
+    }
+    return result;
+}
+/** Returns true only when all four rate fields are finite numbers. */
+function hasValidRates(rates) {
+    return (Number.isFinite(rates.input_per_mtok) &&
+        Number.isFinite(rates.output_per_mtok) &&
+        Number.isFinite(rates.cache_write_per_mtok) &&
+        Number.isFinite(rates.cache_read_per_mtok));
+}
+export function calculateCost(model, baseInputTokens, outputTokens, cacheWriteTokens, cacheReadTokens, pricing) {
+    if (!model)
+        return null;
+    const rates = pricing[model];
+    if (!rates || !hasValidRates(rates))
+        return null;
+    const raw = (baseInputTokens * rates.input_per_mtok +
+        outputTokens * rates.output_per_mtok +
+        cacheWriteTokens * rates.cache_write_per_mtok +
+        cacheReadTokens * rates.cache_read_per_mtok) /
+        1_000_000;
+    // Round to 6 decimal places to match DB DECIMAL(10,6) precision
+    return Math.round(raw * 1_000_000) / 1_000_000;
+}
+/**
+ * Returns a human-readable warning string explaining why cost could not be
+ * computed, or null if cost should be calculable (no warning needed).
+ */
+export function getCostWarning(model, pricing) {
+    if (!model)
+        return null;
+    const rates = pricing[model];
+    if (!rates) {
+        return `Model "${model}" not in pricing table — cost_usd will be null. Extend DEFAULT_PRICING or add future pricing overrides when supported.`;
+    }
+    if (!hasValidRates(rates)) {
+        return `Incomplete pricing for "${model}" — all four *_per_mtok fields are required for new model IDs. cost_usd will be null.`;
+    }
+    return null;
+}