@iowarp/clio-coder 0.3.0 → 0.3.1

package/src/domains/observability/cost.ts

@@ -0,0 +1,206 @@
+/**
+ * Running USD cost accumulator. The catalog-backed auto-pricing fallback was
+ * dropped in the provider redesign; pricing now flows from the providers
+ * domain's TargetPricing + knowledge-base entries and the caller supplies
+ * the resolved `usd` per call. Unknown or unpriced calls accumulate zero so
+ * they never blow up the tally.
+ *
+ * Per-entry token breakdown (input/output/cacheRead/cacheWrite/reasoning)
+ * matches the shape of pi-ai's `Usage` plus provider-specific reasoning detail
+ * fields. The /cost overlay aggregates it via `aggregateCostEntries`; the TUI
+ * footer consumes the session sum through `ObservabilityContract.sessionTokens()`.
+ */
+
+import { type CostProvenance, normalizeCostProvenance } from "../providers/index.js";
+
+export interface CostAmount {
+	usd: number;
+	provenance: CostProvenance;
+}
+
+export interface CostAggregate {
+	knownUsd: number;
+	hasEstimated: boolean;
+	hasUnknown: boolean;
+	allKnownFree: boolean;
+	/**
+	 * How many priced calls this aggregate folded.
+	 *
+	 * Zero and "measured zero" are different claims and the flags above cannot
+	 * tell them apart: a session that has not made a call and a session whose one
+	 * call was genuinely free both reduce to `knownUsd: 0` with every flag false.
+	 * The footer rendered the first as `$0.00`, a number nothing had measured,
+	 * while `/cost` on the same session said no usage was recorded. Callers ask
+	 * {@link costWasMeasured} rather than reading this directly.
+	 */
+	calls: number;
+}
+
+export function emptyCostAggregate(): CostAggregate {
+	return { knownUsd: 0, hasEstimated: false, hasUnknown: false, allKnownFree: false, calls: 0 };
+}
+
+/** False when nothing has been priced yet, so no cost claim of any kind is available. */
+export function costWasMeasured(cost: CostAggregate | null | undefined): cost is CostAggregate {
+	return cost !== null && cost !== undefined && cost.calls > 0;
+}
+
+function accumulateCostAmount(aggregate: CostAggregate, amount: CostAmount, first: boolean): CostAggregate {
+	return {
+		knownUsd: aggregate.knownUsd + (amount.provenance === "unknown" ? 0 : amount.usd),
+		hasEstimated: aggregate.hasEstimated || amount.provenance === "estimated",
+		hasUnknown: aggregate.hasUnknown || amount.provenance === "unknown",
+		allKnownFree: amount.provenance === "known_free" && (first || aggregate.allKnownFree),
+		calls: aggregate.calls + 1,
+	};
+}
+
+export function aggregateCostAmounts(amounts: ReadonlyArray<CostAmount>): CostAggregate {
+	return amounts.reduce(
+		(aggregate, amount, index) => accumulateCostAmount(aggregate, amount, index === 0),
+		emptyCostAggregate(),
+	);
+}
+
+function formatUsdAmount(value: number): string {
+	if (!Number.isFinite(value) || value <= 0) return "$0.00";
+	return value < 0.01 ? `$${value.toFixed(4)}` : `$${value.toFixed(2)}`;
+}
+
+/**
+ * The one derivation every cost surface renders. Null means there is no cost
+ * claim to make, and a null must be shown as the absence of a cost field rather
+ * than as any number: `$0.00` before the first call was a measurement that had
+ * not happened, and it sat beside a `/cost` overlay saying no usage was recorded.
+ *
+ * Two different situations reduce to null. Nothing priced yet is one. A target
+ * that reports no pricing at all is the other: those calls were made and their
+ * tokens were measured, but nobody put a number on them, so the honest cost
+ * field is no field. The words `cost unknown` were themselves a claim, and they
+ * rendered beside a Σ total that was real, which read as if the tokens were in
+ * doubt too. Usage always shows; cost shows when something priced it.
+ */
+export function formatCostAggregate(cost: CostAggregate | null | undefined): string | null {
+	if (!costWasMeasured(cost)) return null;
+	if (cost.allKnownFree) return "$0.00 local";
+	// Partly priced still says what it knows, with the `+?` marking the rest.
+	if (cost.hasUnknown) return cost.knownUsd > 0 ? `${formatUsdAmount(cost.knownUsd)} +?` : null;
+	if (cost.hasEstimated) return `~${formatUsdAmount(cost.knownUsd)} est`;
+	return formatUsdAmount(cost.knownUsd);
+}
+
+/**
+ * What a fixed-width surface says when there is no cost claim. The footer and
+ * `/cost` drop their cost field instead; a table cell that owns a column cannot,
+ * so it says the same thing in words rather than inventing `$0.00`.
+ */
+export const COST_NOT_MEASURED = "not measured";
+
+export function costAggregateForAmount(usd: number, provenance: CostProvenance | undefined): CostAggregate {
+	return aggregateCostAmounts([{ usd, provenance: normalizeCostProvenance(provenance) }]);
+}
+
+export interface UsageBreakdown {
+	input: number;
+	output: number;
+	cacheRead: number;
+	cacheWrite: number;
+	reasoningTokens: number;
+	totalTokens: number;
+	apiCalls?: number;
+}
+
+export interface CostEntry {
+	providerId: string;
+	modelId: string;
+	tokens: number;
+	usd: number;
+	provenance: CostProvenance;
+	input: number;
+	output: number;
+	cacheRead: number;
+	cacheWrite: number;
+	reasoningTokens: number;
+	apiCalls?: number;
+}
+
+export interface CostTracker {
+	accumulate(
+		providerId: string,
+		modelId: string,
+		tokens: number,
+		usd?: number,
+		breakdown?: Partial<UsageBreakdown>,
+		provenance?: CostProvenance,
+	): number;
+	sessionTotal(): number;
+	sessionCost(): CostAggregate;
+	sessionTokens(): UsageBreakdown;
+	entries(): ReadonlyArray<CostEntry>;
+	reset(): void;
+}
+
+function emptyBreakdown(): UsageBreakdown {
+	return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, reasoningTokens: 0, totalTokens: 0 };
+}
+
+export function createCostTracker(): CostTracker {
+	const log: CostEntry[] = [];
+	let total = 0;
+	const totals = emptyBreakdown();
+	return {
+		accumulate(providerId, modelId, tokens, usd, breakdown, costProvenance) {
+			const resolvedUsd = usd ?? 0;
+			const provenance = normalizeCostProvenance(costProvenance);
+			const input = breakdown?.input ?? 0;
+			const output = breakdown?.output ?? 0;
+			const cacheRead = breakdown?.cacheRead ?? 0;
+			const cacheWrite = breakdown?.cacheWrite ?? 0;
+			const reasoningTokens = breakdown?.reasoningTokens ?? 0;
+			const apiCalls = breakdown?.apiCalls;
+			log.push({
+				providerId,
+				modelId,
+				tokens,
+				usd: resolvedUsd,
+				provenance,
+				input,
+				output,
+				cacheRead,
+				cacheWrite,
+				reasoningTokens,
+				...(apiCalls !== undefined ? { apiCalls } : {}),
+			});
+			total += resolvedUsd;
+			totals.input += input;
+			totals.output += output;
+			totals.cacheRead += cacheRead;
+			totals.cacheWrite += cacheWrite;
+			totals.reasoningTokens += reasoningTokens;
+			totals.totalTokens += tokens;
+			return resolvedUsd;
+		},
+		sessionTotal() {
+			return total;
+		},
+		sessionCost() {
+			return aggregateCostAmounts(log.map((entry) => ({ usd: entry.usd, provenance: entry.provenance })));
+		},
+		sessionTokens() {
+			return { ...totals };
+		},
+		entries() {
+			return log;
+		},
+		reset() {
+			log.length = 0;
+			total = 0;
+			totals.input = 0;
+			totals.output = 0;
+			totals.cacheRead = 0;
+			totals.cacheWrite = 0;
+			totals.reasoningTokens = 0;
+			totals.totalTokens = 0;
+		},
+	};
+}

package/src/domains/observability/evidence-index.ts

@@ -0,0 +1,123 @@
+/**
+ * Sidecar evidence index. A compact, append/merge-by-runId ledger written
+ * under `<stateDir>/evidence-index.json` whenever a dispatch run completes and
+ * the forensic evidence bundle is built (see extension.ts). Slice 6 reads this
+ * to surface a rolling first-pass-success rate and a failure-cause histogram in
+ * observability without re-running the heavy `buildEvidence` aggregator.
+ *
+ * The file is a JSON array kept as a bounded ring (newest rows win, capped at
+ * MAX_EVIDENCE_INDEX_ROWS) mirroring the dispatch runs ledger. Read/merge/write
+ * sections use the same cross-process state-file lock as runs.json; writes are
+ * then atomic via safeResourceWrite (tmp + rename). Reads are tolerant: a
+ * missing or malformed file yields an empty index rather than throwing, so a
+ * corrupt sidecar never blocks a run or a view.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { safeResourceWrite } from "../../core/safe-resource-write.js";
+import { withStateFileLock } from "../../core/state-file-lock.js";
+import type { EvidenceTag } from "../evidence/index.js";
+
+/** Cap on retained index rows. Matches the dispatch runs ledger default. */
+export const MAX_EVIDENCE_INDEX_ROWS = 1000;
+
+/** Filename of the sidecar index under the state dir. */
+export const EVIDENCE_INDEX_FILE = "evidence-index.json";
+
+let evidenceIndexWriteQueue: Promise<void> = Promise.resolve();
+
+/**
+ * One row of the sidecar evidence index, keyed by runId. Derived from the
+ * `EvidenceBuildResult` produced by `buildEvidence` plus the terminal dispatch
+ * payload. `tags` and `findingCount` come from the built bundle's findings.
+ * `firstPassSuccess` is computed from forensic evidence and is the authority
+ * for user-visible accountability rates. The receipt's cheap findings summary
+ * is intentionally conservative and may be false when transcript-level
+ * validation evidence makes this value true.
+ */
+export interface EvidenceIndexRow {
+	runId: string;
+	evidenceId: string;
+	tags: EvidenceTag[];
+	firstPassSuccess: boolean;
+	findingCount: number;
+	/** ISO-8601 timestamp the row was written. */
+	generatedAt: string;
+}
+
+function indexPath(stateDir: string): string {
+	return join(stateDir, EVIDENCE_INDEX_FILE);
+}
+
+function isEvidenceIndexRow(value: unknown): value is EvidenceIndexRow {
+	if (typeof value !== "object" || value === null) return false;
+	const row = value as Record<string, unknown>;
+	return (
+		typeof row.runId === "string" &&
+		typeof row.evidenceId === "string" &&
+		Array.isArray(row.tags) &&
+		row.tags.every((tag) => typeof tag === "string") &&
+		typeof row.firstPassSuccess === "boolean" &&
+		typeof row.findingCount === "number" &&
+		typeof row.generatedAt === "string"
+	);
+}
+
+/**
+ * Read the sidecar evidence index. Tolerant by design: a missing file, invalid
+ * JSON, or a non-array payload all yield an empty array. Malformed rows are
+ * dropped, valid rows are kept.
+ */
+export function readEvidenceIndex(stateDir: string): EvidenceIndexRow[] {
+	let raw: string;
+	try {
+		raw = readFileSync(indexPath(stateDir), "utf8");
+	} catch {
+		return [];
+	}
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(raw) as unknown;
+	} catch {
+		return [];
+	}
+	if (!Array.isArray(parsed)) return [];
+	return parsed.filter(isEvidenceIndexRow);
+}
+
+/**
+ * Merge one row into the sidecar index by runId and write it back atomically.
+ * An existing row with the same runId is replaced (a retried run that finalizes
+ * again overwrites the stale entry); the merged row is moved to the tail so the
+ * ring keeps the most recently written entries when it is bounded. Returns the
+ * full index as written.
+ */
+async function writeEvidenceIndexRow(stateDir: string, row: EvidenceIndexRow): Promise<EvidenceIndexRow[]> {
+	let bounded: EvidenceIndexRow[] = [];
+	await withStateFileLock(indexPath(stateDir), () => {
+		const existing = readEvidenceIndex(stateDir).filter((entry) => entry.runId !== row.runId);
+		existing.push(row);
+		bounded = existing.length > MAX_EVIDENCE_INDEX_ROWS ? existing.slice(-MAX_EVIDENCE_INDEX_ROWS) : existing;
+		safeResourceWrite(indexPath(stateDir), `${JSON.stringify(bounded, null, 2)}\n`, { encoding: "utf8" });
+	});
+	return bounded;
+}
+
+/**
+ * Queue index row merges within this process. The state-file lock serializes
+ * across processes; this queue avoids avoidable local lock contention when
+ * terminal dispatch events start several evidence builds in parallel.
+ */
+export async function writeEvidenceIndexRowQueued(
+	stateDir: string,
+	row: EvidenceIndexRow,
+): Promise<EvidenceIndexRow[]> {
+	let written: EvidenceIndexRow[] = [];
+	const write = evidenceIndexWriteQueue.then(async () => {
+		written = await writeEvidenceIndexRow(stateDir, row);
+	});
+	evidenceIndexWriteQueue = write.catch(() => undefined);
+	await write;
+	return written;
+}

package/src/domains/observability/extension.ts

@@ -0,0 +1,281 @@
+/**
+ * Observability domain wire-up. Listens to dispatch + safety bus channels and
+ * folds payloads into telemetry/cost trackers. Emits nothing; other domains
+ * read the snapshot through the contract.
+ */
+
+import { BusChannels, type DispatchCompletedPayload } from "../../core/bus-events.js";
+import type { DomainBundle, DomainContext, DomainExtension } from "../../core/domain-loader.js";
+import { clioDataDir, clioStateDir } from "../../core/xdg.js";
+import { buildEvidence, type EvidenceBuildResult } from "../evidence/index.js";
+import { readAccountabilitySummary } from "./accountability.js";
+import type { ObservabilityContract, ObservabilityRunEvidence, TokenThroughputSnapshot } from "./contract.js";
+import { createCostTracker } from "./cost.js";
+import { type EvidenceIndexRow, writeEvidenceIndexRowQueued } from "./evidence-index.js";
+import { aggregateMetrics } from "./metrics.js";
+import { createObservabilityProjection } from "./projection.js";
+import { createTelemetry } from "./telemetry.js";
+import { createDispatchTraceMirror, type DispatchTraceMirror, traceDatabasePath } from "./trace-store.js";
+
+/**
+ * Callbacks the auto-build path uses to report evidence readiness back to the
+ * projection without coupling the pure build helper to it. `onReady` fires once
+ * the sidecar index row lands; `onFailed` fires when the build or write throws.
+ */
+interface EvidenceBuildHooks {
+	onReady(runId: string, evidence: ObservabilityRunEvidence): void;
+	onFailed(runId: string, message: string): void;
+}
+
+/**
+ * Terminal dispatch payload with every field optional. Partial<> alone does
+ * not admit DispatchFailedPayload under exactOptionalPropertyTypes, and this
+ * subscriber treats completed/failed identically for cost purposes.
+ */
+type DispatchTerminalLike = {
+	[K in keyof DispatchCompletedPayload]?: DispatchCompletedPayload[K] | undefined;
+};
+
+function recordDispatchCost(
+	telemetry: ReturnType<typeof createTelemetry>,
+	cost: ReturnType<typeof createCostTracker>,
+	payload: DispatchTerminalLike,
+): void {
+	if (!payload.targetId || !payload.wireModelId || typeof payload.tokenCount !== "number") {
+		return;
+	}
+	telemetry.record("counter", "tokens.total", payload.tokenCount);
+	// Dispatch terminal payloads carry the same full split as receipts. Preserve
+	// it so /cost and the footer agree with the fleet board instead of showing
+	// zero input/output/cache for worker-only sessions.
+	cost.accumulate(
+		payload.targetId,
+		payload.wireModelId,
+		payload.tokenCount,
+		payload.costUsd,
+		{
+			input: payload.inputTokenCount ?? 0,
+			output: payload.outputTokenCount ?? 0,
+			cacheRead: payload.cacheReadTokenCount ?? 0,
+			cacheWrite: payload.cacheWriteTokenCount ?? 0,
+			reasoningTokens: payload.reasoningTokenCount ?? 0,
+			totalTokens: payload.tokenCount,
+		},
+		payload.costProvenance,
+	);
+}
+
+/**
+ * Build the forensic evidence bundle for a finalized run and record a compact
+ * sidecar index row. Best-effort: every failure (build throws, write throws) is
+ * logged to stderr and swallowed so a run completes normally regardless.
+ *
+ * `succeeded` distinguishes the DispatchCompleted channel (terminal success)
+ * from DispatchFailed; only a succeeded run is eligible for firstPassSuccess.
+ * `attempt` is the dispatch lineage attempt (0 = first try, increments per
+ * retry). A retry, a non-success outcome, or a bundle that shows no validation
+ * evidence all force firstPassSuccess to false. See section 7 of the spec.
+ */
+async function buildAndIndexEvidence(
+	runId: string,
+	succeeded: boolean,
+	attempt: number | undefined,
+	hooks: EvidenceBuildHooks,
+): Promise<void> {
+	try {
+		const dataDir = clioDataDir();
+		const stateDir = clioStateDir();
+		const result = await buildEvidence({ dataDir, stateDir, runId });
+		const row = evidenceIndexRow(runId, result, succeeded, attempt);
+		await writeEvidenceIndexRowQueued(stateDir, row);
+		hooks.onReady(runId, {
+			evidenceId: row.evidenceId,
+			firstPassSuccess: row.firstPassSuccess,
+			findingCount: row.findingCount,
+			tags: row.tags,
+		});
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		process.stderr.write(`[clio:evidence] auto-build failed for run ${runId}: ${message}\n`);
+		hooks.onFailed(runId, message);
+	}
+}
+
+/**
+ * firstPassSuccess is TRUE only when the terminal outcome succeeded, the run
+ * had zero dispatch retries (lineage attempt 0), and the built bundle carries
+ * validation evidence. We read validation evidence negatively: a bundle whose
+ * overview or findings tags include `no-validation` means the run produced no
+ * validation, so it cannot first-pass-succeed.
+ */
+function evidenceIndexRow(
+	runId: string,
+	result: EvidenceBuildResult,
+	succeeded: boolean,
+	attempt: number | undefined,
+): EvidenceIndexRow {
+	const tags = result.overview.tags;
+	const hasNoValidationTag =
+		tags.includes("no-validation") || result.findings.some((finding) => finding.tag === "no-validation");
+	const firstPassSuccess = succeeded && attempt === 0 && !hasNoValidationTag;
+	return {
+		runId,
+		evidenceId: result.evidenceId,
+		tags: [...tags],
+		firstPassSuccess,
+		findingCount: result.findings.length,
+		generatedAt: new Date().toISOString(),
+	};
+}
+
+export interface ObservabilityBundleOptions {
+	/** Disable the SQLite dispatch mirror for short-lived internal generators. */
+	dispatchTrace?: boolean;
+}
+
+export function createObservabilityBundle(
+	context: DomainContext,
+	options: ObservabilityBundleOptions = {},
+): DomainBundle<ObservabilityContract> {
+	const telemetry = createTelemetry();
+	const cost = createCostTracker();
+	const trace: DispatchTraceMirror =
+		options.dispatchTrace === false
+			? { enqueue: () => {}, enqueueSessionTurn: () => {}, flush: async () => {}, close: async () => {} }
+			: createDispatchTraceMirror(traceDatabasePath(clioStateDir()));
+	const unsubscribes: Array<() => void> = [];
+	let latestThroughput: TokenThroughputSnapshot | null = null;
+
+	// The product-facing projection folds the bus channels plus the session
+	// cost/telemetry trackers into a single bounded snapshot. It reads these
+	// accessors at snapshot-build time, so it always observes the latest state
+	// regardless of bus-handler ordering.
+	const projection = createObservabilityProjection(context.bus, {
+		metrics: () => aggregateMetrics(telemetry.snapshot()),
+		sessionCost: () => cost.sessionTotal(),
+		sessionCostSummary: () => cost.sessionCost(),
+		sessionTokens: () => cost.sessionTokens(),
+		latestThroughput: () => latestThroughput,
+		readAccountability: () => readAccountabilitySummary(clioStateDir()),
+	});
+
+	// In-flight forensic builds. The terminal event is emitted after the receipt
+	// and ledger are persisted (dispatch finalizers persist before emit), so a
+	// build that starts here reads durable state. We keep the bus handler
+	// non-blocking by not awaiting the build inline, but a headless one-shot
+	// `clio-coder run` tears the process down right after the run, which would abandon
+	// the build mid-flight. Tracking the promises lets stop() flush them so the
+	// bundle and index row reliably land on every path, not just long-lived
+	// interactive sessions.
+	const pendingBuilds = new Set<Promise<void>>();
+	const trackBuild = (runId: string, succeeded: boolean, attempt: number | undefined): void => {
+		projection.evidenceBuildStarted(runId);
+		const build = buildAndIndexEvidence(runId, succeeded, attempt, {
+			onReady: (id, evidence) => projection.evidenceBuildSucceeded(id, evidence),
+			onFailed: (id, message) => projection.evidenceBuildFailed(id, message),
+		});
+		pendingBuilds.add(build);
+		void build.finally(() => pendingBuilds.delete(build));
+	};
+
+	const extension: DomainExtension = {
+		async start() {
+			for (const channel of [
+				BusChannels.DispatchEnqueued,
+				BusChannels.DispatchStarted,
+				BusChannels.DispatchProgress,
+				BusChannels.DispatchCompleted,
+				BusChannels.DispatchFailed,
+			] as const) {
+				unsubscribes.push(context.bus.on(channel, (payload) => trace.enqueue(channel, payload)));
+			}
+			unsubscribes.push(
+				context.bus.on(BusChannels.DispatchCompleted, (raw) => {
+					const payload: DispatchTerminalLike = raw ?? {};
+					telemetry.record("counter", "dispatch.completed", 1);
+					if (typeof payload.durationMs === "number") {
+						telemetry.record("histogram", "dispatch.duration_ms", payload.durationMs);
+					}
+					recordDispatchCost(telemetry, cost, payload);
+					// Kick off the heavy forensic build without blocking the bus.
+					// buildAndIndexEvidence swallows all failures; stop() flushes it.
+					if (typeof payload.runId === "string" && payload.runId.length > 0) {
+						trackBuild(payload.runId, true, payload.lineage?.attempt);
+					}
+				}),
+			);
+			unsubscribes.push(
+				context.bus.on(BusChannels.DispatchFailed, (raw) => {
+					const payload: DispatchTerminalLike = raw ?? {};
+					telemetry.record("counter", "dispatch.failed", 1);
+					if (typeof payload.durationMs === "number") {
+						telemetry.record("histogram", "dispatch.duration_ms", payload.durationMs);
+					}
+					recordDispatchCost(telemetry, cost, payload);
+					// A failed run is never a first-pass success; still build the
+					// bundle so its failure-cause tags exist for the index.
+					if (typeof payload.runId === "string" && payload.runId.length > 0) {
+						trackBuild(payload.runId, false, payload.lineage?.attempt);
+					}
+				}),
+			);
+			unsubscribes.push(
+				context.bus.on(BusChannels.SafetyClassified, () => {
+					telemetry.record("counter", "safety.classified", 1);
+					// The projection reads metrics off telemetry; nudge it so the
+					// safety-classification counter reaches the snapshot.
+					projection.refresh();
+				}),
+			);
+		},
+		async stop() {
+			for (const off of unsubscribes) off();
+			unsubscribes.length = 0;
+			projection.stop();
+			// Terminal trace facts are the live operator contract. Flush them before
+			// potentially slower evidence builds consume the remaining hook budget.
+			await trace.close();
+			// Flush any in-flight forensic builds so a headless run that shuts down
+			// immediately after dispatch still persists its bundle and index row.
+			// Best-effort and bounded by the shutdown hook budget; each build
+			// already swallows its own failures.
+			if (pendingBuilds.size > 0) {
+				await Promise.allSettled([...pendingBuilds]);
+			}
+		},
+	};
+
+	const contract: ObservabilityContract = {
+		telemetry: () => telemetry.snapshot(),
+		metrics: () => aggregateMetrics(telemetry.snapshot()),
+		sessionCost: () => cost.sessionTotal(),
+		sessionCostSummary: () => cost.sessionCost(),
+		sessionTokens: () => cost.sessionTokens(),
+		costEntries: () => cost.entries(),
+		accountability: () => readAccountabilitySummary(clioStateDir()),
+		latestTokenThroughput: () => latestThroughput,
+		resetSession() {
+			cost.reset();
+			latestThroughput = null;
+			projection.refresh();
+		},
+		recordTokens(providerId, modelId, tokens, costUsd, breakdown, costProvenance) {
+			telemetry.record("counter", "tokens.total", tokens);
+			cost.accumulate(providerId, modelId, tokens, costUsd, breakdown, costProvenance);
+			projection.refresh();
+		},
+		recordSessionTurn(sessionTurn) {
+			trace.enqueueSessionTurn(sessionTurn);
+		},
+		recordTokenThroughput(snapshot) {
+			latestThroughput = snapshot;
+			telemetry.record("histogram", "tokens.output_per_second", snapshot.tokensPerSecond);
+			telemetry.record("histogram", "tokens.ttft_ms", snapshot.ttftMs ?? 0);
+			projection.refresh();
+		},
+		snapshot: () => projection.snapshot(),
+		subscribe: (listener) => projection.subscribe(listener),
+	};
+
+	return { extension, contract };
+}

package/src/domains/observability/index.ts

@@ -0,0 +1,78 @@
+import type { DomainModule } from "../../core/domain-loader.js";
+import { createObservabilityBundle, type ObservabilityBundleOptions } from "./extension.js";
+import { ObservabilityManifest } from "./manifest.js";
+
+export const ObservabilityDomainModule: DomainModule = {
+	manifest: ObservabilityManifest,
+	createExtension: createObservabilityBundle,
+};
+
+export function createObservabilityDomainModule(options: ObservabilityBundleOptions = {}): DomainModule {
+	return {
+		manifest: ObservabilityManifest,
+		createExtension: (context) => createObservabilityBundle(context, options),
+	};
+}
+
+export type { AccountabilitySummary } from "./accountability.js";
+export { readAccountabilitySummary, summarizeEvidenceIndex } from "./accountability.js";
+export type {
+	ObservabilityContract,
+	ObservabilityNotice,
+	ObservabilityRunEvidence,
+	ObservabilityRunSummary,
+	ObservabilitySnapshot,
+	TokenThroughputSnapshot,
+} from "./contract.js";
+export {
+	aggregateCostAmounts,
+	COST_NOT_MEASURED,
+	type CostAggregate,
+	type CostAmount,
+	type CostEntry,
+	costAggregateForAmount,
+	costWasMeasured,
+	emptyCostAggregate,
+	formatCostAggregate,
+	type UsageBreakdown,
+} from "./cost.js";
+export type { EvidenceIndexRow } from "./evidence-index.js";
+export { EVIDENCE_INDEX_FILE, MAX_EVIDENCE_INDEX_ROWS, readEvidenceIndex } from "./evidence-index.js";
+export { ObservabilityManifest } from "./manifest.js";
+export type { MetricsView } from "./metrics.js";
+export type { ObservabilityProjection, ProjectionReadModel } from "./projection.js";
+export {
+	createObservabilityProjection,
+	MAX_PROJECTION_NOTICES,
+	MAX_PROJECTION_RUNS,
+	PROJECTION_FLUSH_DEBOUNCE_MS,
+} from "./projection.js";
+export { DEFAULT_HISTOGRAM_CAPACITY, type MetricKind, type TelemetrySnapshot } from "./telemetry.js";
+export type {
+	DispatchTraceMirror,
+	SessionTurnEvent,
+	SessionTurnFinish,
+	SessionTurnStart,
+	SessionTurnTrace,
+	SessionTurnUsage,
+	TraceEventInput,
+	TraceEventRow,
+	TraceGateCheck,
+	TraceGateResultInput,
+	TracePhaseRow,
+	TraceProcessInput,
+	TraceProcessRow,
+	TraceRunRow,
+	TraceSpendInput,
+} from "./trace-store.js";
+export {
+	createDispatchTraceMirror,
+	SESSION_TRACE_ASSIGNMENT_ID,
+	TRACE_DATABASE_FILE,
+	TRACE_EVENT_POLL_LIMIT,
+	TRACE_SCHEMA_VERSION,
+	TraceReader,
+	TraceSchemaVersionError,
+	TraceStore,
+	traceDatabasePath,
+} from "./trace-store.js";

package/src/domains/observability/manifest.ts

@@ -0,0 +1,10 @@
+import type { DomainManifest } from "../../core/domain-loader.js";
+
+export const ObservabilityManifest: DomainManifest = {
+	// observability listens to dispatch + safety bus channels but never reads
+	// their contracts. Keeping dispatch out of dependsOn lets scheduling sit
+	// between observability and dispatch (scheduling -> observability, dispatch
+	// -> scheduling) without a topological cycle.
+	name: "observability",
+	dependsOn: ["providers", "session"],
+};