@davesheffer/hunch 1.31.1 → 1.32.0

package/dist/constitution/scorecard.d.ts

@@ -0,0 +1,219 @@
+import { z } from "zod";
+export declare const CompilerCaseBankSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    experiment: z.ZodLiteral<"EXP-03">;
+    threshold: z.ZodDefault<z.ZodNumber>;
+    preregistered_metric: z.ZodLiteral<"intended supported assertion or honest non-minting classification">;
+    cases: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        family: z.ZodString;
+        evidence: z.ZodString;
+        expected: z.ZodObject<{
+            outcome: z.ZodEnum<{
+                conflicted: "conflicted";
+                covered: "covered";
+                uncompilable: "uncompilable";
+                assertion: "assertion";
+            }>;
+            assertion: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"exists">;
+                subject: z.ZodObject<{
+                    selector: z.ZodString;
+                }, z.core.$strip>;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodEnum<{
+                    reaches: "reaches";
+                    "not-reaches": "not-reaches";
+                }>;
+                subject: z.ZodObject<{
+                    selector: z.ZodString;
+                }, z.core.$strip>;
+                relation: z.ZodObject<{
+                    edges: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+                        depends_on: "depends_on";
+                        calls: "calls";
+                        imports: "imports";
+                        contains: "contains";
+                    }>>>;
+                    transitive: z.ZodDefault<z.ZodBoolean>;
+                    max_depth: z.ZodDefault<z.ZodNumber>;
+                }, z.core.$strip>;
+                object: z.ZodObject<{
+                    selector: z.ZodString;
+                }, z.core.$strip>;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"must-pass-through">;
+                subject: z.ZodObject<{
+                    selector: z.ZodString;
+                }, z.core.$strip>;
+                relation: z.ZodObject<{
+                    edges: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+                        depends_on: "depends_on";
+                        calls: "calls";
+                        imports: "imports";
+                        contains: "contains";
+                    }>>>;
+                    transitive: z.ZodDefault<z.ZodBoolean>;
+                    max_depth: z.ZodDefault<z.ZodNumber>;
+                }, z.core.$strip>;
+                via: z.ZodObject<{
+                    selector: z.ZodString;
+                }, z.core.$strip>;
+                object: z.ZodObject<{
+                    selector: z.ZodString;
+                }, z.core.$strip>;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"executable-behavior">;
+                test: z.ZodObject<{
+                    file: z.ZodString;
+                    name: z.ZodString;
+                    source_commit: z.ZodString;
+                    source_hash: z.ZodString;
+                }, z.core.$strict>;
+                runner: z.ZodEnum<{
+                    "node-test": "node-test";
+                    "node-test-tsx": "node-test-tsx";
+                }>;
+                attestation: z.ZodObject<{
+                    id: z.ZodString;
+                    content_hash: z.ZodString;
+                    candidate_id: z.ZodString;
+                    candidate_hash: z.ZodString;
+                    replay_id: z.ZodString;
+                    replay_hash: z.ZodString;
+                }, z.core.$strict>;
+                dependency_snapshot_ids: z.ZodArray<z.ZodString>;
+                timeout_ms: z.ZodNumber;
+            }, z.core.$strict>], "kind">>;
+            scope: z.ZodOptional<z.ZodObject<{
+                repos: z.ZodDefault<z.ZodArray<z.ZodString>>;
+                paths: z.ZodDefault<z.ZodArray<z.ZodString>>;
+                components: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            }, z.core.$strict>>;
+            uncertainty: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            conflicts: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            incumbent: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+            reason: z.ZodDefault<z.ZodString>;
+        }, z.core.$strict>;
+        actual: z.ZodObject<{
+            outcome: z.ZodEnum<{
+                conflicted: "conflicted";
+                covered: "covered";
+                uncompilable: "uncompilable";
+                assertion: "assertion";
+            }>;
+            assertion: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"exists">;
+                subject: z.ZodObject<{
+                    selector: z.ZodString;
+                }, z.core.$strip>;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodEnum<{
+                    reaches: "reaches";
+                    "not-reaches": "not-reaches";
+                }>;
+                subject: z.ZodObject<{
+                    selector: z.ZodString;
+                }, z.core.$strip>;
+                relation: z.ZodObject<{
+                    edges: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+                        depends_on: "depends_on";
+                        calls: "calls";
+                        imports: "imports";
+                        contains: "contains";
+                    }>>>;
+                    transitive: z.ZodDefault<z.ZodBoolean>;
+                    max_depth: z.ZodDefault<z.ZodNumber>;
+                }, z.core.$strip>;
+                object: z.ZodObject<{
+                    selector: z.ZodString;
+                }, z.core.$strip>;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"must-pass-through">;
+                subject: z.ZodObject<{
+                    selector: z.ZodString;
+                }, z.core.$strip>;
+                relation: z.ZodObject<{
+                    edges: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+                        depends_on: "depends_on";
+                        calls: "calls";
+                        imports: "imports";
+                        contains: "contains";
+                    }>>>;
+                    transitive: z.ZodDefault<z.ZodBoolean>;
+                    max_depth: z.ZodDefault<z.ZodNumber>;
+                }, z.core.$strip>;
+                via: z.ZodObject<{
+                    selector: z.ZodString;
+                }, z.core.$strip>;
+                object: z.ZodObject<{
+                    selector: z.ZodString;
+                }, z.core.$strip>;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"executable-behavior">;
+                test: z.ZodObject<{
+                    file: z.ZodString;
+                    name: z.ZodString;
+                    source_commit: z.ZodString;
+                    source_hash: z.ZodString;
+                }, z.core.$strict>;
+                runner: z.ZodEnum<{
+                    "node-test": "node-test";
+                    "node-test-tsx": "node-test-tsx";
+                }>;
+                attestation: z.ZodObject<{
+                    id: z.ZodString;
+                    content_hash: z.ZodString;
+                    candidate_id: z.ZodString;
+                    candidate_hash: z.ZodString;
+                    replay_id: z.ZodString;
+                    replay_hash: z.ZodString;
+                }, z.core.$strict>;
+                dependency_snapshot_ids: z.ZodArray<z.ZodString>;
+                timeout_ms: z.ZodNumber;
+            }, z.core.$strict>], "kind">>;
+            scope: z.ZodOptional<z.ZodObject<{
+                repos: z.ZodDefault<z.ZodArray<z.ZodString>>;
+                paths: z.ZodDefault<z.ZodArray<z.ZodString>>;
+                components: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            }, z.core.$strict>>;
+            uncertainty: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            conflicts: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            incumbent: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+            reason: z.ZodDefault<z.ZodString>;
+        }, z.core.$strict>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type CompilerCaseBank = z.infer<typeof CompilerCaseBankSchema>;
+export interface CompilerScorecard {
+    experiment: "EXP-03";
+    denominator: number;
+    numerator: number;
+    incorrect: number;
+    silent_semantic_substitutions: number;
+    rate: number;
+    threshold: number;
+    risk_difference_vs_threshold: number;
+    wilson_95: {
+        low: number;
+        high: number;
+    };
+    passed: boolean;
+    by_outcome: Record<"assertion" | "uncompilable" | "conflicted" | "covered", {
+        total: number;
+        correct: number;
+    }>;
+    cases: Array<{
+        id: string;
+        family: string;
+        correct: boolean;
+        silent_substitution: boolean;
+        reason: string;
+    }>;
+    deterministic_hash: string;
+}
+/** 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 declare function scoreCompilerCaseBank(raw: unknown): CompilerScorecard;
+export declare function renderCompilerScorecard(card: CompilerScorecard): string;

package/dist/constitution/service.d.ts

@@ -0,0 +1,398 @@
+import type { HunchStore } from "../store/hunchStore.js";
+import { type CompilePolicyOptions } from "./compiler.js";
+import { type GraphSnapshot } from "./evaluator.js";
+import { PolicyRepository } from "./repository.js";
+import type { PolicyEvaluation, PolicyProof, PolicySpec, ProofCorpus } from "./schema.js";
+import type { ProofPlan } from "./schema.js";
+import { type BootstrapOptions, type BootstrapReport } from "./bootstrap.js";
+import { type StructuralInspection } from "./structural.js";
+import { type ProofPlanOptions } from "./plan.js";
+import { type LocalEvidenceOptions, type LocalEvidenceReport } from "./adapters.js";
+import { type ProofCard } from "./card.js";
+import { type ShadowPrecisionReport, type ShadowPrecisionThresholds } from "./shadow.js";
+import type { HistoryDisposition, HistoryDispositionClassification, ShadowDisposition, ShadowEvaluationRecord } from "./schema.js";
+import { G2_RUNBOOK_CATEGORIES, G2EvidenceRepository, type CompileG2PlanInput, type G2ReadinessReport, type G2ShadowQueue, type G2ShadowBackfillReport, type G2ShadowSweepReport, type RunbookRehearsal } from "./g2.js";
+import { type G2CandidateReviewOptions, type G2CandidateReviewReport } from "./g2Candidates.js";
+import { G2CandidateAttestationRepository, type G2CandidateAttestation } from "./g2CandidateAttestation.js";
+import { type G2BehaviorCandidateReviewOptions, type G2BehaviorCandidateReview, type G2BehaviorReplayReceipt } from "./g2BehaviorCandidates.js";
+import { type G2BehaviorDependencySnapshotReceipt } from "./g2BehaviorDependencies.js";
+import { G2BehaviorAttestationRepository, type G2BehaviorAttestation } from "./g2BehaviorAttestation.js";
+import { type G2BehaviorMaterializationAssessment } from "./g2BehaviorMaterialization.js";
+import { type G2BehaviorPolicyMaterialization } from "./g2BehaviorPolicyMaterializer.js";
+import { type BehaviorEvaluationOptions } from "./behaviorEvaluator.js";
+import { type G2OperationalDrillReceipt } from "./g2Drills.js";
+import { G3EvidenceRepository, type CompileExperimentPreregistrationInput, type CompileG3PlanInput, type G3ReadinessReport, type ProofReviewMeasurement, type ExperimentPreregistration, type AdapterConformanceReceipt } from "./g3.js";
+import { ExperimentRepository, experimentReviewGuide, type CompileExperimentCaseBankInput, type Exp03ReviewResponse, type CompileExperimentRunInput, type ExperimentCaseBank, type ExperimentFollowup, type ExperimentOutcome, type ExperimentReport, type ExperimentReviewStart, type CompileExperimentReviewerQualificationInput, type ExperimentReviewerQualification, type ExperimentRun, type ExperimentStop } from "./experiment.js";
+import { type CorrectionPolicySweep, type CorrectionPolicyUpgrade, type CorrectionUpgradeOptions } from "./correctionPolicyMaterializer.js";
+export interface PolicyEvaluationSet {
+    policy: PolicySpec;
+    evaluation: PolicyEvaluation;
+    blocks: boolean;
+    strict_error: boolean;
+    gate_error?: string;
+}
+/** Client-neutral evaluator receipt plus the fail-closed enforcement decision.
+ * The canonical evaluation hash remains untouched; adapters expose the wrapper
+ * so a persisted active-state configuration error can never disappear behind a
+ * valid-looking satisfied/violated receipt. */
+export type PolicyEvaluationEnvelope = PolicyEvaluation & {
+    enforcement: {
+        blocks: boolean;
+        strict_error: boolean;
+        gate_error: string | null;
+    };
+};
+export declare function policyEvaluationEnvelope(result: PolicyEvaluationSet): PolicyEvaluationEnvelope;
+export interface PolicyRelationSummary {
+    id: string;
+    statement: string;
+    state: PolicySpec["state"];
+    severity: PolicySpec["severity"];
+    data_class: PolicySpec["data_class"];
+    scope: PolicySpec["scope"];
+    exception_of: string | null;
+}
+export interface PolicyExceptionRelations {
+    policy: PolicyRelationSummary;
+    exception_parent: PolicyRelationSummary | null;
+    missing_exception_parent: string | null;
+    exceptions: PolicyRelationSummary[];
+}
+export interface PolicyConsolidationCandidate {
+    anchor: PolicyRelationSummary;
+    suggested_scope: PolicySpec["scope"] | null;
+    status: "unavailable" | "reviewable" | "challenged";
+    members: PolicyRelationSummary[];
+    independent_decisions: string[];
+    counterexamples: string[];
+    conflicts: string[];
+    exception_linked_members: string[];
+    reasons: string[];
+}
+export interface PolicyHistoryDispositionView {
+    policy_id: string;
+    proof_id: string;
+    violations: Array<{
+        commit: string;
+        receipt_hash: string;
+        disposition: HistoryDisposition | null;
+    }>;
+    current: HistoryDisposition[];
+    audit: HistoryDisposition[];
+}
+export interface PolicyShadowView extends ShadowPrecisionReport {
+    evaluations: Array<{
+        record: ShadowEvaluationRecord;
+        disposition: ShadowDisposition | null;
+    }>;
+    disposition_audit: ShadowDisposition[];
+}
+export declare function shadowCommitEligible(root: string, policy: PolicySpec, commit: string): boolean;
+/** The commit a shadow receipt's ancestry check must be anchored to.
+ *
+ *  A WORKSPACE receipt retains a content-addressed PSEUDO-head for dedupe — it is not a
+ *  real git rev. Handing it to `git merge-base --is-ancestor` makes git exit with
+ *  neither 0 nor 1, which shadowCommitEligible turns into a THROW, so the surface
+ *  hard-fails instead of reporting. Ancestry is always the real base commit.
+ *
+ *  Shared because that rule was previously written out at one call site (with this
+ *  explanation attached) and silently omitted at another — the same one-side-only drift
+ *  as OVERLAY_IGNORE. One definition, both callers. */
+export declare function shadowAncestryCommit(record: ShadowEvaluationRecord): string;
+export declare class ConstitutionService {
+    private readonly store;
+    private readonly root;
+    readonly repository: PolicyRepository;
+    readonly g2Repository: G2EvidenceRepository;
+    readonly g3Repository: G3EvidenceRepository;
+    readonly experimentRepository: ExperimentRepository;
+    readonly g2CandidateRepository: G2CandidateAttestationRepository;
+    readonly g2BehaviorAttestationRepository: G2BehaviorAttestationRepository;
+    constructor(store: HunchStore, root: string);
+    createG2Plan(input: CompileG2PlanInput, opts?: {
+        now?: string;
+    }): {
+        id: string;
+        content_hash: string;
+        gate: "G2";
+        policy_ids: string[];
+        runbooks: {
+            evaluator_error: string;
+            false_positive: string;
+            private_leak: string;
+            stale_policy: string;
+            provider_outage: string;
+            corrupt_graph: string;
+            adapter_break: string;
+        };
+        min_shadow_applicable: number;
+        actor: string;
+        reason: string;
+        supersedes: string | null;
+        data_class: "private";
+        authority: "none";
+        created_at: string;
+    };
+    recordRunbookRehearsal(runbookId: string, result: "passed" | "failed", actor: string, evidenceHashes: string[], notes: string, opts?: {
+        now?: string;
+        supersedes?: string | null;
+    }): RunbookRehearsal;
+    g2Readiness(): G2ReadinessReport;
+    registerG3Experiment(input: CompileExperimentPreregistrationInput, opts?: {
+        now?: string;
+    }): ExperimentPreregistration;
+    createG3Plan(input: CompileG3PlanInput, opts?: {
+        now?: string;
+    }): {
+        id: string;
+        content_hash: string;
+        gate: "G3";
+        g2_readiness_hash: string;
+        policy_ids: string[];
+        clients: string[];
+        experiments: {
+            retrieval: string;
+            compiler: string;
+        };
+        actor: string;
+        reason: string;
+        supersedes: string | null;
+        data_class: "private";
+        authority: "none";
+        created_at: string;
+    };
+    recordG3ProofReview(input: {
+        policy_id: string;
+        reviewer: string;
+        duration_ms: number;
+        comprehension: {
+            requirement: "correct" | "incorrect";
+            limitations: "correct" | "incorrect";
+            authority: "correct" | "incorrect";
+        };
+        notes: string;
+        supersedes?: string | null;
+    }, opts?: {
+        now?: string;
+    }): ProofReviewMeasurement;
+    g3AdapterConformance(opts?: {
+        timeoutMs?: number;
+        now?: string;
+    }): AdapterConformanceReceipt;
+    g3Readiness(): G3ReadinessReport;
+    validateExperimentCaseBank(input: CompileExperimentCaseBankInput, opts?: {
+        now?: string;
+    }): ExperimentCaseBank;
+    lockExperimentCaseBank(input: CompileExperimentCaseBankInput, opts?: {
+        now?: string;
+    }): ExperimentCaseBank;
+    createExperimentRun(caseBankId: string, input: CompileExperimentRunInput, opts?: {
+        now?: string;
+    }): ExperimentRun;
+    experimentRun(runId: string): ExperimentRun;
+    executeExperimentRun(runId: string, opts?: {
+        limit?: number;
+        timeoutMs?: number;
+        now?: string;
+    }): {
+        outcomes: ExperimentOutcome[];
+        report: ExperimentReport;
+    };
+    nextExperimentReview(runId: string, reviewer: string, opts?: {
+        now?: string;
+    }): {
+        start: ExperimentReviewStart;
+        assignment: ExperimentRun["assignments"][number];
+        treatment: unknown;
+        review_guide: ReturnType<typeof experimentReviewGuide>;
+    };
+    qualifyExperimentReviewer(input: CompileExperimentReviewerQualificationInput, opts?: {
+        now?: string;
+    }): ExperimentReviewerQualification;
+    /** Resolve an EXP-03 run/assignment/case triple (the shared lookup for both
+     *  review-submission dialects). */
+    private resolveExp03Assignment;
+    /** Raw metrics-vocabulary submission — the ORIGINAL revision-1 contract, kept
+     *  byte-identical for the append-only pilot. Revision-2 cases are refused here:
+     *  they must go through the standardized plain-language template (dec_0be4fd3717)
+     *  so the presented question and the recorded outcome cannot drift apart. */
+    submitExperimentReview(runId: string, assignmentId: string, input: {
+        reviewer: string;
+        decision: "accepted_precise" | "accepted_edited" | "rejected" | "uncompilable" | "abandoned" | "timeout";
+        precise: boolean;
+        proof_inspected: boolean;
+        result: string | null;
+        silent_semantic_substitution: boolean;
+        rejection_reason: string | null;
+        confirmed_private_leak: boolean;
+        data_loss_or_corruption: boolean;
+        unsafe_evaluator_behavior: boolean;
+        reason: string;
+    }, opts?: {
+        now?: string;
+    }): ExperimentOutcome;
+    /** Revision-2 standardized submission: the reviewer answers in the SAME
+     *  plain-language vocabulary the treatment presented (choice + rule + one
+     *  sentence); the deterministic mapper translates it into canonical metrics.
+     *  Revision-1 cases are refused (the mapper throws) — they keep the raw path. */
+    respondExperimentReview(runId: string, assignmentId: string, input: Exp03ReviewResponse & {
+        reviewer: string;
+        confirmed_private_leak?: boolean;
+        data_loss_or_corruption?: boolean;
+        unsafe_evaluator_behavior?: boolean;
+    }, opts?: {
+        now?: string;
+    }): ExperimentOutcome;
+    /** The shared review-completion core: machine-owned timing, append-only dedup,
+     *  derived edit distance, and the outcome write. Both dialects land here. */
+    private completeExp03Review;
+    recordExperimentFollowup(runId: string, assignmentId: string, input: {
+        reviewer: string;
+        reversed: boolean | null;
+        missing_reason: string | null;
+        notes: string;
+        supersedes?: string | null;
+    }, opts?: {
+        now?: string;
+    }): ExperimentFollowup;
+    stopExperiment(runId: string, input: {
+        category: ExperimentStop["category"];
+        actor: string;
+        reason: string;
+        evidence_hashes: string[];
+    }, opts?: {
+        now?: string;
+    }): ExperimentStop;
+    experimentReport(runId: string): ExperimentReport;
+    g2ShadowSweep(opts?: {
+        now?: string;
+    }): G2ShadowSweepReport;
+    g2ShadowBackfill(maxCommits?: number, opts?: {
+        now?: string;
+    }): G2ShadowBackfillReport;
+    g2OperationalDrill(category: (typeof G2_RUNBOOK_CATEGORIES)[number]): G2OperationalDrillReceipt;
+    g2CandidateReview(opts?: G2CandidateReviewOptions): G2CandidateReviewReport;
+    attestG2Candidate(candidateId: string, reviewHash: string, disposition: "selected" | "rejected", actor: string, reason: string, opts?: G2CandidateReviewOptions & {
+        now?: string;
+        supersedes?: string | null;
+    }): G2CandidateAttestation;
+    g2BehaviorCandidateReview(opts?: G2BehaviorCandidateReviewOptions): G2BehaviorCandidateReview;
+    g2BehaviorCandidateReplay(candidateId: string, reviewHash: string, opts?: G2BehaviorCandidateReviewOptions & {
+        timeoutMs?: number;
+    }): G2BehaviorReplayReceipt;
+    g2BehaviorMaterializationAssessment(opts?: G2BehaviorCandidateReviewOptions): G2BehaviorMaterializationAssessment;
+    g2BehaviorPolicyMaterialize(opts?: G2BehaviorCandidateReviewOptions & {
+        allowInstallScripts?: string[];
+        dependencyTimeoutMs?: number;
+        now?: string;
+    }): G2BehaviorPolicyMaterialization;
+    g2BehaviorDependencySnapshots(candidateId: string, reviewHash: string, opts?: G2BehaviorCandidateReviewOptions & {
+        allowInstallScripts?: string[];
+        timeoutMs?: number;
+    }): G2BehaviorDependencySnapshotReceipt;
+    attestG2BehaviorCandidate(candidateId: string, reviewHash: string, disposition: "selected" | "rejected", actor: string, reason: string, opts?: G2BehaviorCandidateReviewOptions & {
+        timeoutMs?: number;
+        now?: string;
+        supersedes?: string | null;
+    }): G2BehaviorAttestation;
+    g2ShadowQueue(limit?: number): G2ShadowQueue;
+    list(opts?: {
+        publicOnly?: boolean;
+        privateOnly?: boolean;
+        state?: string;
+    }): PolicySpec[];
+    get(id: string, opts?: {
+        publicOnly?: boolean;
+        privateOnly?: boolean;
+    }): PolicySpec;
+    private composition;
+    proof(id: string, opts?: {
+        publicOnly?: boolean;
+        privateOnly?: boolean;
+    }): PolicyProof;
+    card(id: string, opts?: {
+        publicOnly?: boolean;
+        privateOnly?: boolean;
+    }): ProofCard;
+    corpus(id: string, opts?: {
+        publicOnly?: boolean;
+        privateOnly?: boolean;
+    }): ProofCorpus;
+    importCorpus(id: string, raw: unknown, opts?: {
+        now?: string;
+    }): ProofCorpus;
+    compile(decisionId: string, opts?: CompilePolicyOptions): PolicySpec;
+    bootstrap(opts?: BootstrapOptions): BootstrapReport;
+    inspectStructural(decisionId: string, opts?: {
+        publicOnly?: boolean;
+        privateOnly?: boolean;
+    }): StructuralInspection;
+    ingest(opts?: LocalEvidenceOptions): LocalEvidenceReport;
+    upgradeCorrection(id: string, opts?: CorrectionUpgradeOptions): CorrectionPolicyUpgrade;
+    upgradeCorrections(opts?: CorrectionUpgradeOptions): CorrectionPolicySweep;
+    plan(id: string, opts?: ProofPlanOptions): ProofPlan;
+    prove(id: string, opts?: {
+        now?: string;
+        repositoryName?: string;
+    }): {
+        policy: PolicySpec;
+        proof: PolicyProof;
+    };
+    approve(id: string, mode: "advisory" | "blocking", actor: string, opts?: {
+        now?: string;
+    }): PolicySpec;
+    historyDispositions(id: string, opts?: {
+        publicOnly?: boolean;
+        privateOnly?: boolean;
+    }): PolicyHistoryDispositionView;
+    classifyHistory(id: string, commit: string, classification: HistoryDispositionClassification, actor: string, reason: string, opts?: {
+        now?: string;
+        supersedes?: string | null;
+    }): HistoryDisposition;
+    private compileShadowRecord;
+    recordShadow(id: string, opts?: {
+        now?: string;
+        latencyMs?: number;
+        commit?: string;
+        snapshot?: GraphSnapshot;
+        behavior?: BehaviorEvaluationOptions;
+    }): ShadowEvaluationRecord;
+    classifyShadow(id: string, shadowId: string, classification: HistoryDispositionClassification, actor: string, reason: string, opts?: {
+        now?: string;
+        supersedes?: string | null;
+    }): ShadowDisposition;
+    shadowReport(id: string, thresholds?: Partial<ShadowPrecisionThresholds>, opts?: {
+        publicOnly?: boolean;
+        privateOnly?: boolean;
+    }): PolicyShadowView;
+    demote(id: string, actor: string, reason: string, opts?: {
+        now?: string;
+    }): PolicySpec;
+    /** Targeted advisory withdrawal (§57): active_advisory → proposed; authority
+     *  returns to the human pool and the policy re-enters the escalation loop. */
+    withdraw(id: string, actor: string, reason: string, opts?: {
+        now?: string;
+    }): PolicySpec;
+    /** Permanent retirement: active/proposed → retired; window closed, history kept. */
+    retire(id: string, actor: string, reason: string, opts?: {
+        now?: string;
+    }): PolicySpec;
+    linkException(id: string, parentId: string, actor: string, reason: string, opts?: {
+        now?: string;
+    }): PolicySpec;
+    relations(id: string, opts?: {
+        publicOnly?: boolean;
+        privateOnly?: boolean;
+    }): PolicyExceptionRelations;
+    consolidation(id: string, opts?: {
+        publicOnly?: boolean;
+        privateOnly?: boolean;
+    }): PolicyConsolidationCandidate;
+    evaluate(opts?: {
+        id?: string;
+        activeOnly?: boolean;
+        publicOnly?: boolean;
+        behavior?: BehaviorEvaluationOptions;
+        snapshot?: GraphSnapshot;
+    }): PolicyEvaluationSet[];
+}

package/dist/constitution/shadow.d.ts

@@ -0,0 +1,54 @@
+import { type HistoryDisposition, type HistoryDispositionClassification, type PolicyEvaluation, type PolicyProof, type PolicySpec, type ShadowDisposition, type ShadowEvaluationRecord } from "./schema.js";
+export declare function policyEvaluationContentHash(evaluation: PolicyEvaluation): string;
+export declare function shadowEvaluationContentHash(record: ShadowEvaluationRecord): string;
+export declare function shadowEvaluationIdentityHash(record: ShadowEvaluationRecord): string;
+export declare function shadowDispositionContentHash(record: ShadowDisposition): string;
+export declare function shadowDispositionJudgmentHash(record: ShadowDisposition): string;
+export declare function compileShadowEvaluation(policy: PolicySpec, proof: PolicyProof, expectedPolicyHash: string, evaluation: PolicyEvaluation, alsoDetectedBy: string[], latencyMs: number, now?: string): ShadowEvaluationRecord;
+export declare function compileShadowDisposition(evaluation: ShadowEvaluationRecord, classification: HistoryDispositionClassification, actor: string, reason: string, opts?: {
+    now?: string;
+    supersedes?: string | null;
+}): ShadowDisposition;
+/** Resolve append-only correction chains without trusting timestamps. */
+export declare function currentShadowDispositions(records: ShadowDisposition[]): ShadowDisposition[];
+export interface ShadowPrecisionThresholds {
+    minApplicable: number;
+    recentApplicable: number;
+    maxUnknownErrorRate: number;
+    minMutationSensitivity: number;
+}
+export declare const DEFAULT_SHADOW_THRESHOLDS: ShadowPrecisionThresholds;
+export interface ShadowPrecisionReport {
+    policy_id: string;
+    proof_id: string;
+    policy_hash: string;
+    thresholds: ShadowPrecisionThresholds;
+    counts: {
+        total: number;
+        applicable: number;
+        satisfied: number;
+        violated: number;
+        not_applicable: number;
+        unknown: number;
+        error: number;
+        stale_excluded: number;
+    };
+    window: {
+        recent_limit: number;
+        applicable: number;
+        violated: number;
+    };
+    dispositions: Record<HistoryDispositionClassification | "unclassified", number>;
+    precision: {
+        true_positives: number;
+        false_positives: number;
+        confirmed_denominator: number;
+        confirmed: number | null;
+        lower_bound: number | null;
+    };
+    unknown_error_rate: number;
+    mutation_sensitivity: number;
+    recommendation: "not_ready" | "eligible_for_p4_review";
+    reasons: string[];
+}
+export declare function scoreShadowPrecision(policy: PolicySpec, proof: PolicyProof, evaluations: ShadowEvaluationRecord[], dispositions: ShadowDisposition[], historyDispositions: HistoryDisposition[], thresholdOverrides?: Partial<ShadowPrecisionThresholds>): ShadowPrecisionReport;

package/dist/constitution/sourceMutation.d.ts

@@ -0,0 +1,15 @@
+import { type GraphSnapshot } from "./evaluator.js";
+import type { PolicyEvaluation, PolicySpec } from "./schema.js";
+export interface SourceMutationOutcome {
+    snapshot?: GraphSnapshot;
+    evaluation?: PolicyEvaluation;
+    source_patch?: {
+        files: string[];
+        diff: string;
+        diff_hash: string;
+    };
+    error_code?: string;
+}
+/** Apply one primary mutation to an immutable disposable source checkout. No
+ * project script, build, test, provider, model, or repository hook executes. */
+export declare function runSourceMutation(root: string, policy: PolicySpec, base: GraphSnapshot): SourceMutationOutcome;