@davesheffer/hunch 1.7.0 → 1.8.0

package/dist/constitution/schema.js

@@ -0,0 +1,545 @@
+import { z } from "zod";
+import { ProvenanceSchema } from "../core/types.js";
+export const POLICY_IR_VERSION = 1;
+export const POLICY_EVALUATOR = { name: "hunch-graph-policy", version: "1.3.0" };
+export const MUTATION_ENGINE = { name: "hunch-static-graph-controls", version: "5" };
+export const EXECUTABLE_BEHAVIOR_IR_VERSION = 2;
+export const BEHAVIOR_POLICY_EVALUATOR = { name: "hunch-executable-behavior", version: "1.0.0" };
+export const BEHAVIOR_MUTATION_ENGINE = { name: "hunch-behavior-controls", version: "1" };
+export const DataClassSchema = z.enum(["public", "private", "secret"]);
+export const StructuralSymbolRefSchema = z.object({
+    file: z.string().min(1),
+    name: z.string().min(1),
+    kind: z.enum(["function", "method", "class", "interface", "type"]),
+});
+export const StructuralCallRefSchema = z.object({
+    file: z.string().min(1),
+    caller: z.string().min(1),
+    callee: z.string().min(1),
+    member: z.boolean().default(false),
+});
+export const StructuralImportRefSchema = z.object({
+    file: z.string().min(1),
+    specifier: z.string().min(1),
+});
+export const StructuralDeltaSchema = z.object({
+    id: z.string().regex(/^delta_[a-f0-9]{10}$/),
+    before_commit: z.string(),
+    after_commit: z.string().min(1),
+    files: z.array(z.string()).default([]),
+    symbols: z.object({
+        added: z.array(StructuralSymbolRefSchema).default([]),
+        removed: z.array(StructuralSymbolRefSchema).default([]),
+        moved: z.array(z.object({
+            from: z.string().min(1),
+            to: z.string().min(1),
+            name: z.string().min(1),
+            kind: StructuralSymbolRefSchema.shape.kind,
+        })).default([]),
+    }),
+    calls: z.object({
+        added: z.array(StructuralCallRefSchema).default([]),
+        removed: z.array(StructuralCallRefSchema).default([]),
+    }),
+    imports: z.object({
+        added: z.array(StructuralImportRefSchema).default([]),
+        removed: z.array(StructuralImportRefSchema).default([]),
+    }),
+    content_hash: z.string().min(1),
+}).strict();
+export const CandidateAlternativeSchema = z.object({
+    id: z.string().regex(/^cand_[a-f0-9]{10}$/),
+    basis: z.string().min(1),
+    reason: z.string().min(1),
+    assertion_hash: z.string().min(1),
+}).strict();
+export const PolicyScopeSchema = z.object({
+    repos: z.array(z.string()).default([]),
+    paths: z.array(z.string()).default([]),
+    components: z.array(z.string()).default([]),
+}).default({ repos: [], paths: [], components: [] });
+export const CandidateContextSchema = z.object({
+    alternatives: z.array(CandidateAlternativeSchema).default([]),
+    uncertainty: z.array(z.string().min(1)).default([]),
+    conflicts: z.array(z.string().regex(/^pol_[a-f0-9]{10}$/)).default([]),
+    incumbent: z.string().regex(/^pol_[a-f0-9]{10}$/).nullable().default(null),
+    scope_suggestion: PolicyScopeSchema.nullable().default(null),
+    counterexamples: z.array(z.string().min(1)).default([]),
+}).default({ alternatives: [], uncertainty: [], conflicts: [], incumbent: null, scope_suggestion: null, counterexamples: [] });
+export const EvidenceEventSchema = z.object({
+    id: z.string().regex(/^ev_[a-f0-9]{10}$/),
+    kind: z.enum(["correction", "review", "incident", "decision", "revert", "bug_fix", "test_failure", "instruction", "commit"]),
+    occurred_at: z.string().datetime({ offset: true }),
+    actor: z.string().optional(),
+    repository: z.string().min(1),
+    commit: z.string().optional(),
+    files: z.array(z.string()).default([]),
+    symbols: z.array(z.string()).default([]),
+    text_ref: z.string().optional(),
+    diff_ref: z.string().optional(),
+    related_records: z.array(z.string()).default([]),
+    data_class: DataClassSchema,
+    content_hash: z.string(),
+    structural_delta: StructuralDeltaSchema.optional(),
+    compiler: z.object({
+        status: z.enum(["eligible", "compiled", "covered", "uncompilable", "conflicted"]),
+        policy: z.string().nullable().default(null),
+        reason: z.string().default(""),
+        alternatives: z.array(CandidateAlternativeSchema).optional(),
+        uncertainty: z.array(z.string().min(1)).optional(),
+        conflicts: z.array(z.string().regex(/^pol_[a-f0-9]{10}$/)).optional(),
+        incumbent: z.string().regex(/^pol_[a-f0-9]{10}$/).nullable().optional(),
+        scope_suggestion: PolicyScopeSchema.nullable().optional(),
+        counterexamples: z.array(z.string().min(1)).optional(),
+    }).optional(),
+    provenance: ProvenanceSchema,
+}).passthrough();
+export const EvidenceImportItemSchema = z.object({
+    id: z.string().min(1).max(200),
+    kind: z.enum(["review", "instruction", "decision", "commit"]),
+    occurred_at: z.string().datetime({ offset: true }),
+    actor: z.string().min(1).max(200).optional(),
+    commit: z.string().regex(/^[0-9a-fA-F]{4,64}$/, "commit must be a hexadecimal object id").optional(),
+    files: z.array(z.string().min(1).max(1024)).max(64).default([]),
+    symbols: z.array(z.string().min(1).max(500)).max(64).default([]),
+    text: z.string().min(1).max(65_536).optional(),
+    text_ref: z.string().min(1).max(1024).optional(),
+    related_records: z.array(z.string().min(1).max(200)).max(64).default([]),
+    data_class: DataClassSchema.default("public"),
+    maintainer_confirmed: z.boolean().default(false),
+}).strict().refine((item) => !!item.text || !!item.text_ref, {
+    message: "imported evidence needs text or text_ref",
+});
+export const EvidenceImportSchema = z.object({
+    version: z.literal(1),
+    source: z.enum(["pr_export", "review_export", "conversation_export"]),
+    items: z.array(EvidenceImportItemSchema).min(1).max(100),
+}).strict();
+export const PolicyStateSchema = z.enum([
+    "observed",
+    "drafted",
+    "compiled",
+    "uncompilable",
+    "validating",
+    "proposed",
+    "active_advisory",
+    "active_blocking",
+    "stale",
+    "repaired",
+    "superseded",
+    "retired",
+    "rejected",
+]);
+export const PolicySelectorSchema = z.object({
+    selector: z.string().min(1),
+});
+export const PolicyRelationSchema = z.object({
+    edges: z.array(z.enum(["calls", "imports", "depends_on", "contains"])).min(1).default(["calls", "imports"]),
+    transitive: z.boolean().default(true),
+    max_depth: z.number().int().min(1).max(64).default(6),
+});
+const ExistsAssertionSchema = z.object({
+    kind: z.literal("exists"),
+    subject: PolicySelectorSchema,
+});
+const ReachAssertionSchema = z.object({
+    kind: z.enum(["reaches", "not-reaches"]),
+    subject: PolicySelectorSchema,
+    relation: PolicyRelationSchema,
+    object: PolicySelectorSchema,
+});
+const MustPassThroughAssertionSchema = z.object({
+    kind: z.literal("must-pass-through"),
+    subject: PolicySelectorSchema,
+    relation: PolicyRelationSchema,
+    via: PolicySelectorSchema,
+    object: PolicySelectorSchema,
+});
+const ExecutableBehaviorAssertionSchema = z.object({
+    kind: z.literal("executable-behavior"),
+    test: z.object({
+        file: z.string().min(1).max(1024).refine((file) => !file.includes("\\") && !file.includes("\0") && !file.split("/").some((part) => part === "" || part === "." || part === ".."), "behavior test file must be a safe relative POSIX path"),
+        name: z.string().min(1).max(500).refine((name) => !/[\0\r\n]/.test(name), "behavior test name cannot contain control line breaks"),
+        source_commit: z.string().regex(/^[a-f0-9]{40}$/),
+        source_hash: z.string().regex(/^sha1:[a-f0-9]{40}$/),
+    }).strict(),
+    runner: z.enum(["node-test", "node-test-tsx"]),
+    attestation: z.object({
+        id: z.string().regex(/^g2behaviorattest_[a-f0-9]{10}$/),
+        content_hash: z.string().regex(/^sha1:[a-f0-9]{40}$/),
+        candidate_id: z.string().regex(/^g2behavior_[a-f0-9]{10}$/),
+        candidate_hash: z.string().regex(/^sha1:[a-f0-9]{40}$/),
+        replay_id: z.string().regex(/^g2behaviorreplay_[a-f0-9]{10}$/),
+        replay_hash: z.string().regex(/^sha1:[a-f0-9]{40}$/),
+    }).strict(),
+    dependency_snapshot_ids: z.array(z.string().regex(/^g2deps_[a-f0-9]{10}$/)).min(1).max(3),
+    timeout_ms: z.number().int().min(1).max(120_000),
+}).strict();
+export const PolicyAssertionSchema = z.discriminatedUnion("kind", [
+    ExistsAssertionSchema,
+    ReachAssertionSchema,
+    MustPassThroughAssertionSchema,
+    ExecutableBehaviorAssertionSchema,
+]);
+export const PolicyAuditEventSchema = z.object({
+    action: z.enum(["compiled", "enriched", "linked_exception", "proved", "approved_advisory", "approved_blocking", "demoted", "withdrawn", "retired", "rejected", "repaired"]),
+    actor_kind: z.enum(["system", "human"]),
+    actor: z.string().min(1),
+    at: z.string().datetime({ offset: true }),
+    reason: z.string().default(""),
+    proof: z.string().nullable().default(null),
+});
+export const PolicyAuthoritySchema = z.object({
+    kind: z.literal("human"),
+    actor: z.string().min(1),
+    event: z.string().min(1),
+    at: z.string().datetime({ offset: true }),
+});
+export const PolicySpecSchema = z.object({
+    id: z.string().regex(/^pol_[a-f0-9]{10}$/),
+    topic: z.string().min(1),
+    ir_version: z.union([z.literal(POLICY_IR_VERSION), z.literal(EXECUTABLE_BEHAVIOR_IR_VERSION)]),
+    revision: z.number().int().min(1),
+    state: PolicyStateSchema,
+    statement: z.string().min(1),
+    rationale: z.string().default(""),
+    scope: PolicyScopeSchema,
+    assertion: PolicyAssertionSchema,
+    severity: z.enum(["advisory", "warning", "blocking"]).default("warning"),
+    surfaces: z.array(z.enum(["pre_edit", "pre_commit", "ci", "mcp", "cli"])).default(["cli", "mcp"]),
+    authority: PolicyAuthoritySchema.nullable().default(null),
+    evidence: z.array(z.string()).default([]),
+    proof: z.string().nullable().default(null),
+    reversal_conditions: z.array(z.string()).default([]),
+    supersedes: z.string().nullable().default(null),
+    superseded_by: z.string().nullable().default(null),
+    exception_of: z.string().regex(/^pol_[a-f0-9]{10}$/).nullable().default(null),
+    valid_from: z.string().nullable().default(null),
+    valid_to: z.string().nullable().default(null),
+    data_class: DataClassSchema.default("public"),
+    limitations: z.array(z.string()).default([]),
+    candidate: CandidateContextSchema,
+    legacy_refs: z.array(z.string()).default([]),
+    audit: z.array(PolicyAuditEventSchema).default([]),
+    created_at: z.string().datetime({ offset: true }),
+    updated_at: z.string().datetime({ offset: true }),
+    provenance: ProvenanceSchema,
+}).passthrough().superRefine((policy, context) => {
+    if (policy.assertion.kind === "executable-behavior" && policy.ir_version !== EXECUTABLE_BEHAVIOR_IR_VERSION) {
+        context.addIssue({ code: "custom", path: ["ir_version"], message: `executable-behavior requires Policy IR v${EXECUTABLE_BEHAVIOR_IR_VERSION}` });
+    }
+    if (policy.assertion.kind !== "executable-behavior" && policy.ir_version !== POLICY_IR_VERSION) {
+        context.addIssue({ code: "custom", path: ["ir_version"], message: `graph assertions require Policy IR v${POLICY_IR_VERSION}` });
+    }
+});
+export const PolicyCompositionMemberSchema = z.object({
+    policy_id: z.string().regex(/^pol_[a-f0-9]{10}$/),
+    policy_hash: z.string().regex(/^sha1:[a-f0-9]{40}$/),
+    exception_of: z.string().regex(/^pol_[a-f0-9]{10}$/),
+    scope: PolicyScopeSchema,
+}).strict();
+export const PolicyCompositionBindingSchema = z.object({
+    kind: z.literal("parent_with_exceptions"),
+    root_policy_id: z.string().regex(/^pol_[a-f0-9]{10}$/),
+    root_policy_hash: z.string().regex(/^sha1:[a-f0-9]{40}$/),
+    members: z.array(PolicyCompositionMemberSchema).min(1),
+    composite_hash: z.string().regex(/^sha1:[a-f0-9]{40}$/),
+}).strict();
+export const PolicyEvaluationResultSchema = z.enum([
+    "satisfied",
+    "violated",
+    "not_applicable",
+    "unknown",
+    "error",
+]);
+export const BehaviorExecutionSchema = z.object({
+    commit: z.string().regex(/^[a-f0-9]{40}$/),
+    workspace: z.object({
+        kind: z.enum(["staged", "working"]),
+        base_commit: z.string().regex(/^[a-f0-9]{40}$/),
+        snapshot_hash: z.string().regex(/^sha1:[a-f0-9]{40}$/),
+        files: z.array(z.string().min(1)).max(10_000),
+    }).strict().optional(),
+    test: z.object({
+        file: z.string().min(1),
+        name: z.string().min(1),
+        source_hash: z.string().regex(/^sha1:[a-f0-9]{40}$/),
+    }).strict(),
+    runner: z.enum(["node-test", "node-test-tsx"]),
+    dependency_snapshot_id: z.string().regex(/^g2deps_[a-f0-9]{10}$/).optional(),
+    exit_code: z.number().int().nullable(),
+    selected_event: z.enum(["passed", "failed"]).nullable(),
+    error_code: z.string().min(1).optional(),
+    execution_hash: z.string().regex(/^sha1:[a-f0-9]{40}$/),
+}).strict();
+const HumanFixtureAttestationSchema = z.object({
+    actor: z.string().regex(/^(human|github|git):[^\s]+$/i, "fixture attestation requires an explicit human actor (human:, github:, or git:)"),
+    reason: z.string().min(1).max(2000),
+}).strict();
+export const ProofFixtureRefSchema = z.object({
+    kind: z.enum(["commit", "fixture", "event", "mutation"]),
+    ref: z.string().min(1),
+    label: z.string().min(1),
+    expected: PolicyEvaluationResultSchema,
+    attestation: HumanFixtureAttestationSchema.optional(),
+});
+const CorpusInputFixtureSchema = z.object({
+    ref: z.string().min(1).max(1024),
+    label: z.string().min(1).max(500),
+}).strict();
+const KnownGoodCorpusInputFixtureSchema = z.object({
+    ref: z.string().min(1).max(1024),
+    label: z.string().min(1).max(500),
+    attestation: HumanFixtureAttestationSchema.optional(),
+}).strict();
+export const ProofCorpusInputSchema = z.object({
+    known_bad: z.array(CorpusInputFixtureSchema).max(50).default([]),
+    known_good: z.array(KnownGoodCorpusInputFixtureSchema).max(50).default([]),
+}).strict().refine((value) => value.known_bad.length + value.known_good.length > 0, {
+    message: "corpus import must declare at least one known-good or known-bad fixture",
+});
+const CorpusCommitFixtureSchema = z.object({
+    kind: z.literal("commit"),
+    ref: z.string().regex(/^[a-f0-9]{40}$/),
+    label: z.string().min(1).max(500),
+    expected: PolicyEvaluationResultSchema,
+}).strict();
+const KnownGoodCorpusCommitFixtureSchema = z.object({
+    kind: z.literal("commit"),
+    ref: z.string().regex(/^[a-f0-9]{40}$/),
+    label: z.string().min(1).max(500),
+    expected: z.literal("satisfied"),
+    attestation: HumanFixtureAttestationSchema.optional(),
+}).strict();
+export const ProofCorpusSchema = z.object({
+    id: z.string().regex(/^corpus_[a-f0-9]{10}$/),
+    content_hash: z.string().min(1),
+    policy_id: z.string().regex(/^pol_[a-f0-9]{10}$/),
+    policy_hash: z.string().min(1),
+    repository: z.string().min(1),
+    data_class: DataClassSchema,
+    known_bad: z.array(CorpusCommitFixtureSchema.extend({ expected: z.literal("violated") })).max(50).default([]),
+    known_good: z.array(KnownGoodCorpusCommitFixtureSchema).max(50).default([]),
+    created_at: z.string().datetime({ offset: true }),
+}).strict();
+export const ProofPlanSchema = z.object({
+    id: z.string().regex(/^plan_[a-f0-9]{10}$/),
+    content_hash: z.string().min(1),
+    policy_id: z.string().regex(/^pol_[a-f0-9]{10}$/),
+    policy_candidate_hash: z.string().min(1),
+    repository: z.string().min(1),
+    data_class: DataClassSchema,
+    source_commit: z.string().min(1),
+    valid_from_commit: z.string().min(1),
+    evaluator: z.object({ name: z.string().min(1), version: z.string().min(1) }),
+    mutation_engine: z.object({ name: z.string().min(1), version: z.string().min(1) }).optional(),
+    composition: PolicyCompositionBindingSchema.optional(),
+    corpus_manifest: z.object({
+        id: z.string().regex(/^corpus_[a-f0-9]{10}$/),
+        content_hash: z.string().min(1),
+    }).strict().optional(),
+    corpus: z.object({
+        current_baseline: ProofFixtureRefSchema,
+        accepted_history: z.object({
+            from: z.string().min(1),
+            to: z.string().min(1),
+            first_parent: z.boolean().default(true),
+            max_commits: z.number().int().min(0).max(500),
+            exclude: z.array(z.string()).default([]),
+        }),
+        known_bad: z.array(ProofFixtureRefSchema).default([]),
+        known_good: z.array(ProofFixtureRefSchema).default([]),
+    }),
+    mutations: z.array(z.object({
+        operator: z.string().min(1),
+        base: z.string().min(1),
+        expected: PolicyEvaluationResultSchema,
+        required: z.boolean().default(true),
+    })).default([]),
+    budgets: z.object({
+        max_commits: z.number().int().min(0).max(500),
+        max_mutations: z.number().int().min(0).max(100),
+        max_minutes: z.number().int().min(1).max(120),
+    }),
+    expected: z.array(z.object({
+        leg: z.enum(["current_baseline", "known_bad", "known_good", "accepted_history", "mutations"]),
+        result: PolicyEvaluationResultSchema.optional(),
+        classification_required: z.boolean().default(false),
+    })).default([]),
+    evidence_refs: z.array(z.string()).default([]),
+    limitations: z.array(z.string()).default([]),
+    created_at: z.string().datetime({ offset: true }),
+}).strict();
+export const PolicyEvaluationSchema = z.object({
+    policy_id: z.string(),
+    policy_revision: z.number().int(),
+    result: PolicyEvaluationResultSchema,
+    evaluator: z.object({ name: z.string(), version: z.string() }),
+    repository: z.object({
+        base: z.string().optional(),
+        head: z.string(),
+        graph_hash: z.string(),
+    }),
+    matches: z.array(z.object({
+        file: z.string(),
+        line: z.number().int().optional(),
+        symbol: z.string().optional(),
+        relation_path: z.array(z.string()).optional(),
+    })),
+    explanation: z.string(),
+    evidence_refs: z.array(z.string()),
+    behavior: BehaviorExecutionSchema.optional(),
+    composition: PolicyCompositionBindingSchema.extend({
+        selected_policy_id: z.string().regex(/^pol_[a-f0-9]{10}$/),
+        applicable_policy_ids: z.array(z.string().regex(/^pol_[a-f0-9]{10}$/)).min(1),
+        member_evaluation_hashes: z.record(z.string().regex(/^pol_[a-f0-9]{10}$/), z.string().regex(/^sha1:[a-f0-9]{40}$/)),
+    }).strict().optional(),
+    deterministic_hash: z.string(),
+});
+export const ProofClassSchema = z.enum(["P0", "P1", "P2", "P3", "P4", "P5"]);
+export const EvaluationSummarySchema = z.object({
+    total: z.number().int().min(0),
+    satisfied: z.number().int().min(0),
+    violated: z.number().int().min(0),
+    not_applicable: z.number().int().min(0),
+    unknown: z.number().int().min(0),
+    error: z.number().int().min(0),
+    receipt_hashes: z.array(z.string()).default([]),
+});
+export const ReplayReceiptSchema = z.object({
+    leg: z.enum(["current_baseline", "known_bad", "known_good", "accepted_history"]),
+    commit: z.string().regex(/^[a-f0-9]{40}$/),
+    expected: PolicyEvaluationResultSchema.optional(),
+    policy_hash: z.string().min(1),
+    evaluator: z.object({ name: z.string().min(1), version: z.string().min(1) }),
+    result: PolicyEvaluationResultSchema,
+    graph_hash: z.string().min(1).optional(),
+    evaluation_hash: z.string().min(1).optional(),
+    error_code: z.string().min(1).optional(),
+    behavior: BehaviorExecutionSchema.optional(),
+    deterministic_hash: z.string().min(1),
+}).strict();
+export const HistoryDispositionClassificationSchema = z.enum([
+    "true_positive_actionable",
+    "true_positive_accepted_exception",
+    "false_positive_selector",
+    "false_positive_semantics",
+    "false_positive_stale",
+    "unknown_insufficient_parser",
+]);
+export const HistoryDispositionSchema = z.object({
+    id: z.string().regex(/^disp_[a-f0-9]{10}$/),
+    content_hash: z.string().regex(/^sha1:[a-f0-9]{40}$/),
+    policy_id: z.string().regex(/^pol_[a-f0-9]{10}$/),
+    proof_id: z.string().regex(/^proof_[a-f0-9]{10}$/),
+    policy_hash: z.string().regex(/^sha1:[a-f0-9]{40}$/),
+    plan_hash: z.string().regex(/^sha1:[a-f0-9]{40}$/),
+    commit: z.string().regex(/^[a-f0-9]{40}$/),
+    receipt_hash: z.string().regex(/^sha1:[a-f0-9]{40}$/),
+    classification: HistoryDispositionClassificationSchema,
+    actor: z.string().regex(/^(human|github|git):[^\s]+$/i, "history disposition requires an explicit human actor (human:, github:, or git:)"),
+    reason: z.string().trim().min(1).max(2000),
+    supersedes: z.string().regex(/^disp_[a-f0-9]{10}$/).nullable().default(null),
+    data_class: DataClassSchema,
+    created_at: z.string().datetime({ offset: true }),
+}).strict();
+export const ShadowEvaluationRecordSchema = z.object({
+    record_type: z.literal("evaluation"),
+    id: z.string().regex(/^shadow_[a-f0-9]{10}$/),
+    content_hash: z.string().regex(/^sha1:[a-f0-9]{40}$/),
+    policy_id: z.string().regex(/^pol_[a-f0-9]{10}$/),
+    proof_id: z.string().regex(/^proof_[a-f0-9]{10}$/),
+    policy_hash: z.string().regex(/^sha1:[a-f0-9]{40}$/),
+    plan_hash: z.string().regex(/^sha1:[a-f0-9]{40}$/),
+    evaluation: PolicyEvaluationSchema,
+    also_detected_by: z.array(z.string().regex(/^pol_[a-f0-9]{10}$/)).default([]),
+    latency_ms: z.number().nonnegative(),
+    data_class: DataClassSchema,
+    observed_at: z.string().datetime({ offset: true }),
+}).strict();
+export const ShadowDispositionSchema = z.object({
+    record_type: z.literal("disposition"),
+    id: z.string().regex(/^sdisp_[a-f0-9]{10}$/),
+    content_hash: z.string().regex(/^sha1:[a-f0-9]{40}$/),
+    shadow_id: z.string().regex(/^shadow_[a-f0-9]{10}$/),
+    policy_id: z.string().regex(/^pol_[a-f0-9]{10}$/),
+    proof_id: z.string().regex(/^proof_[a-f0-9]{10}$/),
+    policy_hash: z.string().regex(/^sha1:[a-f0-9]{40}$/),
+    evaluation_hash: z.string().regex(/^sha1:[a-f0-9]{40}$/),
+    classification: HistoryDispositionClassificationSchema,
+    actor: z.string().regex(/^(human|github|git):[^\s]+$/i, "shadow disposition requires an explicit human actor (human:, github:, or git:)"),
+    reason: z.string().trim().min(1).max(2000),
+    supersedes: z.string().regex(/^sdisp_[a-f0-9]{10}$/).nullable().default(null),
+    data_class: DataClassSchema,
+    created_at: z.string().datetime({ offset: true }),
+}).strict();
+export const ShadowRecordSchema = z.discriminatedUnion("record_type", [ShadowEvaluationRecordSchema, ShadowDispositionSchema]);
+export const MutationReceiptSchema = z.object({
+    id: z.string().regex(/^mut_[a-f0-9]{10}$/),
+    kind: z.enum(["primary", "control"]),
+    operator: z.string().min(1),
+    required: z.boolean(),
+    engine: z.object({ name: z.string().min(1), version: z.string().min(1) }),
+    policy_hash: z.string().min(1),
+    base_commit: z.string().min(1),
+    base_graph_hash: z.string().min(1),
+    mutated_graph_hash: z.string().min(1).optional(),
+    expected: PolicyEvaluationResultSchema,
+    result: PolicyEvaluationResultSchema,
+    passed: z.boolean(),
+    parseability: z.enum(["parseable", "unparseable", "not_applicable"]),
+    graph_diff: z.object({
+        added_symbols: z.array(z.string()).default([]),
+        removed_symbols: z.array(z.string()).default([]),
+        added_edges: z.array(z.string()).default([]),
+        removed_edges: z.array(z.string()).default([]),
+    }).strict(),
+    parser_control: z.object({
+        source_hash: z.string().min(1),
+        observed_target_calls: z.array(z.string()).default([]),
+        observed_target_imports: z.array(z.string()).default([]),
+    }).strict().optional(),
+    source_patch: z.object({
+        files: z.array(z.string()).min(1),
+        diff: z.string().min(1).max(65536),
+        diff_hash: z.string().min(1),
+    }).strict().optional(),
+    evaluation_hash: z.string().min(1).optional(),
+    error_code: z.string().min(1).optional(),
+    behavior: BehaviorExecutionSchema.optional(),
+    deterministic_hash: z.string().min(1),
+}).strict();
+const MutationControlSummarySchema = z.object({
+    total: z.number().int().min(0),
+    passed: z.number().int().min(0),
+    failed: z.number().int().min(0),
+    receipt_hashes: z.array(z.string()).default([]),
+}).strict();
+const ProjectChecksSchema = z.object({
+    build: z.enum(["not_run", "passed", "failed", "error"]).default("not_run"),
+    test: z.enum(["not_run", "passed", "failed", "error"]).default("not_run"),
+    required_for_evaluator_sensitivity: z.boolean().default(false),
+}).strict();
+export const PolicyProofSchema = z.object({
+    id: z.string().regex(/^proof_[a-f0-9]{10}$/),
+    plan_hash: z.string(),
+    policy_hash: z.string(),
+    evaluator: z.object({ name: z.string(), version: z.string() }),
+    mutation_engine: z.object({ name: z.string(), version: z.string() }).optional(),
+    composition: PolicyCompositionBindingSchema.optional(),
+    generated_at: z.string().datetime({ offset: true }),
+    current: EvaluationSummarySchema,
+    known_bad: EvaluationSummarySchema,
+    known_good: EvaluationSummarySchema,
+    accepted_history: EvaluationSummarySchema.extend({ classified_hits: z.array(z.string()).default([]) }),
+    mutations: EvaluationSummarySchema.extend({ operator_coverage: z.record(z.string(), z.number().int().min(0)).default({}) }),
+    replay_receipts: z.array(ReplayReceiptSchema).default([]),
+    mutation_receipts: z.array(MutationReceiptSchema).default([]),
+    mutation_controls: MutationControlSummarySchema.default({ total: 0, passed: 0, failed: 0, receipt_hashes: [] }),
+    project_checks: ProjectChecksSchema.default({ build: "not_run", test: "not_run", required_for_evaluator_sensitivity: false }),
+    limitations: z.array(z.string()).default([]),
+    proof_class: ProofClassSchema,
+    artifact_hashes: z.record(z.string(), z.string()).default({}),
+    data_class: DataClassSchema,
+}).passthrough();
+//# sourceMappingURL=schema.js.map

package/dist/constitution/scorecard.js

@@ -0,0 +1,106 @@
+import { z } from "zod";
+import { canonicalHash, canonicalJson } from "./canonical.js";
+import { PolicyAssertionSchema } from "./schema.js";
+const ScopeSchema = z.object({
+    repos: z.array(z.string()).default([]),
+    paths: z.array(z.string()).default([]),
+    components: z.array(z.string()).default([]),
+}).strict();
+const CompilerOutcomeSchema = z.object({
+    outcome: z.enum(["assertion", "uncompilable", "conflicted", "covered"]),
+    assertion: PolicyAssertionSchema.optional(),
+    scope: ScopeSchema.optional(),
+    uncertainty: z.array(z.string()).default([]),
+    conflicts: z.array(z.string()).default([]),
+    incumbent: z.string().nullable().default(null),
+    reason: z.string().default(""),
+}).strict().superRefine((value, context) => {
+    if (value.outcome === "assertion" && (!value.assertion || !value.scope)) {
+        context.addIssue({ code: "custom", message: "assertion outcomes require exact assertion and scope" });
+    }
+    if (value.outcome !== "assertion" && (value.assertion || value.scope)) {
+        context.addIssue({ code: "custom", message: "non-assertion outcomes cannot smuggle assertion semantics" });
+    }
+});
+export const CompilerCaseBankSchema = z.object({
+    version: z.literal(1),
+    experiment: z.literal("EXP-03"),
+    threshold: z.number().min(0).max(1).default(0.7),
+    preregistered_metric: z.literal("intended supported assertion or honest non-minting classification"),
+    cases: z.array(z.object({
+        id: z.string().regex(/^exp03_[a-z0-9_]+$/),
+        family: z.string().min(1),
+        evidence: z.string().min(1),
+        expected: CompilerOutcomeSchema,
+        actual: CompilerOutcomeSchema,
+    }).strict()).min(20),
+}).strict();
+function semanticOutcome(value) {
+    return value.outcome === "assertion"
+        ? { outcome: value.outcome, assertion: value.assertion, scope: value.scope }
+        : { outcome: value.outcome, conflicts: [...value.conflicts].sort(), incumbent: value.incumbent };
+}
+function wilson(successes, total) {
+    if (!total)
+        return { low: 0, high: 0 };
+    const z95 = 1.959963984540054;
+    const p = successes / total;
+    const denominator = 1 + (z95 * z95) / total;
+    const centre = p + (z95 * z95) / (2 * total);
+    const spread = z95 * Math.sqrt((p * (1 - p) + (z95 * z95) / (4 * total)) / total);
+    return { low: (centre - spread) / denominator, high: (centre + spread) / denominator };
+}
+/** Score only exact semantic outcomes. Wording/reason text is diagnostic and
+ * never rescues a wrong assertion. An expected refusal that becomes any
+ * assertion is counted separately as a silent semantic substitution. */
+export function scoreCompilerCaseBank(raw) {
+    const bank = CompilerCaseBankSchema.parse(raw);
+    const details = bank.cases.map((item) => {
+        const semanticMatch = canonicalJson(semanticOutcome(item.expected)) === canonicalJson(semanticOutcome(item.actual));
+        const uncertaintyMatch = item.actual.uncertainty.length >= item.expected.uncertainty.length;
+        const correct = semanticMatch && uncertaintyMatch;
+        const silentSubstitution = item.expected.outcome !== "assertion" && item.actual.outcome === "assertion";
+        return {
+            id: item.id,
+            family: item.family,
+            correct,
+            silent_substitution: silentSubstitution,
+            reason: correct ? "exact intended semantics" : silentSubstitution ? "unsupported meaning was silently substituted" : "actual compiler classification differs from the reviewed expectation",
+        };
+    });
+    const numerator = details.filter((item) => item.correct).length;
+    const denominator = details.length;
+    const rate = numerator / denominator;
+    const byOutcome = Object.fromEntries(["assertion", "uncompilable", "conflicted", "covered"].map((outcome) => {
+        const matching = bank.cases.map((item, index) => ({ item, detail: details[index] })).filter(({ item }) => item.expected.outcome === outcome);
+        return [outcome, { total: matching.length, correct: matching.filter(({ detail }) => detail.correct).length }];
+    }));
+    const body = {
+        experiment: "EXP-03",
+        denominator,
+        numerator,
+        incorrect: denominator - numerator,
+        silent_semantic_substitutions: details.filter((item) => item.silent_substitution).length,
+        rate,
+        threshold: bank.threshold,
+        risk_difference_vs_threshold: rate - bank.threshold,
+        wilson_95: wilson(numerator, denominator),
+        passed: rate >= bank.threshold && details.every((item) => !item.silent_substitution),
+        by_outcome: byOutcome,
+        cases: details,
+    };
+    return { ...body, deterministic_hash: canonicalHash(body) };
+}
+export function renderCompilerScorecard(card) {
+    const pct = (value) => `${(value * 100).toFixed(1)}%`;
+    return [
+        `EXP-03 Intent Compiler scorecard — ${card.passed ? "PASS" : "FAIL"}`,
+        `  primary: ${card.numerator}/${card.denominator} (${pct(card.rate)}) exact or honest outcomes`,
+        `  threshold: ${pct(card.threshold)} · risk difference: ${(card.risk_difference_vs_threshold * 100).toFixed(1)} pp`,
+        `  Wilson 95% interval: ${pct(card.wilson_95.low)}–${pct(card.wilson_95.high)}`,
+        `  silent semantic substitutions: ${card.silent_semantic_substitutions}`,
+        ...Object.entries(card.by_outcome).map(([outcome, result]) => `  ${outcome}: ${result.correct}/${result.total}`),
+        `  receipt: ${card.deterministic_hash}`,
+    ].join("\n");
+}
+//# sourceMappingURL=scorecard.js.map