@davesheffer/hunch 1.31.1 → 1.32.0

package/dist/constitution/card.d.ts

@@ -0,0 +1,58 @@
+import type { EvaluationSummary, HistoryDisposition, HistoryDispositionClassification, PolicyProof, PolicySpec, ProofClass } from "./schema.js";
+import type { ShadowPrecisionReport } from "./shadow.js";
+export interface ProofCard {
+    card_hash: string;
+    policy: {
+        id: string;
+        statement: string;
+        state: PolicySpec["state"];
+        severity: PolicySpec["severity"];
+        data_class: PolicySpec["data_class"];
+        assertion: PolicySpec["assertion"];
+        scope: PolicySpec["scope"];
+        evidence: string[];
+        candidate: PolicySpec["candidate"];
+        exception_of: string | null;
+        activation_gate: PolicySpec["activation_gate"];
+    };
+    proof: {
+        id: string;
+        proof_class: ProofClass;
+        plan_hash: string;
+        generated_at: string;
+    };
+    evidence_vector: {
+        current: EvaluationSummary;
+        known_bad: EvaluationSummary;
+        known_good: EvaluationSummary;
+        accepted_history: PolicyProof["accepted_history"];
+        mutations: PolicyProof["mutations"];
+        mutation_controls: PolicyProof["mutation_controls"];
+    };
+    project_checks: PolicyProof["project_checks"];
+    composition: PolicyProof["composition"] | null;
+    shadow_precision: ShadowPrecisionReport | null;
+    history_dispositions: {
+        current: HistoryDisposition[];
+        counts: Record<HistoryDispositionClassification, number>;
+        missing_commits: string[];
+        unresolved_count: number;
+    };
+    uncertainty: {
+        unclassified_history_hits: number;
+        unknown_results: number;
+        error_results: number;
+        limitations: string[];
+        compiler_uncertainty: string[];
+        candidate_conflicts: string[];
+    };
+    authority: {
+        current: PolicySpec["authority"];
+        eligible_for_human_blocking_approval: boolean;
+        can_block_now: boolean;
+        blocking_evidence_error: string | null;
+    };
+    actions: string[];
+}
+export declare function buildProofCard(policy: PolicySpec, proof: PolicyProof, dispositions?: HistoryDisposition[], composition?: PolicySpec[], shadowPrecision?: ShadowPrecisionReport | null): ProofCard;
+export declare function renderProofCard(card: ProofCard): string;

package/dist/constitution/compiler.d.ts

@@ -0,0 +1,52 @@
+import type { Constraint, Decision } from "../core/types.js";
+import type { HunchStore } from "../store/hunchStore.js";
+import { type CandidateContext, type DataClass, type PolicyAssertion, type PolicySpec } from "./schema.js";
+export interface CompilePolicyOptions {
+    through?: string;
+    private?: boolean;
+    now?: string;
+}
+export declare function compileDecisionRecord(store: HunchStore, source: Decision, isPrivate: boolean, opts?: Omit<CompilePolicyOptions, "private">): {
+    policy: PolicySpec;
+    private: boolean;
+    source: Decision;
+};
+/** Deterministic compatibility compiler: one structured legacy conformance
+ * predicate becomes one Policy IR candidate. It never interprets prose into a
+ * nearest available rule. */
+export declare function compileDecisionPolicy(store: HunchStore, decisionId: string, opts?: CompilePolicyOptions): {
+    policy: PolicySpec;
+    private: boolean;
+    source: Decision;
+};
+export interface StructuralPolicyInput {
+    source: Decision;
+    evidenceId: string;
+    commit: string;
+    assertion: PolicyAssertion;
+    scope: PolicySpec["scope"];
+    dataClass: DataClass;
+    candidate?: CandidateContext;
+    now?: string;
+}
+/** Compile one already-enumerated structural assertion. This function does not
+ * infer or rank semantics; callers must pass an exact supported candidate. */
+export declare function compileStructuralPolicy(store: HunchStore, input: StructuralPolicyInput): {
+    policy: PolicySpec;
+    private: boolean;
+};
+export interface CorrectionPolicyInput {
+    source: Constraint;
+    evidenceId: string;
+    assertion: PolicyAssertion;
+    scope: PolicySpec["scope"];
+    dataClass: DataClass;
+    candidate?: CandidateContext;
+    now?: string;
+}
+/** Compile one already-bound correction projection. The caller must first prove
+ * that the projection has exactly one supported structural interpretation. */
+export declare function compileCorrectionPolicy(store: HunchStore, input: CorrectionPolicyInput): {
+    policy: PolicySpec;
+    private: boolean;
+};

package/dist/constitution/composition.d.ts

@@ -0,0 +1,10 @@
+import { type PolicyCompositionBinding, type PolicySpec } from "./schema.js";
+export declare function oppositeExceptionAssertions(child: PolicySpec, parent: PolicySpec): boolean;
+export declare function exceptionScopeIsNarrower(child: PolicySpec, parent: PolicySpec): boolean;
+export declare function validateExceptionRelationship(child: PolicySpec, parent: PolicySpec): void;
+/** Return every explicit descendant of a broad root. Parent links define the
+ * precedence tree; stable policy-id ordering keeps the binding canonical. */
+export declare function compositionDescendants(root: PolicySpec, policies: PolicySpec[]): PolicySpec[];
+export declare function policyCompositionBinding(root: PolicySpec, members: PolicySpec[]): PolicyCompositionBinding | undefined;
+export declare function policyProofHash(root: PolicySpec, members?: PolicySpec[]): string;
+export declare function assertCompositionBinding(root: PolicySpec, members: PolicySpec[], binding: PolicyCompositionBinding | undefined): void;

package/dist/constitution/corpus.d.ts

@@ -0,0 +1,7 @@
+import { type PolicySpec, type ProofCorpus } from "./schema.js";
+/** Resolve human-authored Git refs once, then persist an immutable, policy-bound
+ * fixture manifest. No checkout, evaluator, model, provider, or project command runs. */
+export declare function compileProofCorpus(root: string, policy: PolicySpec, raw: unknown, opts?: {
+    now?: string;
+}): ProofCorpus;
+export declare function proofCorpusContentHash(corpus: ProofCorpus): string;

package/dist/constitution/correctionPolicyMaterializer.d.ts

@@ -0,0 +1,57 @@
+import type { HunchStore } from "../store/hunchStore.js";
+import type { PolicyRepository } from "./repository.js";
+import { type EvidenceEvent, type PolicyProof, type PolicySpec, type ProofPlan } from "./schema.js";
+export interface CorrectionUpgradeOptions {
+    publicOnly?: boolean;
+    privateOnly?: boolean;
+    now?: string;
+}
+export interface CorrectionReview {
+    status: "ready_for_review";
+    rule: string;
+    meaning: string;
+    why: string;
+    catches: string;
+    does_not_catch: string;
+    authority: "none" | "existing_human";
+    next_action: string;
+}
+export interface CorrectionPolicyUpgrade {
+    status: "proved" | "already_proved" | "legacy_only" | "pending" | "conflicted";
+    correction_id: string;
+    reason: string;
+    evidence: EvidenceEvent;
+    policy: PolicySpec | null;
+    plan: ProofPlan | null;
+    proof: PolicyProof | null;
+    review: CorrectionReview | null;
+    authority: "none";
+    effects: "proposal_only";
+    activation: "not_available_in_this_operation";
+}
+export interface CorrectionPolicySweep {
+    scanned: number;
+    proved: number;
+    already_proved: number;
+    legacy_only: number;
+    pending: number;
+    conflicted: number;
+    failed: Array<{
+        correction_id: string;
+        home: Home;
+        error: string;
+    }>;
+    upgrades: CorrectionPolicyUpgrade[];
+    authority: "none";
+}
+type Home = "public" | "private";
+/** Upgrade one safe correction projection into a proved proposal. This operation
+ * cannot activate, warn, or block; unsupported corrections retain only their
+ * immediate legacy Constraint. */
+export declare function materializeCorrectionPolicy(store: HunchStore, root: string, repository: PolicyRepository, correctionId: string, opts?: CorrectionUpgradeOptions): CorrectionPolicyUpgrade;
+/** Durable retry queue: the captured Constraints are the source of truth, so a
+ * crashed process needs no in-memory job record. Normal indexing and post-commit
+ * sync can safely rescan both exact homes; every artifact is deterministic and
+ * no result grants authority. */
+export declare function materializeCorrectionPolicies(store: HunchStore, root: string, repository: PolicyRepository, opts?: CorrectionUpgradeOptions): CorrectionPolicySweep;
+export {};

package/dist/constitution/delta.d.ts

@@ -0,0 +1,4 @@
+import { type StructuralDelta } from "./schema.js";
+/** Compare exact git blobs at a commit and its first parent. No checkout,
+ * worktree, hook, or model/provider is involved. */
+export declare function extractStructuralDelta(root: string, commit: string): StructuralDelta;

package/dist/constitution/disposition.d.ts

@@ -0,0 +1,20 @@
+import { type HistoryDisposition, type HistoryDispositionClassification, type PolicyProof, type PolicySpec, type ReplayReceipt } from "./schema.js";
+export declare function historyDispositionContentHash(disposition: HistoryDisposition): string;
+export declare function historyDispositionJudgmentHash(disposition: HistoryDisposition): string;
+export declare function compileHistoryDisposition(policy: PolicySpec, proof: PolicyProof, receipt: ReplayReceipt, classification: HistoryDispositionClassification, actor: string, reason: string, opts?: {
+    now?: string;
+    supersedes?: string | null;
+    composition?: PolicySpec[];
+}): HistoryDisposition;
+/** Resolve the append-only supersession chain without trusting timestamps.
+ * Missing parents, cross-hit links, branches, and cycles fail visibly. */
+export declare function currentHistoryDispositions(records: HistoryDisposition[]): HistoryDisposition[];
+export interface HistoryDispositionAssessment {
+    current: HistoryDisposition[];
+    bound: HistoryDisposition[];
+    missing_commits: string[];
+    unresolved_count: number;
+    counts: Record<HistoryDispositionClassification, number>;
+    blocking_error: string | null;
+}
+export declare function assessHistoryDispositions(proof: PolicyProof, records: HistoryDisposition[]): HistoryDispositionAssessment;

package/dist/constitution/evaluator.d.ts

@@ -0,0 +1,47 @@
+import type { Component, Edge, Symbol } from "../core/types.js";
+import type { HunchStore } from "../store/hunchStore.js";
+import { type BehaviorEvaluationOptions } from "./behaviorEvaluator.js";
+import { type PolicyEvaluation, type PolicySpec } from "./schema.js";
+export interface GraphSnapshot {
+    root: string;
+    head: string;
+    symbols: Symbol[];
+    edges: Edge[];
+    components: Component[];
+    graph_hash: string;
+}
+export declare function graphSnapshotFromRecords(root: string, head: string, symbols: Symbol[], edges: Edge[], components?: Component[]): GraphSnapshot;
+/** Bind a filesystem-derived graph to its content, never to a Git commit whose
+ * tree may not contain the scanned bytes. The graph hash is independent of the
+ * receipt head, so it is safe to use as the explicit checkout identity. */
+export declare function checkoutGraphSnapshot(root: string, symbols: Symbol[], edges: Edge[], components?: Component[]): GraphSnapshot;
+/** Bind a semantic check receipt to both the selected source surface and the
+ * exact raw source bytes. The graph hash remains explicit because two source
+ * bodies can differ while producing the same topology. */
+export declare function sourceGraphSnapshot(root: string, source: {
+    kind: string;
+    revision?: string;
+    content_hash: string;
+}, symbols: Symbol[], edges: Edge[], components?: Component[]): GraphSnapshot;
+export declare function graphSnapshot(store: HunchStore, root: string, opts?: {
+    publicOnly?: boolean;
+    head?: string;
+}): GraphSnapshot;
+export declare function evaluatePolicyOnSnapshot(policy: PolicySpec, snapshot: GraphSnapshot): PolicyEvaluation;
+export declare function selectedPolicyForComposition(root: PolicySpec, members: PolicySpec[], snapshot: GraphSnapshot): PolicySpec;
+/** Evaluate explicit scope precedence as one receipt. The deepest applicable
+ * linked exception wins; severity and adapter order never participate. */
+export declare function evaluateCompositePolicyOnSnapshot(root: PolicySpec, members: PolicySpec[], snapshot: GraphSnapshot): PolicyEvaluation;
+export declare function evaluatePolicy(store: HunchStore, root: string, policy: PolicySpec, opts?: {
+    publicOnly?: boolean;
+    composition?: PolicySpec[];
+    behavior?: BehaviorEvaluationOptions;
+    snapshot?: GraphSnapshot;
+}): PolicyEvaluation;
+export declare function policyIsActive(policy: PolicySpec): boolean;
+export declare function policyBlocks(policy: PolicySpec, evaluation: PolicyEvaluation): boolean;
+export declare function mutationOperatorForPolicy(policy: PolicySpec): string;
+export declare function mutateSnapshotForPolicy(policy: PolicySpec, snapshot: GraphSnapshot): {
+    snapshot: GraphSnapshot;
+    operator: string;
+} | null;