@resolveio/server-lib 22.3.140 → 22.3.142

package/src/util/ai-run-evidence.ts

@@ -0,0 +1,964 @@
+export type AIRunSource =
+	| 'support_ticket'
+	| 'aicoder_app'
+	| 'ai_assistant'
+	| 'qa_runner'
+	| 'unknown';
+
+export type AIRunOutcomeLabel =
+	| 'accepted'
+	| 'rejected'
+	| 'qa_incomplete'
+	| 'qa_infra_failed'
+	| 'build_failed'
+	| 'release_blocked'
+	| 'manual_handoff'
+	| 'false_pass'
+	| 'stopped'
+	| 'unknown';
+
+export type AIRunEventType =
+	| 'model_call'
+	| 'log'
+	| 'qa_infra'
+	| 'qa_compile'
+	| 'qa_route_probe'
+	| 'qa_business_assertion'
+	| 'scorecard'
+	| 'deploy'
+	| 'publish'
+	| 'assistant_message'
+	| 'git_commit'
+	| 'usage'
+	| 'human_intervention';
+
+export type AIRunGateStatus = 'pass' | 'fail' | 'warn' | 'blocked' | 'skipped';
+
+export type AIQaCheckStatus = 'pass' | 'fail' | 'blocked' | 'warn' | 'skipped' | 'unknown';
+
+export type AIQaCompileStatus = 'pass' | 'fail' | 'blocked' | 'stale' | 'skipped' | 'unknown';
+
+export type AIQaOutcome =
+	| 'infra_failed'
+	| 'compile_failed'
+	| 'route_failed'
+	| 'route_only_pass'
+	| 'business_assertion_passed'
+	| 'business_assertion_failed'
+	| 'incomplete';
+
+export interface AIRunEvent {
+	id?: string;
+	type: AIRunEventType;
+	source?: AIRunSource | string;
+	message?: string;
+	category?: string;
+	artifactPaths?: string[];
+	metadata?: Record<string, any>;
+	recordedAt?: Date | string;
+}
+
+export interface AIRunGateResult {
+	key: string;
+	label: string;
+	status: AIRunGateStatus;
+	reason: string;
+	evidenceRefs: string[];
+	recordedAt: string;
+	metadata?: Record<string, any>;
+}
+
+export interface AIRunCost {
+	inputTokens: number;
+	cachedInputTokens: number;
+	outputTokens: number;
+	totalTokens: number;
+	estimatedUsd: number;
+	models: string[];
+	categories: Record<string, {
+		inputTokens: number;
+		cachedInputTokens: number;
+		outputTokens: number;
+		totalTokens: number;
+		estimatedUsd: number;
+		count: number;
+	}>;
+	wallTimeMs?: number;
+	retries?: number;
+}
+
+export interface OpenAIUsageCostEntry {
+	model?: string;
+	category?: string;
+	id_request?: string;
+	idRequest?: string;
+	id_conversation?: string;
+	idConversation?: string;
+	timestamp?: Date | string;
+	input_tokens?: number;
+	inputTokens?: number;
+	cached_input_tokens?: number;
+	cachedInputTokens?: number;
+	output_tokens?: number;
+	outputTokens?: number;
+	total_tokens?: number;
+	totalTokens?: number;
+	cost_estimate?: number;
+	estimatedUsd?: number;
+	[key: string]: any;
+}
+
+export interface AIQaInfraCheck {
+	name: string;
+	status: AIQaCheckStatus;
+	message?: string;
+	path?: string;
+	durationMs?: number;
+	metadata?: Record<string, any>;
+	checkedAt?: Date | string;
+}
+
+export interface AIQaCompileResult {
+	status: AIQaCompileStatus;
+	command?: string;
+	artifactPath?: string;
+	message?: string;
+	durationMs?: number;
+	staleEvidence?: boolean;
+	recordedAt?: Date | string;
+	metadata?: Record<string, any>;
+}
+
+export interface AIQaRouteProbe {
+	route: string;
+	status: AIQaCheckStatus;
+	screenshot?: string;
+	caption?: string;
+	shellOnly?: boolean;
+	authenticated?: boolean;
+	consoleErrors?: string[];
+	networkErrors?: string[];
+	message?: string;
+	recordedAt?: Date | string;
+	metadata?: Record<string, any>;
+}
+
+export interface AIQaBusinessAssertion {
+	assertion: string;
+	status: AIQaCheckStatus;
+	workflow?: string;
+	route?: string;
+	action?: string;
+	expected?: string;
+	observed?: string;
+	dataProof?: string;
+	mongoDelta?: Record<string, any>;
+	artifactPaths?: string[];
+	message?: string;
+	recordedAt?: Date | string;
+	metadata?: Record<string, any>;
+}
+
+export interface AIQaArtifact {
+	type: 'screenshot' | 'trace' | 'console_log' | 'network_log' | 'coverage_matrix' | 'seed_data' | 'script' | 'other';
+	path?: string;
+	url?: string;
+	title?: string;
+	caption?: string;
+	metadata?: Record<string, any>;
+}
+
+export interface AIQaRun {
+	outcome: AIQaOutcome;
+	infraChecks: AIQaInfraCheck[];
+	compile?: AIQaCompileResult;
+	routeProbes: AIQaRouteProbe[];
+	businessAssertions: AIQaBusinessAssertion[];
+	artifacts: AIQaArtifact[];
+	gateResults: AIRunGateResult[];
+	updatedAt: string;
+}
+
+export interface AIRun {
+	id?: string;
+	source: AIRunSource;
+	sourceIds: Record<string, string>;
+	title?: string;
+	status?: string;
+	phase?: string;
+	startedAt?: Date | string;
+	completedAt?: Date | string;
+	outcome: AIRunOutcomeLabel;
+	events: AIRunEvent[];
+	gates: AIRunGateResult[];
+	qa?: AIQaRun;
+	cost?: AIRunCost;
+	nextAction?: string;
+	warnings?: string[];
+	metadata?: Record<string, any>;
+}
+
+export interface AIRunTrainingExample {
+	runId: string;
+	source: AIRunSource;
+	inputSummary: string;
+	actionSummary: string;
+	outcome: AIRunOutcomeLabel;
+	evidence: string[];
+	cost?: AIRunCost;
+	metadata?: Record<string, any>;
+}
+
+export interface AIQaEvaluationInput {
+	infraChecks?: AIQaInfraCheck[];
+	compile?: AIQaCompileResult;
+	routeProbes?: AIQaRouteProbe[];
+	businessAssertions?: AIQaBusinessAssertion[];
+	artifacts?: AIQaArtifact[];
+	now?: Date | string;
+}
+
+export interface AIRunOutcomeInput {
+	source?: AIRunSource;
+	status?: string;
+	phase?: string;
+	qa?: AIQaRun | AIQaEvaluationInput;
+	gates?: AIRunGateResult[];
+	scorecardPassed?: boolean;
+	scorecardStatus?: string;
+	deployStatus?: string;
+	publishStatus?: string;
+	sampleDataStatus?: string;
+	manualHandoff?: boolean;
+	stopped?: boolean;
+	rejected?: boolean;
+	explicitAccepted?: boolean;
+	terminal?: boolean;
+	now?: Date | string;
+}
+
+export interface AIRunOutcomeDecision {
+	outcome: AIRunOutcomeLabel;
+	reason: string;
+	nextAction: string;
+	gates: AIRunGateResult[];
+	warnings: string[];
+	recordedAt: string;
+}
+
+function isoNow(value?: Date | string): string {
+	if (value instanceof Date) {
+		return value.toISOString();
+	}
+	const parsed = value ? new Date(value) : new Date();
+	if (Number.isFinite(parsed.getTime())) {
+		return parsed.toISOString();
+	}
+	return new Date().toISOString();
+}
+
+function cleanText(value: any, max = 1000): string {
+	return String(value || '').replace(/\s+/g, ' ').trim().slice(0, max);
+}
+
+function cleanUsageNumber(value: any): number {
+	const parsed = Number(value);
+	return Number.isFinite(parsed) ? parsed : 0;
+}
+
+function cleanUsageDate(value: any): Date | undefined {
+	if (!value) {
+		return undefined;
+	}
+	const date = value instanceof Date ? value : new Date(value);
+	return Number.isFinite(date.getTime()) ? date : undefined;
+}
+
+export function isCumulativeCodexUsageEntry(entry: OpenAIUsageCostEntry): boolean {
+	return cleanText(entry?.category, 180).toLowerCase().startsWith('ai-dashboard-codex:');
+}
+
+export function resolveOpenAIUsageThreadKey(entry: OpenAIUsageCostEntry): string {
+	const conversationId = cleanText(entry?.id_conversation ?? entry?.idConversation, 240);
+	if (conversationId) {
+		return conversationId;
+	}
+	return cleanText(entry?.id_request ?? entry?.idRequest, 240);
+}
+
+export function normalizeOpenAIUsageRowsForCosting<T extends OpenAIUsageCostEntry>(rows: T[] = []): T[] {
+	if (!Array.isArray(rows) || !rows.length) {
+		return [];
+	}
+	const sortedRows = rows
+		.map((row, index) => ({
+			...row,
+			_sortIndex: index
+		}))
+		.sort((a, b) => {
+			const timeA = cleanUsageDate(a.timestamp)?.getTime() || 0;
+			const timeB = cleanUsageDate(b.timestamp)?.getTime() || 0;
+			if (timeA !== timeB) {
+				return timeA - timeB;
+			}
+			const requestCompare = cleanText(a.id_request ?? a.idRequest, 240)
+				.localeCompare(cleanText(b.id_request ?? b.idRequest, 240));
+			if (requestCompare) {
+				return requestCompare;
+			}
+			const conversationCompare = cleanText(a.id_conversation ?? a.idConversation, 240)
+				.localeCompare(cleanText(b.id_conversation ?? b.idConversation, 240));
+			if (conversationCompare) {
+				return conversationCompare;
+			}
+			return cleanUsageNumber(a._sortIndex) - cleanUsageNumber(b._sortIndex);
+		});
+	const previousByThread = new Map<string, {
+		inputTokens: number;
+		cachedInputTokens: number;
+		outputTokens: number;
+		totalTokens: number;
+		estimatedUsd: number;
+	}>();
+	return sortedRows.map((row) => {
+		const inputTokens = cleanUsageNumber(row.input_tokens ?? row.inputTokens);
+		const cachedInputTokens = cleanUsageNumber(row.cached_input_tokens ?? row.cachedInputTokens);
+		const outputTokens = cleanUsageNumber(row.output_tokens ?? row.outputTokens);
+		const totalTokens = cleanUsageNumber(row.total_tokens ?? row.totalTokens ?? (inputTokens + outputTokens));
+		const estimatedUsd = cleanUsageNumber(row.cost_estimate ?? row.estimatedUsd);
+		const threadKey = isCumulativeCodexUsageEntry(row) ? resolveOpenAIUsageThreadKey(row) : '';
+		let normalizedInputTokens = inputTokens;
+		let normalizedCachedInputTokens = cachedInputTokens;
+		let normalizedOutputTokens = outputTokens;
+		let normalizedTotalTokens = totalTokens;
+		let normalizedEstimatedUsd = estimatedUsd;
+		if (threadKey) {
+			const previous = previousByThread.get(threadKey);
+			if (previous
+				&& inputTokens >= previous.inputTokens
+				&& cachedInputTokens >= previous.cachedInputTokens
+				&& outputTokens >= previous.outputTokens
+				&& totalTokens >= previous.totalTokens
+				&& estimatedUsd >= previous.estimatedUsd
+			) {
+				normalizedInputTokens = Math.max(0, inputTokens - previous.inputTokens);
+				normalizedCachedInputTokens = Math.max(0, cachedInputTokens - previous.cachedInputTokens);
+				normalizedOutputTokens = Math.max(0, outputTokens - previous.outputTokens);
+				normalizedTotalTokens = Math.max(0, totalTokens - previous.totalTokens);
+				normalizedEstimatedUsd = Math.max(0, estimatedUsd - previous.estimatedUsd);
+			}
+			previousByThread.set(threadKey, {
+				inputTokens,
+				cachedInputTokens,
+				outputTokens,
+				totalTokens,
+				estimatedUsd
+			});
+		}
+		const resolvedTotalTokens = normalizedTotalTokens || (normalizedInputTokens + normalizedOutputTokens);
+		const resolvedEstimatedUsd = Number(normalizedEstimatedUsd.toFixed(6));
+		return {
+			...row,
+			input_tokens: normalizedInputTokens,
+			inputTokens: normalizedInputTokens,
+			cached_input_tokens: normalizedCachedInputTokens,
+			cachedInputTokens: normalizedCachedInputTokens,
+			output_tokens: normalizedOutputTokens,
+			outputTokens: normalizedOutputTokens,
+			total_tokens: resolvedTotalTokens,
+			totalTokens: resolvedTotalTokens,
+			cost_estimate: resolvedEstimatedUsd,
+			estimatedUsd: resolvedEstimatedUsd
+		} as T;
+	});
+}
+
+function cleanList(values: any, limit = 20, max = 500): string[] {
+	if (!Array.isArray(values)) {
+		return [];
+	}
+	const result: string[] = [];
+	for (const value of values) {
+		const normalized = cleanText(value, max);
+		if (normalized && !result.includes(normalized)) {
+			result.push(normalized);
+		}
+		if (result.length >= limit) {
+			break;
+		}
+	}
+	return result;
+}
+
+function normalizeCheckStatus(value: any): AIQaCheckStatus {
+	const normalized = cleanText(value, 40).toLowerCase().replace(/[_\s-]+/g, '_');
+	if (normalized === 'passed' || normalized === 'ok' || normalized === 'ready') {
+		return 'pass';
+	}
+	if (normalized === 'failed' || normalized === 'error' || normalized === 'fail') {
+		return 'fail';
+	}
+	if (normalized === 'blocked' || normalized === 'dependency_blocked') {
+		return 'blocked';
+	}
+	if (normalized === 'warning') {
+		return 'warn';
+	}
+	if (normalized === 'skipped' || normalized === 'not_applicable') {
+		return 'skipped';
+	}
+	return normalized === 'pass' || normalized === 'warn' ? normalized : 'unknown';
+}
+
+function normalizeCompileStatus(value: any): AIQaCompileStatus {
+	const normalized = cleanText(value, 40).toLowerCase().replace(/[_\s-]+/g, '_');
+	if (normalized === 'passed' || normalized === 'ok') {
+		return 'pass';
+	}
+	if (normalized === 'failed' || normalized === 'error') {
+		return 'fail';
+	}
+	if (normalized === 'blocked') {
+		return 'blocked';
+	}
+	if (normalized === 'stale' || normalized === 'stale_evidence') {
+		return 'stale';
+	}
+	if (normalized === 'skipped' || normalized === 'not_applicable') {
+		return 'skipped';
+	}
+	return normalized === 'pass' || normalized === 'fail' ? normalized : 'unknown';
+}
+
+function makeGate(
+	key: string,
+	label: string,
+	status: AIRunGateStatus,
+	reason: string,
+	evidenceRefs: string[] = [],
+	now?: Date | string,
+	metadata?: Record<string, any>
+): AIRunGateResult {
+	return {
+		key,
+		label,
+		status,
+		reason: cleanText(reason, 1400),
+		evidenceRefs: cleanList(evidenceRefs, 20, 500),
+		recordedAt: isoNow(now),
+		...(metadata ? { metadata } : {})
+	};
+}
+
+function failedOrBlocked(status: AIQaCheckStatus | AIQaCompileStatus): boolean {
+	return status === 'fail' || status === 'blocked';
+}
+
+function passed(status: AIQaCheckStatus | AIQaCompileStatus): boolean {
+	return status === 'pass';
+}
+
+function normalizeInfraChecks(values: AIQaInfraCheck[] | undefined): AIQaInfraCheck[] {
+	return (Array.isArray(values) ? values : []).map((entry) => ({
+		...entry,
+		name: cleanText(entry?.name, 120) || 'infra_check',
+		status: normalizeCheckStatus(entry?.status),
+		message: cleanText(entry?.message, 1000),
+		path: cleanText(entry?.path, 500)
+	}));
+}
+
+function normalizeRouteProbes(values: AIQaRouteProbe[] | undefined): AIQaRouteProbe[] {
+	return (Array.isArray(values) ? values : []).map((entry) => ({
+		...entry,
+		route: cleanText(entry?.route, 500) || '/',
+		status: normalizeCheckStatus(entry?.status),
+		screenshot: cleanText(entry?.screenshot, 500),
+		caption: cleanText(entry?.caption, 1000),
+		message: cleanText(entry?.message, 1000),
+		consoleErrors: cleanList(entry?.consoleErrors, 30, 500),
+		networkErrors: cleanList(entry?.networkErrors, 30, 500)
+	}));
+}
+
+function normalizeBusinessAssertions(values: AIQaBusinessAssertion[] | undefined): AIQaBusinessAssertion[] {
+	return (Array.isArray(values) ? values : []).map((entry) => ({
+		...entry,
+		assertion: cleanText(entry?.assertion, 1000) || 'business assertion',
+		status: normalizeCheckStatus(entry?.status),
+		workflow: cleanText(entry?.workflow, 400),
+		route: cleanText(entry?.route, 500),
+		action: cleanText(entry?.action, 500),
+		expected: cleanText(entry?.expected, 1000),
+		observed: cleanText(entry?.observed, 1000),
+		dataProof: cleanText(entry?.dataProof, 1400),
+		artifactPaths: cleanList(entry?.artifactPaths, 30, 500),
+		message: cleanText(entry?.message, 1000)
+	}));
+}
+
+function collectBusinessAssertionArtifactPaths(assertions: AIQaBusinessAssertion[]): string[] {
+	const paths: string[] = [];
+	for (const assertion of assertions) {
+		for (const artifactPath of assertion.artifactPaths || []) {
+			if (artifactPath && !paths.includes(artifactPath)) {
+				paths.push(artifactPath);
+			}
+		}
+	}
+	return paths;
+}
+
+export function buildAIQaRun(input: AIQaEvaluationInput = {}): AIQaRun {
+	const now = isoNow(input.now);
+	const infraChecks = normalizeInfraChecks(input.infraChecks);
+	const compile = input.compile
+		? {
+			...input.compile,
+			status: normalizeCompileStatus(input.compile.status),
+			command: cleanText(input.compile.command, 500),
+			artifactPath: cleanText(input.compile.artifactPath, 500),
+			message: cleanText(input.compile.message, 1000)
+		}
+		: undefined;
+	const routeProbes = normalizeRouteProbes(input.routeProbes);
+	const businessAssertions = normalizeBusinessAssertions(input.businessAssertions);
+	const artifacts = Array.isArray(input.artifacts) ? input.artifacts : [];
+	const gateResults: AIRunGateResult[] = [];
+
+	const failedInfra = infraChecks.filter((check) => failedOrBlocked(check.status));
+	if (failedInfra.length) {
+		gateResults.push(makeGate(
+			'qa_infra',
+			'QA infrastructure',
+			'blocked',
+			`QA infrastructure failed before model/business validation: ${failedInfra.map((check) => `${check.name}: ${check.message || check.status}`).join('; ')}`,
+			failedInfra.map((check) => check.path || '').filter(Boolean),
+			now,
+			{ failed_checks: failedInfra.map((check) => check.name) }
+		));
+		return { outcome: 'infra_failed', infraChecks, compile, routeProbes, businessAssertions, artifacts, gateResults, updatedAt: now };
+	}
+	if (infraChecks.length) {
+		gateResults.push(makeGate('qa_infra', 'QA infrastructure', 'pass', 'QA infrastructure preflight checks passed.', [], now));
+	}
+
+	if (compile && (failedOrBlocked(compile.status) || compile.status === 'stale' || compile.staleEvidence === true)) {
+		gateResults.push(makeGate(
+			'qa_compile',
+			'Compile/build',
+			'fail',
+			compile.status === 'stale' || compile.staleEvidence === true
+				? 'Compile/build evidence is stale and cannot be used for acceptance.'
+				: (compile.message || 'Compile/build failed before browser QA.'),
+			compile.artifactPath ? [compile.artifactPath] : [],
+			now,
+			{ command: compile.command || '' }
+		));
+		return { outcome: 'compile_failed', infraChecks, compile, routeProbes, businessAssertions, artifacts, gateResults, updatedAt: now };
+	}
+	if (compile && passed(compile.status)) {
+		gateResults.push(makeGate('qa_compile', 'Compile/build', 'pass', 'Compile/build evidence passed.', compile.artifactPath ? [compile.artifactPath] : [], now));
+	}
+
+	const failedRouteProbes = routeProbes.filter((probe) => failedOrBlocked(probe.status) || probe.shellOnly === true);
+	if (failedRouteProbes.length) {
+		gateResults.push(makeGate(
+			'qa_route_probe',
+			'Browser route probe',
+			'fail',
+			`Browser route probe failed or showed shell-only UI: ${failedRouteProbes.map((probe) => `${probe.route}: ${probe.message || probe.caption || probe.status}`).join('; ')}`,
+			failedRouteProbes.map((probe) => probe.screenshot || '').filter(Boolean),
+			now
+		));
+		return { outcome: 'route_failed', infraChecks, compile, routeProbes, businessAssertions, artifacts, gateResults, updatedAt: now };
+	}
+	if (routeProbes.some((probe) => passed(probe.status))) {
+		gateResults.push(makeGate(
+			'qa_route_probe',
+			'Browser route probe',
+			'pass',
+			'Browser route reached authenticated application content. This is not business acceptance by itself.',
+			routeProbes.map((probe) => probe.screenshot || '').filter(Boolean),
+			now
+		));
+	}
+
+	const failedBusinessAssertions = businessAssertions.filter((assertion) => failedOrBlocked(assertion.status));
+	if (failedBusinessAssertions.length) {
+		gateResults.push(makeGate(
+			'qa_business_assertion',
+			'Business assertion',
+			'fail',
+			`Issue-specific workflow assertion failed: ${failedBusinessAssertions.map((assertion) => assertion.message || assertion.observed || assertion.assertion).join('; ')}`,
+			collectBusinessAssertionArtifactPaths(failedBusinessAssertions),
+			now
+		));
+		return { outcome: 'business_assertion_failed', infraChecks, compile, routeProbes, businessAssertions, artifacts, gateResults, updatedAt: now };
+	}
+
+	const passedBusinessAssertions = businessAssertions.filter((assertion) => passed(assertion.status));
+	if (passedBusinessAssertions.length) {
+		gateResults.push(makeGate(
+			'qa_business_assertion',
+			'Business assertion',
+			'pass',
+			'At least one issue-specific workflow/data assertion passed.',
+			collectBusinessAssertionArtifactPaths(passedBusinessAssertions),
+			now,
+			{ passed_assertions: passedBusinessAssertions.map((assertion) => assertion.assertion) }
+		));
+		return { outcome: 'business_assertion_passed', infraChecks, compile, routeProbes, businessAssertions, artifacts, gateResults, updatedAt: now };
+	}
+
+	if (routeProbes.some((probe) => passed(probe.status))) {
+		gateResults.push(makeGate(
+			'qa_business_assertion',
+			'Business assertion',
+			'blocked',
+			'Browser route loaded, but no issue-specific business assertion passed. Route-only proof cannot accept the run.',
+			[],
+			now
+		));
+		return { outcome: 'route_only_pass', infraChecks, compile, routeProbes, businessAssertions, artifacts, gateResults, updatedAt: now };
+	}
+
+	gateResults.push(makeGate(
+		'qa_business_assertion',
+		'Business assertion',
+		'blocked',
+		'No issue-specific QA assertion was recorded.',
+		[],
+		now
+	));
+	return { outcome: 'incomplete', infraChecks, compile, routeProbes, businessAssertions, artifacts, gateResults, updatedAt: now };
+}
+
+function normalizeQaRun(input?: AIQaRun | AIQaEvaluationInput): AIQaRun | undefined {
+	if (!input) {
+		return undefined;
+	}
+	if ((input as AIQaRun).outcome && Array.isArray((input as AIQaRun).gateResults)) {
+		return input as AIQaRun;
+	}
+	return buildAIQaRun(input as AIQaEvaluationInput);
+}
+
+function statusLooksFailed(value: any): boolean {
+	const normalized = cleanText(value, 120).toLowerCase();
+	return !!normalized && /(fail|failed|error|blocked|missing|empty|stale|skipped|not ready|not_ready|could not|cannot)/i.test(normalized);
+}
+
+function statusLooksPassed(value: any): boolean {
+	const normalized = cleanText(value, 120).toLowerCase();
+	return !!normalized && /(pass|passed|success|complete|completed|ready|published|deployed|live|merged)/i.test(normalized);
+}
+
+function addGateOnce(gates: AIRunGateResult[], gate: AIRunGateResult): void {
+	if (gates.some((entry) => entry.key === gate.key && entry.status === gate.status && entry.reason === gate.reason)) {
+		return;
+	}
+	gates.push(gate);
+}
+
+export function classifyAIRunOutcome(input: AIRunOutcomeInput = {}): AIRunOutcomeDecision {
+	const now = isoNow(input.now);
+	const gates = Array.isArray(input.gates) ? [...input.gates] : [];
+	const warnings: string[] = [];
+	const qa = normalizeQaRun(input.qa);
+	if (qa) {
+		for (const gate of qa.gateResults) {
+			addGateOnce(gates, gate);
+		}
+	}
+
+	if (input.manualHandoff === true) {
+		return {
+			outcome: 'manual_handoff',
+			reason: 'Run requires manual handoff.',
+			nextAction: 'Ask a human operator to resolve the blocked run.',
+			gates,
+			warnings,
+			recordedAt: now
+		};
+	}
+	if (input.stopped === true || /stop|stopped|cancel|cancelled|paused/i.test(`${input.status || ''} ${input.phase || ''}`)) {
+		return {
+			outcome: 'stopped',
+			reason: 'Run was stopped before accepted evidence was recorded.',
+			nextAction: 'Resume or restart only if the request is still active.',
+			gates,
+			warnings,
+			recordedAt: now
+		};
+	}
+	if (input.rejected === true) {
+		return {
+			outcome: 'rejected',
+			reason: 'Run was explicitly rejected.',
+			nextAction: 'Start a repair run from the failing evidence.',
+			gates,
+			warnings,
+			recordedAt: now
+		};
+	}
+
+	if (qa?.outcome === 'infra_failed') {
+		return {
+			outcome: 'qa_infra_failed',
+			reason: 'QA infrastructure failed before product validation.',
+			nextAction: 'Repair QA harness dependencies, ports, browser, Mongo, or startup before another model repair loop.',
+			gates,
+			warnings,
+			recordedAt: now
+		};
+	}
+	if (qa?.outcome === 'compile_failed') {
+		return {
+			outcome: 'build_failed',
+			reason: 'Compile/build evidence failed or was stale.',
+			nextAction: 'Repair compile/build first, then rerun QA from the same failed step.',
+			gates,
+			warnings,
+			recordedAt: now
+		};
+	}
+	if (qa?.outcome === 'route_failed') {
+		return {
+			outcome: 'qa_incomplete',
+			reason: 'Browser route probe failed before business proof.',
+			nextAction: 'Repair route/auth/startup issue and rerun the same browser route probe.',
+			gates,
+			warnings,
+			recordedAt: now
+		};
+	}
+	if (qa?.outcome === 'route_only_pass' || qa?.outcome === 'incomplete') {
+		return {
+			outcome: input.scorecardPassed === true ? 'false_pass' : 'qa_incomplete',
+			reason: input.scorecardPassed === true
+				? 'Scorecard or workflow status passed without issue-specific business assertion proof.'
+				: 'QA has not recorded issue-specific business assertion proof.',
+			nextAction: 'Add before/action/after workflow proof with screenshot/data assertions before acceptance.',
+			gates,
+			warnings,
+			recordedAt: now
+		};
+	}
+	if (qa?.outcome === 'business_assertion_failed') {
+		return {
+			outcome: input.terminal === true ? 'rejected' : 'qa_incomplete',
+			reason: 'Issue-specific business assertion failed.',
+			nextAction: 'Repair the product/data defect and rerun the failing assertion.',
+			gates,
+			warnings,
+			recordedAt: now
+		};
+	}
+
+	const hasBusinessPass = qa?.outcome === 'business_assertion_passed';
+	const scorecardPassed = input.scorecardPassed === true || statusLooksPassed(input.scorecardStatus);
+	const releaseBlockers: string[] = [];
+	if (statusLooksFailed(input.deployStatus)) {
+		releaseBlockers.push(`deploy=${cleanText(input.deployStatus, 120)}`);
+	}
+	if (statusLooksFailed(input.publishStatus)) {
+		releaseBlockers.push(`publish=${cleanText(input.publishStatus, 120)}`);
+	}
+	if (statusLooksFailed(input.sampleDataStatus)) {
+		releaseBlockers.push(`sample_data=${cleanText(input.sampleDataStatus, 120)}`);
+	}
+	if (releaseBlockers.length && (scorecardPassed || hasBusinessPass)) {
+		addGateOnce(gates, makeGate(
+			'release',
+			'Release/deploy',
+			'fail',
+			`Final acceptance is blocked after QA/scorecard because release gates failed: ${releaseBlockers.join(', ')}.`,
+			[],
+			now
+		));
+		return {
+			outcome: 'release_blocked',
+			reason: `Release gates failed after QA/scorecard: ${releaseBlockers.join(', ')}.`,
+			nextAction: 'Repair deploy/publish/sample-data coverage before marking the run accepted.',
+			gates,
+			warnings,
+			recordedAt: now
+		};
+	}
+
+	if (scorecardPassed && !hasBusinessPass) {
+		warnings.push('scorecard_pass_without_business_assertion');
+		addGateOnce(gates, makeGate(
+			'business_assertion_required',
+			'Business assertion',
+			'blocked',
+			'Scorecard passed, but no issue-specific business assertion proof was recorded.',
+			[],
+			now
+		));
+		return {
+			outcome: 'false_pass',
+			reason: 'Scorecard-only proof is not acceptance.',
+			nextAction: 'Record issue-specific workflow/data proof, then reclassify the run.',
+			gates,
+			warnings,
+			recordedAt: now
+		};
+	}
+
+	const statusPhase = `${input.status || ''} ${input.phase || ''}`;
+	if ((input.explicitAccepted === true || statusLooksPassed(statusPhase) || scorecardPassed) && hasBusinessPass) {
+		return {
+			outcome: 'accepted',
+			reason: 'Run has terminal success signal and issue-specific business assertion proof.',
+			nextAction: 'No repair action required.',
+			gates,
+			warnings,
+			recordedAt: now
+		};
+	}
+
+	if (statusLooksFailed(statusPhase)) {
+		return {
+			outcome: 'rejected',
+			reason: 'Run ended with a failure status and no accepted proof.',
+			nextAction: 'Classify the failing gate and rerun the smallest repair step.',
+			gates,
+			warnings,
+			recordedAt: now
+		};
+	}
+
+	return {
+		outcome: 'unknown',
+		reason: 'Run does not have enough normalized evidence for a terminal label.',
+		nextAction: 'Ingest QA, deploy, assistant, usage, and commit evidence before using this run for training.',
+		gates,
+		warnings,
+		recordedAt: now
+	};
+}
+
+export function buildAIRun(input: Omit<AIRun, 'outcome' | 'gates'> & {
+	outcome?: AIRunOutcomeLabel;
+	gates?: AIRunGateResult[];
+	scorecardPassed?: boolean;
+	deployStatus?: string;
+	publishStatus?: string;
+	sampleDataStatus?: string;
+	manualHandoff?: boolean;
+	stopped?: boolean;
+	rejected?: boolean;
+	explicitAccepted?: boolean;
+	terminal?: boolean;
+	now?: Date | string;
+}): AIRun {
+	const decision = input.outcome
+		? {
+			outcome: input.outcome,
+			gates: input.gates || [],
+			warnings: input.warnings || [],
+			nextAction: input.nextAction || '',
+			reason: '',
+			recordedAt: isoNow(input.now)
+		}
+		: classifyAIRunOutcome({
+			source: input.source,
+			status: input.status,
+			phase: input.phase,
+			qa: input.qa,
+			gates: input.gates,
+			scorecardPassed: input.scorecardPassed,
+			deployStatus: input.deployStatus,
+			publishStatus: input.publishStatus,
+			sampleDataStatus: input.sampleDataStatus,
+			manualHandoff: input.manualHandoff,
+			stopped: input.stopped,
+			rejected: input.rejected,
+			explicitAccepted: input.explicitAccepted,
+			terminal: input.terminal,
+			now: input.now
+		});
+	return {
+		id: input.id,
+		source: input.source || 'unknown',
+		sourceIds: input.sourceIds || {},
+		title: input.title,
+		status: input.status,
+		phase: input.phase,
+		startedAt: input.startedAt,
+		completedAt: input.completedAt,
+		outcome: decision.outcome,
+		events: Array.isArray(input.events) ? input.events : [],
+		gates: decision.gates,
+		qa: normalizeQaRun(input.qa),
+		cost: input.cost,
+		nextAction: decision.nextAction,
+		warnings: decision.warnings,
+		metadata: input.metadata
+	};
+}
+
+export function buildAIRunCost(entries: OpenAIUsageCostEntry[] = []): AIRunCost {
+	const cost: AIRunCost = {
+		inputTokens: 0,
+		cachedInputTokens: 0,
+		outputTokens: 0,
+		totalTokens: 0,
+		estimatedUsd: 0,
+		models: [],
+		categories: {}
+	};
+	for (const entry of normalizeOpenAIUsageRowsForCosting(entries)) {
+		const category = cleanText(entry.category, 120) || 'unknown';
+		const model = cleanText(entry.model, 120);
+		const inputTokens = Number(entry.input_tokens ?? entry.inputTokens ?? 0) || 0;
+		const cachedInputTokens = Number(entry.cached_input_tokens ?? entry.cachedInputTokens ?? 0) || 0;
+		const outputTokens = Number(entry.output_tokens ?? entry.outputTokens ?? 0) || 0;
+		const totalTokens = Number(entry.total_tokens ?? entry.totalTokens ?? (inputTokens + outputTokens)) || 0;
+		const estimatedUsd = Number(entry.cost_estimate ?? entry.estimatedUsd ?? 0) || 0;
+		cost.inputTokens += inputTokens;
+		cost.cachedInputTokens += cachedInputTokens;
+		cost.outputTokens += outputTokens;
+		cost.totalTokens += totalTokens;
+		cost.estimatedUsd += estimatedUsd;
+		if (model && !cost.models.includes(model)) {
+			cost.models.push(model);
+		}
+		if (!cost.categories[category]) {
+			cost.categories[category] = {
+				inputTokens: 0,
+				cachedInputTokens: 0,
+				outputTokens: 0,
+				totalTokens: 0,
+				estimatedUsd: 0,
+				count: 0
+			};
+		}
+		cost.categories[category].inputTokens += inputTokens;
+		cost.categories[category].cachedInputTokens += cachedInputTokens;
+		cost.categories[category].outputTokens += outputTokens;
+		cost.categories[category].totalTokens += totalTokens;
+		cost.categories[category].estimatedUsd += estimatedUsd;
+		cost.categories[category].count += 1;
+	}
+	cost.estimatedUsd = Number(cost.estimatedUsd.toFixed(6));
+	for (const category of Object.keys(cost.categories)) {
+		cost.categories[category].estimatedUsd = Number(cost.categories[category].estimatedUsd.toFixed(6));
+	}
+	return cost;
+}
+
+export function redactAIRunTrainingExample(example: AIRunTrainingExample): AIRunTrainingExample {
+	const redact = (value: string): string => cleanText(value, 5000)
+		.replace(/mongodb(?:\+srv)?:\/\/[^\s"'<>]+/ig, '[redacted-mongo-url]')
+		.replace(/\b(?:sk|ghp|xoxb|AKIA)[A-Za-z0-9_\-]{12,}\b/g, '[redacted-secret]')
+		.replace(/\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z]{2,}\b/ig, '[redacted-email]');
+	return {
+		...example,
+		inputSummary: redact(example.inputSummary),
+		actionSummary: redact(example.actionSummary),
+		evidence: cleanList(example.evidence, 80, 5000).map(redact)
+	};
+}