@davesheffer/hunch 1.7.0 → 1.8.0

package/dist/constitution/g3Conformance.js

@@ -0,0 +1,132 @@
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { canonicalHash } from "./canonical.js";
+import { compileAdapterConformanceReceipt } from "./g3.js";
+import { NODE_TEST_REPORTER_SOURCE, exactNodeTestPattern, nodeTestIsolationFlag, nodeTestReporterEvents } from "./nodeTestEvidence.js";
+export const G3_CONFORMANCE_CLIENTS = ["ci", "cli", "mcp"];
+export const G3_CONFORMANCE_TEST = {
+    file: "test/behavior-workspace.test.ts",
+    name: "CLI, MCP, and check share one non-blocking working-snapshot receipt without public leakage",
+};
+/** The certifiable client profiles. Each maps a HUMAN-SELECTED client set to the
+ *  ONE executable fixture that exercises every named surface end-to-end and
+ *  asserts receipt equality + zero private leaks. The vscode profile executes the
+ *  extension's real spawn seam (vscode-extension/src/spawnCore.ts) against an
+ *  npm-style shim — naming a client never certifies it; only its fixture does. */
+export const G3_CONFORMANCE_PROFILES = [
+    { clients: G3_CONFORMANCE_CLIENTS, test: G3_CONFORMANCE_TEST },
+    {
+        clients: ["ci", "cli", "mcp", "vscode"],
+        test: {
+            file: "test/behavior-workspace.test.ts",
+            name: "CLI, MCP, check, and the VS Code seam share one non-blocking working-snapshot receipt without public leakage",
+        },
+    },
+];
+export function g3ConformanceSourceHash(root) {
+    return canonicalHash(readFileSync(join(root, G3_CONFORMANCE_TEST.file), "utf8"));
+}
+function sameClients(left, right) {
+    return canonicalHash([...left].sort()) === canonicalHash([...right].sort());
+}
+/** Execute the real end-to-end fixture matching the plan's human-selected client
+ * profile. Unsupported client sets return an error receipt rather than being
+ * silently treated as equivalent to a certified profile. */
+export function executeG3AdapterConformance(root, plan, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 180_000;
+    if (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 300_000)
+        throw new Error("G3 conformance timeout must be a positive integer no greater than 300000");
+    const sourceHash = g3ConformanceSourceHash(root);
+    const isolationFlag = nodeTestIsolationFlag();
+    const profile = G3_CONFORMANCE_PROFILES.find((candidate) => sameClients(plan.clients, candidate.clients));
+    if (!profile) {
+        return compileAdapterConformanceReceipt({
+            plan_id: plan.id,
+            clients: plan.clients,
+            test: { ...G3_CONFORMANCE_TEST, source_hash: sourceHash },
+            runner: { name: "node-test-tsx", isolation_flag: isolationFlag },
+            result: "error",
+            exit_code: null,
+            selected_event: null,
+            verdict_agreement: null,
+            confirmed_private_leaks: null,
+            error_code: "unsupported-client-profile",
+            log_hash: canonicalHash({ supported: G3_CONFORMANCE_PROFILES.map((candidate) => candidate.clients), selected: plan.clients }),
+            supersedes: opts.supersedes ?? null,
+        }, { now: opts.now });
+    }
+    const selectedTest = profile.test;
+    const session = mkdtempSync(join(tmpdir(), "hunch-g3-conformance-"));
+    const reporter = join(session, "reporter.mjs");
+    writeFileSync(reporter, NODE_TEST_REPORTER_SOURCE);
+    const tsx = join(root, "node_modules/tsx/dist/cli.mjs");
+    const env = {};
+    for (const key of ["PATH", "SystemRoot", "WINDIR", "TMPDIR", "TMP", "TEMP"]) {
+        if (process.env[key])
+            env[key] = process.env[key];
+    }
+    Object.assign(env, {
+        HOME: session,
+        HUNCH_PRIVATE_DIR: "",
+        HUNCH_SYNTH_PROVIDER: "deterministic",
+        CI: "1",
+        NO_COLOR: "1",
+        FORCE_COLOR: "0",
+    });
+    const run = spawnSync(process.execPath, [
+        tsx,
+        "--test",
+        isolationFlag,
+        `--test-name-pattern=${exactNodeTestPattern(selectedTest.name)}`,
+        `--test-reporter=${pathToFileURL(reporter).href}`,
+        "--test-reporter-destination=stdout",
+        selectedTest.file,
+    ], {
+        cwd: root,
+        env,
+        encoding: "utf8",
+        timeout: timeoutMs,
+        maxBuffer: 20 * 1024 * 1024,
+        stdio: ["ignore", "pipe", "pipe"],
+        shell: false,
+    });
+    rmSync(session, { recursive: true, force: true });
+    const stdout = run.stdout ?? "";
+    const stderr = run.stderr ?? "";
+    const events = nodeTestReporterEvents(stdout).filter((event) => event.name === selectedTest.name && !event.skip && !event.todo);
+    const selectedEvent = events.length === 1 ? (events[0].type === "test:pass" ? "passed" : "failed") : null;
+    let result = "error";
+    let errorCode;
+    if (run.error)
+        errorCode = run.error.code === "ETIMEDOUT" ? "timeout" : "runner-failed";
+    else if (run.signal)
+        errorCode = "runner-signaled";
+    else if (events.length === 0)
+        errorCode = "selected-test-not-executed";
+    else if (events.length > 1)
+        errorCode = "selected-test-ambiguous";
+    else if (selectedEvent === "passed" && run.status === 0)
+        result = "passed";
+    else if (selectedEvent === "failed" && run.status !== 0)
+        result = "failed";
+    else
+        errorCode = "runner-outcome-inconsistent";
+    return compileAdapterConformanceReceipt({
+        plan_id: plan.id,
+        clients: plan.clients,
+        test: { ...selectedTest, source_hash: sourceHash },
+        runner: { name: "node-test-tsx", isolation_flag: isolationFlag },
+        result,
+        exit_code: run.status ?? null,
+        selected_event: selectedEvent,
+        verdict_agreement: result === "passed" ? 1 : null,
+        confirmed_private_leaks: result === "passed" ? 0 : null,
+        ...(errorCode ? { error_code: errorCode } : {}),
+        log_hash: canonicalHash({ stdout, stderr }),
+        supersedes: opts.supersedes ?? null,
+    }, { now: opts.now });
+}
+//# sourceMappingURL=g3Conformance.js.map

package/dist/constitution/lifecycle.js

@@ -0,0 +1,224 @@
+import { assertCompositionBinding, exceptionScopeIsNarrower, oppositeExceptionAssertions, policyProofHash } from "./composition.js";
+import { assessHistoryDispositions } from "./disposition.js";
+import { evaluatorForPolicy, mutationEngineForPolicy } from "./policyRuntime.js";
+import { executableBehaviorAttestationError } from "./behaviorAttestationBinding.js";
+function isHumanActor(actor) {
+    return /^(human|github|git):[^\s]+$/i.test(actor);
+}
+export function blockingEvidenceError(proof, dispositions = []) {
+    if (proof.mutation_receipts.some((receipt) => receipt.required && !receipt.passed)) {
+        return "blocking proof has a failed required mutation receipt";
+    }
+    if (proof.mutation_controls.failed > 0) {
+        return "blocking proof has failed required mutation controls";
+    }
+    if (proof.known_bad.total > 0 && proof.known_bad.violated !== proof.known_bad.total) {
+        return "blocking proof did not catch every declared known-bad fixture";
+    }
+    if (proof.known_good.total > 0 && proof.known_good.satisfied !== proof.known_good.total) {
+        return "blocking proof did not satisfy every declared known-good fixture";
+    }
+    if (proof.accepted_history.error || proof.accepted_history.unknown) {
+        return "blocking proof has unresolved accepted-history unknown/error results";
+    }
+    return assessHistoryDispositions(proof, dispositions).blocking_error;
+}
+const proofRank = { P0: 0, P1: 1, P2: 2, P3: 3, P4: 4, P5: 5 };
+/** Rechecked on every blocking evaluation; a hand-edited lifecycle flag without
+ * a current P3 proof is a configuration error, never authority. */
+export function blockingProofError(policy, proof, dispositions = [], composition = [], currentBehaviorAttestations = []) {
+    if (policy.state !== "active_blocking")
+        return null;
+    if (policy.authority?.kind !== "human")
+        return "active blocking policy has no human authority event";
+    const behaviorAttestationError = executableBehaviorAttestationError(policy, currentBehaviorAttestations);
+    if (behaviorAttestationError)
+        return behaviorAttestationError;
+    if (!policy.proof || !proof)
+        return "active blocking policy has no readable proof artifact";
+    if (proofRank[proof.proof_class] < proofRank.P3)
+        return `blocking proof is ${proof.proof_class}; P3+ is required`;
+    const evaluator = evaluatorForPolicy(policy);
+    const mutationEngine = mutationEngineForPolicy(policy);
+    if (proof.evaluator.name !== evaluator.name || proof.evaluator.version !== evaluator.version)
+        return "blocking proof evaluator version is stale";
+    if (proof.mutation_engine?.name !== mutationEngine.name || proof.mutation_engine.version !== mutationEngine.version)
+        return "blocking proof mutation engine version is stale";
+    try {
+        assertCompositionBinding(policy, composition, proof.composition);
+    }
+    catch {
+        return "blocking proof does not match the current parent/exception composition";
+    }
+    if (proof.policy_hash !== policyProofHash(policy, composition))
+        return "blocking proof does not match current policy semantics";
+    if (proof.current.satisfied !== 1 || proof.current.error || proof.current.unknown)
+        return "blocking proof has no clean satisfied baseline";
+    const replayError = blockingEvidenceError(proof, dispositions);
+    if (replayError)
+        return replayError;
+    return null;
+}
+function requireHuman(actor) {
+    if (!isHumanActor(actor))
+        throw new Error("policy authority requires an explicit human actor (human:, github:, or git:); machine/model identities cannot activate policy");
+}
+function requireCurrentProof(policy, proof, composition = []) {
+    const evaluator = evaluatorForPolicy(policy);
+    const mutationEngine = mutationEngineForPolicy(policy);
+    if (proof.evaluator.name !== evaluator.name || proof.evaluator.version !== evaluator.version)
+        throw new Error(`proof ${proof.id} evaluator version is stale`);
+    if (proof.mutation_engine?.name !== mutationEngine.name || proof.mutation_engine.version !== mutationEngine.version)
+        throw new Error(`proof ${proof.id} mutation engine version is stale`);
+    assertCompositionBinding(policy, composition, proof.composition);
+    if (proof.policy_hash !== policyProofHash(policy, composition))
+        throw new Error(`proof ${proof.id} does not match the current policy semantics`);
+    if (proof.current.satisfied !== 1 || proof.current.error || proof.current.unknown)
+        throw new Error(`proof ${proof.id} has no clean satisfied baseline`);
+}
+export function proposeProvedPolicy(policy, proof, at, composition = [], currentBehaviorAttestations = []) {
+    const behaviorAttestationError = executableBehaviorAttestationError(policy, currentBehaviorAttestations);
+    if (behaviorAttestationError)
+        throw new Error(behaviorAttestationError);
+    if (policy.state !== "compiled" && policy.state !== "validating" && policy.state !== "proposed")
+        throw new Error(`cannot attach proof while policy is ${policy.state}`);
+    if (proofRank[proof.proof_class] < proofRank.P1)
+        throw new Error(`proof ${proof.id} is ${proof.proof_class}; a clean current baseline is required`);
+    requireCurrentProof(policy, proof, composition);
+    return {
+        ...policy,
+        revision: policy.revision + 1,
+        state: "proposed",
+        proof: proof.id,
+        updated_at: at,
+        audit: [...policy.audit, { action: "proved", actor_kind: "system", actor: "hunch:evidence-harness", at, reason: `Proof ${proof.id} reached ${proof.proof_class}.`, proof: proof.id }],
+    };
+}
+export function approvePolicy(policy, proof, mode, actor, at, dispositions = [], composition = [], currentBehaviorAttestations = []) {
+    requireHuman(actor);
+    const behaviorAttestationError = executableBehaviorAttestationError(policy, currentBehaviorAttestations);
+    if (behaviorAttestationError)
+        throw new Error(behaviorAttestationError);
+    if (policy.exception_of && mode === "blocking")
+        throw new Error(`exception policy ${policy.id} cannot block independently; activate its broad parent only after parent/exception composition is proved`);
+    if (policy.state !== "proposed")
+        throw new Error(`policy ${policy.id} is ${policy.state}; only a proposed policy can be activated`);
+    requireCurrentProof(policy, proof, composition);
+    if (mode === "blocking" && proofRank[proof.proof_class] < proofRank.P3) {
+        throw new Error(`blocking activation requires P3+ proof; ${proof.id} is ${proof.proof_class}`);
+    }
+    if (mode === "blocking") {
+        const replayError = blockingEvidenceError(proof, dispositions);
+        if (replayError)
+            throw new Error(replayError);
+    }
+    const event = `${mode === "blocking" ? "approval-blocking" : "approval-advisory"}:${at}`;
+    return {
+        ...policy,
+        revision: policy.revision + 1,
+        state: mode === "blocking" ? "active_blocking" : "active_advisory",
+        severity: mode === "blocking" ? "blocking" : "warning",
+        surfaces: policy.assertion.kind === "executable-behavior"
+            ? ["pre_commit", "ci", "mcp", "cli"]
+            : mode === "blocking" ? ["pre_commit", "ci", "mcp", "cli"] : ["pre_edit", "pre_commit", "ci", "mcp", "cli"],
+        authority: { kind: "human", actor, event, at },
+        valid_from: at,
+        valid_to: null,
+        updated_at: at,
+        audit: [...policy.audit, {
+                action: mode === "blocking" ? "approved_blocking" : "approved_advisory",
+                actor_kind: "human",
+                actor,
+                at,
+                reason: `Human activated policy as ${mode}.`,
+                proof: proof.id,
+            }],
+    };
+}
+/** Human-authored exception relationship only. It invalidates the child's old
+ * proof/authority; the broad parent remains the separately activated unit. */
+export function linkPolicyException(child, parent, actor, reason, at) {
+    requireHuman(actor);
+    if (child.id === parent.id)
+        throw new Error("a policy cannot be its own exception parent");
+    if (child.data_class !== parent.data_class)
+        throw new Error("exception and parent must have the same data class");
+    if (child.exception_of && child.exception_of !== parent.id)
+        throw new Error(`policy ${child.id} is already linked to exception parent ${child.exception_of}`);
+    if (!oppositeExceptionAssertions(child, parent))
+        throw new Error("exception must be the exact opposite reaches/not-reaches assertion over the same bindings and relation");
+    if (!exceptionScopeIsNarrower(child, parent))
+        throw new Error("exception scope must be strictly narrower than and contained by its parent scope");
+    if (!reason.trim())
+        throw new Error("exception link requires an audited human reason");
+    if (child.exception_of === parent.id)
+        return child;
+    return {
+        ...child,
+        revision: child.revision + 1,
+        state: "compiled",
+        severity: "warning",
+        authority: null,
+        proof: null,
+        exception_of: parent.id,
+        updated_at: at,
+        audit: [...child.audit, {
+                action: "linked_exception",
+                actor_kind: "human",
+                actor,
+                at,
+                reason,
+                proof: null,
+            }],
+    };
+}
+export function demotePolicy(policy, actor, reason, at) {
+    requireHuman(actor);
+    if (policy.state !== "active_blocking")
+        throw new Error(`policy ${policy.id} is ${policy.state}; only active blocking policy can be demoted`);
+    return {
+        ...policy,
+        revision: policy.revision + 1,
+        state: "active_advisory",
+        severity: "warning",
+        authority: { kind: "human", actor, event: `demotion:${at}`, at },
+        updated_at: at,
+        audit: [...policy.audit, { action: "demoted", actor_kind: "human", actor, at, reason, proof: policy.proof }],
+    };
+}
+/** Targeted advisory withdrawal (the §57 gap): pull the human authority back and
+ *  return the policy to `proposed`. It stops surfacing as an active rule and
+ *  RE-ENTERS the inline escalation loop ("activate or reject?") — the reversible
+ *  half of retirement. History is append-only; nothing is erased. */
+export function withdrawPolicy(policy, actor, reason, at) {
+    requireHuman(actor);
+    if (policy.state !== "active_advisory")
+        throw new Error(`policy ${policy.id} is ${policy.state}; only active advisory policy can be withdrawn to proposed`);
+    return {
+        ...policy,
+        revision: policy.revision + 1,
+        state: "proposed",
+        authority: null,
+        updated_at: at,
+        audit: [...policy.audit, { action: "withdrawn", actor_kind: "human", actor, at, reason, proof: policy.proof }],
+    };
+}
+/** Permanent retirement: the rule is deliberately DONE — it stops surfacing
+ *  anywhere (active rules, escalations) but its full history and audit trail stay
+ *  (supersede-never-erase, HC-08). Closes the valid-time window. */
+export function retirePolicy(policy, actor, reason, at) {
+    requireHuman(actor);
+    if (policy.state !== "active_advisory" && policy.state !== "active_blocking" && policy.state !== "proposed") {
+        throw new Error(`policy ${policy.id} is ${policy.state}; only an active or proposed policy can be retired`);
+    }
+    return {
+        ...policy,
+        revision: policy.revision + 1,
+        state: "retired",
+        authority: null,
+        valid_to: at,
+        updated_at: at,
+        audit: [...policy.audit, { action: "retired", actor_kind: "human", actor, at, reason, proof: policy.proof }],
+    };
+}
+//# sourceMappingURL=lifecycle.js.map

package/dist/constitution/mutation.js

@@ -0,0 +1,262 @@
+import { shortHash } from "../core/ids.js";
+import { externalPackage } from "../core/externalImports.js";
+import { parseSource } from "../extractors/parse.js";
+import { canonicalHash, canonicalJson, policySemanticHash, proofEvaluationHash } from "./canonical.js";
+import { evaluatePolicyOnSnapshot, graphSnapshotFromRecords, mutateSnapshotForPolicy, mutationOperatorForPolicy, } from "./evaluator.js";
+import { MutationReceiptSchema, MUTATION_ENGINE, } from "./schema.js";
+import { runSourceMutation } from "./sourceMutation.js";
+function policySelectors(policy) {
+    const assertion = policy.assertion;
+    if (assertion.kind === "executable-behavior")
+        return [];
+    return [
+        assertion.subject,
+        ...(assertion.kind === "exists" ? [] : [assertion.object]),
+        ...(assertion.kind === "must-pass-through" ? [assertion.via] : []),
+    ];
+}
+function symbolForSelector(snapshot, selector) {
+    const raw = selector.selector;
+    if (raw.startsWith("symbol-id:")) {
+        return snapshot.symbols.find((symbol) => symbol.id === raw.slice("symbol-id:".length)) ?? null;
+    }
+    if (!raw.startsWith("symbol:"))
+        return null;
+    const target = raw.slice("symbol:".length);
+    const split = target.lastIndexOf(":");
+    const matches = split > 0
+        ? snapshot.symbols.filter((symbol) => symbol.name === target.slice(split + 1) && (symbol.file === target.slice(0, split) || symbol.file.endsWith(`/${target.slice(0, split)}`)))
+        : snapshot.symbols.filter((symbol) => symbol.name === target);
+    return matches.length === 1 ? matches[0] : null;
+}
+function nameForSelector(snapshot, selector) {
+    const symbol = symbolForSelector(snapshot, selector);
+    if (symbol)
+        return symbol.name;
+    const component = componentForSelector(snapshot, selector);
+    if (component)
+        return component.name;
+    return selector.selector.startsWith("external:")
+        ? externalPackage(selector.selector.slice("external:".length))
+        : null;
+}
+function componentForSelector(snapshot, selector) {
+    const raw = selector.selector;
+    if (raw.startsWith("component-id:"))
+        return snapshot.components.find((component) => component.id === raw.slice("component-id:".length)) ?? null;
+    if (!raw.startsWith("component:"))
+        return null;
+    const name = raw.slice("component:".length);
+    const matches = snapshot.components.filter((component) => component.name === name);
+    return matches.length === 1 ? matches[0] : null;
+}
+function graphDiff(base, mutated) {
+    const baseSymbols = new Set(base.symbols.map((symbol) => symbol.id));
+    const mutatedSymbols = new Set(mutated.symbols.map((symbol) => symbol.id));
+    const baseEdges = new Set(base.edges.map((edge) => edge.id));
+    const mutatedEdges = new Set(mutated.edges.map((edge) => edge.id));
+    return {
+        added_symbols: [...mutatedSymbols].filter((id) => !baseSymbols.has(id)).sort(),
+        removed_symbols: [...baseSymbols].filter((id) => !mutatedSymbols.has(id)).sort(),
+        added_edges: [...mutatedEdges].filter((id) => !baseEdges.has(id)).sort(),
+        removed_edges: [...baseEdges].filter((id) => !mutatedEdges.has(id)).sort(),
+    };
+}
+function receipt(policy, base, input, policyHash = policySemanticHash(policy)) {
+    const seed = {
+        engine: MUTATION_ENGINE,
+        policy_hash: policyHash,
+        base_commit: base.head,
+        base_graph_hash: base.graph_hash,
+        kind: input.kind,
+        operator: input.operator,
+    };
+    const body = {
+        id: `mut_${shortHash(canonicalJson(seed))}`,
+        engine: { ...MUTATION_ENGINE },
+        policy_hash: seed.policy_hash,
+        base_commit: seed.base_commit,
+        base_graph_hash: seed.base_graph_hash,
+        ...input,
+    };
+    return MutationReceiptSchema.parse({ ...body, deterministic_hash: canonicalHash(body) });
+}
+function errorReceipt(policy, base, planned, kind, code, parseability = "not_applicable", policyHash = policySemanticHash(policy)) {
+    return receipt(policy, base, {
+        kind,
+        operator: planned.operator,
+        required: planned.required,
+        expected: planned.expected,
+        result: "error",
+        passed: false,
+        parseability,
+        graph_diff: { added_symbols: [], removed_symbols: [], added_edges: [], removed_edges: [] },
+        error_code: code,
+    }, policyHash);
+}
+function primaryMutation(root, policy, base, planned, context) {
+    const expectedOperator = mutationOperatorForPolicy(context.mutation_policy);
+    if (planned.operator !== expectedOperator) {
+        throw new Error(`proof plan mutation ${planned.operator} does not match evaluator operator ${expectedOperator}`);
+    }
+    if (/^[a-f0-9]{40}$/.test(base.head)) {
+        const source = runSourceMutation(root, context.mutation_policy, base);
+        if (!source.snapshot || !source.evaluation || !source.source_patch) {
+            const code = source.error_code ?? "source-mutation-failed";
+            return {
+                receipt: errorReceipt(policy, base, planned, "primary", code, code === "mutation-source-unparseable" ? "unparseable" : "not_applicable", context.policy_hash),
+            };
+        }
+        const evaluation = context.evaluate(source.snapshot);
+        return {
+            evaluation,
+            receipt: receipt(policy, base, {
+                kind: "primary",
+                operator: planned.operator,
+                required: planned.required,
+                mutated_graph_hash: source.snapshot.graph_hash,
+                expected: planned.expected,
+                result: evaluation.result,
+                passed: evaluation.result === planned.expected,
+                parseability: "parseable",
+                graph_diff: graphDiff(base, source.snapshot),
+                source_patch: source.source_patch,
+                evaluation_hash: proofEvaluationHash(evaluation),
+            }, context.policy_hash),
+        };
+    }
+    const mutation = mutateSnapshotForPolicy(context.mutation_policy, base);
+    if (!mutation)
+        return { receipt: errorReceipt(policy, base, planned, "primary", "mutation-unavailable", "not_applicable", context.policy_hash) };
+    const evaluation = context.evaluate(mutation.snapshot);
+    return {
+        evaluation,
+        receipt: receipt(policy, base, {
+            kind: "primary",
+            operator: planned.operator,
+            required: planned.required,
+            mutated_graph_hash: mutation.snapshot.graph_hash,
+            expected: planned.expected,
+            result: evaluation.result,
+            passed: evaluation.result === planned.expected,
+            parseability: "not_applicable",
+            graph_diff: graphDiff(base, mutation.snapshot),
+            evaluation_hash: proofEvaluationHash(evaluation),
+        }, context.policy_hash),
+    };
+}
+function commentStringControl(policy, base, planned, context) {
+    const baseline = context.evaluate(base);
+    const targets = [...new Set(policySelectors(policy)
+            .map((selector) => nameForSelector(base, selector))
+            .filter((name) => !!name))].sort();
+    if (!targets.length)
+        return errorReceipt(policy, base, planned, "control", "control-selector-unresolved", "not_applicable", context.policy_hash);
+    const marker = targets.map((name) => `${name}()`).join(" ");
+    const source = [
+        "export function hunchMutationCommentStringControl(){",
+        `  const marker = ${JSON.stringify(marker)};`,
+        `  // ${marker}`,
+        "  return marker;",
+        "}",
+        "",
+    ].join("\n");
+    const parsed = parseSource("hunch-mutation-comment-string-control.ts", source);
+    const observedCalls = parsed?.calls.map((call) => call.callee).filter((name) => targets.includes(name)).sort() ?? [];
+    const observedImports = parsed?.imports.filter((specifier) => targets.includes(specifier)).sort() ?? [];
+    const parserPassed = !!parsed?.parseable && observedCalls.length === 0 && observedImports.length === 0;
+    const result = parserPassed ? baseline.result : "error";
+    return receipt(policy, base, {
+        kind: "control",
+        operator: planned.operator,
+        required: planned.required,
+        mutated_graph_hash: base.graph_hash,
+        expected: planned.expected,
+        result,
+        passed: parserPassed && result === planned.expected,
+        parseability: parsed?.parseable ? "parseable" : "unparseable",
+        graph_diff: { added_symbols: [], removed_symbols: [], added_edges: [], removed_edges: [] },
+        parser_control: {
+            source_hash: canonicalHash(source),
+            observed_target_calls: observedCalls,
+            observed_target_imports: observedImports,
+        },
+        ...(parserPassed ? { evaluation_hash: proofEvaluationHash(baseline) } : { error_code: "comment-string-parser-control-failed" }),
+    }, context.policy_hash);
+}
+function sameNameControl(policy, base, planned, context) {
+    const selected = policySelectors(policy).map((selector) => symbolForSelector(base, selector)).filter((symbol) => !!symbol);
+    if (!selected.length) {
+        const selectedComponents = policySelectors(policy).map((selector) => componentForSelector(base, selector)).filter((component) => !!component);
+        if (!selectedComponents.length)
+            return errorReceipt(policy, base, planned, "control", "control-selector-unresolved", "not_applicable", context.policy_hash);
+        const clones = [...new Map(selectedComponents.map((component) => [component.id, component])).values()].map((component, index) => ({
+            ...component,
+            id: `${component.id}_mutation_control_${index + 1}`,
+            paths: [`__hunch_controls__/same-name-component-${index + 1}/**`],
+        }));
+        const controlled = graphSnapshotFromRecords(base.root, base.head, base.symbols, base.edges, [...base.components, ...clones]);
+        const evaluation = context.evaluate(controlled);
+        return receipt(policy, base, {
+            kind: "control",
+            operator: planned.operator,
+            required: planned.required,
+            mutated_graph_hash: controlled.graph_hash,
+            expected: planned.expected,
+            result: evaluation.result,
+            passed: evaluation.result === planned.expected,
+            parseability: "not_applicable",
+            graph_diff: graphDiff(base, controlled),
+            evaluation_hash: proofEvaluationHash(evaluation),
+        }, context.policy_hash);
+    }
+    const unique = [...new Map(selected.map((symbol) => [symbol.id, symbol])).values()];
+    const clones = unique.map((symbol, index) => ({
+        ...symbol,
+        id: `${symbol.id}_mutation_control_${index + 1}`,
+        file: `__hunch_controls__/same-name-${index + 1}.ts`,
+        calls: [],
+        called_by: [],
+        metrics: { ...symbol.metrics, fan_in: 0, fan_out: 0, churn_90d: 0, bug_count: 0 },
+        last_changed: "",
+    }));
+    const controlled = graphSnapshotFromRecords(base.root, base.head, [...base.symbols, ...clones], base.edges, base.components);
+    const evaluation = context.evaluate(controlled);
+    return receipt(policy, base, {
+        kind: "control",
+        operator: planned.operator,
+        required: planned.required,
+        mutated_graph_hash: controlled.graph_hash,
+        expected: planned.expected,
+        result: evaluation.result,
+        passed: evaluation.result === planned.expected,
+        parseability: "not_applicable",
+        graph_diff: graphDiff(base, controlled),
+        evaluation_hash: proofEvaluationHash(evaluation),
+    }, context.policy_hash);
+}
+/** Execute only canonical evaluator/parser mutations. Project scripts, builds,
+ * tests, models, and providers are deliberately outside this evidence path. */
+export function runMutationHarness(root, policy, base, planned, opts = {}) {
+    const context = {
+        policy_hash: opts.policyHash ?? policySemanticHash(policy),
+        mutation_policy: opts.mutationPolicy ?? policy,
+        evaluate: opts.evaluate ?? ((snapshot) => evaluatePolicyOnSnapshot(policy, snapshot)),
+    };
+    const receipts = [];
+    const primaryEvaluations = [];
+    for (const mutation of planned) {
+        if (mutation.operator === "comment-string-control")
+            receipts.push(commentStringControl(policy, base, mutation, context));
+        else if (mutation.operator === "same-name-ambiguity-control")
+            receipts.push(sameNameControl(policy, base, mutation, context));
+        else {
+            const primary = primaryMutation(root, policy, base, mutation, context);
+            receipts.push(primary.receipt);
+            if (primary.evaluation)
+                primaryEvaluations.push(primary.evaluation);
+        }
+    }
+    return { receipts, primary_evaluations: primaryEvaluations };
+}
+//# sourceMappingURL=mutation.js.map

package/dist/constitution/nodeTestEvidence.js

@@ -0,0 +1,47 @@
+export const NODE_TEST_REPORTER_PROTOCOL = "hunch-node-test-reporter-v1";
+export const NODE_TEST_REPORTER_SOURCE = `export default async function* hunchReporter(source) {
+  for await (const event of source) {
+    if (event.type !== "test:pass" && event.type !== "test:fail") continue;
+    yield JSON.stringify({
+      protocol: "${NODE_TEST_REPORTER_PROTOCOL}",
+      type: event.type,
+      name: event.data.name,
+      nesting: event.data.nesting,
+      skip: event.data.skip ?? null,
+      todo: event.data.todo ?? null
+    }) + "\\n";
+  }
+}
+`;
+export function exactNodeTestPattern(name) {
+    return `^${name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}$`;
+}
+export function nodeTestIsolationFlag() {
+    const [major = 0, minor = 0] = process.versions.node.split(".").map(Number);
+    return major > 23 || (major === 23 && minor >= 6)
+        ? "--test-isolation=none"
+        : "--experimental-test-isolation=none";
+}
+export function nodeTestReporterEvents(output) {
+    const events = [];
+    for (const line of output.split("\n").filter(Boolean)) {
+        try {
+            const event = JSON.parse(line);
+            if (event.protocol !== NODE_TEST_REPORTER_PROTOCOL
+                || (event.type !== "test:pass" && event.type !== "test:fail")
+                || typeof event.name !== "string")
+                continue;
+            events.push({
+                protocol: NODE_TEST_REPORTER_PROTOCOL,
+                type: event.type,
+                name: event.name,
+                ...(typeof event.nesting === "number" ? { nesting: event.nesting } : {}),
+                skip: event.skip ?? null,
+                todo: event.todo ?? null,
+            });
+        }
+        catch { /* non-protocol output cannot become evidence */ }
+    }
+    return events;
+}
+//# sourceMappingURL=nodeTestEvidence.js.map