@resolveio/server-lib 22.3.142 → 22.3.143

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

@@ -1,964 +0,0 @@
-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)
-	};
-}