@davesheffer/hunch 1.6.0 → 1.7.1

package/dist/constitution/bootstrap.js

@@ -0,0 +1,133 @@
+import { basename } from "node:path";
+import { shortHash } from "../core/ids.js";
+import { canonicalHash } from "./canonical.js";
+import { compileDecisionRecord } from "./compiler.js";
+import { EvidenceEventSchema } from "./schema.js";
+export function clampCandidateLimit(value) {
+    if (value == null || !Number.isFinite(value))
+        return 3;
+    return Math.max(1, Math.min(3, Math.trunc(value)));
+}
+export function durationCutoff(since, now) {
+    const match = /^(\d+)([dw])$/.exec(since.trim());
+    if (!match)
+        throw new Error(`--since must be a positive duration such as 30d or 12w (got "${since}")`);
+    const amount = Number(match[1]);
+    if (!Number.isFinite(amount) || amount <= 0)
+        throw new Error("--since duration must be positive");
+    const days = match[2] === "w" ? amount * 7 : amount;
+    return Date.parse(now) - days * 86_400_000;
+}
+function eligible(decision, minDate) {
+    const at = Date.parse(decision.valid_from ?? decision.date);
+    return decision.status === "accepted"
+        && !decision.superseded_by
+        && !decision.valid_to
+        && decision.provenance.source.includes("human_confirmed")
+        && decision.conformance?.length === 1
+        && Number.isFinite(at)
+        && at >= minDate;
+}
+function eventFor(root, decision, isPrivate) {
+    const predicate = decision.conformance[0];
+    const contentHash = canonicalHash({
+        decision: decision.id,
+        predicate,
+        related_files: decision.related_files,
+        related_components: decision.related_components,
+        caused_by_bug: decision.caused_by_bug,
+    });
+    const symbols = [predicate.subject, predicate.object].filter((v) => !!v);
+    return EvidenceEventSchema.parse({
+        id: `ev_${shortHash(`${decision.id}:${contentHash}`)}`,
+        kind: "decision",
+        occurred_at: decision.valid_from ?? decision.date,
+        repository: basename(root),
+        ...(decision.commit ? { commit: decision.commit } : {}),
+        files: decision.related_files.filter((f) => !f.startsWith("private:")),
+        symbols,
+        text_ref: decision.id,
+        ...(decision.commit ? { diff_ref: `git:${decision.commit}` } : {}),
+        related_records: [decision.id],
+        data_class: isPrivate ? "private" : "public",
+        content_hash: contentHash,
+        compiler: { status: "eligible", policy: null, reason: "Structured human-confirmed Decision.conformance predicate." },
+        provenance: {
+            source: "derived",
+            confidence: 1,
+            evidence: [decision.id, ...decision.provenance.evidence],
+            last_verified: decision.provenance.last_verified,
+        },
+    });
+}
+function canReclassify(event) {
+    const status = event?.compiler?.status;
+    return !event || status === "eligible" || status === "uncompilable";
+}
+/** Model-free Phase-2A bootstrap. It accepts only explicit structured evidence,
+ * creates an auditable event, compiles at most three new candidates, and never
+ * changes lifecycle authority. */
+export function bootstrapPolicies(store, root, repository, opts = {}) {
+    if (opts.publicOnly && opts.privateOnly)
+        throw new Error("choose only one of publicOnly or privateOnly");
+    if (opts.privateOnly && !store.hasPrivate)
+        throw new Error("private bootstrap needs a configured Hunch private overlay");
+    const now = opts.now ?? new Date().toISOString();
+    const minDate = durationCutoff(opts.since ?? "90d", now);
+    const decisions = opts.privateOnly
+        ? store.recsInHome("decisions", "private")
+        : opts.publicOnly
+            ? store.json.loadAll("decisions")
+            : store.recs("decisions");
+    const candidates = decisions
+        .filter((d) => eligible(d, minDate))
+        .sort((a, b) => (b.valid_from ?? b.date).localeCompare(a.valid_from ?? a.date) || a.id.localeCompare(b.id));
+    const maxCandidates = clampCandidateLimit(opts.maxCandidates);
+    const homeView = { publicOnly: opts.publicOnly, privateOnly: opts.privateOnly };
+    const openCandidates = repository.listPolicies(homeView).filter((p) => p.state === "compiled" || p.state === "validating" || p.state === "proposed").length;
+    const available = Math.max(0, maxCandidates - Math.min(maxCandidates, openCandidates));
+    const report = { scanned: decisions.length, eligible: candidates.length, compiled: [], covered: 0, deferred: 0, uncompilable: 0, conflicted: 0 };
+    for (const decision of candidates) {
+        const isPrivate = opts.privateOnly ? true : opts.publicOnly ? false : !!store.getPrivateRec("decisions", decision.id);
+        const baseEvent = eventFor(root, decision, isPrivate);
+        const priorEvent = repository.getEvidence(baseEvent.id, homeView);
+        try {
+            const compiled = compileDecisionRecord(store, decision, isPrivate, { now });
+            const incumbent = repository.getPolicy(compiled.policy.id, homeView);
+            if (incumbent) {
+                report.covered++;
+                if (canReclassify(priorEvent))
+                    repository.putEvidence({
+                        ...baseEvent,
+                        related_records: [...baseEvent.related_records, incumbent.id],
+                        compiler: { status: "covered", policy: incumbent.id, reason: "Equivalent Policy IR already exists; lifecycle state preserved." },
+                    }, { private: isPrivate });
+                continue;
+            }
+            if (report.compiled.length >= available) {
+                report.deferred++;
+                if (canReclassify(priorEvent) && priorEvent?.compiler?.status !== "eligible") {
+                    repository.putEvidence(baseEvent, { private: isPrivate });
+                }
+                continue;
+            }
+            const policy = repository.putPolicy(compiled.policy, { private: compiled.private });
+            const event = repository.putEvidence({
+                ...baseEvent,
+                related_records: [...baseEvent.related_records, policy.id],
+                compiler: { status: "compiled", policy: policy.id, reason: "Deterministic structured compatibility compilation." },
+            }, { private: isPrivate });
+            report.compiled.push({ evidence: event, policy });
+        }
+        catch (e) {
+            report.uncompilable++;
+            if (canReclassify(priorEvent) && priorEvent?.compiler?.status !== "uncompilable")
+                repository.putEvidence({
+                    ...baseEvent,
+                    compiler: { status: "uncompilable", policy: null, reason: e.message },
+                }, { private: isPrivate });
+        }
+    }
+    return report;
+}
+//# sourceMappingURL=bootstrap.js.map

package/dist/constitution/canonical.js

@@ -0,0 +1,51 @@
+import { sha1, shortHash } from "../core/ids.js";
+function canonicalValue(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalValue);
+    if (value && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value)
+            .filter(([, v]) => v !== undefined)
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([k, v]) => [k, canonicalValue(v)]));
+    }
+    return value;
+}
+/** Stable, whitespace-free JSON for hashes and cross-client receipts. Arrays retain
+ * semantic order; object keys are recursively sorted. */
+export function canonicalJson(value) {
+    return JSON.stringify(canonicalValue(value));
+}
+export function canonicalHash(value) {
+    return sha1(canonicalJson(value));
+}
+/** Proofs bind evaluator semantics, not mutable lifecycle fields such as approval,
+ * severity, timestamps, or state. */
+export function policySemanticHash(policy) {
+    return canonicalHash({
+        id: policy.id,
+        ir_version: policy.ir_version,
+        statement: policy.statement,
+        scope: policy.scope,
+        assertion: policy.assertion,
+        exception_of: policy.exception_of,
+        data_class: policy.data_class,
+    });
+}
+export function proofPlanContentHash(plan) {
+    const { id: _id, content_hash: _contentHash, created_at: _createdAt, ...body } = plan;
+    return canonicalHash(body);
+}
+/** A proof rerun is bound to policy semantics, not a mutable lifecycle revision.
+ * Live gate receipts keep policy_revision in their own deterministic hash; this
+ * projection is only for immutable proof/replay evidence. */
+export function proofEvaluationHash(evaluation) {
+    const { policy_revision: _revision, deterministic_hash: _hash, ...semantic } = evaluation;
+    return canonicalHash(semantic);
+}
+export function policyId(seed) {
+    return `pol_${shortHash(canonicalJson(seed))}`;
+}
+export function proofId(seed) {
+    return `proof_${shortHash(canonicalJson(seed))}`;
+}
+//# sourceMappingURL=canonical.js.map

package/dist/constitution/card.js

@@ -0,0 +1,133 @@
+import { canonicalHash } from "./canonical.js";
+import { assertCompositionBinding, policyProofHash } from "./composition.js";
+import { blockingEvidenceError } from "./lifecycle.js";
+import { assessHistoryDispositions } from "./disposition.js";
+const proofRank = { P0: 0, P1: 1, P2: 2, P3: 3, P4: 4, P5: 5 };
+export function buildProofCard(policy, proof, dispositions = [], composition = [], shadowPrecision = null) {
+    let semanticMatch = proof.policy_hash === policyProofHash(policy, composition);
+    try {
+        assertCompositionBinding(policy, composition, proof.composition);
+    }
+    catch {
+        semanticMatch = false;
+    }
+    const baselineClean = proof.current.total === 1 && proof.current.satisfied === 1 && proof.current.unknown === 0 && proof.current.error === 0;
+    const dispositionAssessment = assessHistoryDispositions(proof, dispositions);
+    const evidenceError = blockingEvidenceError(proof, dispositions);
+    const proofStrongEnough = proofRank[proof.proof_class] >= proofRank.P3;
+    const eligible = semanticMatch && baselineClean && proofStrongEnough && !evidenceError;
+    const canBlock = eligible && policy.state === "active_blocking" && policy.severity === "blocking" && policy.authority?.kind === "human";
+    const unknownResults = proof.current.unknown + proof.known_bad.unknown + proof.known_good.unknown + proof.accepted_history.unknown + proof.mutations.unknown;
+    const errorResults = proof.current.error + proof.known_bad.error + proof.known_good.error + proof.accepted_history.error + proof.mutations.error;
+    const actions = [];
+    if (!semanticMatch)
+        actions.push("Regenerate the plan and proof for the current policy semantics.");
+    if (dispositionAssessment.unresolved_count)
+        actions.push("Classify every accepted-history violation with an exact human disposition before considering blocking approval.");
+    if (dispositionAssessment.counts.false_positive_selector + dispositionAssessment.counts.false_positive_semantics + dispositionAssessment.counts.false_positive_stale > 0)
+        actions.push("Repair and re-prove the policy before blocking because a human classified a historical hit as a false positive.");
+    if (dispositionAssessment.counts.true_positive_accepted_exception > 0)
+        actions.push("Prove combined parent/exception semantics before treating an accepted exception as resolved.");
+    if (dispositionAssessment.counts.unknown_insufficient_parser > 0)
+        actions.push("Improve parser support and re-prove before resolving an unknown historical hit.");
+    if (unknownResults || errorResults)
+        actions.push("Repair or explicitly resolve every unknown/error proof result.");
+    if (proof.mutation_controls.failed)
+        actions.push("Repair every failed required mutation control before considering blocking approval.");
+    if (policy.candidate.conflicts.length)
+        actions.push("Resolve every direct candidate conflict with a human disposition before lifecycle promotion.");
+    if (shadowPrecision?.recommendation === "eligible_for_p4_review")
+        actions.push("Shadow thresholds are met; a human may review P4 evidence, but measurement grants no authority.");
+    else if (shadowPrecision)
+        actions.push("Continue bounded shadow review until every reported precision threshold is met.");
+    if (eligible && !canBlock)
+        actions.push("A human may review and explicitly activate blocking mode; the proof and any earlier advisory approval grant no blocking authority by themselves.");
+    if (!eligible && actions.length === 0)
+        actions.push("Strengthen the evidence vector before requesting blocking approval.");
+    actions.push("Review the exact assertion, scope, evidence, and limitations before any lifecycle action.");
+    const body = {
+        policy: {
+            id: policy.id,
+            statement: policy.statement,
+            state: policy.state,
+            severity: policy.severity,
+            data_class: policy.data_class,
+            assertion: policy.assertion,
+            scope: policy.scope,
+            evidence: [...policy.evidence],
+            candidate: policy.candidate,
+            exception_of: policy.exception_of,
+        },
+        proof: { id: proof.id, proof_class: proof.proof_class, plan_hash: proof.plan_hash, generated_at: proof.generated_at },
+        evidence_vector: {
+            current: proof.current,
+            known_bad: proof.known_bad,
+            known_good: proof.known_good,
+            accepted_history: proof.accepted_history,
+            mutations: proof.mutations,
+            mutation_controls: proof.mutation_controls,
+        },
+        project_checks: proof.project_checks,
+        composition: proof.composition ?? null,
+        shadow_precision: shadowPrecision,
+        history_dispositions: {
+            current: dispositionAssessment.current,
+            counts: dispositionAssessment.counts,
+            missing_commits: dispositionAssessment.missing_commits,
+            unresolved_count: dispositionAssessment.unresolved_count,
+        },
+        uncertainty: {
+            unclassified_history_hits: dispositionAssessment.unresolved_count,
+            unknown_results: unknownResults,
+            error_results: errorResults,
+            limitations: [...proof.limitations],
+            compiler_uncertainty: [...policy.candidate.uncertainty],
+            candidate_conflicts: [...policy.candidate.conflicts],
+        },
+        authority: {
+            current: policy.authority,
+            eligible_for_human_blocking_approval: eligible,
+            can_block_now: canBlock,
+            blocking_evidence_error: evidenceError,
+        },
+        actions,
+    };
+    return { card_hash: canonicalHash(body), ...body };
+}
+function line(label, summary) {
+    return `${label}: ${summary.total} total · ${summary.satisfied} satisfied · ${summary.violated} violated · ${summary.not_applicable} n/a · ${summary.unknown} unknown · ${summary.error} error`;
+}
+export function renderProofCard(card) {
+    return [
+        `CONSTITUTION PROOF CARD  ${card.policy.id}`,
+        `  ${card.policy.statement}`,
+        `  state: ${card.policy.state} · severity: ${card.policy.severity} · proof: ${card.proof.proof_class} (${card.proof.id})`,
+        `  assertion: ${JSON.stringify(card.policy.assertion)}`,
+        `  scope: ${JSON.stringify(card.policy.scope)}`,
+        `  evidence: ${card.policy.evidence.join(", ") || "none"}`,
+        `  candidate alternatives: ${card.policy.candidate.alternatives.length} · conflicts: ${card.policy.candidate.conflicts.length} · incumbent: ${card.policy.candidate.incumbent ?? "none"}`,
+        `  scope suggestion: ${card.policy.candidate.scope_suggestion ? JSON.stringify(card.policy.candidate.scope_suggestion) : "none — narrow compiled scope retained"}`,
+        `  exception parent: ${card.policy.exception_of ?? "none"}`,
+        `  ${line("current", card.evidence_vector.current)}`,
+        `  ${line("known bad", card.evidence_vector.known_bad)}`,
+        `  ${line("known good", card.evidence_vector.known_good)}`,
+        `  ${line("accepted history", card.evidence_vector.accepted_history)}`,
+        `  history dispositions: ${card.history_dispositions.current.length} current · ${card.history_dispositions.counts.true_positive_actionable} actionable true positive · ${card.history_dispositions.unresolved_count} unresolved`,
+        `  ${line("mutations", card.evidence_vector.mutations)}`,
+        `  mutation controls: ${card.evidence_vector.mutation_controls.passed}/${card.evidence_vector.mutation_controls.total} passed · ${card.evidence_vector.mutation_controls.failed} failed`,
+        `  project checks: build ${card.project_checks.build} · test ${card.project_checks.test} · never required for evaluator sensitivity`,
+        ...(card.composition ? [`  composition: ${card.composition.root_policy_id} + ${card.composition.members.length} exception(s) · ${card.composition.composite_hash}`] : []),
+        ...(card.shadow_precision ? [`  shadow: ${card.shadow_precision.window.applicable} recent applicable · ${card.shadow_precision.window.violated} violated · precision ${card.shadow_precision.precision.confirmed == null ? "n/a" : (card.shadow_precision.precision.confirmed * 100).toFixed(1) + "%"} · ${card.shadow_precision.recommendation}`] : []),
+        `  uncertainty: ${card.uncertainty.unclassified_history_hits} unclassified history hit · ${card.uncertainty.unknown_results} unknown · ${card.uncertainty.error_results} error`,
+        `  blocking readiness: ${card.authority.eligible_for_human_blocking_approval ? "eligible for explicit human review" : `not eligible${card.authority.blocking_evidence_error ? ` — ${card.authority.blocking_evidence_error}` : ""}`}`,
+        `  authority: ${card.authority.current?.kind === "human" ? card.authority.current.actor : "none — proof cannot activate policy"}`,
+        ...card.uncertainty.limitations.map((limitation) => `  limitation: ${limitation}`),
+        ...card.uncertainty.compiler_uncertainty.map((uncertainty) => `  compiler uncertainty: ${uncertainty}`),
+        ...card.uncertainty.candidate_conflicts.map((conflict) => `  candidate conflict: ${conflict}`),
+        ...card.history_dispositions.current.map((disposition) => `  history disposition: ${disposition.commit} · ${disposition.classification} · ${disposition.actor} · ${disposition.id}`),
+        ...card.policy.candidate.counterexamples.map((counterexample) => `  counterexample: ${counterexample}`),
+        ...card.actions.map((action) => `  action: ${action}`),
+        `  card: ${card.card_hash}`,
+    ].join("\n");
+}
+//# sourceMappingURL=card.js.map

package/dist/constitution/compiler.js

@@ -0,0 +1,176 @@
+import { policyId } from "./canonical.js";
+import { POLICY_IR_VERSION, PolicySpecSchema } from "./schema.js";
+function selector(ref) {
+    if (ref.startsWith("symbol-id:") || ref.startsWith("symbol:"))
+        return { selector: ref };
+    return { selector: ref.startsWith("sym_") ? `symbol-id:${ref}` : `symbol:${ref}` };
+}
+function compileAssertion(predicate, through) {
+    if (predicate.assert === "exists")
+        return { kind: "exists", subject: selector(predicate.subject) };
+    if (!predicate.object)
+        throw new Error(`legacy ${predicate.assert} predicate has no object`);
+    const relation = {
+        // Legacy conformance deliberately treated calls/imports as one unified graph.
+        // Preserve that verdict exactly in the bridge instead of pretending edge-type
+        // precision already exists.
+        edges: ["calls", "imports", "depends_on", "contains"],
+        transitive: predicate.transitive,
+        max_depth: predicate.transitive ? 6 : 1,
+    };
+    const negative = predicate.assert === "not-calls" || predicate.assert === "not-imports";
+    if (through) {
+        if (!negative)
+            throw new Error("--through can only upgrade a not-calls/not-imports boundary into must-pass-through");
+        return {
+            kind: "must-pass-through",
+            subject: selector(predicate.subject),
+            relation: { ...relation, transitive: true, max_depth: 6 },
+            via: selector(through),
+            object: selector(predicate.object),
+        };
+    }
+    return {
+        kind: negative ? "not-reaches" : "reaches",
+        subject: selector(predicate.subject),
+        relation,
+        object: selector(predicate.object),
+    };
+}
+export function compileDecisionRecord(store, source, isPrivate, opts = {}) {
+    if (source.status === "rejected" || source.status === "superseded" || source.superseded_by) {
+        throw new Error(`decision ${source.id} is not in force`);
+    }
+    if (source.conformance?.length !== 1) {
+        throw new Error(`Gate G1 compiles exactly one structured conformance predicate; ${source.id} has ${source.conformance?.length ?? 0}`);
+    }
+    const assertion = compileAssertion(source.conformance[0], opts.through);
+    if (isPrivate && !store.hasPrivate)
+        throw new Error("private compilation needs a configured Hunch private overlay");
+    const now = opts.now ?? new Date().toISOString();
+    const id = policyId({ source: source.id, assertion });
+    const policy = PolicySpecSchema.parse({
+        id,
+        topic: source.topic ?? `decision.${source.id}`,
+        ir_version: POLICY_IR_VERSION,
+        revision: 1,
+        state: "compiled",
+        statement: source.title,
+        rationale: source.context || source.decision,
+        scope: {
+            repos: [],
+            paths: source.related_files.filter((f) => !f.startsWith("private:")),
+            components: [...source.related_components],
+        },
+        assertion,
+        severity: "warning",
+        surfaces: ["cli", "mcp", "ci"],
+        authority: null,
+        evidence: [source.id, ...(source.caused_by_bug ? [source.caused_by_bug] : [])],
+        proof: null,
+        reversal_conditions: [`Source decision ${source.id} is superseded or explicitly retired.`],
+        supersedes: null,
+        superseded_by: null,
+        valid_from: null,
+        valid_to: null,
+        data_class: isPrivate ? "private" : "public",
+        limitations: [
+            "TypeScript/JavaScript static graph only in Gate G1.",
+            "Dynamic calls and runtime dependency injection are not covered.",
+            ...(opts.through ? [] : ["Legacy bridge preserves unified calls/imports/depends_on/contains reachability semantics."]),
+        ],
+        legacy_refs: [source.id],
+        audit: [{ action: "compiled", actor_kind: "system", actor: "hunch:deterministic-compiler", at: now, reason: "Compiled from one structured Decision.conformance predicate.", proof: null }],
+        created_at: now,
+        updated_at: now,
+        provenance: { source: "derived", confidence: 1, evidence: [source.id], last_verified: now },
+    });
+    return { policy, private: isPrivate, source };
+}
+/** Deterministic compatibility compiler: one structured legacy conformance
+ * predicate becomes one Policy IR candidate. It never interprets prose into a
+ * nearest available rule. */
+export function compileDecisionPolicy(store, decisionId, opts = {}) {
+    const source = store.getRec("decisions", decisionId);
+    if (!source)
+        throw new Error(`decision ${decisionId} not found`);
+    // A private source always taints its compiled artifact. `--private` can
+    // promote a public source into the overlay, but an omitted/false CLI flag
+    // must never declassify a same-id private overlay record into the public
+    // repository.
+    const isPrivate = !!opts.private || !!store.getPrivateRec("decisions", decisionId);
+    return compileDecisionRecord(store, source, isPrivate, { through: opts.through, now: opts.now });
+}
+/** Compile one already-enumerated structural assertion. This function does not
+ * infer or rank semantics; callers must pass an exact supported candidate. */
+export function compileStructuralPolicy(store, input) {
+    const isPrivate = input.dataClass !== "public";
+    if (isPrivate && !store.hasPrivate)
+        throw new Error("private structural compilation needs a configured Hunch private overlay");
+    const now = input.now ?? new Date().toISOString();
+    const externalImport = input.assertion.kind === "not-reaches"
+        && input.assertion.relation.edges.length === 1
+        && input.assertion.relation.edges[0] === "imports"
+        && input.assertion.object.selector.startsWith("external:");
+    const componentRelation = input.assertion.kind !== "exists"
+        && input.assertion.kind !== "executable-behavior"
+        && input.assertion.relation.edges.length === 1
+        && input.assertion.relation.edges[0] === "depends_on"
+        && input.assertion.subject.selector.startsWith("component");
+    const id = policyId({ assertion: input.assertion, scope: input.scope, data_class: input.dataClass });
+    const policy = PolicySpecSchema.parse({
+        id,
+        topic: input.source.topic ?? `decision.${input.source.id}`,
+        ir_version: POLICY_IR_VERSION,
+        revision: 1,
+        state: "compiled",
+        statement: input.source.title,
+        rationale: input.source.context || input.source.decision,
+        scope: input.scope,
+        assertion: input.assertion,
+        severity: "warning",
+        surfaces: ["cli", "mcp", "ci"],
+        authority: null,
+        evidence: [input.source.id, input.evidenceId, `commit:${input.commit}`],
+        proof: null,
+        reversal_conditions: [`Source decision ${input.source.id} is superseded or the structural interpretation is rejected.`],
+        supersedes: null,
+        superseded_by: null,
+        valid_from: null,
+        valid_to: null,
+        data_class: input.dataClass,
+        limitations: [
+            "Inferred from one exact first-parent Git structural delta; replay coverage is established only by a later plan-bound proof.",
+            externalImport
+                ? "Scope is intentionally limited to the changed file and anchored to one stable symbol in that file."
+                : componentRelation
+                    ? "Scope is intentionally limited to the exact source and target components resolved from one relative static import."
+                    : "Scope is intentionally limited to the changed caller or introduced-symbol file.",
+            externalImport
+                ? "TypeScript/JavaScript static ESM import/export specifiers only; require(), dynamic import(), package aliases, and runtime loading are not covered."
+                : componentRelation
+                    ? "TypeScript/JavaScript static relative ESM import/export specifiers only; aliases, absolute paths, import maps, require(), dynamic import(), and runtime loading are not covered."
+                    : "TypeScript/JavaScript static calls only; dynamic calls and runtime dependency injection are not covered.",
+        ],
+        candidate: input.candidate,
+        legacy_refs: [input.source.id],
+        audit: [{
+                action: "compiled",
+                actor_kind: "system",
+                actor: "hunch:structural-delta-compiler",
+                at: now,
+                reason: `Compiled from one unambiguous assertion enumerated by evidence ${input.evidenceId}.`,
+                proof: null,
+            }],
+        created_at: now,
+        updated_at: now,
+        provenance: {
+            source: "derived",
+            confidence: 0.8,
+            evidence: [input.source.id, input.evidenceId, `commit:${input.commit}`],
+            last_verified: now,
+        },
+    });
+    return { policy, private: isPrivate };
+}
+//# sourceMappingURL=compiler.js.map

package/dist/constitution/composition.js

@@ -0,0 +1,101 @@
+import { pathMatchesGlob } from "../core/glob.js";
+import { canonicalHash, canonicalJson, policySemanticHash } from "./canonical.js";
+import { PolicyCompositionBindingSchema } from "./schema.js";
+function sameValues(left, right) {
+    const a = [...left].sort();
+    const b = [...right].sort();
+    return a.length === b.length && a.every((value, index) => value === b[index]);
+}
+export function oppositeExceptionAssertions(child, parent) {
+    const left = child.assertion;
+    const right = parent.assertion;
+    if (!((left.kind === "reaches" && right.kind === "not-reaches") || (left.kind === "not-reaches" && right.kind === "reaches")))
+        return false;
+    return left.subject.selector === right.subject.selector
+        && left.object.selector === right.object.selector
+        && canonicalJson(left.relation) === canonicalJson(right.relation);
+}
+export function exceptionScopeIsNarrower(child, parent) {
+    const reposInside = !parent.scope.repos.length || child.scope.repos.every((repo) => parent.scope.repos.includes(repo));
+    const componentsInside = !parent.scope.components.length || child.scope.components.every((component) => parent.scope.components.includes(component));
+    const pathsInside = !parent.scope.paths.length || child.scope.paths.every((path) => parent.scope.paths.some((glob) => path === glob || pathMatchesGlob(path, glob)));
+    const strict = !sameValues(child.scope.repos, parent.scope.repos)
+        || !sameValues(child.scope.paths, parent.scope.paths)
+        || !sameValues(child.scope.components, parent.scope.components);
+    return reposInside && componentsInside && pathsInside && strict;
+}
+export function validateExceptionRelationship(child, parent) {
+    if (child.id === parent.id)
+        throw new Error("a policy cannot be its own exception parent");
+    if (child.exception_of !== parent.id)
+        throw new Error(`exception policy ${child.id} does not link parent ${parent.id}`);
+    if (child.data_class !== parent.data_class)
+        throw new Error("exception and parent must have the same data class");
+    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");
+}
+/** Return every explicit descendant of a broad root. Parent links define the
+ * precedence tree; stable policy-id ordering keeps the binding canonical. */
+export function compositionDescendants(root, policies) {
+    if (root.exception_of)
+        return [];
+    const byParent = new Map();
+    for (const policy of policies) {
+        if (!policy.exception_of)
+            continue;
+        const children = byParent.get(policy.exception_of) ?? [];
+        children.push(policy);
+        byParent.set(policy.exception_of, children);
+    }
+    const out = [];
+    const visited = new Set([root.id]);
+    const queue = [...(byParent.get(root.id) ?? [])].sort((a, b) => a.id.localeCompare(b.id));
+    while (queue.length) {
+        const policy = queue.shift();
+        if (visited.has(policy.id))
+            throw new Error(`exception composition contains a cycle at ${policy.id}`);
+        visited.add(policy.id);
+        out.push(policy);
+        queue.push(...[...(byParent.get(policy.id) ?? [])].sort((a, b) => a.id.localeCompare(b.id)));
+    }
+    return out.sort((a, b) => a.id.localeCompare(b.id));
+}
+export function policyCompositionBinding(root, members) {
+    if (!members.length)
+        return undefined;
+    const byId = new Map([root, ...members].map((policy) => [policy.id, policy]));
+    if (byId.size !== members.length + 1)
+        throw new Error("exception composition contains duplicate policy ids");
+    for (const member of members) {
+        const parent = member.exception_of ? byId.get(member.exception_of) : undefined;
+        if (!parent)
+            throw new Error(`exception policy ${member.id} has missing composition parent ${member.exception_of ?? "null"}`);
+        validateExceptionRelationship(member, parent);
+    }
+    const body = {
+        kind: "parent_with_exceptions",
+        root_policy_id: root.id,
+        root_policy_hash: policySemanticHash(root),
+        members: [...members]
+            .sort((a, b) => a.id.localeCompare(b.id))
+            .map((policy) => ({
+            policy_id: policy.id,
+            policy_hash: policySemanticHash(policy),
+            exception_of: policy.exception_of,
+            scope: policy.scope,
+        })),
+    };
+    return PolicyCompositionBindingSchema.parse({ ...body, composite_hash: canonicalHash(body) });
+}
+export function policyProofHash(root, members = []) {
+    return policyCompositionBinding(root, members)?.composite_hash ?? policySemanticHash(root);
+}
+export function assertCompositionBinding(root, members, binding) {
+    const expected = policyCompositionBinding(root, members);
+    if (canonicalJson(expected) !== canonicalJson(binding)) {
+        throw new Error(`proof artifacts do not match the current parent/exception composition for policy ${root.id}`);
+    }
+}
+//# sourceMappingURL=composition.js.map

package/dist/constitution/corpus.js

@@ -0,0 +1,58 @@
+import { basename } from "node:path";
+import { shortHash } from "../core/ids.js";
+import { revExists, revParse } from "../extractors/git.js";
+import { canonicalHash, policySemanticHash } from "./canonical.js";
+import { ProofCorpusInputSchema, ProofCorpusSchema, } from "./schema.js";
+function resolveFixture(root, fixture, expected) {
+    if (!revExists(fixture.ref, root))
+        throw new Error(`corpus fixture ref ${fixture.ref} does not resolve to a commit`);
+    const ref = revParse(`${fixture.ref}^{commit}`, root);
+    if (!/^[a-f0-9]{40}$/.test(ref))
+        throw new Error(`corpus fixture ref ${fixture.ref} did not resolve to a full commit SHA`);
+    return {
+        kind: "commit",
+        ref,
+        label: fixture.label,
+        expected,
+        ...(fixture.attestation ? { attestation: fixture.attestation } : {}),
+    };
+}
+function sorted(fixtures) {
+    return fixtures.sort((a, b) => a.ref.localeCompare(b.ref) || a.label.localeCompare(b.label));
+}
+/** Resolve human-authored Git refs once, then persist an immutable, policy-bound
+ * fixture manifest. No checkout, evaluator, model, provider, or project command runs. */
+export function compileProofCorpus(root, policy, raw, opts = {}) {
+    const input = ProofCorpusInputSchema.parse(raw);
+    const knownBad = sorted(input.known_bad.map((fixture) => resolveFixture(root, fixture, "violated")));
+    const knownGood = sorted(input.known_good.map((fixture) => resolveFixture(root, fixture, "satisfied")));
+    const seen = new Map();
+    for (const [leg, fixtures] of [["known_bad", knownBad], ["known_good", knownGood]]) {
+        for (const fixture of fixtures) {
+            const existing = seen.get(fixture.ref);
+            if (existing)
+                throw new Error(`corpus fixture commit ${fixture.ref} is duplicated in ${existing} and ${leg}`);
+            seen.set(fixture.ref, leg);
+        }
+    }
+    const body = {
+        policy_id: policy.id,
+        policy_hash: policySemanticHash(policy),
+        repository: basename(root),
+        data_class: policy.data_class,
+        known_bad: knownBad,
+        known_good: knownGood,
+    };
+    const contentHash = canonicalHash(body);
+    return ProofCorpusSchema.parse({
+        id: `corpus_${shortHash(contentHash)}`,
+        content_hash: contentHash,
+        ...body,
+        created_at: opts.now ?? new Date().toISOString(),
+    });
+}
+export function proofCorpusContentHash(corpus) {
+    const { id: _id, content_hash: _contentHash, created_at: _createdAt, ...body } = corpus;
+    return canonicalHash(body);
+}
+//# sourceMappingURL=corpus.js.map