@skill-harness/core 0.12.0 → 0.14.0

package/dist/adoption.d.ts

@@ -0,0 +1,128 @@
+export interface AdoptionInput {
+    hypothesisDigest: string;
+    experimentDigest: string;
+    candidateDigest: string;
+    scopeDigest: string;
+    assessmentPolicyDigest: string;
+    rollbackCandidateDigest: string;
+    activationBoundary: "next-orders";
+    expiresAt: number;
+}
+export interface AdoptionBinding extends AdoptionInput {
+    version: "adoption-binding-v1";
+    id: string;
+}
+export interface AdoptionAuthority {
+    id: string;
+    adoptions: readonly string[];
+    rollbacks: readonly string[];
+}
+export interface AdoptionFacts {
+    experimentDigest: string;
+    candidateDigest: string;
+    scopeDigest: string;
+    assessmentPolicyDigest: string;
+    eligible: boolean;
+}
+export declare function buildAdoptionBinding(input: AdoptionInput): AdoptionBinding;
+/** Independent host declarations and independently verified eligible facts are required again at use. */
+export declare function authorizeAdoption(binding: AdoptionBinding, authority: AdoptionAuthority | null, facts: AdoptionFacts, now: number): Readonly<{
+    id: string;
+    version: "adoption-receipt-v1";
+    bindingId: string;
+    authorityId: string;
+    hypothesisDigest: string;
+    experimentDigest: string;
+    candidateDigest: string;
+    scopeDigest: string;
+    assessmentPolicyDigest: string;
+    rollbackCandidateDigest: string;
+    activationBoundary: "next-orders";
+    grantExpansion: false;
+    expiresAt: number;
+}>;
+export type AdoptionReceipt = ReturnType<typeof authorizeAdoption>;
+export declare function validateAdoptionReceipt(receipt: AdoptionReceipt, binding: AdoptionBinding, authority: AdoptionAuthority | null, facts: AdoptionFacts, now: number): void;
+export interface ProductionObservation {
+    id: string;
+    adoptionId: string;
+    candidateDigest: string;
+    scopeDigest: string;
+    originalRequirementDigest: string;
+    currentRequirementDigest: string;
+    /** Only an independent host may supply confirmed outcomes; observer/model claims are not confirmation. */
+    outcome: "confirmed-defect" | "success" | "unknown";
+    acceptanceDigest: string | null;
+    acceptedArtifactDigest: string | null;
+    observedArtifactDigest: string;
+    evidence: string[];
+}
+export declare function classifyProductionObservation(adoption: AdoptionReceipt, input: ProductionObservation): Readonly<{
+    state: "unknown" | "success" | "out-of-scope" | "changed-requirements" | "changed-artifact" | "caught-defect" | "escape";
+    adoptionId: string;
+    hypothesisDigest: string;
+    experimentDigest: string;
+    observationId: string;
+    acceptanceDigest: string | null;
+    acceptedArtifactDigest: string | null;
+    observedArtifactDigest: string;
+    automaticRollback: false;
+}>;
+export interface RollbackRequest {
+    version: "rollback-request-v1";
+    id: string;
+    adoptionId: string;
+    scopeDigest: string;
+    restoreCandidateDigest: string;
+    reason: "operator-request" | "confirmed-escape";
+    evidence: readonly string[];
+    expiresAt: number;
+}
+export declare function buildRollbackRequest(adoption: AdoptionReceipt, reason: RollbackRequest["reason"], evidence: string[], expiresAt?: number): RollbackRequest;
+/** This validates a recorded choice, not an automatic rollback action or a caller-created authority flag. */
+export declare function authorizeRollback(adoption: AdoptionReceipt, request: RollbackRequest, authority: AdoptionAuthority | null, now: number, current: {
+    adoptionId: string;
+    candidateDigest: string;
+    scopeDigest: string;
+}): Readonly<{
+    requestId: string;
+    adoptionId: string;
+    restoreCandidateDigest: string;
+    scopeDigest: string;
+    grantExpansion: false;
+    application: "not-performed";
+}>;
+export interface LeanOutcome {
+    population: string;
+    complete: boolean;
+    accepted: boolean | null;
+    repairAttempts: number | null;
+    escape: "confirmed" | "none-observed" | "unknown";
+    requirementsChanged: boolean;
+    decisionWaitMs: number | null;
+    questions: number | null;
+}
+export declare function summarizeLeanOutcomes(population: string, rows: readonly LeanOutcome[]): {
+    population: string;
+    firstPassAccepted: number;
+    firstPassDenominator: number;
+    incomplete: number;
+    confirmedEscapes: number;
+    changedRequirements: number;
+    recovery: {
+        known: number;
+        observed: number;
+        total: number;
+    };
+    decisionWait: {
+        known: number;
+        observed: number;
+        total: number;
+    };
+    questions: {
+        known: number;
+        observed: number;
+        total: number;
+    };
+    universalScore: null;
+};

package/dist/adoption.js

@@ -0,0 +1,102 @@
+import { createHash } from "node:crypto";
+const SHA = /^[a-f0-9]{64}$/;
+const text = (x) => typeof x === "string" && x.length > 0 && x.length <= 512 && !/[\u0000-\u001f\u007f]/.test(x);
+const closed = (value, names) => {
+    if (!value || ![Object.prototype, null].includes(Object.getPrototypeOf(value)))
+        return false;
+    const fields = Object.getOwnPropertyDescriptors(value);
+    return Reflect.ownKeys(fields).length === names.length && Reflect.ownKeys(fields).every(key => typeof key === "string" && names.includes(key) && fields[key].enumerable && Object.hasOwn(fields[key], "value"));
+};
+const hash = (value) => createHash("sha256").update(JSON.stringify(Object.keys(value).sort().map(k => [k, value[k]]))).digest("hex");
+export function buildAdoptionBinding(input) {
+    if (!input || !closed(input, ["hypothesisDigest", "experimentDigest", "candidateDigest", "scopeDigest", "assessmentPolicyDigest", "rollbackCandidateDigest", "activationBoundary", "expiresAt"])
+        || ![input.hypothesisDigest, input.experimentDigest, input.candidateDigest, input.scopeDigest, input.assessmentPolicyDigest, input.rollbackCandidateDigest].every(s => typeof s === "string" && SHA.test(s))
+        || input.activationBoundary !== "next-orders" || !Number.isSafeInteger(input.expiresAt) || input.expiresAt < 0)
+        throw new Error("invalid scoped adoption binding");
+    const body = { version: "adoption-binding-v1", ...input };
+    return Object.freeze({ ...body, id: hash(body) });
+}
+function bindingValid(binding) {
+    const { version, id, ...input } = binding;
+    if (version !== "adoption-binding-v1" || buildAdoptionBinding(input).id !== id)
+        throw new Error("adoption binding changed");
+}
+function authorityValid(authority) {
+    return !!authority && text(authority.id) && Array.isArray(authority.adoptions) && Array.isArray(authority.rollbacks)
+        && authority.adoptions.length <= 256 && authority.rollbacks.length <= 256 && [...authority.adoptions, ...authority.rollbacks].every(id => typeof id === "string" && SHA.test(id));
+}
+/** Independent host declarations and independently verified eligible facts are required again at use. */
+export function authorizeAdoption(binding, authority, facts, now) {
+    bindingValid(binding);
+    if (!authorityValid(authority) || !authority.adoptions.includes(binding.id))
+        throw new Error("independent adoption authority required");
+    if (!Number.isSafeInteger(now) || now < 0 || now >= binding.expiresAt || !facts || !closed(facts, ["experimentDigest", "candidateDigest", "scopeDigest", "assessmentPolicyDigest", "eligible"]) || facts.eligible !== true
+        || facts.experimentDigest !== binding.experimentDigest || facts.candidateDigest !== binding.candidateDigest
+        || facts.scopeDigest !== binding.scopeDigest || facts.assessmentPolicyDigest !== binding.assessmentPolicyDigest)
+        throw new Error("adoption expired, ineligible or outside verified scope");
+    const body = { version: "adoption-receipt-v1", bindingId: binding.id, authorityId: authority.id, hypothesisDigest: binding.hypothesisDigest,
+        experimentDigest: binding.experimentDigest, candidateDigest: binding.candidateDigest, scopeDigest: binding.scopeDigest,
+        assessmentPolicyDigest: binding.assessmentPolicyDigest, rollbackCandidateDigest: binding.rollbackCandidateDigest,
+        activationBoundary: "next-orders", grantExpansion: false, expiresAt: binding.expiresAt };
+    return Object.freeze({ ...body, id: hash(body) });
+}
+export function validateAdoptionReceipt(receipt, binding, authority, facts, now) {
+    if (authorizeAdoption(binding, authority, facts, now).id !== receipt.id)
+        throw new Error("adoption receipt does not match current independent authority/facts");
+    receiptValid(receipt);
+}
+function receiptValid(receipt) {
+    const { id, ...body } = receipt;
+    if (!closed(receipt, ["version", "bindingId", "authorityId", "hypothesisDigest", "experimentDigest", "candidateDigest", "scopeDigest", "assessmentPolicyDigest", "rollbackCandidateDigest", "activationBoundary", "grantExpansion", "expiresAt", "id"])
+        || body.version !== "adoption-receipt-v1" || !text(body.authorityId) || body.activationBoundary !== "next-orders" || body.grantExpansion !== false || hash(body) !== id)
+        throw new Error("adoption receipt changed");
+    const binding = buildAdoptionBinding({ hypothesisDigest: body.hypothesisDigest, experimentDigest: body.experimentDigest, candidateDigest: body.candidateDigest,
+        scopeDigest: body.scopeDigest, assessmentPolicyDigest: body.assessmentPolicyDigest, rollbackCandidateDigest: body.rollbackCandidateDigest, activationBoundary: body.activationBoundary, expiresAt: body.expiresAt });
+    if (binding.id !== body.bindingId)
+        throw new Error("adoption receipt binding mismatch");
+}
+export function classifyProductionObservation(adoption, input) {
+    receiptValid(adoption);
+    if (!input || !text(input.id) || input.evidence.length > 256 || input.evidence.some(h => !SHA.test(h))
+        || ![input.originalRequirementDigest, input.currentRequirementDigest, input.candidateDigest, input.scopeDigest, input.observedArtifactDigest].every(h => typeof h === "string" && SHA.test(h))
+        || ![input.acceptanceDigest, input.acceptedArtifactDigest].every(h => h === null || (typeof h === "string" && SHA.test(h)))
+        || (input.acceptanceDigest === null) !== (input.acceptedArtifactDigest === null)
+        || !["confirmed-defect", "success", "unknown"].includes(input.outcome))
+        throw new Error("invalid production observation");
+    const state = input.adoptionId !== adoption.id || input.candidateDigest !== adoption.candidateDigest || input.scopeDigest !== adoption.scopeDigest ? "out-of-scope"
+        : input.originalRequirementDigest !== input.currentRequirementDigest ? "changed-requirements"
+            : input.acceptedArtifactDigest !== null && input.acceptedArtifactDigest !== input.observedArtifactDigest ? "changed-artifact"
+                : input.outcome === "confirmed-defect" && input.evidence.length ? input.acceptanceDigest === null ? "caught-defect" : "escape" : input.outcome === "success" ? "success" : "unknown";
+    return Object.freeze({ state, adoptionId: adoption.id, hypothesisDigest: adoption.hypothesisDigest, experimentDigest: adoption.experimentDigest, observationId: input.id, acceptanceDigest: input.acceptanceDigest, acceptedArtifactDigest: input.acceptedArtifactDigest, observedArtifactDigest: input.observedArtifactDigest, automaticRollback: false });
+}
+export function buildRollbackRequest(adoption, reason, evidence, expiresAt = adoption.expiresAt) {
+    receiptValid(adoption);
+    if (!Number.isSafeInteger(expiresAt) || expiresAt < 0 || !["operator-request", "confirmed-escape"].includes(reason) || !evidence.length || evidence.length > 256 || evidence.some(h => !SHA.test(h)))
+        throw new Error("invalid rollback request");
+    const body = { version: "rollback-request-v1", adoptionId: adoption.id, scopeDigest: adoption.scopeDigest, restoreCandidateDigest: adoption.rollbackCandidateDigest, reason, expiresAt, evidence: Object.freeze([...new Set(evidence)].sort()) };
+    return Object.freeze({ ...body, id: hash(body) });
+}
+/** This validates a recorded choice, not an automatic rollback action or a caller-created authority flag. */
+export function authorizeRollback(adoption, request, authority, now, current) {
+    receiptValid(adoption);
+    const { id, ...body } = request;
+    if (!authorityValid(authority) || authority.id !== adoption.authorityId || !authority.rollbacks.includes(id))
+        throw new Error("independent rollback authority required");
+    if (hash(body) !== id || request.version !== "rollback-request-v1" || request.adoptionId !== adoption.id || request.scopeDigest !== adoption.scopeDigest
+        || request.restoreCandidateDigest !== adoption.rollbackCandidateDigest || !Number.isSafeInteger(now) || now < 0 || !Number.isSafeInteger(request.expiresAt) || now >= request.expiresAt
+        || !current || current.adoptionId !== adoption.id || current.candidateDigest !== adoption.candidateDigest || current.scopeDigest !== adoption.scopeDigest)
+        throw new Error("rollback binding changed or expired");
+    return Object.freeze({ requestId: id, adoptionId: adoption.id, restoreCandidateDigest: request.restoreCandidateDigest, scopeDigest: adoption.scopeDigest, grantExpansion: false, application: "not-performed" });
+}
+export function summarizeLeanOutcomes(population, rows) {
+    if (!text(population) || rows.length > 10000 || rows.some(r => r.population !== population || typeof r.complete !== "boolean" || typeof r.requirementsChanged !== "boolean"
+        || ![true, false, null].includes(r.accepted) || !["confirmed", "none-observed", "unknown"].includes(r.escape)
+        || [r.repairAttempts, r.decisionWaitMs, r.questions].some(n => n !== null && (!Number.isSafeInteger(n) || n < 0))))
+        throw new Error("invalid or incomparable lean population");
+    const complete = rows.filter(r => r.complete && r.accepted !== null && r.repairAttempts !== null);
+    const observed = (field) => ({ known: rows.reduce((n, r) => n + (r[field] ?? 0), 0), observed: rows.filter(r => r[field] !== null).length, total: rows.length });
+    return { population, firstPassAccepted: complete.filter(r => r.accepted && r.repairAttempts === 0).length, firstPassDenominator: complete.length,
+        incomplete: rows.length - complete.length, confirmedEscapes: rows.filter(r => r.escape === "confirmed" && !r.requirementsChanged).length,
+        changedRequirements: rows.filter(r => r.requirementsChanged).length, recovery: observed("repairAttempts"), decisionWait: observed("decisionWaitMs"), questions: observed("questions"), universalScore: null };
+}
+//# sourceMappingURL=adoption.js.map

package/dist/command-cost.d.ts

@@ -4,6 +4,6 @@
  * Keep this list narrow: commands that can conditionally spend (notably `regate`)
  * do not belong here even when their common path only replays saved artifacts.
  */
-export declare const FREE_OFFLINE_COMMANDS: readonly ["affected", "coverage", "init", "judge-agreement", "lint", "list", "mutation-test", "rescore", "restamp", "screen", "stability"];
+export declare const FREE_OFFLINE_COMMANDS: readonly ["affected", "archive", "coverage", "init", "judge-agreement", "lint", "list", "rescore", "restamp", "screen", "stability"];
 export type FreeOfflineCommand = typeof FREE_OFFLINE_COMMANDS[number];
 export declare function isFreeOfflineCommand(command: string): command is FreeOfflineCommand;

package/dist/command-cost.js

@@ -6,12 +6,12 @@
  */
 export const FREE_OFFLINE_COMMANDS = [
     "affected",
+    "archive",
     "coverage",
     "init",
     "judge-agreement",
     "lint",
     "list",
-    "mutation-test",
     "rescore",
     "restamp",
     "screen",

package/dist/factory-calibration.d.ts

@@ -0,0 +1,63 @@
+export interface CalibrationComponent {
+    kind: "detector" | "adjudicator";
+    id: string;
+    version: string;
+    population: string;
+}
+export type CalibrationKind = "positive" | "approval" | "rejection";
+export type CalibrationSplit = "calibration" | "heldout" | "tuning";
+export interface CalibrationPrediction {
+    id: string;
+    incidentId: string;
+    component: CalibrationComponent;
+    kind: CalibrationKind;
+    split: CalibrationSplit;
+}
+/** Independently established host context, not fields accepted from predictions or panel agreement. */
+export interface CalibrationOutcome extends CalibrationPrediction {
+    correct: boolean;
+}
+export interface CalibrationReport {
+    component: CalibrationComponent;
+    kind: CalibrationKind;
+    split: Exclude<CalibrationSplit, "tuning">;
+    correct: number;
+    incorrect: number;
+    resolved: number;
+    unresolved: number;
+    conflicted: number;
+    totalIncidents: number;
+    precision: number | null;
+    interval: {
+        lower: number;
+        upper: number;
+    } | null;
+    advisoryOnly: true;
+}
+/** Version/population/conditioning-specific statistics; no policy, grants, routing or adoption is changed. */
+export declare function calibratePredictions(predictions: readonly CalibrationPrediction[], context?: {
+    outcomes: readonly CalibrationOutcome[];
+}): {
+    version: "factory-calibration-v1";
+    reports: CalibrationReport[];
+    excludedTuning: number;
+    referenceBasis: "independently-supplied-host-context";
+    advisoryOnly: true;
+};
+export interface ExposurePolicy {
+    id: string;
+    component: CalibrationComponent;
+    kind: CalibrationKind;
+    split: "calibration" | "heldout";
+    minimumResolved: number;
+    minimumLowerBound: number;
+    attentionRemaining: number;
+    expiresAt: number;
+    retireBelowUpperBound?: number;
+}
+/** A selected pre-established host policy may produce advice; this never applies it or expands authority. */
+export declare function recommendExposure(report: CalibrationReport, policy: ExposurePolicy | null, now: number): {
+    mode: "silent" | "ask" | "retire";
+    reason: string;
+    advisoryOnly: true;
+};

package/dist/factory-calibration.js

@@ -0,0 +1,115 @@
+const computedReports = new WeakSet();
+const text = (x) => typeof x === "string" && x.length > 0 && x.length <= 512 && !/[\u0000-\u001f\u007f]/.test(x);
+function closed(x, fields) {
+    return x !== null && typeof x === "object" && !Array.isArray(x) && Object.keys(x).length === fields.length && Object.keys(x).every(k => fields.includes(k));
+}
+function valid(x, outcome = false) {
+    return closed(x, outcome ? ["id", "incidentId", "component", "kind", "split", "correct"] : ["id", "incidentId", "component", "kind", "split"])
+        && text(x.id) && text(x.incidentId) && closed(x.component, ["kind", "id", "version", "population"])
+        && [x.component.id, x.component.version, x.component.population].every(text)
+        && ["calibration", "heldout", "tuning"].includes(x.split)
+        && (x.component.kind === "detector" ? x.kind === "positive" : x.component.kind === "adjudicator" && ["approval", "rejection"].includes(x.kind))
+        && (!outcome || typeof x.correct === "boolean");
+}
+const key = (x) => JSON.stringify([x.component.kind, x.component.id, x.component.version, x.component.population, x.kind, x.split]);
+function interval(correct, count) {
+    const z = 1.96, z2 = z * z, p = correct / count, denominator = 1 + z2 / count;
+    const center = (p + z2 / (2 * count)) / denominator;
+    const half = z * Math.sqrt(p * (1 - p) / count + z2 / (4 * count * count)) / denominator;
+    return { lower: Math.max(0, center - half), upper: Math.min(1, center + half) };
+}
+/** Version/population/conditioning-specific statistics; no policy, grants, routing or adoption is changed. */
+export function calibratePredictions(predictions, context = { outcomes: [] }) {
+    if (predictions.length > 10000 || context.outcomes.length > 10000 || predictions.some(p => !valid(p)) || context.outcomes.some(r => !valid(r, true)))
+        throw new Error("invalid calibration input");
+    const byId = new Map();
+    for (const p of predictions) {
+        const previous = byId.get(p.id);
+        if (previous && (key(previous) !== key(p) || previous.incidentId !== p.incidentId))
+            throw new Error("prediction identity conflict");
+        byId.set(p.id, p);
+    }
+    const groups = new Map();
+    let excludedTuning = 0;
+    for (const p of byId.values()) {
+        if (p.split === "tuning") {
+            excludedTuning++;
+            continue;
+        }
+        const k = key(p);
+        groups.set(k, [...(groups.get(k) ?? []), p]);
+    }
+    const referenceIds = new Map();
+    const conflictingIds = new Set();
+    for (const r of context.outcomes) {
+        const signature = JSON.stringify([key(r), r.incidentId, r.correct]);
+        if (referenceIds.has(r.id) && referenceIds.get(r.id) !== signature)
+            conflictingIds.add(r.id);
+        referenceIds.set(r.id, signature);
+    }
+    const labels = new Map();
+    const conflictedIncidents = new Set();
+    for (const r of context.outcomes) {
+        const k = JSON.stringify([key(r), r.incidentId]);
+        if (conflictingIds.has(r.id)) {
+            conflictedIncidents.add(k);
+            continue;
+        }
+        const values = labels.get(k) ?? new Set();
+        values.add(r.correct);
+        labels.set(k, values);
+    }
+    const reports = [...groups].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([groupKey, group]) => {
+        const incidents = new Set(group.map(p => p.incidentId));
+        let correct = 0, incorrect = 0, unresolved = 0, conflicted = 0;
+        for (const incident of incidents) {
+            const incidentKey = JSON.stringify([groupKey, incident]);
+            const outcomes = labels.get(incidentKey) ?? new Set();
+            if (outcomes.size !== 1 || conflictedIncidents.has(incidentKey)) {
+                unresolved++;
+                if (outcomes.size > 1 || conflictedIncidents.has(incidentKey))
+                    conflicted++;
+            }
+            else if (outcomes.has(true))
+                correct++;
+            else
+                incorrect++;
+        }
+        const resolved = correct + incorrect;
+        return { component: { ...group[0].component }, kind: group[0].kind, split: group[0].split,
+            correct, incorrect, resolved, unresolved, conflicted, totalIncidents: incidents.size,
+            precision: resolved ? correct / resolved : null, interval: resolved ? interval(correct, resolved) : null, advisoryOnly: true };
+    });
+    for (const report of reports) {
+        Object.freeze(report.component);
+        if (report.interval)
+            Object.freeze(report.interval);
+        Object.freeze(report);
+        computedReports.add(report);
+    }
+    return { version: "factory-calibration-v1", reports, excludedTuning, referenceBasis: "independently-supplied-host-context", advisoryOnly: true };
+}
+/** A selected pre-established host policy may produce advice; this never applies it or expands authority. */
+export function recommendExposure(report, policy, now) {
+    if (!computedReports.has(report))
+        throw new Error("recompute calibration from predictions and independent reference context before evaluating exposure");
+    const result = (mode, reason) => ({ mode, reason, advisoryOnly: true });
+    if (!policy)
+        return result("silent", "policy-unavailable");
+    if (!text(policy.id) || !Number.isSafeInteger(policy.minimumResolved) || policy.minimumResolved < 1
+        || !Number.isSafeInteger(policy.attentionRemaining) || policy.attentionRemaining < 0
+        || !Number.isFinite(policy.minimumLowerBound) || policy.minimumLowerBound < 0 || policy.minimumLowerBound > 1
+        || !Number.isFinite(policy.expiresAt) || !Number.isFinite(now)
+        || (policy.retireBelowUpperBound !== undefined && (!Number.isFinite(policy.retireBelowUpperBound) || policy.retireBelowUpperBound < 0 || policy.retireBelowUpperBound > 1)))
+        throw new Error("invalid exposure policy");
+    if (key(policy) !== key(report) || now >= policy.expiresAt)
+        return result("silent", "policy-inapplicable-or-expired");
+    if (!report.interval || report.resolved < policy.minimumResolved)
+        return result("silent", "insufficient-independent-evidence");
+    if (policy.retireBelowUpperBound !== undefined && report.interval.upper < policy.retireBelowUpperBound)
+        return result("retire", "below-selected-reliability-policy");
+    if (report.interval.lower < policy.minimumLowerBound || policy.attentionRemaining === 0)
+        return result("silent", "confidence-or-attention-bound");
+    return result("ask", "selected-evidence-and-attention-policy-met");
+}
+//# sourceMappingURL=factory-calibration.js.map

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+export * from "./trusted-host-supervision.js";
 export * from "./spec.js";
 export * from "./discover.js";
 export * from "./run.js";
@@ -33,6 +34,14 @@ export * from "./downgrade.js";
 export * from "./canary.js";
 export * from "./stability.js";
 export * from "./capture-trace-types.js";
+export * from "./work-capture.js";
+export * from "./work-signals.js";
+export * from "./work-capture-schema.js";
+export * from "./factory-calibration.js";
+export * from "./adoption.js";
+export * from "./investigation.js";
+export * from "./intervention.js";
+export * from "./intervention-results.js";
 export * from "./spec-write.js";
 export * from "./capture.js";
 export * from "./execution-trace.js";

package/dist/index.js

@@ -1,3 +1,4 @@
+export * from "./trusted-host-supervision.js";
 export * from "./spec.js";
 export * from "./discover.js";
 export * from "./run.js";
@@ -33,6 +34,14 @@ export * from "./downgrade.js";
 export * from "./canary.js";
 export * from "./stability.js";
 export * from "./capture-trace-types.js";
+export * from "./work-capture.js";
+export * from "./work-signals.js";
+export * from "./work-capture-schema.js";
+export * from "./factory-calibration.js";
+export * from "./adoption.js";
+export * from "./investigation.js";
+export * from "./intervention.js";
+export * from "./intervention-results.js";
 export * from "./spec-write.js";
 export * from "./capture.js";
 export * from "./execution-trace.js";

package/dist/intervention-results.d.ts

@@ -0,0 +1,6 @@
+import type { InterventionManifest, InterventionEvidence } from "./intervention.js";
+/** Normalize existing validated schema3 records, retaining the complete source votes alongside the summary. */
+export declare function interventionEvidenceFromResults(manifest: InterventionManifest, armId: string, raw: unknown, outputBytes: ReadonlyMap<string, Uint8Array>): {
+    evidence: InterventionEvidence;
+    sourceResults: import("./results.js").ResultsFile;
+};

package/dist/intervention-results.js

@@ -0,0 +1,52 @@
+import { createHash } from "node:crypto";
+import { validateResults } from "./results.js";
+import { aggregateMetrics } from "./comparison.js";
+/** Normalize existing validated schema3 records, retaining the complete source votes alongside the summary. */
+export function interventionEvidenceFromResults(manifest, armId, raw, outputBytes) {
+    const sourceResults = validateResults(raw), arm = manifest.arms.find(a => a.id === armId);
+    if (!arm || sourceResults.model !== arm.configuration.model)
+        throw new Error("intervention result model mismatch");
+    if (sourceResults.schema !== 3 || sourceResults.partial || sourceResults.mode !== manifest.common.mode
+        || `${sourceResults.judge.provider}:${sourceResults.judge.model}` !== manifest.judge)
+        throw new Error("incomplete or incompatible intervention results");
+    if (sourceResults.source_hashes?.["intervention:manifest"] !== manifest.id || sourceResults.source_hashes?.["intervention:inputs"] !== manifest.inputDigest)
+        throw new Error("recorded frozen intervention binding missing; never stamp historical results");
+    if (sourceResults.scenarios.length !== manifest.cases.length || sourceResults.scenarios.some(s => !manifest.cases.some(c => c.id === s.id)))
+        throw new Error("intervention scenario plan mismatch");
+    const cells = [], artifacts = new Set();
+    for (const spec of manifest.cases) {
+        const scenario = sourceResults.scenarios.find(s => s.id === spec.id);
+        if (scenario.criterion_count !== spec.criteria || (scenario.reps ?? 1) !== spec.reps || (scenario.pass_threshold ?? 1) !== spec.threshold)
+            throw new Error("intervention repetition/criterion policy mismatch");
+        for (const panel of scenario.rep_judgments ?? []) {
+            const delivery = sourceResults.subject_invocations.find(o => o.scenario_id === spec.id && o.repetition === panel.repetition)?.prompt?.status;
+            if (!delivery || !panel.objective)
+                throw new Error("intervention objective/delivery evidence missing");
+            const objective = panel.objective.status;
+            const bytes = outputBytes.get(`${spec.id}:${panel.repetition}`);
+            if (bytes !== undefined && (!(bytes instanceof Uint8Array) || bytes.byteLength > 8 * 1024 * 1024))
+                throw new Error("intervention output exceeds bounds");
+            const artifactSha256 = bytes ? createHash("sha256").update(bytes).digest("hex") : null;
+            if (artifactSha256)
+                artifacts.add(artifactSha256);
+            let criteria = [], suspect = false;
+            if (delivery === "PASS" && objective === "PASS") {
+                if (panel.judgments.length !== 1)
+                    throw new Error("multi-judge normalization not yet supported; retain original panel without selecting a convenient vote");
+                const judgment = panel.judgments[0];
+                if (`${judgment.judge.provider}:${judgment.judge.model}` !== manifest.judge)
+                    throw new Error("intervention cell judge mismatch");
+                criteria = [...(judgment.criteria ?? [])].sort((a, b) => a.index - b.index).map(c => c.verdict === "ERROR" ? "UNKNOWN" : c.verdict);
+                suspect = judgment.suspect || scenario.suspect;
+            }
+            cells.push({ caseId: spec.id, repetition: panel.repetition, delivery, objective, criteria, suspect, artifactSha256 });
+        }
+    }
+    const metrics = aggregateMetrics(sourceResults.scenarios);
+    const cost = manifest.resourceMetric === "wall_ms" ? (sourceResults.scenarios.every(s => s.metrics) ? metrics.wall_time_ms : null)
+        : manifest.resourceMetric === "tool_calls" ? metrics.tool_calls
+            : metrics.cost_source === "provider-reported" && metrics.subject_metrics_reps === metrics.total_reps ? metrics.subject_cost_usd : null;
+    const evidence = { armId, inputDigest: manifest.inputDigest, artifactDigests: [...artifacts].sort(), cells, cost, costUnit: manifest.resourceMetric };
+    return { evidence, sourceResults };
+}
+//# sourceMappingURL=intervention-results.js.map

package/dist/intervention.d.ts

@@ -0,0 +1,123 @@
+/** Plain, bounded JSON encoding for retained intervention inputs; not semantic validation. */
+export declare function interventionCanonicalJson(value: unknown): string;
+export type InterventionAxis = "model" | "effort" | "skill" | "prompt" | "configuration";
+export interface InterventionDraft {
+    family: "intervention";
+    investigationSha256: string;
+    resourceMetric: "usd" | "wall_ms" | "tool_calls";
+    axes: InterventionAxis[];
+    common: {
+        mode: "green" | "force";
+        scenarioSha256: string;
+        rubricSha256: string;
+        fixtureSha256: string;
+        heldoutSha256: string;
+        harnessSha256: string;
+        judgePolicySha256: string;
+    };
+    proposer: string;
+    judge: string;
+    cases: Array<{
+        id: string;
+        criteria: number;
+        reps: number;
+        threshold: number;
+        critical: boolean;
+    }>;
+    arms: Array<{
+        id: string;
+        configuration: Record<InterventionAxis, string>;
+    }>;
+}
+export interface InterventionManifest extends InterventionDraft {
+    version: "intervention-comparison-v1";
+    id: string;
+    inputDigest: string;
+    changedAxes: InterventionAxis[];
+    deterministicSampling: false;
+}
+export declare function freezeIntervention(input: InterventionDraft): InterventionManifest;
+export interface InterventionCell {
+    caseId: string;
+    repetition: number;
+    delivery: "PASS" | "NOT-MEASURED" | "ERROR";
+    objective: "PASS" | "FAIL" | "ERROR" | "NOT-MEASURED";
+    criteria: Array<"PASS" | "FAIL" | "UNKNOWN">;
+    suspect: boolean;
+    artifactSha256: string | null;
+}
+export interface InterventionEvidence {
+    armId: string;
+    inputDigest: string;
+    artifactDigests: string[];
+    cells: InterventionCell[];
+    cost: number | null;
+    costUnit: string;
+}
+export declare const interventionEvidenceDigest: (value: InterventionEvidence) => string;
+export interface InterventionQualification {
+    manifestId: string;
+    proposer: {
+        requested: string;
+        canonical: string;
+    };
+    judge: {
+        requested: string;
+        canonical: string;
+    };
+    subjects: Record<string, {
+        requested: string;
+        canonical: string;
+    }>;
+    evidenceDigests: Record<string, string>;
+    /** Actual independently retained output bytes, not an availability flag supplied by an arm. */
+    artifacts: ReadonlyMap<string, Uint8Array>;
+}
+export interface InterventionAssessment {
+    manifestId: string;
+    complete: boolean;
+    arms: Array<{
+        armId: string;
+        state: "MEASURED" | "FAILED" | "MISSING" | "ERROR" | "NOT-MEASURED" | "UNRESOLVED";
+        eligible: boolean;
+        artifactDigests: string[];
+        cost: number | null;
+        costUnit: string;
+    }>;
+    cheapestEligible: string | null;
+    routingDefault: null;
+    adoptionAuthorized: false;
+}
+/** Pre-spend role gate: consumes independently resolved host facts, never guesses aliases or calls a provider. */
+export declare function assertInterventionRoles(manifest: InterventionManifest, qualification: InterventionQualification | null): asserts qualification is InterventionQualification;
+/** Inspects separately host-qualified evidence; does not obtain qualification or execute a model. */
+export declare function assessIntervention(manifest: InterventionManifest, evidence: readonly InterventionEvidence[], qualification: InterventionQualification | null): InterventionAssessment;
+export type BlindQualityChoice = {
+    kind: "one" | "tie" | "none" | "insufficient";
+    labels: string[];
+};
+/** Only this view omits identity/cost; arbitrary artifact content can still leak clues and must be reviewed. */
+export declare function createBlindComparison(manifest: InterventionManifest, assessment: InterventionAssessment, fixtureOrPersistedSeed?: string): Readonly<{
+    view: () => {
+        version: string;
+        cards: {
+            label: string;
+            artifactDigests: string[];
+        }[];
+        limitations: string[];
+    };
+    readArtifact(label: string, hash: string): Buffer<ArrayBuffer>;
+    choose(input: BlindQualityChoice): BlindQualityChoice;
+    reveal(): {
+        manifestId: string;
+        choice: BlindQualityChoice;
+        arms: {
+            label: string;
+            armId: string;
+            configuration: Record<InterventionAxis, string>;
+            cost: number | null;
+            costUnit: string;
+        }[];
+        routingDefault: null;
+    };
+}>;