@skill-harness/core 0.12.0 → 0.13.0

package/dist/intervention.js

@@ -0,0 +1,218 @@
+import { createHash, randomBytes } from "node:crypto";
+const SHA = /^[a-f0-9]{64}$/;
+const text = (x, max = 512) => typeof x === "string" && x.length > 0 && x.length <= max && !/[\u0000-\u001f\u007f]/.test(x);
+const closed = (x, names) => !!x && typeof x === "object" && !Array.isArray(x) && Object.keys(x).sort().join() === [...names].sort().join();
+function canonical(x, depth = 0) {
+    if (depth > 16)
+        throw new Error("intervention data exceeds depth");
+    if (x === null || typeof x === "string" || typeof x === "boolean" || (typeof x === "number" && Number.isFinite(x)))
+        return JSON.stringify(x);
+    if (!x || typeof x !== "object" || (!Array.isArray(x) && ![Object.prototype, null].includes(Object.getPrototypeOf(x))))
+        throw new Error("plain intervention JSON required");
+    const d = Object.getOwnPropertyDescriptors(x);
+    if (Array.isArray(x)) {
+        if (x.length > 4096 || Reflect.ownKeys(x).length !== x.length + 1)
+            throw new Error("bounded dense array required");
+        return `[${Array.from({ length: x.length }, (_, i) => { if (!d[i] || !Object.hasOwn(d[i], "value"))
+            throw new Error("plain array required"); return canonical(d[i].value, depth + 1); }).join(",")}]`;
+    }
+    return `{${Reflect.ownKeys(d).sort((a, b) => String(a) < String(b) ? -1 : 1).map(k => { if (typeof k !== "string" || !d[k].enumerable || !Object.hasOwn(d[k], "value"))
+        throw new Error("plain object required"); return `${JSON.stringify(k)}:${canonical(d[k].value, depth + 1)}`; }).join(",")}}`;
+}
+/** Plain, bounded JSON encoding for retained intervention inputs; not semantic validation. */
+export function interventionCanonicalJson(value) {
+    const bytes = canonical(value);
+    if (Buffer.byteLength(bytes) > 2 * 1024 * 1024)
+        throw new Error("intervention data exceeds byte bound");
+    return bytes;
+}
+const digest = (value) => createHash("sha256").update(interventionCanonicalJson(value)).digest("hex");
+function frozen(value) { if (value && typeof value === "object") {
+    Object.values(value).forEach(frozen);
+    Object.freeze(value);
+} return value; }
+const clone = (value) => JSON.parse(canonical(value));
+const axes = ["model", "effort", "skill", "prompt", "configuration"];
+export function freezeIntervention(input) {
+    const d = clone(input);
+    if (!closed(d, ["family", "investigationSha256", "resourceMetric", "axes", "common", "proposer", "judge", "cases", "arms"]) || d.family !== "intervention" || !SHA.test(d.investigationSha256)
+        || !["usd", "wall_ms", "tool_calls"].includes(d.resourceMetric)
+        || !Array.isArray(d.axes) || !d.axes.length || new Set(d.axes).size !== d.axes.length || d.axes.some(a => !axes.includes(a))
+        || !closed(d.common, ["mode", "scenarioSha256", "rubricSha256", "fixtureSha256", "heldoutSha256", "harnessSha256", "judgePolicySha256"])
+        || !["green", "force"].includes(d.common.mode) || Object.entries(d.common).some(([k, v]) => k !== "mode" && !SHA.test(v))
+        || !text(d.proposer) || !text(d.judge) || !Array.isArray(d.arms) || d.arms.length < 2 || d.arms.length > 8
+        || !Array.isArray(d.cases) || !d.cases.length || d.cases.length > 128)
+        throw new Error("invalid intervention manifest");
+    for (const arm of d.arms)
+        if (!closed(arm, ["id", "configuration"]) || !text(arm.id, 128) || !closed(arm.configuration, axes)
+            || !text(arm.configuration.model) || !text(arm.configuration.effort) || ["skill", "prompt", "configuration"].some(k => !SHA.test(arm.configuration[k])))
+            throw new Error("invalid intervention arm");
+    if (new Set(d.arms.map(a => a.id)).size !== d.arms.length || new Set(d.cases.map(c => c.id)).size !== d.cases.length)
+        throw new Error("duplicate intervention identity");
+    for (const c of d.cases)
+        if (!closed(c, ["id", "criteria", "reps", "threshold", "critical"]) || !text(c.id, 128)
+            || !Number.isSafeInteger(c.criteria) || c.criteria < 1 || c.criteria > 128 || !Number.isSafeInteger(c.reps) || c.reps < 1 || c.reps > 20
+            || !Number.isFinite(c.threshold) || c.threshold <= 0 || c.threshold > 1 || typeof c.critical !== "boolean"
+            || ((c.critical || c.id.startsWith("B")) && c.threshold !== 1))
+            throw new Error("invalid frozen case policy");
+    const changedAxes = axes.filter(axis => d.arms.some(a => a.configuration[axis] !== d.arms[0].configuration[axis]));
+    if (changedAxes.some(axis => !d.axes.includes(axis)))
+        throw new Error("undeclared intervention axis");
+    const body = { ...d, version: "intervention-comparison-v1", inputDigest: digest({ common: d.common, cases: d.cases }), changedAxes, deterministicSampling: false };
+    return frozen({ ...body, id: digest(body) });
+}
+export const interventionEvidenceDigest = (value) => digest(value);
+const assessments = new WeakSet();
+const assessmentArtifacts = new WeakMap();
+function manifestValid(m) {
+    const detached = clone(m);
+    const { version, id: _id, inputDigest: _inputs, changedAxes: _axes, deterministicSampling, ...draft } = detached;
+    if (version !== "intervention-comparison-v1" || deterministicSampling !== false || canonical(freezeIntervention(draft)) !== canonical(detached))
+        throw new Error("frozen intervention changed");
+}
+/** Pre-spend role gate: consumes independently resolved host facts, never guesses aliases or calls a provider. */
+export function assertInterventionRoles(manifest, qualification) {
+    manifestValid(manifest);
+    if (!qualification || !qualification.proposer || !qualification.judge || !qualification.subjects || qualification.manifestId !== manifest.id || qualification.proposer.requested !== manifest.proposer || qualification.judge.requested !== manifest.judge
+        || !text(qualification.proposer.canonical) || !text(qualification.judge.canonical))
+        throw new Error("independent role qualification required");
+    const reserved = new Set([qualification.proposer.canonical, qualification.judge.canonical]);
+    if (reserved.size !== 2 || manifest.arms.some(a => !Object.hasOwn(qualification.subjects, a.id) || qualification.subjects[a.id].requested !== a.configuration.model
+        || !text(qualification.subjects[a.id].canonical) || reserved.has(qualification.subjects[a.id].canonical)))
+        throw new Error("role identity conflict or unresolved role");
+}
+/** Inspects separately host-qualified evidence; does not obtain qualification or execute a model. */
+export function assessIntervention(manifest, evidence, qualification) {
+    assertInterventionRoles(manifest, qualification);
+    if (evidence.length > manifest.arms.length || new Set(evidence.map(e => e.armId)).size !== evidence.length || evidence.some(e => !manifest.arms.some(a => a.id === e.armId)))
+        throw new Error("unexpected intervention evidence identity");
+    const retained = new Map();
+    let retainedBytes = 0;
+    const arms = manifest.arms.map(arm => {
+        const e = evidence.find(e => e.armId === arm.id);
+        let admitted = false;
+        const result = (state) => ({ armId: arm.id, state, eligible: state === "MEASURED", artifactDigests: admitted ? [...e.artifactDigests] : [], cost: admitted ? e.cost : null, costUnit: admitted ? e.costUnit : "unknown" });
+        if (!e)
+            return result("MISSING");
+        if (qualification.evidenceDigests[arm.id] !== interventionEvidenceDigest(e) || !closed(e, ["armId", "inputDigest", "artifactDigests", "cells", "cost", "costUnit"])
+            || e.inputDigest !== manifest.inputDigest || !Array.isArray(e.artifactDigests) || e.artifactDigests.length > 4096 || e.artifactDigests.some(h => !SHA.test(h))
+            || !(e.cost === null || (Number.isFinite(e.cost) && e.cost >= 0)) || e.costUnit !== manifest.resourceMetric || !Array.isArray(e.cells)
+            || new Set(e.artifactDigests).size !== e.artifactDigests.length || e.cells.length !== manifest.cases.reduce((n, c) => n + c.reps, 0))
+            return result("ERROR");
+        admitted = true;
+        const cells = new Map();
+        let error = false, unmeasured = false, unresolved = false, missingOutput = false;
+        for (const c of e.cells) {
+            const spec = manifest.cases.find(s => s.id === c.caseId), id = `${c.caseId}:${c.repetition}`;
+            if (!closed(c, ["caseId", "repetition", "delivery", "objective", "criteria", "suspect", "artifactSha256"]) || !spec || !Number.isSafeInteger(c.repetition) || c.repetition < 0 || c.repetition >= spec.reps || cells.has(id)
+                || !["PASS", "NOT-MEASURED", "ERROR"].includes(c.delivery) || !["PASS", "FAIL", "ERROR", "NOT-MEASURED"].includes(c.objective) || !Array.isArray(c.criteria) || typeof c.suspect !== "boolean") {
+                error = true;
+                continue;
+            }
+            cells.set(id, c);
+            if (c.artifactSha256 !== null && (typeof c.artifactSha256 !== "string" || !SHA.test(c.artifactSha256) || !e.artifactDigests.includes(c.artifactSha256)))
+                error = true;
+            if (c.delivery === "PASS" && c.objective === "PASS" && c.artifactSha256 === null)
+                missingOutput = true;
+            if (c.delivery !== "PASS" || c.objective !== "PASS") {
+                if (c.criteria.length)
+                    error = true;
+                if (c.delivery === "NOT-MEASURED")
+                    unmeasured = true;
+                if (c.delivery === "ERROR" || c.objective === "ERROR" || (c.objective === "NOT-MEASURED" && c.delivery !== "NOT-MEASURED"))
+                    error = true;
+            }
+            else if (c.criteria.length !== spec.criteria || c.criteria.some(v => !["PASS", "FAIL", "UNKNOWN"].includes(v)))
+                error = true;
+            else if (c.suspect || c.criteria.includes("UNKNOWN"))
+                unresolved = true;
+        }
+        if (error)
+            return result("ERROR");
+        if (unmeasured)
+            return result("NOT-MEASURED");
+        if (unresolved)
+            return result("UNRESOLVED");
+        if (missingOutput)
+            return result("MISSING");
+        const passed = manifest.cases.every(spec => Array.from(cells.values()).filter(c => c.caseId === spec.id && c.objective === "PASS" && c.criteria.every(v => v === "PASS")).length / spec.reps >= spec.threshold);
+        if (!passed)
+            return result("FAILED");
+        if (!e.artifactDigests.length)
+            return result("MISSING");
+        for (const hash of e.artifactDigests) {
+            const bytes = qualification.artifacts?.get(hash);
+            if (bytes === undefined)
+                return result("MISSING");
+            if (!(bytes instanceof Uint8Array) || bytes.byteLength > 8 * 1024 * 1024)
+                return result("ERROR");
+            const stable = Buffer.from(bytes);
+            if (createHash("sha256").update(stable).digest("hex") !== hash)
+                return result("ERROR");
+            if (!retained.has(hash)) {
+                if (retainedBytes + bytes.byteLength > 64 * 1024 * 1024)
+                    return result("ERROR");
+                retained.set(hash, stable);
+                retainedBytes += stable.byteLength;
+            }
+        }
+        return result("MEASURED");
+    });
+    const eligible = arms.filter(a => a.eligible), knownCosts = eligible.length && eligible.every(a => a.cost !== null && a.costUnit === eligible[0].costUnit);
+    const cheapestEligible = knownCosts ? [...eligible].sort((a, b) => a.cost - b.cost || (a.armId < b.armId ? -1 : 1))[0].armId : null;
+    const result = frozen({ manifestId: manifest.id, complete: arms.every(a => a.state === "MEASURED" || a.state === "FAILED"), arms, cheapestEligible, routingDefault: null, adoptionAuthorized: false });
+    assessments.add(result);
+    assessmentArtifacts.set(result, retained);
+    return result;
+}
+/** Only this view omits identity/cost; arbitrary artifact content can still leak clues and must be reviewed. */
+export function createBlindComparison(manifest, assessment, fixtureOrPersistedSeed) {
+    manifestValid(manifest);
+    if (!assessments.has(assessment) || assessment.manifestId !== manifest.id || !assessment.complete)
+        throw new Error("complete recomputed intervention assessment required");
+    const seed = fixtureOrPersistedSeed ?? randomBytes(32).toString("hex");
+    if (!SHA.test(seed))
+        throw new Error("invalid private blinding seed");
+    const assessmentId = digest(assessment);
+    const eligible = assessment.arms.filter(a => a.eligible).sort((a, b) => {
+        const left = digest([seed, manifest.id, assessmentId, a.armId]), right = digest([seed, manifest.id, assessmentId, b.armId]);
+        return left < right ? -1 : left > right ? 1 : 0;
+    });
+    const mapping = new Map(eligible.map((a, i) => [`variant-${digest([seed, manifest.id, assessmentId, i]).slice(0, 16)}`, a.armId]));
+    if (mapping.size !== eligible.length)
+        throw new Error("opaque label collision");
+    const cards = [...mapping].map(([label, armId]) => ({ label, artifactDigests: assessment.arms.find(a => a.armId === armId).artifactDigests }));
+    let choice = null, revealed = false;
+    return Object.freeze({
+        view: () => frozen({ version: "blind-intervention-view-v1", cards, limitations: ["artifact-content-may-disclose-identity"] }),
+        readArtifact(label, hash) {
+            const armId = mapping.get(label), arm = assessment.arms.find(a => a.armId === armId);
+            if (!arm || !arm.artifactDigests.includes(hash))
+                throw new Error("artifact outside blind view");
+            const bytes = assessmentArtifacts.get(assessment)?.get(hash);
+            if (!bytes)
+                throw new Error("retained blind artifact missing");
+            return Buffer.from(bytes);
+        },
+        choose(input) {
+            const value = clone(input);
+            if (!closed(value, ["kind", "labels"]) || !["one", "tie", "none", "insufficient"].includes(value.kind) || !Array.isArray(value.labels)
+                || new Set(value.labels).size !== value.labels.length || value.labels.some(l => !mapping.has(l))
+                || (value.kind === "one" ? value.labels.length !== 1 : value.kind === "tie" ? value.labels.length < 2 : value.labels.length !== 0))
+                throw new Error("invalid blind quality choice");
+            value.labels.sort();
+            if (revealed && canonical(choice) !== canonical(value))
+                throw new Error("quality choice locked after reveal");
+            choice = frozen(value);
+            return choice;
+        },
+        reveal() {
+            if (!choice)
+                throw new Error("quality choice required before reveal");
+            revealed = true;
+            return frozen({ manifestId: manifest.id, choice, arms: [...mapping].map(([label, armId]) => ({ label, armId, configuration: manifest.arms.find(a => a.id === armId).configuration,
+                    cost: assessment.arms.find(a => a.armId === armId).cost, costUnit: assessment.arms.find(a => a.armId === armId).costUnit })), routingDefault: null });
+        },
+    });
+}
+//# sourceMappingURL=intervention.js.map

package/dist/investigation.d.ts

@@ -0,0 +1,94 @@
+/** Bounded operator envelope; duplicate keys and over-expanded/cyclic objects are refused before dispatch. */
+export declare function parseLearningRequest(text: string): unknown;
+export interface HypothesisProposal {
+    archiveSnapshot: string;
+    caseIds: string[];
+    population: string;
+    intervention: string;
+    alternatives: string[];
+    prediction: string;
+    downside: string;
+    disproof: string;
+    rollback: string;
+    limits: {
+        subjectCalls: number;
+        judgeCalls: number;
+        wallMs: number;
+    };
+    effectProfile: string | null;
+}
+export interface Hypothesis {
+    version: "factory-hypothesis-v1";
+    id: string;
+    proposal: HypothesisProposal;
+    status: "proposed";
+}
+export declare function buildHypothesis(input: HypothesisProposal): Hypothesis;
+export interface InvestigationAuthority {
+    id: string;
+    investigations: readonly string[];
+    promotions: readonly string[];
+}
+/** Independent host declarations, not approval fields on a proposal and never adoption/activation authority. */
+export declare function authorizeInvestigation(h: Hypothesis, authority: InvestigationAuthority | null): {
+    version: string;
+    hypothesisId: string;
+    authorityId: string;
+    scope: "investigation-only";
+};
+export interface InvestigationScenarioPreview {
+    version: "investigation-scenario-preview-v1";
+    hypothesisId: string;
+    specPath: string;
+    baseSha256: string;
+    afterSha256: string;
+    scenario: Record<string, unknown>;
+    block: string;
+    digest: string;
+}
+export declare function previewInvestigationScenario(h: Hypothesis, specPath: string, scenario: Record<string, unknown>): InvestigationScenarioPreview;
+/** Exact preview consent includes destination, existing spec and complete scenario bytes. No automatic sanitization claim. */
+export declare function applyInvestigationScenario(h: Hypothesis, preview: InvestigationScenarioPreview, authority: InvestigationAuthority | null): {
+    scenarioId: string;
+    replayed: boolean;
+    sha256: string;
+    scope: "scenario-only";
+};
+export interface FrozenInvestigationInputs {
+    specSha256: string;
+    rubricSha256: string;
+    judgePolicySha256: string;
+    heldoutSha256: string;
+    configurationSha256: string;
+}
+export declare function freezeInvestigation(h: Hypothesis, inputs: FrozenInvestigationInputs, authority: InvestigationAuthority | null): {
+    digest: string;
+    version: string;
+    hypothesisId: string;
+    authorityId: string;
+    inputs: FrozenInvestigationInputs;
+    executionReady: false;
+};
+export declare function assertFrozenInvestigation(frozen: ReturnType<typeof freezeInvestigation>, current: FrozenInvestigationInputs): void;
+export interface WeeklyInvestigationInput {
+    week: string;
+    population: string;
+    policyDigest: string;
+    archiveSnapshot: string;
+    eligibleCaseIds: string[];
+    maxCases: number;
+}
+export interface WeeklyInvestigationSelection {
+    version: "weekly-investigation-selection-v1";
+    id: string;
+    key: string;
+    inputDigest: string;
+    week: string;
+    population: string;
+    policyDigest: string;
+    archiveSnapshot: string;
+    selectedCaseIds: string[];
+    sampling: "exploratory-sha256-order-v1";
+}
+/** The host persists these immutable selections; this function neither schedules a process nor spends tokens. */
+export declare function selectWeeklyInvestigation(history: readonly WeeklyInvestigationSelection[], input: WeeklyInvestigationInput): WeeklyInvestigationSelection;

package/dist/investigation.js

@@ -0,0 +1,148 @@
+import { createHash } from "node:crypto";
+import yaml from "js-yaml";
+import { readFileSync, realpathSync } from "node:fs";
+import { appendScenario, renderScenarioBlock, specSha256 } from "./spec-write.js";
+import { parseSpec } from "./spec.js";
+const SHA = /^[a-f0-9]{64}$/;
+const keys = (x, expected) => Object.keys(x).sort().join() === [...expected].sort().join();
+const text = (x, max = 4000) => typeof x === "string" && x.length > 0 && x.length <= max;
+function json(input) {
+    let nodes = 0;
+    const visit = (x, depth) => {
+        if (++nodes > 4096 || depth > 16)
+            throw new Error("investigation JSON exceeds bounds");
+        if (x === null || typeof x === "boolean" || typeof x === "string" || (typeof x === "number" && Number.isFinite(x)))
+            return x;
+        if (!x || typeof x !== "object" || (!Array.isArray(x) && ![Object.prototype, null].includes(Object.getPrototypeOf(x))))
+            throw new Error("plain investigation JSON required");
+        const descriptors = Object.getOwnPropertyDescriptors(x);
+        if (Array.isArray(x)) {
+            if (Object.getPrototypeOf(x) !== Array.prototype || x.length > 256 || Reflect.ownKeys(x).length !== x.length + 1)
+                throw new Error("bounded dense JSON array required");
+            return Array.from({ length: x.length }, (_, i) => { const d = descriptors[String(i)]; if (!d || !('value' in d))
+                throw new Error("plain JSON array required"); return visit(d.value, depth + 1); });
+        }
+        const out = {};
+        for (const key of Reflect.ownKeys(descriptors).sort((a, b) => String(a) < String(b) ? -1 : 1)) {
+            const d = descriptors[key];
+            if (typeof key !== "string" || !d.enumerable || !('value' in d))
+                throw new Error("plain JSON properties required");
+            Object.defineProperty(out, key, { value: visit(d.value, depth + 1), enumerable: true });
+        }
+        return out;
+    };
+    const result = visit(input, 0);
+    if (Buffer.byteLength(JSON.stringify(result)) > 65536)
+        throw new Error("investigation JSON exceeds byte bound");
+    return result;
+}
+/** Bounded operator envelope; duplicate keys and over-expanded/cyclic objects are refused before dispatch. */
+export function parseLearningRequest(text) {
+    if (typeof text !== "string" || Buffer.byteLength(text) > 65536)
+        throw new Error("learning request exceeds bound");
+    let value;
+    try {
+        value = yaml.load(text, { schema: yaml.JSON_SCHEMA, json: false });
+    }
+    catch {
+        throw new Error("invalid learning request");
+    }
+    return json(value);
+}
+const digest = (x) => createHash("sha256").update(JSON.stringify(json(x))).digest("hex");
+function freeze(value) { if (value && typeof value === "object") {
+    Object.values(value).forEach(freeze);
+    Object.freeze(value);
+} return value; }
+export function buildHypothesis(input) {
+    const p = json(input);
+    if (!keys(p, ["archiveSnapshot", "caseIds", "population", "intervention", "alternatives", "prediction", "downside", "disproof", "rollback", "limits", "effectProfile"])
+        || !SHA.test(p.archiveSnapshot) || !Array.isArray(p.caseIds) || !p.caseIds.length || p.caseIds.some(id => typeof id !== "string" || !SHA.test(id))
+        || ![p.population, p.intervention, p.prediction, p.downside, p.disproof, p.rollback].every(s => text(s))
+        || !Array.isArray(p.alternatives) || !p.alternatives.length || p.alternatives.some(a => !text(a))
+        || !p.limits || !keys(p.limits, ["subjectCalls", "judgeCalls", "wallMs"])
+        || !Object.values(p.limits).every(n => Number.isSafeInteger(n) && n >= 0 && n <= 1000000000)
+        || !(p.effectProfile === null || text(p.effectProfile, 512)))
+        throw new Error("invalid bounded hypothesis");
+    return freeze({ version: "factory-hypothesis-v1", id: digest({ version: "factory-hypothesis-v1", proposal: p }), proposal: p, status: "proposed" });
+}
+function authorize(h, authority) {
+    const value = json(h);
+    if (!keys(value, ["version", "id", "proposal", "status"]) || value.version !== "factory-hypothesis-v1" || value.status !== "proposed" || buildHypothesis(value.proposal).id !== value.id)
+        throw new Error("hypothesis identity changed");
+    if (!authority || !text(authority.id, 512) || !Array.isArray(authority.investigations) || !Array.isArray(authority.promotions)
+        || authority.investigations.length > 256 || authority.promotions.length > 256
+        || [...authority.investigations, ...authority.promotions].some(id => typeof id !== "string" || !SHA.test(id))
+        || !authority.investigations.includes(value.id))
+        throw new Error("independent investigation authority required");
+    return authority;
+}
+/** Independent host declarations, not approval fields on a proposal and never adoption/activation authority. */
+export function authorizeInvestigation(h, authority) {
+    const selected = authorize(h, authority);
+    return freeze({ version: "investigation-approval-v1", hypothesisId: h.id, authorityId: selected.id, scope: "investigation-only" });
+}
+export function previewInvestigationScenario(h, specPath, scenario) {
+    if (buildHypothesis(h.proposal).id !== h.id)
+        throw new Error("hypothesis identity changed");
+    const path = realpathSync(specPath), current = readFileSync(path, "utf8"), safe = json(scenario), block = renderScenarioBlock(safe);
+    parseSpec(current + block, path);
+    const value = { version: "investigation-scenario-preview-v1", hypothesisId: h.id, specPath: path, baseSha256: specSha256(current), afterSha256: specSha256(current + block), scenario: safe, block };
+    return freeze({ ...value, digest: digest(value) });
+}
+/** Exact preview consent includes destination, existing spec and complete scenario bytes. No automatic sanitization claim. */
+export function applyInvestigationScenario(h, preview, authority) {
+    const selected = authorize(h, authority), copy = json(preview), { digest: claimed, ...body } = copy;
+    if (!keys(copy, ["version", "hypothesisId", "specPath", "baseSha256", "afterSha256", "scenario", "block", "digest"])
+        || body.version !== "investigation-scenario-preview-v1" || body.hypothesisId !== h.id || digest(body) !== claimed
+        || renderScenarioBlock(body.scenario) !== body.block || !selected.promotions.includes(claimed))
+        throw new Error("exact privacy/promotion preview authority required");
+    if (realpathSync(body.specPath) !== body.specPath)
+        throw new Error("promotion destination changed");
+    const current = readFileSync(body.specPath, "utf8");
+    if (specSha256(current) === body.afterSha256)
+        return { scenarioId: String(body.scenario.id), replayed: true, sha256: body.afterSha256, scope: "scenario-only" };
+    const result = appendScenario({ specPath: body.specPath, scenario: body.scenario, baseSha256: body.baseSha256 });
+    return { scenarioId: result.id, replayed: false, sha256: result.sha256, scope: "scenario-only" };
+}
+function frozenInputs(input) {
+    const value = json(input);
+    if (!keys(value, ["specSha256", "rubricSha256", "judgePolicySha256", "heldoutSha256", "configurationSha256"]) || Object.values(value).some(v => typeof v !== "string" || !SHA.test(v)))
+        throw new Error("invalid frozen evaluation inputs");
+    return value;
+}
+export function freezeInvestigation(h, inputs, authority) {
+    const approved = authorizeInvestigation(h, authority), value = { version: "frozen-investigation-v1", hypothesisId: h.id, authorityId: approved.authorityId, inputs: frozenInputs(inputs), executionReady: false };
+    return freeze({ ...value, digest: digest(value) });
+}
+export function assertFrozenInvestigation(frozen, current) {
+    const { digest: recorded, ...value } = json(frozen);
+    if (!keys(value, ["version", "hypothesisId", "authorityId", "inputs", "executionReady"]) || !SHA.test(value.hypothesisId) || !text(value.authorityId, 512)
+        || value.version !== "frozen-investigation-v1" || value.executionReady !== false || digest(value) !== recorded || digest(value.inputs) !== digest(frozenInputs(current)))
+        throw new Error("frozen investigation changed or invalid");
+}
+/** The host persists these immutable selections; this function neither schedules a process nor spends tokens. */
+export function selectWeeklyInvestigation(history, input) {
+    const value = json(input);
+    if (!keys(value, ["week", "population", "policyDigest", "archiveSnapshot", "eligibleCaseIds", "maxCases"])
+        || !/^\d{4}-W(?:0[1-9]|[1-4]\d|5[0-3])$/.test(value.week) || !text(value.population, 512)
+        || !SHA.test(value.policyDigest) || !SHA.test(value.archiveSnapshot) || !Array.isArray(value.eligibleCaseIds)
+        || !value.eligibleCaseIds.length || value.eligibleCaseIds.some(id => typeof id !== "string" || !SHA.test(id))
+        || !Number.isSafeInteger(value.maxCases) || value.maxCases < 1 || value.maxCases > 32 || history.length > 4096)
+        throw new Error("invalid weekly investigation selection");
+    const eligible = [...new Set(value.eligibleCaseIds)].sort();
+    const key = digest({ week: value.week, population: value.population, policyDigest: value.policyDigest });
+    const inputDigest = digest({ ...value, eligibleCaseIds: eligible });
+    const selectedCaseIds = eligible.sort((a, b) => { const ka = digest([key, value.archiveSnapshot, a]), kb = digest([key, value.archiveSnapshot, b]); return ka < kb ? -1 : ka > kb ? 1 : 0; }).slice(0, value.maxCases);
+    const body = { version: "weekly-investigation-selection-v1", key, inputDigest, week: value.week, population: value.population,
+        policyDigest: value.policyDigest, archiveSnapshot: value.archiveSnapshot, selectedCaseIds, sampling: "exploratory-sha256-order-v1" };
+    const result = freeze({ ...body, id: digest(body) });
+    const previous = history.filter(record => record.key === key);
+    for (const record of previous) {
+        const { id, ...old } = json(record);
+        if (digest(old) !== id || id !== result.id)
+            throw new Error("weekly investigation already frozen or history invalid");
+    }
+    return previous.length ? freeze(json(previous[0])) : result;
+}
+//# sourceMappingURL=investigation.js.map

package/dist/qualification-process.js

@@ -154,10 +154,12 @@ function qualificationLinuxProcessGroupMembers(processGroupId) {
     if (process.platform !== "linux")
         return [];
     const members = [];
-    for (const entry of readdirSync("/proc", { withFileTypes: true })) {
-        if (!entry.isDirectory() || !/^\d+$/.test(entry.name))
+    // Dirent construction may lstat an unrelated disappearing PID before our
+    // per-entry guard runs. Names need no metadata; validate each stat below.
+    for (const name of readdirSync("/proc")) {
+        if (!/^\d+$/.test(name))
             continue;
-        const pid = Number(entry.name);
+        const pid = Number(name);
         try {
             const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
             const close = stat.lastIndexOf(")");

package/dist/trajectory-gates.d.ts

@@ -135,15 +135,3 @@ export declare function deserializeTrajectoryEvents(text: string): TrajectoryEve
 /** Evaluate a closed, declarative assertion set over saved normalized events. */
 export declare function evaluateTrajectoryGates(assert: TrajectoryAssert, input: TrajectoryEventV1[]): TrajectoryGateResult;
 export declare function parseTrajectoryAssert(raw: unknown, ctx: string): TrajectoryAssert;
-export interface MutationSelfTestCase {
-    id: string;
-    detected: boolean;
-    status: TrajectoryAssertionStatus;
-    detail: string;
-}
-export interface MutationSelfTestReport {
-    baseline: "PASS";
-    cases: MutationSelfTestCase[];
-}
-/** Fast, deterministic proof that every trajectory assertion class can turn red. */
-export declare function runTrajectoryMutationSelfTest(): MutationSelfTestReport;

package/dist/trajectory-gates.js

@@ -429,42 +429,6 @@ function parseCount(raw, ctx) {
         throw new Error(`${ctx}.min exceeds max`);
     return out;
 }
-/** Fast, deterministic proof that every trajectory assertion class can turn red. */
-export function runTrajectoryMutationSelfTest() {
-    const e = (seq, type, extra = {}) => ({ event_version: TRAJECTORY_EVENT_VERSION, seq, type, source: "mutation-self-test", at: `2026-01-01T00:00:${String(seq).padStart(2, "0")}Z`, ...extra });
-    const h = "a".repeat(40), t = "b".repeat(40), p = "1".repeat(64);
-    const cases = [
-        { id: "remove-required-event", assertion: { version: "1.0", require: [{ event: "risk_classified" }] }, good: [e(1, "risk_classified")], mutate: () => [e(1, "unrelated")] },
-        { id: "add-forbidden-tool-side-effect-approval", assertion: { version: "1.0", forbid: [{ event: "tool_called", where: { tool: { equals: "rm" } } }, { event: "side_effect_approved" }] }, good: [e(1, "tool_called", { tool: "read" })], mutate: (events) => [...events, e(2, "side_effect_approved", { attributes: { action: "migration" } })] },
-        { id: "reorder-transition", assertion: { version: "1.0", ordered: [[{ event: "phase_started" }, { event: "phase_completed" }]] }, good: [e(1, "phase_started"), e(2, "phase_completed")], mutate: () => [e(2, "phase_started"), e(1, "phase_completed")] },
-        { id: "substitute-workspace-id", assertion: { version: "1.0", correlate: [{ left: { event: "code_changed" }, right: { event: "evidence_recorded" }, same: ["workspace_id"] }] }, good: [e(1, "code_changed", { workspace_id: "ws-1" }), e(2, "evidence_recorded", { workspace_id: "ws-1" })], mutate: (events) => events.map((x) => x.type === "evidence_recorded" ? { ...x, workspace_id: "ws-2" } : x) },
-        { id: "concurrent-writer", assertion: { version: "1.0", forbid: [{ event: "writer_lease_conflict" }] }, good: [e(1, "writer_lease_acquired", { workspace_id: "ws-1" })], mutate: (events) => [...events, e(2, "writer_lease_conflict", { workspace_id: "ws-1" })] },
-        { id: "approval-expired-or-mismatched", assertion: { version: "1.0", approvals: [{ grant: { event: "approval_granted" }, use: { event: "approval_used" }, same: ["approval.id", "approval.capability"], unexpired: true }] }, good: [e(1, "approval_granted", { approval: { id: "a1", capability: "push", expires_at: "2026-01-01T01:00:00Z" } }), e(2, "approval_used", { approval: { id: "a1", capability: "push", used_at: "2026-01-01T00:01:00Z" } })], mutate: (events) => events.map((x) => x.type === "approval_used" ? { ...x, approval: { ...x.approval, used_at: "2026-01-01T02:00:00Z" } } : x) },
-        { id: "evidence-before-change", assertion: { version: "1.0", freshness: [{ subject: { event: "evidence_recorded" }, after: [{ event: "code_changed" }] }] }, good: [e(1, "code_changed"), e(2, "evidence_recorded")], mutate: () => [e(2, "code_changed"), e(1, "evidence_recorded")] },
-        { id: "evidence-before-authority", assertion: { version: "1.0", freshness: [{ subject: { event: "evidence_recorded" }, after: [{ event: "plan_recorded" }] }] }, good: [e(1, "plan_recorded", { digests: { plan: p } }), e(2, "evidence_recorded")], mutate: () => [e(2, "plan_recorded", { digests: { plan: p } }), e(1, "evidence_recorded")] },
-        { id: "evidence-before-build-completion", assertion: { version: "1.0", freshness: [{ subject: { event: "evidence_recorded" }, after: [{ event: "phase_completed", where: { phase: { equals: "build" } } }] }] }, good: [e(1, "phase_completed", { phase: "build" }), e(2, "evidence_recorded")], mutate: () => [e(2, "phase_completed", { phase: "build" }), e(1, "evidence_recorded")] },
-        { id: "head-equal-tree-different", assertion: { version: "1.0", correlate: [{ left: { event: "code_changed" }, right: { event: "evidence_recorded" }, same: ["digests.head", "digests.tree"] }] }, good: [e(1, "code_changed", { digests: { head: h, tree: t } }), e(2, "evidence_recorded", { digests: { head: h, tree: t } })], mutate: (events) => events.map((x) => x.type === "evidence_recorded" ? { ...x, digests: { head: h, tree: "c".repeat(40) } } : x) },
-        { id: "command-receipt-nonzero", assertion: { version: "1.0", require: [{ event: "evidence_recorded", where: { exit_code: { equals: 0 } } }] }, good: [e(1, "evidence_recorded", { exit_code: 0 })], mutate: (events) => events.map((x) => ({ ...x, exit_code: 1 })) },
-        { id: "remove-requirement-coverage", assertion: { version: "1.0", coverage: [{ requirements: ["AUTH-7"], events: { event: "evidence_recorded" } }] }, good: [e(1, "evidence_recorded", { requirements: ["AUTH-7"] })], mutate: (events) => events.map((x) => ({ ...x, requirements: [] })) },
-        { id: "mutate-superseded-task", assertion: { version: "1.0", forbid_after: [{ anchor: { event: "task_packet_superseded" }, forbidden: [{ event: "code_changed" }, { event: "repair_started" }], same: ["task_id"] }] }, good: [e(1, "task_packet_superseded", { task_id: "old" }), e(2, "code_changed", { task_id: "new" })], mutate: (events) => events.map((x) => x.type === "code_changed" ? { ...x, task_id: "old" } : x) },
-        { id: "reuse-context-id", assertion: { version: "1.0", unique: [{ events: { event: "review_recorded" }, fields: ["context_id"] }] }, good: [e(1, "review_recorded", { context_id: "c1" }), e(2, "review_recorded", { context_id: "c2" })], mutate: (events) => events.map((x) => x.seq === 2 ? { ...x, context_id: "c1" } : x) },
-        { id: "mismatch-finalization-identity", assertion: { version: "1.0", correlate: [{ left: { event: "gate_evaluated", where: { "attributes.gate": { equals: "finalize" } } }, right: { event: "finalization_completed" }, same: ["digests.head", "digests.tree"], order: "before" }] }, good: [e(1, "gate_evaluated", { digests: { head: h, tree: t }, attributes: { gate: "finalize", code: "OK" } }), e(2, "finalization_completed", { digests: { head: h, tree: t } })], mutate: (events) => events.map((x) => x.type === "finalization_completed" ? { ...x, digests: { head: h, tree: "d".repeat(40) } } : x) },
-        { id: "v3-blocked-critical-code", assertion: { version: "1.0", require: [{ event: "gate_evaluated", where: { "attributes.code": { equals: "BLOCKED_CRITICAL_ASSURANCE" } } }] }, good: [e(1, "gate_evaluated", { attributes: { gate: "finalize", code: "BLOCKED_CRITICAL_ASSURANCE", missing_count: 2 } })], mutate: (events) => events.map((x) => ({ ...x, attributes: { ...x.attributes, code: "OK" } })) },
-        { id: "v3-stale-gate-must-block", assertion: { version: "1.0", require: [{ event: "gate_evaluated", where: { "attributes.code": { matches: "^BLOCKED_" } } }] }, good: [e(1, "gate_evaluated", { attributes: { gate: "finalize", code: "BLOCKED_ASSURANCE" } })], mutate: (events) => events.map((x) => ({ ...x, attributes: { ...x.attributes, code: "OK" } })) },
-        { id: "v3-finalize-gate-must-be-ok", assertion: { version: "1.0", require: [{ event: "gate_evaluated", where: { "attributes.gate": { equals: "finalize" }, "attributes.code": { equals: "OK" } } }] }, good: [e(1, "gate_evaluated", { attributes: { gate: "finalize", code: "OK" } })], mutate: (events) => events.map((x) => ({ ...x, attributes: { ...x.attributes, code: "BLOCKED_ASSURANCE" } })) },
-        { id: "v3-discard-requires-explicit-request", assertion: { version: "1.0", forbid: [{ event: "finish_selected", where: { "attributes.choice": { equals: "discard" }, "attributes.explicit_request": { equals: false } } }] }, good: [e(1, "finish_selected", { attributes: { choice: "discard", explicit_request: true } })], mutate: (events) => events.map((x) => ({ ...x, attributes: { ...x.attributes, explicit_request: false } })) },
-        { id: "v3-side-effect-approval-and-gate", assertion: { version: "1.0", ordered: [[{ event: "side_effect_approved", where: { "attributes.action": { equals: "migration" } } }, { event: "gate_evaluated", where: { "attributes.gate": { equals: "side-effect" }, "attributes.code": { equals: "OK" } } }]] }, good: [e(1, "side_effect_approved", { attributes: { action: "migration" } }), e(2, "gate_evaluated", { attributes: { gate: "side-effect", code: "OK" } })], mutate: (events) => events.map((x) => x.type === "gate_evaluated" ? { ...x, attributes: { ...x.attributes, code: "BLOCKED_ASSURANCE" } } : x) },
-        { id: "v3-governed-spawn-started", assertion: { version: "1.0", require: [{ event: "child_started", where: { source: { equals: "pi-daddy-v3" }, "attributes.state": { equals: "starting" } } }] }, good: [e(1, "child_started", { source: "pi-daddy-v3", attributes: { state: "starting" } })], mutate: (events) => events.map((x) => ({ ...x, attributes: { ...x.attributes, state: "failed" } })) },
-    ];
-    const results = cases.map((testCase) => {
-        const baseline = evaluateTrajectoryGates(testCase.assertion, testCase.good);
-        if (baseline.status !== "PASS")
-            throw new Error(`mutation self-test baseline ${testCase.id} is ${baseline.status}`);
-        const mutated = evaluateTrajectoryGates(testCase.assertion, testCase.mutate(structuredClone(testCase.good)));
-        return { id: testCase.id, detected: mutated.status !== "PASS", status: mutated.status, detail: mutated.assertions.find((result) => result.status !== "PASS")?.detail ?? "mutation was not detected" };
-    });
-    return { baseline: "PASS", cases: results };
-}
 // ---------------------------------------------------------------------------
 // Internals
 // ---------------------------------------------------------------------------

package/dist/trusted-host-supervision.d.ts

@@ -0,0 +1,25 @@
+import type { ChildProcess } from 'node:child_process';
+import { type QualificationProcessIdentity } from './qualification-process.js';
+export interface TrustedHostSupervisionLimits {
+    wallMs: number;
+    settlementMs: number;
+    maxOutputBytes: number;
+    signal: AbortSignal;
+}
+export interface TrustedHostProcessObservation {
+    outcome: 'completed' | 'failed' | 'aborted' | 'timed-out' | 'output-limit' | 'unknown';
+    identity: QualificationProcessIdentity;
+    exitCode: number | null;
+    signal: NodeJS.Signals | null;
+    stdoutBytes: number;
+    stderrBytes: number;
+    truncated: boolean;
+    cleanupAttempted: boolean;
+    acceptance: 'not-assessed';
+}
+/** Observe an ALREADY admitted, caller-owned detached Linux child, after its spawn event.
+ * No spawn/authorization/accounting/retry is performed here. The parent event loop must
+ * remain responsive. Occurrence-safe same-group cleanup is not hostile-code containment,
+ * survivor/crash recovery, hard aggregate RAM/CPU, or proof of remote provider termination.
+ * Bytes are discarded, not retained or hashed; the existing worker journal owns artifacts. */
+export declare function superviseTrustedHost(child: ChildProcess, limits: TrustedHostSupervisionLimits): Promise<TrustedHostProcessObservation>;