@davesheffer/hunch 1.7.0 → 1.7.1

package/dist/constitution/plan.js

@@ -0,0 +1,172 @@
+import { basename } from "node:path";
+import { shortHash } from "../core/ids.js";
+import { firstCommitForFile, headSha, revExists, revParse } from "../extractors/git.js";
+import { canonicalHash, policySemanticHash } from "./canonical.js";
+import { policyCompositionBinding, policyProofHash } from "./composition.js";
+import { graphSnapshot, mutationOperatorForPolicy, selectedPolicyForComposition } from "./evaluator.js";
+import { createExecutableBehaviorProofPlan } from "./behaviorProof.js";
+import { POLICY_EVALUATOR, MUTATION_ENGINE, ProofPlanSchema, } from "./schema.js";
+function clamp(value, fallback, min, max) {
+    if (value == null || !Number.isFinite(value))
+        return fallback;
+    return Math.max(min, Math.min(max, Math.trunc(value)));
+}
+function hasBareNameSelector(policy) {
+    const assertion = policy.assertion;
+    if (assertion.kind === "executable-behavior")
+        return false;
+    const selectors = [assertion.subject, ...(assertion.kind === "exists" ? [] : [assertion.object]), ...(assertion.kind === "must-pass-through" ? [assertion.via] : [])];
+    return selectors.some(({ selector }) => selector.startsWith("symbol:") && !selector.slice("symbol:".length).includes(":"));
+}
+function relevantEvents(repository, policy, opts) {
+    const refs = new Set(policy.evidence.filter((ref) => ref.startsWith("ev_")));
+    return repository.listEvidence(opts)
+        .filter((event) => refs.has(event.id) || event.related_records.includes(policy.id))
+        .sort((a, b) => a.id.localeCompare(b.id));
+}
+function mergeFixtures(groups) {
+    const byCommit = new Map();
+    for (const fixture of groups.flat()) {
+        const existing = byCommit.get(fixture.ref);
+        if (existing && existing.expected !== fixture.expected) {
+            throw new Error(`fixture commit ${fixture.ref} has conflicting ${existing.expected}/${fixture.expected} expectations`);
+        }
+        if (!existing)
+            byCommit.set(fixture.ref, fixture);
+    }
+    return [...byCommit.values()].sort((a, b) => a.ref.localeCompare(b.ref) || a.label.localeCompare(b.label));
+}
+/** Deterministic compiler-to-harness contract. It plans replay and mutations but
+ * executes neither, grants no authority, and performs no provider/model call. */
+export function createProofPlan(store, root, repository, policy, opts = {}) {
+    if (opts.publicOnly && opts.privateOnly)
+        throw new Error("choose only one of publicOnly or privateOnly");
+    if (policy.assertion.kind === "executable-behavior") {
+        if (opts.composition?.length)
+            throw new Error("executable-behavior policies cannot have exception composition");
+        return createExecutableBehaviorProofPlan(root, repository, policy, { now: opts.now, privateOnly: true });
+    }
+    const head = headSha(root);
+    if (!head)
+        throw new Error("proof planning needs a Git repository with a current HEAD");
+    const composition = opts.composition ?? [];
+    const parentHash = policySemanticHash(policy);
+    const policyHash = policyProofHash(policy, composition);
+    const compositionBinding = policyCompositionBinding(policy, composition);
+    const corpus = repository.getCorpus(policy.id, opts);
+    if (corpus) {
+        if (corpus.policy_hash !== parentHash) {
+            throw new Error(`proof corpus ${corpus.id} is stale for policy ${policy.id}; re-import it after the policy semantic change`);
+        }
+        if (corpus.repository !== basename(root) || corpus.data_class !== policy.data_class) {
+            throw new Error(`proof corpus ${corpus.id} does not match repository/data class for policy ${policy.id}`);
+        }
+    }
+    const events = relevantEvents(repository, policy, opts);
+    const sourceEvent = events.find((event) => !!event.commit);
+    const readDecision = (id) => opts.publicOnly
+        ? store.json.get("decisions", id)
+        : opts.privateOnly
+            ? store.getPrivateRec("decisions", id)
+            : store.getRec("decisions", id);
+    const decision = [...policy.legacy_refs, ...policy.evidence]
+        .filter((ref) => ref.startsWith("dec_"))
+        .map(readDecision)
+        .find((record) => !!record);
+    const policyCommit = firstCommitForFile(`.hunch/policies/${policy.id}.json`, root);
+    const sourceRef = sourceEvent?.commit ?? decision?.commit ?? (policyCommit || head);
+    if (!revExists(sourceRef, root))
+        throw new Error(`proof-plan source commit ${sourceRef} does not resolve in this repository`);
+    const sourceCommit = revParse(sourceRef, root);
+    const structural = events.find((event) => event.structural_delta && (event.kind === "bug_fix" || event.kind === "revert" || event.kind === "decision"));
+    const structuralKnownBad = structural?.structural_delta
+        ? [{
+                kind: "commit",
+                ref: structural.structural_delta.before_commit,
+                label: `first parent before linked ${structural.kind.replace("_", " ")}`,
+                expected: "violated",
+            }]
+        : [];
+    const knownBad = mergeFixtures([corpus?.known_bad ?? [], structuralKnownBad]);
+    const knownGood = mergeFixtures([
+        corpus?.known_good ?? [],
+        [{ kind: "commit", ref: head, label: "current accepted baseline", expected: "satisfied" }],
+    ]);
+    const attestedKnownGood = knownGood.filter((fixture) => !!fixture.attestation);
+    const maxCommits = clamp(opts.maxCommits, 20, 0, 500);
+    const maxMutations = clamp(opts.maxMutations, 3, 0, 100);
+    const mutationPolicy = composition.length
+        ? selectedPolicyForComposition(policy, composition, graphSnapshot(store, root, { publicOnly: opts.publicOnly }))
+        : policy;
+    const operator = mutationOperatorForPolicy(mutationPolicy);
+    const plannedMutations = [
+        { operator, base: head, expected: "violated", required: true },
+        { operator: "comment-string-control", base: head, expected: "satisfied", required: true },
+        {
+            operator: "same-name-ambiguity-control",
+            base: head,
+            expected: hasBareNameSelector(policy) ? "unknown" : "satisfied",
+            required: true,
+        },
+    ].slice(0, maxMutations);
+    const body = {
+        policy_id: policy.id,
+        policy_candidate_hash: policyHash,
+        repository: basename(root),
+        data_class: policy.data_class,
+        source_commit: sourceCommit,
+        valid_from_commit: sourceCommit,
+        evaluator: { ...POLICY_EVALUATOR },
+        mutation_engine: { ...MUTATION_ENGINE },
+        ...(compositionBinding ? { composition: compositionBinding } : {}),
+        ...(corpus ? { corpus_manifest: { id: corpus.id, content_hash: corpus.content_hash } } : {}),
+        corpus: {
+            current_baseline: { kind: "commit", ref: head, label: "current repository baseline", expected: "satisfied" },
+            accepted_history: {
+                from: sourceCommit,
+                to: head,
+                first_parent: true,
+                max_commits: maxCommits,
+                exclude: [...new Set([
+                        ...knownBad.map((fixture) => fixture.ref),
+                        ...attestedKnownGood.map((fixture) => fixture.ref),
+                    ])].sort(),
+            },
+            known_bad: knownBad,
+            known_good: knownGood,
+        },
+        mutations: plannedMutations,
+        budgets: {
+            max_commits: maxCommits,
+            max_mutations: maxMutations,
+            max_minutes: clamp(opts.maxMinutes, 5, 1, 120),
+        },
+        expected: [
+            { leg: "current_baseline", result: "satisfied", classification_required: false },
+            ...(knownBad.length ? [{ leg: "known_bad", result: "violated", classification_required: false }] : []),
+            { leg: "known_good", result: "satisfied", classification_required: false },
+            { leg: "accepted_history", classification_required: true },
+            ...(maxMutations > 0 ? [{ leg: "mutations", result: "violated", classification_required: false }] : []),
+        ],
+        evidence_refs: [...new Set([...policy.evidence, ...events.map((event) => event.id)])].sort(),
+        limitations: [
+            "ProofPlan generation does not execute accepted-history replay or project tests.",
+            "Known-bad commits are included only when an attributable fix/revert delta identifies the first parent.",
+            ...(attestedKnownGood.length
+                ? ["Human-attested known-good fixtures are replayed as explicit corpus evidence and excluded from accepted-history sampling; attestation cannot waive a policy or grant authority."]
+                : []),
+            ...(compositionBinding
+                ? [`Plan binds the broad parent and ${compositionBinding.members.length} explicit scoped exception policy record(s) into one evaluator receipt.`]
+                : []),
+            ...policy.limitations,
+        ],
+    };
+    const contentHash = canonicalHash(body);
+    return ProofPlanSchema.parse({
+        id: `plan_${shortHash(contentHash)}`,
+        content_hash: contentHash,
+        ...body,
+        created_at: opts.now ?? new Date().toISOString(),
+    });
+}
+//# sourceMappingURL=plan.js.map

package/dist/constitution/policyRuntime.js

@@ -0,0 +1,8 @@
+import { BEHAVIOR_MUTATION_ENGINE, BEHAVIOR_POLICY_EVALUATOR, MUTATION_ENGINE, POLICY_EVALUATOR, } from "./schema.js";
+export function evaluatorForPolicy(policy) {
+    return policy.assertion.kind === "executable-behavior" ? BEHAVIOR_POLICY_EVALUATOR : POLICY_EVALUATOR;
+}
+export function mutationEngineForPolicy(policy) {
+    return policy.assertion.kind === "executable-behavior" ? BEHAVIOR_MUTATION_ENGINE : MUTATION_ENGINE;
+}
+//# sourceMappingURL=policyRuntime.js.map

package/dist/constitution/proof.js

@@ -0,0 +1,166 @@
+import { canonicalHash, proofEvaluationHash, proofId } from "./canonical.js";
+import { assertCompositionBinding, policyCompositionBinding, policyProofHash } from "./composition.js";
+import { evaluateCompositePolicyOnSnapshot, evaluatePolicyOnSnapshot, graphSnapshot, mutationOperatorForPolicy, selectedPolicyForComposition } from "./evaluator.js";
+import { runMutationHarness } from "./mutation.js";
+import { replayProofPlan } from "./replay.js";
+import { POLICY_EVALUATOR, MUTATION_ENGINE, PolicyProofSchema, } from "./schema.js";
+import { proveExecutableBehaviorPolicy } from "./behaviorProof.js";
+function summary(results) {
+    const count = (kind) => results.filter((r) => r.result === kind).length;
+    return {
+        total: results.length,
+        satisfied: count("satisfied"),
+        violated: count("violated"),
+        not_applicable: count("not_applicable"),
+        unknown: count("unknown"),
+        error: count("error"),
+        receipt_hashes: results.map((r) => r.deterministic_hash),
+    };
+}
+const emptySummary = () => ({
+    total: 0,
+    satisfied: 0,
+    violated: 0,
+    not_applicable: 0,
+    unknown: 0,
+    error: 0,
+    receipt_hashes: [],
+});
+function replaySummary(receipts) {
+    const count = (kind) => receipts.filter((receipt) => receipt.result === kind).length;
+    return {
+        total: receipts.length,
+        satisfied: count("satisfied"),
+        violated: count("violated"),
+        not_applicable: count("not_applicable"),
+        unknown: count("unknown"),
+        error: count("error"),
+        receipt_hashes: receipts.map((receipt) => receipt.deterministic_hash),
+    };
+}
+/** Inward proof execution. A canonical plan uses immutable disposable replay
+ * snapshots; the no-plan fallback preserves the original Gate-G1 current graph
+ * plus one deterministic mutation behavior. */
+export function provePolicy(store, root, policy, opts = {}) {
+    if (policy.assertion.kind === "executable-behavior") {
+        if (!opts.plan)
+            throw new Error("executable-behavior proof requires an exact ProofPlan");
+        if (opts.composition?.length)
+            throw new Error("executable-behavior policies cannot have exception composition");
+        return proveExecutableBehaviorPolicy(root, policy, opts.plan, { now: opts.now });
+    }
+    if (opts.plan && (opts.plan.mutation_engine?.name !== MUTATION_ENGINE.name
+        || opts.plan.mutation_engine.version !== MUTATION_ENGINE.version)) {
+        throw new Error(`proof plan ${opts.plan.id} requires regeneration for mutation engine ${MUTATION_ENGINE.name}@${MUTATION_ENGINE.version}`);
+    }
+    const composition = opts.composition ?? [];
+    const compositionBinding = policyCompositionBinding(policy, composition);
+    if (opts.plan)
+        assertCompositionBinding(policy, composition, opts.plan.composition);
+    const evaluate = (snapshot) => composition.length
+        ? evaluateCompositePolicyOnSnapshot(policy, composition, snapshot)
+        : evaluatePolicyOnSnapshot(policy, snapshot);
+    const replay = opts.plan ? replayProofPlan(root, policy, opts.plan, { composition }) : undefined;
+    const snapshot = replay?.current_snapshot ?? graphSnapshot(store, root, opts);
+    const fallbackCurrent = replay ? undefined : evaluate(snapshot);
+    const mutationBase = replay?.current_snapshot ?? snapshot;
+    const mutationPolicy = composition.length ? selectedPolicyForComposition(policy, composition, mutationBase) : policy;
+    const plannedMutations = opts.plan?.mutations ?? [{
+            operator: mutationOperatorForPolicy(mutationPolicy),
+            base: mutationBase.head,
+            expected: "violated",
+            required: true,
+        }];
+    const policyHash = policyProofHash(policy, composition);
+    const mutationHarness = runMutationHarness(root, policy, mutationBase, plannedMutations, {
+        policyHash,
+        mutationPolicy,
+        evaluate,
+    });
+    const mutationSummary = summary(mutationHarness.primary_evaluations);
+    if (replay)
+        mutationSummary.receipt_hashes = mutationHarness.primary_evaluations.map(proofEvaluationHash);
+    const primaryMutationReceipts = mutationHarness.receipts.filter((receipt) => receipt.kind === "primary");
+    const controlReceipts = mutationHarness.receipts.filter((receipt) => receipt.kind === "control");
+    const currentSummary = replay ? replaySummary([replay.current]) : summary(fallbackCurrent ? [fallbackCurrent] : []);
+    const knownBadSummary = replay ? replaySummary(replay.known_bad) : emptySummary();
+    const knownGoodSummary = replay ? replaySummary(replay.known_good) : summary(fallbackCurrent?.result === "satisfied" ? [fallbackCurrent] : []);
+    const historySummary = replay ? replaySummary(replay.accepted_history) : emptySummary();
+    let proofClass = "P0";
+    const baselineSatisfied = currentSummary.satisfied === 1 && currentSummary.error === 0 && currentSummary.unknown === 0;
+    if (baselineSatisfied)
+        proofClass = "P1";
+    if (baselineSatisfied && replay?.history_complete)
+        proofClass = "P2";
+    const caughtKnownBad = replay?.known_bad.some((receipt) => receipt.expected === "violated" && receipt.result === "violated") ?? false;
+    const caughtMutation = primaryMutationReceipts.some((receipt) => receipt.passed && receipt.result === "violated");
+    if (baselineSatisfied && (caughtKnownBad || caughtMutation))
+        proofClass = "P3";
+    const fallbackPlan = {
+        policy_hash: policyHash,
+        evaluator: POLICY_EVALUATOR,
+        mutation_engine: MUTATION_ENGINE,
+        ...(compositionBinding ? { composition: compositionBinding } : {}),
+        current_graph: snapshot.graph_hash,
+        mutations: plannedMutations.map((mutation) => mutation.operator),
+        budgets: { max_commits: 1, max_mutations: 1, max_minutes: 1 },
+    };
+    const planHash = opts.plan?.content_hash ?? canonicalHash(fallbackPlan);
+    const id = proofId({ policy_hash: policyHash, plan_hash: planHash, evaluator: POLICY_EVALUATOR });
+    const now = opts.now ?? new Date().toISOString();
+    const historyHits = historySummary.violated;
+    const replayProblems = historySummary.error + historySummary.unknown;
+    return PolicyProofSchema.parse({
+        id,
+        plan_hash: planHash,
+        policy_hash: policyHash,
+        evaluator: { ...POLICY_EVALUATOR },
+        mutation_engine: { ...MUTATION_ENGINE },
+        ...(compositionBinding ? { composition: compositionBinding } : {}),
+        generated_at: now,
+        current: currentSummary,
+        known_bad: knownBadSummary,
+        known_good: knownGoodSummary,
+        accepted_history: { ...historySummary, classified_hits: [] },
+        mutations: {
+            ...mutationSummary,
+            operator_coverage: Object.fromEntries(primaryMutationReceipts.map((receipt) => [receipt.operator, receipt.passed ? 1 : 0])),
+        },
+        replay_receipts: replay?.replay_receipts ?? [],
+        mutation_receipts: mutationHarness.receipts,
+        mutation_controls: {
+            total: controlReceipts.length,
+            passed: controlReceipts.filter((receipt) => receipt.passed).length,
+            failed: controlReceipts.filter((receipt) => !receipt.passed).length,
+            receipt_hashes: controlReceipts.map((receipt) => receipt.deterministic_hash),
+        },
+        project_checks: { build: "not_run", test: "not_run", required_for_evaluator_sensitivity: false },
+        limitations: [
+            ...policy.limitations,
+            ...(replay ? [
+                "Replay uses the pinned static evaluator in disposable Git worktrees; project build/tests and repository code are never executed.",
+                replay.selected_history_commits.length
+                    ? `Accepted-history replay evaluated ${replay.selected_history_commits.length} bounded first-parent commit(s).`
+                    : "Accepted-history selector resolved to zero non-baseline commits.",
+                ...(historyHits ? [`Accepted-history contains ${historyHits} unclassified violation hit(s); no false-positive claim or blocking approval is allowed until classification.`] : []),
+                ...(replayProblems ? [`Accepted-history contains ${replayProblems} unknown/error result(s); they remain visible and prevent blocking approval.`] : []),
+                "Primary mutation applies to an immutable disposable source checkout and must remain parseable; comment/string and same-name controls are separate, while project build/test outcomes remain non-authoritative follow-on evidence.",
+                "Shadow outcomes are tracked as separate append-only measurements and never mutate this immutable proof.",
+                ...(compositionBinding ? [`Composite receipts bind ${compositionBinding.members.length} explicit scoped exception policy record(s) to their broad parent.`] : []),
+            ] : ["Gate G1 proof covers the current graph and one deterministic mutation; historical replay and shadow outcomes are not available without a ProofPlan."]),
+        ],
+        proof_class: proofClass,
+        artifact_hashes: {
+            policy: policyHash,
+            ...(opts.plan ? { plan: opts.plan.content_hash } : {}),
+            ...(compositionBinding ? { composition: compositionBinding.composite_hash } : {}),
+            ...(replay?.current.graph_hash ? { graph: replay.current.graph_hash } : { graph: snapshot.graph_hash }),
+            ...(currentSummary.receipt_hashes[0] ? { current_receipt: currentSummary.receipt_hashes[0] } : {}),
+            ...(replay ? { replay_manifest: canonicalHash(replay.replay_receipts) } : {}),
+            ...(primaryMutationReceipts[0] ? { mutation_receipt: primaryMutationReceipts[0].deterministic_hash } : {}),
+            ...(mutationHarness.receipts.length ? { mutation_manifest: canonicalHash(mutationHarness.receipts) } : {}),
+        },
+        data_class: policy.data_class,
+    });
+}
+//# sourceMappingURL=proof.js.map