agent-scenario-loop 0.1.0

package/dist/core/artifact-layout.d.ts

@@ -0,0 +1,56 @@
+declare const ARTIFACT_LAYOUT_VERSION = "1.0.0";
+declare const ARTIFACT_FILENAMES: {
+    agentSummary: string;
+    comparison: string;
+    health: string;
+    liveProof: string;
+    liveProofSet: string;
+    plannerCompatibility: string;
+    projectValidation: string;
+    verdict: string;
+};
+declare const PROFILE_ARTIFACT_FILENAMES: {
+    budgetVerdict: string;
+    causalRun: string;
+    manifest: string;
+    metrics: string;
+    summary: string;
+};
+type ProfileArtifactPaths = {
+    budgetVerdict: string;
+    causalRun: string;
+    manifest: string;
+    metrics: string;
+    summary: string;
+};
+type ArtifactLayout = {
+    version: string;
+    root: string;
+    health: string;
+    verdict: string;
+    comparison: string;
+    agentSummary: string;
+    liveProof: string;
+    liveProofSet: string;
+    plannerCompatibility: string;
+    projectValidation: string;
+    raw: string;
+    captures: string;
+    signals: {
+        js: string;
+        memory: string;
+        network: string;
+    };
+    profile: ProfileArtifactPaths;
+};
+/**
+ * Builds the stable artifact path contract for one run directory.
+ *
+ * @param {{outputDir: string}} options
+ * @returns {ArtifactLayout}
+ */
+declare function createArtifactLayout({ outputDir }: {
+    outputDir: string;
+}): ArtifactLayout;
+export { ARTIFACT_FILENAMES, ARTIFACT_LAYOUT_VERSION, PROFILE_ARTIFACT_FILENAMES, createArtifactLayout, };
+export type { ArtifactLayout, ProfileArtifactPaths, };

package/dist/core/artifact-layout.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROFILE_ARTIFACT_FILENAMES = exports.ARTIFACT_LAYOUT_VERSION = exports.ARTIFACT_FILENAMES = void 0;
+exports.createArtifactLayout = createArtifactLayout;
+const path = require('node:path');
+const ARTIFACT_LAYOUT_VERSION = '1.0.0';
+exports.ARTIFACT_LAYOUT_VERSION = ARTIFACT_LAYOUT_VERSION;
+const ARTIFACT_FILENAMES = {
+    agentSummary: 'agent-summary.md',
+    comparison: 'comparison.json',
+    health: 'health.json',
+    liveProof: 'live-proof.json',
+    liveProofSet: 'live-proof-set.json',
+    plannerCompatibility: 'planner-compatibility.json',
+    projectValidation: 'project-validation.json',
+    verdict: 'verdict.json',
+};
+exports.ARTIFACT_FILENAMES = ARTIFACT_FILENAMES;
+const PROFILE_ARTIFACT_FILENAMES = {
+    budgetVerdict: 'budget-verdict.json',
+    causalRun: 'causal-run.json',
+    manifest: 'manifest.json',
+    metrics: 'metrics.json',
+    summary: 'summary.md',
+};
+exports.PROFILE_ARTIFACT_FILENAMES = PROFILE_ARTIFACT_FILENAMES;
+/**
+ * Builds the stable artifact path contract for one run directory.
+ *
+ * @param {{outputDir: string}} options
+ * @returns {ArtifactLayout}
+ */
+function createArtifactLayout({ outputDir }) {
+    const profileArtifacts = {
+        budgetVerdict: path.join(outputDir, PROFILE_ARTIFACT_FILENAMES.budgetVerdict),
+        causalRun: path.join(outputDir, PROFILE_ARTIFACT_FILENAMES.causalRun),
+        manifest: path.join(outputDir, PROFILE_ARTIFACT_FILENAMES.manifest),
+        metrics: path.join(outputDir, PROFILE_ARTIFACT_FILENAMES.metrics),
+        summary: path.join(outputDir, PROFILE_ARTIFACT_FILENAMES.summary),
+    };
+    return {
+        version: ARTIFACT_LAYOUT_VERSION,
+        root: outputDir,
+        health: path.join(outputDir, ARTIFACT_FILENAMES.health),
+        verdict: path.join(outputDir, ARTIFACT_FILENAMES.verdict),
+        comparison: path.join(outputDir, ARTIFACT_FILENAMES.comparison),
+        agentSummary: path.join(outputDir, ARTIFACT_FILENAMES.agentSummary),
+        liveProof: path.join(outputDir, ARTIFACT_FILENAMES.liveProof),
+        liveProofSet: path.join(outputDir, ARTIFACT_FILENAMES.liveProofSet),
+        plannerCompatibility: path.join(outputDir, ARTIFACT_FILENAMES.plannerCompatibility),
+        projectValidation: path.join(outputDir, ARTIFACT_FILENAMES.projectValidation),
+        raw: path.join(outputDir, 'raw'),
+        captures: path.join(outputDir, 'captures'),
+        signals: {
+            js: path.join(outputDir, 'signals', 'js'),
+            memory: path.join(outputDir, 'signals', 'memory'),
+            network: path.join(outputDir, 'signals', 'network'),
+        },
+        profile: profileArtifacts,
+    };
+}

package/dist/core/artifact-writer.d.ts

@@ -0,0 +1,44 @@
+type JsonSchema = Record<string, unknown>;
+/**
+ * Writes schema-validated JSON with stable formatting.
+ *
+ * @param {{filePath: string, value: unknown, schema: Record<string, unknown>, label: string}} options
+ * @returns {Promise<string>}
+ */
+declare function writeJsonArtifact({ filePath, value, schema, label, }: {
+    filePath: string;
+    value: unknown;
+    schema: JsonSchema;
+    label: string;
+}): Promise<string>;
+/**
+ * Writes text artifacts with parent-directory creation.
+ *
+ * @param {{filePath: string, content: string}} options
+ * @returns {Promise<string>}
+ */
+declare function writeTextArtifact({ filePath, content, }: {
+    filePath: string;
+    content: string;
+}): Promise<string>;
+/**
+ * Copies a raw evidence artifact with parent-directory creation.
+ *
+ * @param {{sourcePath: string, filePath: string}} options
+ * @returns {Promise<string>}
+ */
+declare function copyRawArtifact({ sourcePath, filePath, }: {
+    sourcePath: string;
+    filePath: string;
+}): Promise<string>;
+/**
+ * Creates an artifact writer object that satisfies the artifact-writer port.
+ *
+ * @returns {{writeJson: typeof writeJsonArtifact, writeText: typeof writeTextArtifact, copyRaw: typeof copyRawArtifact}}
+ */
+declare function createArtifactWriter(): {
+    writeJson: typeof writeJsonArtifact;
+    writeText: typeof writeTextArtifact;
+    copyRaw: typeof copyRawArtifact;
+};
+export { copyRawArtifact, createArtifactWriter, writeJsonArtifact, writeTextArtifact, };

package/dist/core/artifact-writer.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.copyRawArtifact = copyRawArtifact;
+exports.createArtifactWriter = createArtifactWriter;
+exports.writeJsonArtifact = writeJsonArtifact;
+exports.writeTextArtifact = writeTextArtifact;
+const fsp = require('node:fs/promises');
+const path = require('node:path');
+const { assertValidJson } = require('./schema-validator');
+/**
+ * Writes schema-validated JSON with stable formatting.
+ *
+ * @param {{filePath: string, value: unknown, schema: Record<string, unknown>, label: string}} options
+ * @returns {Promise<string>}
+ */
+async function writeJsonArtifact({ filePath, value, schema, label, }) {
+    assertValidJson(value, schema, label);
+    await fsp.mkdir(path.dirname(filePath), { recursive: true });
+    await fsp.writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+    return filePath;
+}
+/**
+ * Writes text artifacts with parent-directory creation.
+ *
+ * @param {{filePath: string, content: string}} options
+ * @returns {Promise<string>}
+ */
+async function writeTextArtifact({ filePath, content, }) {
+    await fsp.mkdir(path.dirname(filePath), { recursive: true });
+    await fsp.writeFile(filePath, content, 'utf8');
+    return filePath;
+}
+/**
+ * Copies a raw evidence artifact with parent-directory creation.
+ *
+ * @param {{sourcePath: string, filePath: string}} options
+ * @returns {Promise<string>}
+ */
+async function copyRawArtifact({ sourcePath, filePath, }) {
+    await fsp.mkdir(path.dirname(filePath), { recursive: true });
+    await fsp.copyFile(sourcePath, filePath);
+    return filePath;
+}
+/**
+ * Creates an artifact writer object that satisfies the artifact-writer port.
+ *
+ * @returns {{writeJson: typeof writeJsonArtifact, writeText: typeof writeTextArtifact, copyRaw: typeof copyRawArtifact}}
+ */
+function createArtifactWriter() {
+    return {
+        writeJson: writeJsonArtifact,
+        writeText: writeTextArtifact,
+        copyRaw: copyRawArtifact,
+    };
+}

package/dist/core/comparison.d.ts

@@ -0,0 +1,133 @@
+type ComparisonRecord = Record<string, any>;
+type ComparisonBudgetCheck = {
+    actual: number | boolean | null;
+    name: string;
+    pass: boolean;
+    unit: 'ms' | 'count' | 'bytes' | 'percent' | 'boolean';
+};
+type MetricComparison = {
+    name: string;
+    unit: ComparisonBudgetCheck['unit'];
+    baseline: number | boolean | null;
+    current: number | boolean | null;
+    delta: number | null;
+    status: 'better' | 'worse' | 'unchanged' | 'inconclusive';
+    notes?: string;
+};
+type ComparisonStatus = MetricComparison['status'] | 'mixed';
+type ComparisonBasisStrategy = 'explicit' | 'latest_trusted_prior';
+type ComparisonRunBasis = {
+    healthStatus?: string;
+    runDir?: string;
+    runId: string;
+    verdictStatus?: string;
+};
+type ComparisonSelectionBasis = {
+    artifactRoot?: string;
+    candidatesInspected?: number;
+    scenarioId?: string;
+    selectedRunDir?: string;
+    selectedRunId?: string;
+    skippedCurrentRun?: boolean;
+    trustedCandidates?: number;
+    trustedPriorCandidates?: number;
+};
+type ComparisonBasis = {
+    baseline: ComparisonRunBasis;
+    current: ComparisonRunBasis;
+    selection?: ComparisonSelectionBasis;
+    strategy: ComparisonBasisStrategy;
+};
+type BuildComparisonOptions = {
+    baselineHealth: ComparisonRecord;
+    baselineVerdict: ComparisonRecord;
+    comparisonBasis?: ComparisonBasis;
+    currentHealth: ComparisonRecord;
+    currentVerdict: ComparisonRecord;
+};
+type CompareRunDirectoriesOptions = {
+    baselineDir: string;
+    currentDir: string;
+    selection?: ComparisonSelectionBasis;
+    strategy?: ComparisonBasisStrategy;
+};
+/**
+ * Reads and validates the health and verdict artifacts from a run directory.
+ *
+ * @param {string} runDir
+ * @returns {{health: Record<string, unknown>, verdict: Record<string, unknown>}}
+ */
+declare function readRunArtifacts(runDir: string): {
+    health: ComparisonRecord;
+    verdict: ComparisonRecord;
+};
+/**
+ * Returns budget checks indexed by stable comparison key.
+ *
+ * @param {unknown} checks
+ * @returns {Map<string, BudgetCheck>}
+ */
+declare function indexBudgetChecks(checks: unknown): Map<string, ComparisonBudgetCheck>;
+/**
+ * Compares one budget check when both runs expose a compatible actual value.
+ *
+ * @param {BudgetCheck} baseline
+ * @param {BudgetCheck} current
+ * @returns {MetricComparison}
+ */
+declare function compareBudgetCheck(baseline: ComparisonBudgetCheck, current: ComparisonBudgetCheck): MetricComparison;
+/**
+ * Collapses metric-level comparison statuses into the run-level comparison status.
+ *
+ * @param {MetricComparison[]} metricComparisons
+ * @param {{baselineVerdictStatus?: unknown, currentVerdictStatus?: unknown}} verdicts
+ * @returns {ComparisonStatus}
+ */
+declare function resolveComparisonStatus(metricComparisons: MetricComparison[], { baselineVerdictStatus, currentVerdictStatus, }: {
+    baselineVerdictStatus?: unknown;
+    currentVerdictStatus?: unknown;
+}): ComparisonStatus;
+/**
+ * Builds the provenance block that explains which runs a comparison used.
+ *
+ * @param {{baselineDir: string, currentDir: string, baselineHealth: ComparisonRecord, baselineVerdict: ComparisonRecord, currentHealth: ComparisonRecord, currentVerdict: ComparisonRecord, selection?: ComparisonSelectionBasis, strategy: ComparisonBasisStrategy}} options
+ * @returns {ComparisonBasis}
+ */
+declare function buildComparisonBasis({ baselineDir, currentDir, baselineHealth, baselineVerdict, currentHealth, currentVerdict, selection, strategy, }: {
+    baselineDir: string;
+    currentDir: string;
+    baselineHealth: ComparisonRecord;
+    baselineVerdict: ComparisonRecord;
+    currentHealth: ComparisonRecord;
+    currentVerdict: ComparisonRecord;
+    selection?: ComparisonSelectionBasis;
+    strategy: ComparisonBasisStrategy;
+}): ComparisonBasis;
+/**
+ * Builds a comparison artifact from two validated run artifact sets.
+ *
+ * @param {BuildComparisonOptions} options
+ * @returns {Record<string, unknown>}
+ */
+declare function buildComparisonArtifact({ baselineHealth, baselineVerdict, comparisonBasis, currentHealth, currentVerdict, }: BuildComparisonOptions): ComparisonRecord;
+/**
+ * Reads two run directories and builds a validated comparison artifact.
+ *
+ * @param {CompareRunDirectoriesOptions} options
+ * @returns {Record<string, unknown>}
+ */
+declare function compareRunDirectories({ baselineDir, currentDir, selection, strategy, }: CompareRunDirectoriesOptions): ComparisonRecord;
+/**
+ * Builds the human-readable comparison summary.
+ *
+ * @param {{comparisonStatus: string, missingRequired: string[], metricComparisons: MetricComparison[], warnings: string[]}} options
+ * @returns {string}
+ */
+declare function summarizeComparison({ comparisonStatus, missingRequired, metricComparisons, warnings, }: {
+    comparisonStatus: string;
+    missingRequired: string[];
+    metricComparisons: MetricComparison[];
+    warnings: string[];
+}): string;
+export { buildComparisonBasis, buildComparisonArtifact, compareBudgetCheck, compareRunDirectories, indexBudgetChecks, readRunArtifacts, resolveComparisonStatus, summarizeComparison, };
+export type { BuildComparisonOptions, ComparisonBasis, ComparisonBasisStrategy, CompareRunDirectoriesOptions, ComparisonBudgetCheck, ComparisonRecord, ComparisonStatus, MetricComparison, };

package/dist/core/comparison.js

@@ -0,0 +1,294 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildComparisonBasis = buildComparisonBasis;
+exports.buildComparisonArtifact = buildComparisonArtifact;
+exports.compareBudgetCheck = compareBudgetCheck;
+exports.compareRunDirectories = compareRunDirectories;
+exports.indexBudgetChecks = indexBudgetChecks;
+exports.readRunArtifacts = readRunArtifacts;
+exports.resolveComparisonStatus = resolveComparisonStatus;
+exports.summarizeComparison = summarizeComparison;
+const fs = require('node:fs');
+const { createArtifactLayout } = require('./artifact-layout');
+const { SCHEMAS, assertValidJson } = require('./schema-validator');
+const MIN_MS_COMPARISON_TOLERANCE = 16;
+const RELATIVE_MS_COMPARISON_TOLERANCE = 0.05;
+/**
+ * Reads and validates the health and verdict artifacts from a run directory.
+ *
+ * @param {string} runDir
+ * @returns {{health: Record<string, unknown>, verdict: Record<string, unknown>}}
+ */
+function readRunArtifacts(runDir) {
+    const layout = createArtifactLayout({ outputDir: runDir });
+    const health = JSON.parse(fs.readFileSync(layout.health, 'utf8'));
+    const verdict = JSON.parse(fs.readFileSync(layout.verdict, 'utf8'));
+    return {
+        health: assertValidJson(health, SCHEMAS.health, 'Health artifact'),
+        verdict: assertValidJson(verdict, SCHEMAS.verdict, 'Verdict artifact'),
+    };
+}
+/**
+ * Returns budget checks indexed by stable comparison key.
+ *
+ * @param {unknown} checks
+ * @returns {Map<string, BudgetCheck>}
+ */
+function indexBudgetChecks(checks) {
+    const indexed = new Map();
+    if (!Array.isArray(checks)) {
+        return indexed;
+    }
+    for (const check of checks) {
+        if (!check || typeof check !== 'object') {
+            continue;
+        }
+        const record = check;
+        if (typeof record.name !== 'string' || typeof record.unit !== 'string') {
+            continue;
+        }
+        indexed.set(`${record.name}\u0000${record.unit}`, record);
+    }
+    return indexed;
+}
+/**
+ * Returns the absolute delta that should still be treated as timing noise.
+ *
+ * @param {ComparisonBudgetCheck} baseline
+ * @param {ComparisonBudgetCheck} current
+ * @returns {number}
+ */
+function comparisonTolerance(baseline, current) {
+    if (baseline.unit !== 'ms' || current.unit !== 'ms') {
+        return 0;
+    }
+    if (typeof baseline.actual !== 'number' || typeof current.actual !== 'number') {
+        return 0;
+    }
+    const reference = Math.max(Math.abs(baseline.actual), Math.abs(current.actual));
+    return Math.max(MIN_MS_COMPARISON_TOLERANCE, reference * RELATIVE_MS_COMPARISON_TOLERANCE);
+}
+/**
+ * Compares one budget check when both runs expose a compatible actual value.
+ *
+ * @param {BudgetCheck} baseline
+ * @param {BudgetCheck} current
+ * @returns {MetricComparison}
+ */
+function compareBudgetCheck(baseline, current) {
+    if (typeof baseline.actual !== 'number' || typeof current.actual !== 'number') {
+        return {
+            name: current.name,
+            unit: current.unit,
+            baseline: baseline.actual ?? null,
+            current: current.actual ?? null,
+            delta: null,
+            status: baseline.actual === current.actual ? 'unchanged' : 'inconclusive',
+            notes: 'Only numeric budget actuals are compared by direction.',
+        };
+    }
+    const delta = current.actual - baseline.actual;
+    const tolerance = comparisonTolerance(baseline, current);
+    const crossedBudgetBoundary = baseline.pass !== current.pass;
+    const withinTolerance = Math.abs(delta) <= tolerance;
+    let status;
+    if (crossedBudgetBoundary) {
+        status = current.pass ? 'better' : 'worse';
+    }
+    else if (withinTolerance) {
+        status = 'unchanged';
+    }
+    else {
+        status = delta < 0 ? 'better' : 'worse';
+    }
+    return {
+        name: current.name,
+        unit: current.unit,
+        baseline: baseline.actual,
+        current: current.actual,
+        delta,
+        status,
+        ...(status === 'unchanged' && delta !== 0 && tolerance > 0 && withinTolerance
+            ? { notes: `Delta within ${tolerance}ms timing tolerance.` }
+            : {}),
+    };
+}
+/**
+ * Collapses metric-level comparison statuses into the run-level comparison status.
+ *
+ * @param {MetricComparison[]} metricComparisons
+ * @param {{baselineVerdictStatus?: unknown, currentVerdictStatus?: unknown}} verdicts
+ * @returns {ComparisonStatus}
+ */
+function resolveComparisonStatus(metricComparisons, { baselineVerdictStatus, currentVerdictStatus, }) {
+    const hasBetterMetric = metricComparisons.some((metric) => metric.status === 'better');
+    const hasWorseMetric = metricComparisons.some((metric) => metric.status === 'worse');
+    if (hasBetterMetric && hasWorseMetric) {
+        return 'mixed';
+    }
+    if (hasWorseMetric) {
+        return 'worse';
+    }
+    if (hasBetterMetric) {
+        return 'better';
+    }
+    if (metricComparisons.length > 0 && metricComparisons.every((metric) => metric.status === 'unchanged')) {
+        return 'unchanged';
+    }
+    if (baselineVerdictStatus === 'failed' && currentVerdictStatus === 'passed') {
+        return 'better';
+    }
+    if (baselineVerdictStatus === 'passed' && currentVerdictStatus === 'failed') {
+        return 'worse';
+    }
+    return 'inconclusive';
+}
+/**
+ * Builds the provenance block that explains which runs a comparison used.
+ *
+ * @param {{baselineDir: string, currentDir: string, baselineHealth: ComparisonRecord, baselineVerdict: ComparisonRecord, currentHealth: ComparisonRecord, currentVerdict: ComparisonRecord, selection?: ComparisonSelectionBasis, strategy: ComparisonBasisStrategy}} options
+ * @returns {ComparisonBasis}
+ */
+function buildComparisonBasis({ baselineDir, currentDir, baselineHealth, baselineVerdict, currentHealth, currentVerdict, selection, strategy, }) {
+    const baselineRunId = String(baselineHealth.runId ?? baselineVerdict.runId ?? 'unknown-baseline');
+    const currentRunId = String(currentHealth.runId ?? currentVerdict.runId ?? 'unknown-current');
+    return {
+        strategy,
+        baseline: {
+            runId: baselineRunId,
+            runDir: baselineDir,
+            ...(typeof baselineHealth.healthStatus === 'string' ? { healthStatus: baselineHealth.healthStatus } : {}),
+            ...(typeof baselineVerdict.verdictStatus === 'string' ? { verdictStatus: baselineVerdict.verdictStatus } : {}),
+        },
+        current: {
+            runId: currentRunId,
+            runDir: currentDir,
+            ...(typeof currentHealth.healthStatus === 'string' ? { healthStatus: currentHealth.healthStatus } : {}),
+            ...(typeof currentVerdict.verdictStatus === 'string' ? { verdictStatus: currentVerdict.verdictStatus } : {}),
+        },
+        ...(selection ? { selection } : {}),
+    };
+}
+/**
+ * Builds a comparison artifact from two validated run artifact sets.
+ *
+ * @param {BuildComparisonOptions} options
+ * @returns {Record<string, unknown>}
+ */
+function buildComparisonArtifact({ baselineHealth, baselineVerdict, comparisonBasis, currentHealth, currentVerdict, }) {
+    const missingRequired = [];
+    const warnings = [];
+    const baselineScenarioId = String(baselineHealth.scenarioId ?? baselineVerdict.scenarioId ?? 'unknown-scenario');
+    const currentScenarioId = String(currentHealth.scenarioId ?? currentVerdict.scenarioId ?? baselineScenarioId);
+    const baselineRunId = String(baselineHealth.runId ?? baselineVerdict.runId ?? 'unknown-baseline');
+    const currentRunId = String(currentHealth.runId ?? currentVerdict.runId ?? 'unknown-current');
+    if (baselineHealth.healthStatus !== 'passed') {
+        missingRequired.push('baseline health passed');
+    }
+    if (currentHealth.healthStatus !== 'passed') {
+        missingRequired.push('current health passed');
+    }
+    if (baselineScenarioId !== currentScenarioId) {
+        missingRequired.push('matching scenario id');
+    }
+    const canCompare = missingRequired.length === 0;
+    const metricComparisons = [];
+    if (canCompare) {
+        const baselineChecks = indexBudgetChecks(baselineVerdict.budgetChecks);
+        const currentChecks = indexBudgetChecks(currentVerdict.budgetChecks);
+        for (const [key, currentCheck] of currentChecks.entries()) {
+            const baselineCheck = baselineChecks.get(key);
+            if (!baselineCheck) {
+                warnings.push(`No baseline budget check matched ${currentCheck.name}.`);
+                continue;
+            }
+            metricComparisons.push(compareBudgetCheck(baselineCheck, currentCheck));
+        }
+        if (metricComparisons.length === 0) {
+            warnings.push('No comparable budget checks were available.');
+        }
+    }
+    const comparisonStatus = canCompare
+        ? resolveComparisonStatus(metricComparisons, {
+            baselineVerdictStatus: baselineVerdict.verdictStatus,
+            currentVerdictStatus: currentVerdict.verdictStatus,
+        })
+        : 'inconclusive';
+    const comparison = {
+        schemaVersion: '1.0.0',
+        scenarioId: currentScenarioId,
+        ...(typeof currentHealth.flowId === 'string'
+            ? { flowId: currentHealth.flowId }
+            : typeof currentVerdict.flowId === 'string'
+                ? { flowId: currentVerdict.flowId }
+                : {}),
+        runId: currentRunId,
+        baselineRunId,
+        comparisonStatus,
+        healthStatus: canCompare ? 'passed' : 'failed',
+        verdictStatus: typeof currentVerdict.verdictStatus === 'string' ? currentVerdict.verdictStatus : 'inconclusive',
+        ...(comparisonBasis ? { comparisonBasis } : {}),
+        ...(metricComparisons.length > 0 ? { metricComparisons } : {}),
+        evidence: {
+            missingRequired,
+            warnings,
+        },
+        summary: summarizeComparison({ comparisonStatus, missingRequired, metricComparisons, warnings }),
+    };
+    return assertValidJson(comparison, SCHEMAS.comparison, 'Comparison artifact');
+}
+/**
+ * Reads two run directories and builds a validated comparison artifact.
+ *
+ * @param {CompareRunDirectoriesOptions} options
+ * @returns {Record<string, unknown>}
+ */
+function compareRunDirectories({ baselineDir, currentDir, selection, strategy = 'explicit', }) {
+    const baseline = readRunArtifacts(baselineDir);
+    const current = readRunArtifacts(currentDir);
+    return buildComparisonArtifact({
+        baselineHealth: baseline.health,
+        baselineVerdict: baseline.verdict,
+        comparisonBasis: buildComparisonBasis({
+            baselineDir,
+            currentDir,
+            baselineHealth: baseline.health,
+            baselineVerdict: baseline.verdict,
+            currentHealth: current.health,
+            currentVerdict: current.verdict,
+            ...(selection ? { selection } : {}),
+            strategy,
+        }),
+        currentHealth: current.health,
+        currentVerdict: current.verdict,
+    });
+}
+/**
+ * Builds the human-readable comparison summary.
+ *
+ * @param {{comparisonStatus: string, missingRequired: string[], metricComparisons: MetricComparison[], warnings: string[]}} options
+ * @returns {string}
+ */
+function summarizeComparison({ comparisonStatus, missingRequired, metricComparisons, warnings, }) {
+    if (missingRequired.length > 0) {
+        return `Comparison is inconclusive because required evidence is missing: ${missingRequired.join(', ')}.`;
+    }
+    if (metricComparisons.length === 0) {
+        return warnings.length > 0
+            ? `Comparison is inconclusive: ${warnings.join(' ')}`
+            : 'Comparison is inconclusive because there were no comparable metrics.';
+    }
+    if (comparisonStatus === 'better') {
+        return 'Current run improved against the explicit baseline.';
+    }
+    if (comparisonStatus === 'worse') {
+        return 'Current run regressed against the explicit baseline.';
+    }
+    if (comparisonStatus === 'mixed') {
+        return 'Current run has mixed metric movement against the explicit baseline.';
+    }
+    if (comparisonStatus === 'unchanged') {
+        return 'Current run matched the explicit baseline.';
+    }
+    return 'Comparison is inconclusive.';
+}

package/dist/core/evidence-interpreter.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Returns whether timing evidence can be used for interpretation.
+ *
+ * @param {Record<string, unknown>} health
+ * @returns {boolean}
+ */
+declare function isTimingEvidenceTrusted(health: EvidenceRecord): boolean;
+/**
+ * Builds evidence-backed interpretation hints without overriding scenario health.
+ *
+ * Timing-based hints are only emitted after scenario health passed.
+ *
+ * @param {{health: Record<string, unknown>, verdict?: Record<string, unknown> | null, comparison?: Record<string, unknown> | null}} options
+ * @returns {{timingTrusted: boolean, recommendations: string[], blockedReasons: string[]}}
+ */
+declare function interpretEvidence({ health, verdict, comparison, }: {
+    health: EvidenceRecord;
+    verdict?: EvidenceRecord | null;
+    comparison?: EvidenceRecord | null;
+}): EvidenceInterpretation;
+export { interpretEvidence, isTimingEvidenceTrusted, };
+export type { EvidenceInterpretation, EvidenceRecord, };
+type EvidenceRecord = Record<string, unknown>;
+type EvidenceInterpretation = {
+    timingTrusted: boolean;
+    recommendations: string[];
+    blockedReasons: string[];
+};