// Ledger introspection READS (CV22.DS7.TS4 plateau 2). // // Port of `inspect llm-calls` and `inspect embedding-provenance` from // `src/memory/cli/inspect.py`, over the summary query DS8 already ported // (`getLlmCallSummary`) plus the two reads this plateau adds. // // MEASURED, and none of it is visible from reading the modules: // // * these two leaves ARE argparse -- a bad `--limit` exits **2** with usage // on stderr -- while every leaf in the catalog family (plateau 1) exits 1 // with usage on stdout. Both classes live under `inspect`; // * `--session` and `--since` are applied by the CLI *after* the store's // `LIMIT`, so `--session X --limit 3` can report "no rows" while // `--session X` alone finds one. Reproduced, not repaired; // * `role` and `model` are NOT NULL in the schema, so the renderer's // `or "?"` fallback is reachable only through an EMPTY STRING; // * the role column is padded to 18 with `{:<18}` and NOT truncated, so // `journal_classification` overflows and misaligns its own row; // * prompts and responses are cut at 200 CODE POINTS after `strip()`, and // printed with `!r`. A UTF-16 cut halves an astral character on the // boundary; the corpus stages exactly that character at index 199. import type { Database } from "#db/database.ts"; import { pyRepr, sortByCodePoint } from "#util/pythonText.ts"; import { getLlmCallSummary, type LlmCallSummary } from "./llmCalls.ts"; export interface LlmCallRow { id: string; role: string; model: string; prompt: string; response: string; promptTokens: number | null; completionTokens: number | null; latencyMs: number | null; costUsd: number | null; conversationId: string | null; sessionId: string | null; calledAt: string; } /** Port of `Store.get_llm_calls`: newest first, filtered in SQL, then LIMIT. */ export function getLlmCalls( db: Database, options: { conversationId?: string | null; role?: string | null; limit?: number } = {}, ): LlmCallRow[] { const clauses: string[] = []; const params: Array = []; if (options.conversationId) { clauses.push("conversation_id = ?"); params.push(options.conversationId); } if (options.role) { clauses.push("role = ?"); params.push(options.role); } const where = clauses.length > 0 ? `WHERE ${clauses.join(" AND ")}` : ""; params.push(options.limit ?? 50); const rows = db .prepare( `SELECT id, role, model, prompt, response, prompt_tokens, completion_tokens, latency_ms, cost_usd, conversation_id, session_id, called_at FROM llm_calls ${where} ORDER BY called_at DESC LIMIT ?`, ) .all(...params); return rows.map((row) => ({ id: String(row.id ?? ""), role: String(row.role ?? ""), model: String(row.model ?? ""), prompt: String(row.prompt ?? ""), response: String(row.response ?? ""), promptTokens: row.prompt_tokens === null ? null : Number(row.prompt_tokens), completionTokens: row.completion_tokens === null ? null : Number(row.completion_tokens), latencyMs: row.latency_ms === null ? null : Number(row.latency_ms), costUsd: row.cost_usd === null ? null : Number(row.cost_usd), conversationId: row.conversation_id === null ? null : String(row.conversation_id), sessionId: row.session_id === null ? null : String(row.session_id), calledAt: String(row.called_at ?? ""), })); } /** * Port of `Store.count_memories_by_embedding_model`. * * Aggregated in TypeScript rather than in SQL, as Python does and for the same * reason: a legacy or malformed `metadata` degrades into the unknown bucket * instead of raising. Sorted by descending count, then by Python's * `str(model)` -- which renders the unknown bucket as the string `None`, so it * sorts before any lowercase model name on a tie. */ export function countMemoriesByEmbeddingModel(db: Database): Array<[string | null, number]> { const rows = db.prepare("SELECT metadata FROM memories WHERE embedding IS NOT NULL").all(); const counts = new Map(); for (const row of rows) { let model: string | null = null; const metadata = row.metadata; if (metadata) { try { const parsed = JSON.parse(String(metadata)); if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) { const value = (parsed as Record).embedding_model; model = typeof value === "string" ? value : null; } } catch { model = null; } } counts.set(model, (counts.get(model) ?? 0) + 1); } const entries = [...counts.entries()]; const keyOf = (model: string | null): string => (model === null ? "None" : model); const order = sortByCodePoint(entries.map(([model]) => keyOf(model))); return entries.sort((left, right) => { if (left[1] !== right[1]) return right[1] - left[1]; return order.indexOf(keyOf(left[0])) - order.indexOf(keyOf(right[0])); }); } /** Python `f"{cost:.6f}"`. */ function formatCost(cost: number): string { return cost.toFixed(6); } /** Port of `_fmt_summary_cost`: an em dash for unpriced. */ export function formatSummaryCost(cost: number | null): string { return cost === null ? "—" : `~$${formatCost(cost)}`; } /** Python `str.ljust`, in code points. */ function ljust(text: string, width: number): string { const length = Array.from(text).length; return length >= width ? text : text + " ".repeat(width - length); } /** Python `text[:limit]` -- CODE POINTS, not UTF-16 units. */ function sliceCodePoints(text: string, limit: number): string { return Array.from(text).slice(0, limit).join(""); } const NO_ROWS = "(no llm_calls rows match the given filters)\n"; /** Port of the row-listing half of `cmd_inspect_llm_calls`. */ export function renderLlmCallRows(rows: readonly LlmCallRow[]): string { if (rows.length === 0) return NO_ROWS; const lines = [`=== llm_calls (${rows.length} row${rows.length !== 1 ? "s" : ""}) ===`]; for (const row of rows) { const calledAt = sliceCodePoints(row.calledAt, 19).replace("T", " "); const latency = row.latencyMs === null ? "?ms" : `${row.latencyMs}ms`; const conversation = sliceCodePoints(row.conversationId ?? "", 8) || "—"; const cost = row.costUsd === null ? "$—" : `~$${formatCost(row.costUsd)}`; lines.push(""); lines.push(`[${calledAt}] ${row.role || "?"} | ${row.model || "?"}`); lines.push( ` id:${sliceCodePoints(row.id, 8)} conv:${conversation} ` + `${row.promptTokens ?? 0}→${row.completionTokens ?? 0} tokens ${latency} ${cost}`, ); lines.push(` prompt: ${pyRepr(sliceCodePoints(row.prompt.trim(), 200))}`); lines.push(` response: ${pyRepr(sliceCodePoints(row.response.trim(), 200))}`); } return `${lines.join("\n")}\n`; } /** Port of `_print_llm_call_summary`. */ export function renderLlmCallSummary(summary: LlmCallSummary, since: string | null): string { if (summary.total.calls === 0) return NO_ROWS; const scope = since ? ` since ${since}` : ""; const lines = [`=== llm_calls summary${scope} ===`]; const block = (title: string, buckets: readonly LlmCallSummary["byRole"][number][]): void => { lines.push(""); lines.push(title); for (const bucket of buckets) { const unpriced = bucket.unpriced ? ` (${bucket.unpriced} unpriced)` : ""; // `{:<18}` pads but never truncates: a longer role overflows the column. lines.push( ` ${ljust(bucket.bucket, 18)} ${String(bucket.calls).padStart(5)} calls ` + `${bucket.promptTokens}→${bucket.completionTokens} tokens ` + `${formatSummaryCost(bucket.costUsd)}${unpriced}`, ); } }; block("By role:", summary.byRole); block("By week:", summary.byWeek); const unpriced = summary.total.unpriced ? ` (${summary.total.unpriced} unpriced)` : ""; lines.push(""); lines.push( `TOTAL ${summary.total.calls} calls ` + `${summary.total.promptTokens}→${summary.total.completionTokens} tokens ` + `${formatSummaryCost(summary.total.costUsd)}${unpriced}`, ); return `${lines.join("\n")}\n`; } /** Port of `render_embedding_provenance`. */ export function renderEmbeddingProvenance( distribution: ReadonlyArray, ): string { const total = distribution.reduce((sum, [, count]) => sum + count, 0); if (total === 0) return "(no stored memory vectors)"; const lines = [`=== embedding provenance (${total} memory vector${total !== 1 ? "s" : ""}) ===`]; for (const [model, count] of distribution) { lines.push(` ${String(count).padStart(6)} ${model ? model : "unknown (pre-provenance)"}`); } return lines.join("\n"); } export interface LedgerCommandResult { stdout: string; stderr: string; exitCode: number; } interface LlmCallOptions { conversationId: string | null; sessionId: string | null; role: string | null; since: string | null; limit: number; summary: boolean; } /** * The argparse-class refusal for these two leaves: exit 2, stderr, and a * one-line TypeScript message rather than argparse's usage block. * * Deliberate, and the same recorded divergence US8 pinned: argparse wraps its * usage to the terminal's `COLUMNS`, so the "byte-identical" text would only * be byte-identical at the width the golden was generated with. The graded * contract is the input set, the stream, and the exit code. */ function usageError(message: string): LedgerCommandResult { return { stdout: "", stderr: `Mirror TS inspect: ${message}\n`, exitCode: 2 }; } const LLM_CALL_VALUE_OPTIONS = new Map([ ["--conversation", "conversationId"], ["--session", "sessionId"], ["--role", "role"], ["--since", "since"], ]); function parseLlmCallArgv(argv: readonly string[]): LlmCallOptions | LedgerCommandResult { const options: LlmCallOptions = { conversationId: null, sessionId: null, role: null, since: null, limit: 20, summary: false, }; for (let index = 0; index < argv.length; index += 1) { const token = argv[index] as string; if (token === "--summary") continue; if (token === "--mirror-home") { if (argv[index + 1] === undefined) return usageError("argument --mirror-home: expected one argument"); index += 1; continue; } if (token === "--limit") { const value = argv[index + 1]; if (value === undefined) return usageError("argument --limit: expected one argument"); if (!/^[+-]?\d+$/.test(value.trim())) { return usageError(`argument --limit: invalid int value: ${pyRepr(value)}`); } options.limit = Number.parseInt(value, 10); index += 1; continue; } const field = LLM_CALL_VALUE_OPTIONS.get(token); if (field === undefined) return usageError(`unrecognized arguments: ${token}`); const value = argv[index + 1]; if (value === undefined) return usageError(`argument ${token}: expected one argument`); (options[field] as string | null) = value; index += 1; } options.summary = argv.includes("--summary"); return options; } /** Port of `cmd_inspect_llm_calls`, both faces. */ export function runInspectLlmCalls(db: Database, argv: readonly string[]): LedgerCommandResult { const parsed = parseLlmCallArgv(argv); if ("stdout" in parsed) return parsed; if (parsed.summary) { const summary = getLlmCallSummary(db, parsed.since ? { since: parsed.since } : {}); return { stdout: renderLlmCallSummary(summary, parsed.since), stderr: "", exitCode: 0 }; } let rows = getLlmCalls(db, { conversationId: parsed.conversationId, role: parsed.role, limit: parsed.limit, }); // AFTER the store's LIMIT, exactly as Python does it. if (parsed.sessionId) rows = rows.filter((row) => row.sessionId === parsed.sessionId); if (parsed.since) { const since = parsed.since; rows = rows.filter((row) => (row.calledAt || "") >= since); } return { stdout: renderLlmCallRows(rows), stderr: "", exitCode: 0 }; } /** Port of `cmd_inspect_embedding_provenance`. */ export function runInspectEmbeddingProvenance( db: Database, argv: readonly string[], ): LedgerCommandResult { for (let index = 0; index < argv.length; index += 1) { const token = argv[index] as string; if (token === "--mirror-home") { if (argv[index + 1] === undefined) { return usageError("argument --mirror-home: expected one argument"); } index += 1; continue; } return usageError(`unrecognized arguments: ${token}`); } return { stdout: `${renderEmbeddingProvenance(countMemoriesByEmbeddingModel(db))}\n`, stderr: "", exitCode: 0, }; }