harnery 0.36.0 → 0.37.0

package/dist/core/diagnostics/comparison.d.ts

@@ -0,0 +1,5 @@
+import { type DiagnosticBundleComparison, type ValidatedDiagnosticBundle } from "./contract.js";
+export declare function compareDiagnosticBundles(repoRoot: string, beforeRef: string, afterRef: string): DiagnosticBundleComparison;
+export declare function compareValidatedDiagnosticBundles(before: ValidatedDiagnosticBundle, after: ValidatedDiagnosticBundle): DiagnosticBundleComparison;
+export declare function renderDiagnosticBundleComparison(comparison: DiagnosticBundleComparison): string;
+//# sourceMappingURL=comparison.d.ts.map

package/dist/core/diagnostics/comparison.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"comparison.d.ts","sourceRoot":"","sources":["../../../src/core/diagnostics/comparison.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,0BAA0B,EAY/B,KAAK,yBAAyB,EAC/B,MAAM,eAAe,CAAC;AAMvB,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,GACf,0BAA0B,CAK5B;AAED,wBAAgB,iCAAiC,CAC/C,MAAM,EAAE,yBAAyB,EACjC,KAAK,EAAE,yBAAyB,GAC/B,0BAA0B,CAiG5B;AAED,wBAAgB,gCAAgC,CAAC,UAAU,EAAE,0BAA0B,GAAG,MAAM,CA0B/F"}

package/dist/core/diagnostics/comparison.js

@@ -0,0 +1,444 @@
+import { validateDiagnosticBundle } from "./bundle.js";
+import { DIAGNOSTIC_COMPARISON_SCHEMA_VERSION, } from "./contract.js";
+import { canonicalJson, sha256 } from "./replay.js";
+const HOOK_SOURCE = "supervisor.hook-health";
+const ADMISSION_SOURCE = "workflow.diagnostic-admission";
+export function compareDiagnosticBundles(repoRoot, beforeRef, afterRef) {
+    return compareValidatedDiagnosticBundles(validateDiagnosticBundle(repoRoot, beforeRef), validateDiagnosticBundle(repoRoot, afterRef));
+}
+export function compareValidatedDiagnosticBundles(before, after) {
+    const warnings = [];
+    if (before.manifest.threshold_digest !== after.manifest.threshold_digest) {
+        warnings.push({
+            code: "threshold_digest_changed",
+            summary: "Finding thresholds changed between captures.",
+        });
+    }
+    if (before.manifest.engine_version !== after.manifest.engine_version) {
+        warnings.push({
+            code: "engine_version_changed",
+            summary: "The captures were produced by different Harnery builds.",
+        });
+    }
+    if (before.manifest.machine_id !== after.manifest.machine_id) {
+        warnings.push({
+            code: "machine_changed",
+            summary: "The captures came from different pseudonymous machines.",
+        });
+    }
+    if (Date.parse(after.manifest.captured_at) < Date.parse(before.manifest.captured_at)) {
+        warnings.push({
+            code: "capture_order_reversed",
+            summary: "The after capture predates the before capture.",
+        });
+    }
+    const beforeIndex = indexFindings(before.expected.findings);
+    const afterIndex = indexFindings(after.expected.findings);
+    if (beforeIndex.duplicateCount + afterIndex.duplicateCount > 0) {
+        warnings.push({
+            code: "duplicate_fingerprint",
+            summary: `${beforeIndex.duplicateCount + afterIndex.duplicateCount} older finding episode(s) shared a fingerprint and were omitted.`,
+        });
+    }
+    const capabilities = compareCapabilities(before, after);
+    if (capabilities.some((row) => row.change !== "unchanged")) {
+        warnings.push({
+            code: "source_capability_changed",
+            summary: "One or more captured source capabilities changed.",
+        });
+    }
+    const hookHealth = optionalSourceComparison(before, after, HOOK_SOURCE, hookHealthSummary);
+    if (!hookHealth.before || !hookHealth.after) {
+        warnings.push({
+            code: "hook_health_unavailable",
+            summary: "Completed-hook comparison is partial because one or both bundles lack hook-health evidence.",
+        });
+    }
+    const shadowAdmission = optionalSourceComparison(before, after, ADMISSION_SOURCE, shadowAdmissionSummary);
+    if (!shadowAdmission.before || !shadowAdmission.after) {
+        warnings.push({
+            code: "shadow_admission_unavailable",
+            summary: "Shadow-admission comparison is partial because one or both bundles lack admission evidence.",
+        });
+    }
+    const rows = compareFindings(beforeIndex.rows, afterIndex.rows);
+    const base = {
+        schema_version: DIAGNOSTIC_COMPARISON_SCHEMA_VERSION,
+        observer_only: true,
+        before: bundleRef(before),
+        after: bundleRef(after),
+        comparability: warnings.length === 0 ? "comparable" : "partial",
+        warnings,
+        advice: {
+            before: before.expected.advice,
+            after: after.expected.advice,
+            direction: adviceDirection(before.expected.advice.pressure, after.expected.advice.pressure),
+        },
+        findings: {
+            total: rows.length,
+            regressions: countImpact(rows, "regression"),
+            worsened: countImpact(rows, "worsened"),
+            changed: countImpact(rows, "changed"),
+            improved: countImpact(rows, "improved"),
+            recoveries: countImpact(rows, "recovery"),
+            unchanged: countImpact(rows, "unchanged"),
+            rows,
+        },
+        capabilities,
+        hook_health: hookHealth,
+        shadow_admission: shadowAdmission,
+    };
+    return {
+        ...base,
+        comparison_digest: sha256(canonicalJson(base)),
+    };
+}
+export function renderDiagnosticBundleComparison(comparison) {
+    const lines = [
+        `diagnostic comparison: ${comparison.before.artifact_id} -> ${comparison.after.artifact_id}`,
+        `comparability: ${comparison.comparability}; pressure: ${comparison.before.pressure} -> ${comparison.after.pressure} (${comparison.advice.direction})`,
+        `findings: ${comparison.findings.regressions} regression, ${comparison.findings.worsened} worsened, ${comparison.findings.changed} changed, ${comparison.findings.improved} improved, ${comparison.findings.recoveries} recovery, ${comparison.findings.unchanged} unchanged`,
+    ];
+    if (comparison.warnings.length > 0) {
+        lines.push("warnings:");
+        for (const warning of comparison.warnings)
+            lines.push(`  - ${warning.code}: ${warning.summary}`);
+    }
+    if (comparison.findings.rows.length > 0) {
+        lines.push("signals:");
+        for (const row of comparison.findings.rows) {
+            const finding = row.after ?? row.before;
+            lines.push(`  ${row.impact.padEnd(10)} ${finding.finding_kind} ${finding.scope_kind}:${finding.scope_id} (${row.fingerprint})`);
+            for (const change of row.field_changes) {
+                lines.push(`    ${change.field}: ${String(change.before)} -> ${String(change.after)}`);
+            }
+        }
+    }
+    lines.push(`comparison digest: ${comparison.comparison_digest}`);
+    lines.push("observer only: no thresholds, processes, hooks, or workflow dispatch changed");
+    return `${lines.join("\n")}\n`;
+}
+function bundleRef(bundle) {
+    return {
+        artifact_id: bundle.manifest.artifact_id,
+        captured_at: bundle.manifest.captured_at,
+        machine_id: bundle.manifest.machine_id,
+        engine_version: bundle.manifest.engine_version,
+        threshold_digest: bundle.manifest.threshold_digest,
+        finding_count: bundle.expected.findings.length,
+        pressure: bundle.expected.advice.pressure,
+    };
+}
+function indexFindings(findings) {
+    const sorted = [...findings].sort((left, right) => Date.parse(right.observed_at) - Date.parse(left.observed_at) ||
+        left.id.localeCompare(right.id));
+    const rows = new Map();
+    let duplicateCount = 0;
+    for (const finding of sorted) {
+        if (rows.has(finding.fingerprint))
+            duplicateCount += 1;
+        else
+            rows.set(finding.fingerprint, finding);
+    }
+    return { rows, duplicateCount };
+}
+function compareFindings(before, after) {
+    const fingerprints = [...new Set([...before.keys(), ...after.keys()])].sort();
+    return fingerprints
+        .map((fingerprint) => {
+        const previous = before.get(fingerprint);
+        const current = after.get(fingerprint);
+        if (!previous && current) {
+            return {
+                fingerprint,
+                change_class: "added",
+                impact: current.state === "opened" ? "regression" : "changed",
+                after: current,
+                field_changes: [],
+            };
+        }
+        if (previous && !current) {
+            return {
+                fingerprint,
+                change_class: "resolved",
+                impact: previous.state === "opened" ? "recovery" : "changed",
+                before: previous,
+                field_changes: [],
+            };
+        }
+        const fieldChanges = compareFindingFields(previous, current);
+        return {
+            fingerprint,
+            change_class: "persistent",
+            impact: persistentImpact(fieldChanges),
+            before: previous,
+            after: current,
+            field_changes: fieldChanges,
+        };
+    })
+        .sort(compareFindingRows);
+}
+function compareFindingFields(before, after) {
+    const rows = [];
+    addRankedChange(rows, "severity", before.severity, after.severity, severityRank);
+    addRankedChange(rows, "state", before.state, after.state, stateRank);
+    addRankedChange(rows, "occurrence_count", before.occurrence_count, after.occurrence_count, numberRank);
+    if (before.peak_unit === after.peak_unit &&
+        before.peak_observed_value !== undefined &&
+        after.peak_observed_value !== undefined) {
+        addRankedChange(rows, "peak_observed_value", before.peak_observed_value, after.peak_observed_value, numberRank);
+    }
+    addChangedField(rows, "owner", owner(before), owner(after));
+    addChangedField(rows, "workload_relationship", before.workload_context?.relationship ?? null, after.workload_context?.relationship ?? null);
+    return rows;
+}
+function addRankedChange(rows, field, before, after, rank) {
+    if (before === after)
+        return;
+    rows.push({
+        field,
+        before,
+        after,
+        impact: rank(after) > rank(before) ? "worsened" : "improved",
+    });
+}
+function addChangedField(rows, field, before, after) {
+    if (before === after)
+        return;
+    rows.push({ field, before, after, impact: "changed" });
+}
+function persistentImpact(changes) {
+    if (changes.length === 0)
+        return "unchanged";
+    const worsened = changes.some((row) => row.impact === "worsened");
+    const improved = changes.some((row) => row.impact === "improved");
+    const changed = changes.some((row) => row.impact === "changed");
+    if (worsened && !improved && !changed)
+        return "worsened";
+    if (improved && !worsened && !changed)
+        return "improved";
+    return "changed";
+}
+function compareFindingRows(left, right) {
+    const impact = impactRank(left.impact) - impactRank(right.impact);
+    if (impact !== 0)
+        return impact;
+    const leftFinding = left.after ?? left.before;
+    const rightFinding = right.after ?? right.before;
+    const severity = severityRank(rightFinding.severity) - severityRank(leftFinding.severity);
+    return (severity ||
+        leftFinding.finding_kind.localeCompare(rightFinding.finding_kind) ||
+        leftFinding.scope_kind.localeCompare(rightFinding.scope_kind) ||
+        leftFinding.scope_id.localeCompare(rightFinding.scope_id) ||
+        left.fingerprint.localeCompare(right.fingerprint));
+}
+function compareCapabilities(before, after) {
+    const previous = capabilityMap(before.manifest.capabilities);
+    const current = capabilityMap(after.manifest.capabilities);
+    const sourceKinds = [...new Set([...previous.keys(), ...current.keys()])].sort();
+    return sourceKinds.map((sourceKind) => {
+        const left = previous.get(sourceKind);
+        const right = current.get(sourceKind);
+        return {
+            source_kind: sourceKind,
+            change: !left
+                ? "added"
+                : !right
+                    ? "removed"
+                    : sameCapability(left, right)
+                        ? "unchanged"
+                        : "changed",
+            ...(left ? { before: left } : {}),
+            ...(right ? { after: right } : {}),
+        };
+    });
+}
+function capabilityMap(rows) {
+    return new Map([...rows]
+        .sort((a, b) => a.source_kind.localeCompare(b.source_kind))
+        .map((row) => [row.source_kind, row]));
+}
+function sameCapability(left, right) {
+    return (left.state === right.state &&
+        left.reason_code === right.reason_code &&
+        left.detail === right.detail);
+}
+function optionalSourceComparison(before, after, sourceKind, parse) {
+    const previous = optionalSource(before, sourceKind, parse);
+    const current = optionalSource(after, sourceKind, parse);
+    return {
+        before_capability: previous.capability,
+        after_capability: current.capability,
+        ...(previous.value ? { before: previous.value } : {}),
+        ...(current.value ? { after: current.value } : {}),
+    };
+}
+function optionalSource(bundle, sourceKind, parse) {
+    const source = bundle.observations.sources.find((candidate) => candidate.source_kind === sourceKind);
+    if (!source) {
+        return {
+            capability: {
+                source_kind: sourceKind,
+                state: "unsupported",
+                reason_code: "source_not_captured",
+            },
+        };
+    }
+    const capability = {
+        source_kind: sourceKind,
+        state: source.capability,
+        ...(source.reason_code ? { reason_code: source.reason_code } : {}),
+    };
+    if (source.value === undefined)
+        return { capability };
+    const value = parse(source.value);
+    return value
+        ? { capability, value }
+        : {
+            capability: {
+                source_kind: sourceKind,
+                state: "malformed",
+                reason_code: "source_projection_malformed",
+            },
+        };
+}
+function hookHealthSummary(value) {
+    const record = object(value);
+    const summary = object(record?.summary);
+    const aggregates = Array.isArray(record?.aggregates) ? record.aggregates : undefined;
+    if (!record || !summary || !aggregates)
+        return undefined;
+    const parsedSummary = integerFields(summary, [
+        "invocation_count",
+        "degraded_count",
+        "faulted_count",
+        "slow_count",
+        "high_memory_count",
+        "retry_count",
+    ]);
+    if (!parsedSummary)
+        return undefined;
+    const parsedAggregates = [];
+    for (const value of aggregates.slice(0, 40)) {
+        const row = object(value);
+        if (!row)
+            return undefined;
+        const numbers = integerFields(row, [
+            "invocation_count",
+            "degraded_count",
+            "faulted_count",
+            "retry_count",
+            "duration_p95_ms",
+            "rss_end_max_bytes",
+        ]);
+        if (!numbers ||
+            typeof row.key !== "string" ||
+            typeof row.hook_name !== "string" ||
+            typeof row.adapter !== "string") {
+            return undefined;
+        }
+        parsedAggregates.push({
+            key: row.key,
+            hook_name: row.hook_name,
+            adapter: row.adapter,
+            ...numbers,
+        });
+    }
+    return {
+        ...parsedSummary,
+        aggregates: parsedAggregates.sort((left, right) => left.key.localeCompare(right.key)),
+    };
+}
+function shadowAdmissionSummary(value) {
+    const record = object(value);
+    const rows = Array.isArray(record?.records) ? record.records : undefined;
+    if (!record || !rows)
+        return undefined;
+    const summary = {
+        record_count: rows.length,
+        observed_count: 0,
+        not_needed_count: 0,
+        unavailable_count: 0,
+        normal_count: 0,
+        elevated_count: 0,
+        critical_count: 0,
+        unknown_count: 0,
+        max_wait_ms: 0,
+    };
+    for (const value of rows) {
+        const row = object(value);
+        if (!row || (row.state !== "observed" && row.state !== "not-needed"))
+            return undefined;
+        if (row.state === "not-needed") {
+            summary.not_needed_count += 1;
+            continue;
+        }
+        summary.observed_count += 1;
+        const pressure = row.pressure;
+        if (pressure === "normal")
+            summary.normal_count += 1;
+        else if (pressure === "elevated")
+            summary.elevated_count += 1;
+        else if (pressure === "critical")
+            summary.critical_count += 1;
+        else
+            summary.unknown_count += 1;
+        if (row.freshness === "unavailable")
+            summary.unavailable_count += 1;
+        if (typeof row.wait_ms === "number" && Number.isSafeInteger(row.wait_ms) && row.wait_ms >= 0) {
+            summary.max_wait_ms = Math.max(summary.max_wait_ms, row.wait_ms);
+        }
+        else
+            return undefined;
+    }
+    return summary;
+}
+function integerFields(record, keys) {
+    const result = {};
+    for (const key of keys) {
+        const value = record[key];
+        if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0)
+            return undefined;
+        result[key] = value;
+    }
+    return result;
+}
+function adviceDirection(before, after) {
+    if (before === after)
+        return "unchanged";
+    if (before === "unknown" || after === "unknown")
+        return "changed";
+    return pressureRank(after) > pressureRank(before) ? "escalated" : "deescalated";
+}
+function countImpact(rows, impact) {
+    return rows.filter((row) => row.impact === impact).length;
+}
+function owner(finding) {
+    const attribution = finding.attribution;
+    if (!attribution)
+        return null;
+    if (attribution.state === "attributed") {
+        return `${attribution.owner_kind ?? "unknown"}:${attribution.owner_id ?? "unknown"}`;
+    }
+    return `unattributed:${attribution.reason_code ?? "unknown"}`;
+}
+function severityRank(value) {
+    return value === "critical" ? 2 : value === "warning" ? 1 : 0;
+}
+function stateRank(value) {
+    return value === "opened" ? 1 : 0;
+}
+function numberRank(value) {
+    return value;
+}
+function pressureRank(value) {
+    return value === "critical" ? 2 : value === "elevated" ? 1 : 0;
+}
+function impactRank(value) {
+    return ["regression", "worsened", "changed", "improved", "recovery", "unchanged"].indexOf(value);
+}
+function object(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}

package/dist/core/diagnostics/contract.d.ts

@@ -0,0 +1,245 @@
+import type { SupervisorCapability, SupervisorFinding, SupervisorFindingExplanation, SupervisorTimeline } from "../supervisor/contract.js";
+export declare const DIAGNOSTIC_BUNDLE_SCHEMA_VERSION: 3;
+export declare const DIAGNOSTIC_COMMAND_SCHEMA_VERSION: 1;
+export declare const DIAGNOSTIC_INPUT_SCHEMA_VERSION: 2;
+export declare const DIAGNOSTIC_EXPECTED_SCHEMA_VERSION: 3;
+export declare const DIAGNOSTIC_SUMMARY_SCHEMA_VERSION: 1;
+export declare const DIAGNOSTIC_ADVICE_SCHEMA_VERSION: 1;
+export declare const DIAGNOSTIC_COMPARISON_SCHEMA_VERSION: 1;
+export declare const DIAGNOSTIC_ADVICE_LIMITS: {
+    readonly max_contributing_findings: 8;
+    readonly max_reasons: 4;
+};
+export type DiagnosticPressure = "normal" | "elevated" | "critical" | "unknown";
+export type DiagnosticFanOutRecommendation = "proceed" | "use-caution" | "avoid-new-fan-out" | "unknown";
+export interface DiagnosticAdviceFinding {
+    finding_id: string;
+    finding_kind: string;
+    severity: "warning" | "critical";
+    summary: string;
+    scope_kind: string;
+    scope_id: string;
+    occurrence_count: number;
+    owner_kind?: "agent" | "service";
+    owner_id?: string;
+    workload_relationship?: "active-work" | "unexpected-idle-growth" | "unknown";
+}
+export interface DiagnosticAdviceReason {
+    code: "critical_findings_active" | "warning_findings_active" | "findings_source_unavailable" | "no_active_pressure_findings";
+    summary: string;
+    finding_ids: readonly string[];
+}
+export interface DiagnosticAdvice {
+    schema_version: typeof DIAGNOSTIC_ADVICE_SCHEMA_VERSION;
+    evaluated_at: string;
+    pressure: DiagnosticPressure;
+    fan_out_recommendation: DiagnosticFanOutRecommendation;
+    observer_only: true;
+    summary: string;
+    source_capability: SupervisorCapability;
+    active_finding_count: number;
+    contributing_finding_count: number;
+    omitted_contributing_finding_count: number;
+    contributing_findings: readonly DiagnosticAdviceFinding[];
+    reasons: readonly DiagnosticAdviceReason[];
+}
+export declare const DIAGNOSTIC_BUNDLE_FILES: readonly ["diagnostic-manifest.json", "inputs/observations.json", "inputs/thresholds.json", "expected.json", "summary.json"];
+export type DiagnosticBundleFilePath = (typeof DIAGNOSTIC_BUNDLE_FILES)[number];
+export interface DiagnosticBundleFile {
+    path: Exclude<DiagnosticBundleFilePath, "diagnostic-manifest.json">;
+    media_type: "application/json";
+    bytes: number;
+    sha256: string;
+}
+export interface DiagnosticBundleSource {
+    source_kind: string;
+    schema_version?: number;
+    capability: SupervisorCapability["state"];
+    entry_count: number;
+    omitted_count: number;
+    file: "inputs/observations.json";
+}
+export interface DiagnosticBundleManifest {
+    schema_version: typeof DIAGNOSTIC_BUNDLE_SCHEMA_VERSION;
+    artifact_id: string;
+    captured_at: string;
+    machine_id: string;
+    finding_id?: string;
+    time_range: {
+        start_at: string;
+        end_at: string;
+    };
+    engine_version: string;
+    threshold_digest: string;
+    sources: readonly DiagnosticBundleSource[];
+    capabilities: readonly SupervisorCapability[];
+    files: readonly DiagnosticBundleFile[];
+    replay: {
+        input_file: "inputs/observations.json";
+        thresholds_file: "inputs/thresholds.json";
+        expected_file: "expected.json";
+    };
+}
+export interface DiagnosticSelection {
+    finding_id?: string;
+    start_at: string;
+    end_at: string;
+}
+export interface DiagnosticCapturedSource {
+    source_kind: string;
+    capability: SupervisorCapability["state"];
+    schema_version?: number;
+    observed_at?: string;
+    value?: unknown;
+    reason_code?: string;
+}
+export interface DiagnosticObservations {
+    schema_version: typeof DIAGNOSTIC_INPUT_SCHEMA_VERSION;
+    captured_at: string;
+    selection: DiagnosticSelection;
+    sources: readonly DiagnosticCapturedSource[];
+}
+export interface DiagnosticThresholds {
+    schema_version: typeof DIAGNOSTIC_INPUT_SCHEMA_VERSION;
+    values: Readonly<Record<string, unknown>>;
+}
+export interface DiagnosticExpected {
+    schema_version: typeof DIAGNOSTIC_EXPECTED_SCHEMA_VERSION;
+    threshold_digest: string;
+    selection: DiagnosticSelection;
+    findings: readonly SupervisorFinding[];
+    timelines: readonly SupervisorTimeline[];
+    explanations: readonly SupervisorFindingExplanation[];
+    advice: DiagnosticAdvice;
+}
+export interface DiagnosticSummary {
+    schema_version: typeof DIAGNOSTIC_SUMMARY_SCHEMA_VERSION;
+    artifact_id: string;
+    captured_at: string;
+    machine_id: string;
+    machine_id_kind: "pseudonymous";
+    selection: DiagnosticSelection;
+    source_count: number;
+    supported_source_count: number;
+    sanitized_value_count: number;
+    omitted_value_count: number;
+    total_bytes: number;
+}
+export interface ValidatedDiagnosticBundle {
+    path: string;
+    manifest: DiagnosticBundleManifest;
+    observations: DiagnosticObservations;
+    thresholds: DiagnosticThresholds;
+    expected: DiagnosticExpected;
+    summary: DiagnosticSummary;
+}
+export interface DiagnosticReplayResult {
+    schema_version: typeof DIAGNOSTIC_COMMAND_SCHEMA_VERSION;
+    artifact_id: string;
+    replayed_at: string;
+    matched: boolean;
+    threshold_digest: string;
+    expected_digest: string;
+    actual_digest: string;
+    finding_count: number;
+}
+export type DiagnosticComparisonImpact = "regression" | "worsened" | "changed" | "improved" | "recovery" | "unchanged";
+export type DiagnosticFindingChangeClass = "added" | "resolved" | "persistent";
+export interface DiagnosticFindingFieldChange {
+    field: "severity" | "state" | "occurrence_count" | "peak_observed_value" | "owner" | "workload_relationship";
+    before: string | number | null;
+    after: string | number | null;
+    impact: "worsened" | "improved" | "changed";
+}
+export interface DiagnosticFindingComparison {
+    fingerprint: string;
+    change_class: DiagnosticFindingChangeClass;
+    impact: DiagnosticComparisonImpact;
+    before?: SupervisorFinding;
+    after?: SupervisorFinding;
+    field_changes: readonly DiagnosticFindingFieldChange[];
+}
+export interface DiagnosticBundleComparisonRef {
+    artifact_id: string;
+    captured_at: string;
+    machine_id: string;
+    engine_version: string;
+    threshold_digest: string;
+    finding_count: number;
+    pressure: DiagnosticPressure;
+}
+export interface DiagnosticCapabilityComparison {
+    source_kind: string;
+    change: "added" | "removed" | "changed" | "unchanged";
+    before?: SupervisorCapability;
+    after?: SupervisorCapability;
+}
+export interface DiagnosticHookAggregateSummary {
+    key: string;
+    hook_name: string;
+    adapter: string;
+    invocation_count: number;
+    degraded_count: number;
+    faulted_count: number;
+    retry_count: number;
+    duration_p95_ms: number;
+    rss_end_max_bytes: number;
+}
+export interface DiagnosticHookHealthSummary {
+    invocation_count: number;
+    degraded_count: number;
+    faulted_count: number;
+    slow_count: number;
+    high_memory_count: number;
+    retry_count: number;
+    aggregates: readonly DiagnosticHookAggregateSummary[];
+}
+export interface DiagnosticShadowAdmissionSummary {
+    record_count: number;
+    observed_count: number;
+    not_needed_count: number;
+    unavailable_count: number;
+    normal_count: number;
+    elevated_count: number;
+    critical_count: number;
+    unknown_count: number;
+    max_wait_ms: number;
+}
+export interface DiagnosticOptionalSourceComparison<T> {
+    before_capability: SupervisorCapability;
+    after_capability: SupervisorCapability;
+    before?: T;
+    after?: T;
+}
+export interface DiagnosticComparisonWarning {
+    code: "threshold_digest_changed" | "engine_version_changed" | "machine_changed" | "capture_order_reversed" | "duplicate_fingerprint" | "source_capability_changed" | "hook_health_unavailable" | "shadow_admission_unavailable";
+    summary: string;
+}
+export interface DiagnosticBundleComparison {
+    schema_version: typeof DIAGNOSTIC_COMPARISON_SCHEMA_VERSION;
+    observer_only: true;
+    before: DiagnosticBundleComparisonRef;
+    after: DiagnosticBundleComparisonRef;
+    comparability: "comparable" | "partial";
+    warnings: readonly DiagnosticComparisonWarning[];
+    advice: {
+        before: DiagnosticAdvice;
+        after: DiagnosticAdvice;
+        direction: "escalated" | "deescalated" | "unchanged" | "changed";
+    };
+    findings: {
+        total: number;
+        regressions: number;
+        worsened: number;
+        changed: number;
+        improved: number;
+        recoveries: number;
+        unchanged: number;
+        rows: readonly DiagnosticFindingComparison[];
+    };
+    capabilities: readonly DiagnosticCapabilityComparison[];
+    hook_health: DiagnosticOptionalSourceComparison<DiagnosticHookHealthSummary>;
+    shadow_admission: DiagnosticOptionalSourceComparison<DiagnosticShadowAdmissionSummary>;
+    comparison_digest: string;
+}
+//# sourceMappingURL=contract.d.ts.map