@davesheffer/hunch 1.31.1 → 1.32.0

package/dist/constitution/g2BehaviorAttestation.d.ts

@@ -0,0 +1,45 @@
+import { z } from "zod";
+import type { HunchStore } from "../store/hunchStore.js";
+import { type G2BehaviorCandidateReview, type G2BehaviorHumanDisposition, type G2BehaviorReplayReceipt, type G2BehaviorReviewResolution } from "./g2BehaviorCandidates.js";
+export declare const G2BehaviorDispositionSchema: z.ZodEnum<{
+    rejected: "rejected";
+    selected: "selected";
+}>;
+export declare const G2BehaviorAttestationSchema: z.ZodObject<{
+    id: z.ZodString;
+    content_hash: z.ZodString;
+    candidate_id: z.ZodString;
+    candidate_hash: z.ZodString;
+    commit: z.ZodString;
+    review_hash: z.ZodString;
+    replay_id: z.ZodString;
+    replay_hash: z.ZodString;
+    dependency_snapshot_ids: z.ZodArray<z.ZodString>;
+    disposition: z.ZodEnum<{
+        rejected: "rejected";
+        selected: "selected";
+    }>;
+    actor: z.ZodString;
+    reason: z.ZodString;
+    supersedes: z.ZodNullable<z.ZodString>;
+    data_class: z.ZodLiteral<"private">;
+    authority: z.ZodLiteral<"none">;
+    effects: z.ZodLiteral<"review_only">;
+    created_at: z.ZodString;
+}, z.core.$strict>;
+export type G2BehaviorAttestation = z.infer<typeof G2BehaviorAttestationSchema>;
+export declare function g2BehaviorAttestationContentHash(attestation: G2BehaviorAttestation): string;
+export declare function compileG2BehaviorAttestation(report: G2BehaviorCandidateReview, candidateId: string, reviewHash: string, replay: G2BehaviorReplayReceipt, disposition: G2BehaviorHumanDisposition, actor: string, reason: string, opts?: {
+    now?: string;
+    supersedes?: string | null;
+}): G2BehaviorAttestation;
+/** Resolve exact-behavior supersession chains without timestamp trust. */
+export declare function currentG2BehaviorAttestations(records: G2BehaviorAttestation[]): G2BehaviorAttestation[];
+export declare class G2BehaviorAttestationRepository {
+    private readonly store;
+    constructor(store: HunchStore);
+    list(): G2BehaviorAttestation[];
+    current(): G2BehaviorAttestation[];
+    resolutions(): G2BehaviorReviewResolution[];
+    put(attestation: G2BehaviorAttestation): G2BehaviorAttestation;
+}

package/dist/constitution/g2BehaviorCandidates.d.ts

@@ -0,0 +1,123 @@
+import type { HunchStore } from "../store/hunchStore.js";
+import { type G2CandidateReviewOptions, type G2CandidateReviewResolution } from "./g2Candidates.js";
+export type G2BehaviorRunnerKind = "node-test" | "node-test-tsx";
+export type G2BehaviorHumanDisposition = "selected" | "rejected";
+export interface G2BehaviorCandidateReviewOptions extends G2CandidateReviewOptions {
+    /** Build one finite review batch directly from an exact current human-confirmed
+     * decision instead of requiring a rejected structural proxy first. */
+    decisionId?: string;
+}
+export interface G2BehaviorReviewResolution {
+    id: string;
+    candidate_id: string;
+    candidate_hash: string;
+    review_hash: string;
+    replay_id: string;
+    replay_hash: string;
+    disposition: G2BehaviorHumanDisposition;
+    actor: string;
+    reason: string;
+    created_at: string;
+}
+export interface G2BehaviorCandidate {
+    id: string;
+    commit: string;
+    commit_subject: string;
+    commit_date: string;
+    statement: string;
+    test: {
+        file: string;
+        name: string;
+        source_hash: string;
+    };
+    runner: {
+        kind: G2BehaviorRunnerKind;
+        argv: string[];
+    };
+    decision_ids: string[];
+    source_candidate_ids: string[];
+    source_attestation_ids: string[];
+    proposed_corpus: {
+        known_bad: {
+            ref: string;
+            expected: "failed";
+        };
+        known_good: {
+            ref: string;
+            expected: "passed";
+        };
+        observed: false;
+    };
+    grounding: "rejected_proxy_plus_added_test" | "human_decision_plus_added_test" | "human_decision_plus_modified_test";
+    data_class: "private";
+    authority: "none";
+    writes: "none";
+    proof_status: "not_run";
+    human_review?: G2BehaviorReviewResolution;
+}
+export interface G2BehaviorCandidateReview {
+    id: string;
+    content_hash: string;
+    structural_review_hash: string;
+    since: string;
+    max_commits: number;
+    limit: number;
+    grounded_rejections_scanned: number;
+    candidate_commits: number;
+    behavior_candidates: number;
+    selected_candidates?: number;
+    rejected_candidates?: number;
+    unreviewed_candidates?: number;
+    commits_without_added_tests: string[];
+    extraction_failures: Array<{
+        commit: string;
+        file: string;
+        error: string;
+    }>;
+    items: G2BehaviorCandidate[];
+    has_more: boolean;
+    limitations: string[];
+    data_class: "private";
+    authority: "none";
+    writes: "none";
+    proof_status: "not_run";
+    grounding_mode?: "human_decision_plus_added_test";
+    source_decision_id?: string;
+    source_grounding_hash?: string;
+}
+export interface G2BehaviorReplayLeg {
+    commit: string;
+    expected: "failed" | "passed";
+    result: "failed" | "passed" | "error";
+    exit_code: number | null;
+    error_code?: string;
+    dependency_snapshot_id?: string;
+}
+export interface G2BehaviorReplayReceipt {
+    id: string;
+    content_hash: string;
+    candidate_id: string;
+    candidate_hash: string;
+    review_hash: string;
+    test: G2BehaviorCandidate["test"];
+    runner: G2BehaviorCandidate["runner"];
+    known_bad: G2BehaviorReplayLeg;
+    known_good: G2BehaviorReplayLeg;
+    verdict: "behavior_confirmed" | "inconclusive";
+    budget_ms: number;
+    limitations: string[];
+    data_class: "private";
+    authority: "none";
+    effects: "diagnostic_only";
+    writes: "disposable_only";
+}
+/** Extract literal node:test names without interpreting source or template expressions. */
+export declare function addedNodeTestNames(source: string): string[];
+export declare function g2BehaviorCandidateHash(candidate: G2BehaviorCandidate): string;
+export declare function g2BehaviorReplayContentHash(receipt: G2BehaviorReplayReceipt): string;
+export declare function g2BehaviorReviewContentHash(report: G2BehaviorCandidateReview): string;
+export declare function buildG2BehaviorCandidateReview(store: HunchStore, root: string, opts?: G2BehaviorCandidateReviewOptions, resolutions?: G2CandidateReviewResolution[], behaviorResolutions?: G2BehaviorReviewResolution[]): G2BehaviorCandidateReview;
+export declare function nodeTestInfrastructureError(output: string): string | null;
+export declare function replayG2BehaviorCandidate(root: string, report: G2BehaviorCandidateReview, candidateId: string, reviewHash: string, opts?: {
+    timeoutMs?: number;
+}): G2BehaviorReplayReceipt;

package/dist/constitution/g2BehaviorDependencies.d.ts

@@ -0,0 +1,83 @@
+import type { G2BehaviorCandidate, G2BehaviorCandidateReview } from "./g2BehaviorCandidates.js";
+export interface G2BehaviorDependencySnapshot {
+    id: string;
+    content_hash: string;
+    input_hash: string;
+    package_json_hash: string;
+    sanitized_package_json_hash: string;
+    package_lock_hash: string;
+    dependency_projection_hash: string;
+    runtime: {
+        node: string;
+        npm: string;
+        platform: NodeJS.Platform;
+        arch: string;
+    };
+    allow_install_scripts: string[];
+    installed_lock_hash: string;
+    native_binaries: Array<{
+        file: string;
+        sha256: string;
+    }>;
+    node_modules_hash: string;
+    format_version: 2;
+    data_class: "private";
+    authority: "none";
+    effects: "cache_only";
+    writes: "cache_only";
+}
+export interface G2BehaviorDependencySnapshotReceipt {
+    id: string;
+    content_hash: string;
+    candidate_id: string;
+    candidate_hash: string;
+    review_hash: string;
+    snapshots: G2BehaviorDependencySnapshot[];
+    legs: {
+        known_bad: {
+            commit: string;
+            dependency_snapshot_id: string;
+        };
+        known_good: {
+            commit: string;
+            dependency_snapshot_id: string;
+        };
+    };
+    allow_install_scripts: string[];
+    data_class: "private";
+    authority: "none";
+    effects: "cache_only";
+    writes: "cache_only";
+}
+export interface G2BehaviorDependencyCommitSnapshots {
+    snapshots: G2BehaviorDependencySnapshot[];
+    commits: Array<{
+        commit: string;
+        dependency_snapshot_id: string;
+    }>;
+}
+/** Hash every directory, regular file, executable bit, and internal symlink in
+ * a dependency tree. Traversal uses raw UTF-8 byte ordering rather than the
+ * host locale, and rejects filesystem shapes that cannot be copied safely. */
+export declare function dependencySnapshotTreeHash(nodeModules: string): string;
+/** Create one independently writable dependency tree. COPYFILE_FICLONE is a
+ * copy-on-write optimization where supported, never a shared hardlink; the
+ * byte-copy fallback has the same isolation. Pre/post hashes bind the copy. */
+export declare function materializeDependencyTree(source: string, destination: string, opts?: {
+    expectedHash?: string;
+}): string;
+/** Materialize a private writable dependency tree for one disposable run. */
+export declare function materializeDependencySnapshot(dependency: {
+    snapshot: Pick<G2BehaviorDependencySnapshot, "id" | "node_modules_hash">;
+    nodeModules: string;
+}, destination: string): void;
+export declare function dependencySnapshotById(root: string, id: string): {
+    snapshot: G2BehaviorDependencySnapshot;
+    nodeModules: string;
+} | null;
+export declare function dependencySnapshotForCommit(root: string, commit: string, allowedIds?: string[]): {
+    snapshot: G2BehaviorDependencySnapshot;
+    nodeModules: string;
+} | null;
+export declare function provisionG2BehaviorDependencySnapshotsForCommits(root: string, commits: string[], allowInstallScripts?: string[], timeoutMs?: number): G2BehaviorDependencyCommitSnapshots;
+export declare function provisionG2BehaviorDependencySnapshots(root: string, report: G2BehaviorCandidateReview, candidate: G2BehaviorCandidate, allowInstallScripts?: string[], timeoutMs?: number): G2BehaviorDependencySnapshotReceipt;

package/dist/constitution/g2BehaviorMaterialization.d.ts

@@ -0,0 +1,77 @@
+import { z } from "zod";
+import { type G2BehaviorCandidateReview } from "./g2BehaviorCandidates.js";
+import { type G2BehaviorAttestation } from "./g2BehaviorAttestation.js";
+export declare const G2BehaviorMaterializationAssessmentSchema: z.ZodObject<{
+    id: z.ZodString;
+    content_hash: z.ZodString;
+    source_review: z.ZodObject<{
+        id: z.ZodString;
+        content_hash: z.ZodString;
+        structural_review_hash: z.ZodString;
+        grounding_mode: z.ZodOptional<z.ZodLiteral<"human_decision_plus_added_test">>;
+        source_decision_id: z.ZodOptional<z.ZodString>;
+        source_grounding_hash: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    policy_ir_version: z.ZodLiteral<2>;
+    evaluator: z.ZodObject<{
+        name: z.ZodLiteral<"hunch-executable-behavior">;
+        version: z.ZodLiteral<"1.0.0">;
+    }, z.core.$strict>;
+    supported_assertion_kinds: z.ZodArray<z.ZodEnum<{
+        exists: "exists";
+        reaches: "reaches";
+        "not-reaches": "not-reaches";
+        "must-pass-through": "must-pass-through";
+        "executable-behavior": "executable-behavior";
+    }>>;
+    selected_attestations: z.ZodNumber;
+    materialized_policies: z.ZodLiteral<0>;
+    readiness: z.ZodLiteral<"ready_for_materialization">;
+    items: z.ZodArray<z.ZodObject<{
+        candidate_id: z.ZodString;
+        candidate_hash: z.ZodString;
+        attestation_id: z.ZodString;
+        attestation_hash: z.ZodString;
+        attested_review_hash: z.ZodString;
+        replay_id: z.ZodString;
+        replay_hash: z.ZodString;
+        dependency_snapshot_ids: z.ZodArray<z.ZodString>;
+        commit: z.ZodString;
+        test: z.ZodObject<{
+            file: z.ZodString;
+            name: z.ZodString;
+            source_hash: z.ZodString;
+        }, z.core.$strict>;
+        durable_meaning: z.ZodString;
+        status: z.ZodLiteral<"ready_for_materialization">;
+        reason: z.ZodString;
+        required_capability: z.ZodObject<{
+            assertion: z.ZodLiteral<"executable-behavior">;
+            current_baseline: z.ZodLiteral<"required">;
+            known_bad: z.ZodLiteral<"must_fail_behaviorally">;
+            known_good: z.ZodLiteral<"must_pass">;
+            mutation_controls: z.ZodLiteral<"required">;
+        }, z.core.$strict>;
+    }, z.core.$strict>>;
+    outputs: z.ZodObject<{
+        policies: z.ZodArray<z.ZodNever>;
+        corpora: z.ZodArray<z.ZodNever>;
+        plans: z.ZodArray<z.ZodNever>;
+        proofs: z.ZodArray<z.ZodNever>;
+    }, z.core.$strict>;
+    limitations: z.ZodArray<z.ZodString>;
+    data_class: z.ZodLiteral<"private">;
+    authority: z.ZodLiteral<"none">;
+    effects: z.ZodLiteral<"assessment_only">;
+    writes: z.ZodLiteral<"none">;
+    proof_status: z.ZodLiteral<"not_run">;
+    activation: z.ZodLiteral<"separate_human_action_required">;
+}, z.core.$strict>;
+export type G2BehaviorMaterializationAssessment = z.infer<typeof G2BehaviorMaterializationAssessmentSchema>;
+export declare function g2BehaviorMaterializationContentHash(assessment: G2BehaviorMaterializationAssessment): string;
+/**
+ * Assess exact selected behavior receipts against the currently implemented
+ * Policy IR. This is intentionally fail-closed: it never substitutes a static
+ * symbol or edge proxy for behavior that the evaluator cannot execute.
+ */
+export declare function assessG2BehaviorMaterialization(report: G2BehaviorCandidateReview, currentAttestations: G2BehaviorAttestation[]): G2BehaviorMaterializationAssessment;

package/dist/constitution/g2BehaviorPolicyMaterializer.d.ts

@@ -0,0 +1,48 @@
+import { z } from "zod";
+import type { HunchStore } from "../store/hunchStore.js";
+import { type G2BehaviorCandidateReview } from "./g2BehaviorCandidates.js";
+import type { G2BehaviorAttestation } from "./g2BehaviorAttestation.js";
+import type { PolicyRepository } from "./repository.js";
+export declare const G2BehaviorPolicyMaterializationSchema: z.ZodObject<{
+    id: z.ZodString;
+    content_hash: z.ZodString;
+    assessment_id: z.ZodString;
+    assessment_hash: z.ZodString;
+    source_review_id: z.ZodString;
+    source_review_hash: z.ZodString;
+    current_commit: z.ZodString;
+    dependency_snapshots: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        content_hash: z.ZodString;
+    }, z.core.$strict>>;
+    materialized_policies: z.ZodNumber;
+    items: z.ZodArray<z.ZodObject<{
+        candidate_id: z.ZodString;
+        attestation_id: z.ZodString;
+        policy_id: z.ZodString;
+        policy_hash: z.ZodString;
+        corpus_id: z.ZodString;
+        corpus_hash: z.ZodString;
+        plan_id: z.ZodString;
+        plan_hash: z.ZodString;
+        proof_id: z.ZodString;
+        proof_hash: z.ZodString;
+        proof_class: z.ZodLiteral<"P3">;
+        policy_state: z.ZodEnum<{
+            proposed: "proposed";
+            active_advisory: "active_advisory";
+            active_blocking: "active_blocking";
+        }>;
+    }, z.core.$strict>>;
+    data_class: z.ZodLiteral<"private">;
+    authority: z.ZodLiteral<"none">;
+    effects: z.ZodLiteral<"policy_proposal_only">;
+    writes: z.ZodLiteral<"private_policy_artifacts">;
+    activation: z.ZodLiteral<"separate_human_action_required">;
+}, z.core.$strict>;
+export type G2BehaviorPolicyMaterialization = z.infer<typeof G2BehaviorPolicyMaterializationSchema>;
+export declare function materializeSelectedG2BehaviorPolicies(store: HunchStore, root: string, repository: PolicyRepository, report: G2BehaviorCandidateReview, currentAttestations: G2BehaviorAttestation[], opts?: {
+    now?: string;
+    allowInstallScripts?: string[];
+    dependencyTimeoutMs?: number;
+}): G2BehaviorPolicyMaterialization;

package/dist/constitution/g2CandidateAttestation.d.ts

@@ -0,0 +1,43 @@
+import { z } from "zod";
+import type { HunchStore } from "../store/hunchStore.js";
+import { type G2CandidateHumanDisposition, type G2CandidateReviewReport, type G2CandidateReviewResolution } from "./g2Candidates.js";
+export declare const G2CandidateDispositionSchema: z.ZodEnum<{
+    rejected: "rejected";
+    selected: "selected";
+}>;
+export declare const G2CandidateAttestationSchema: z.ZodObject<{
+    id: z.ZodString;
+    content_hash: z.ZodString;
+    candidate_id: z.ZodString;
+    candidate_hash: z.ZodString;
+    structural_candidate_id: z.ZodString;
+    commit: z.ZodString;
+    review_hash: z.ZodString;
+    disposition: z.ZodEnum<{
+        rejected: "rejected";
+        selected: "selected";
+    }>;
+    actor: z.ZodString;
+    reason: z.ZodString;
+    supersedes: z.ZodNullable<z.ZodString>;
+    data_class: z.ZodLiteral<"private">;
+    authority: z.ZodLiteral<"none">;
+    effects: z.ZodLiteral<"review_only">;
+    created_at: z.ZodString;
+}, z.core.$strict>;
+export type G2CandidateAttestation = z.infer<typeof G2CandidateAttestationSchema>;
+export declare function g2CandidateAttestationContentHash(attestation: G2CandidateAttestation): string;
+export declare function compileG2CandidateAttestation(report: G2CandidateReviewReport, candidateId: string, reviewHash: string, disposition: G2CandidateHumanDisposition, actor: string, reason: string, opts?: {
+    now?: string;
+    supersedes?: string | null;
+}): G2CandidateAttestation;
+/** Resolve exact-candidate supersession chains without timestamp trust. */
+export declare function currentG2CandidateAttestations(records: G2CandidateAttestation[]): G2CandidateAttestation[];
+export declare class G2CandidateAttestationRepository {
+    private readonly store;
+    constructor(store: HunchStore);
+    list(): G2CandidateAttestation[];
+    current(): G2CandidateAttestation[];
+    resolutions(): G2CandidateReviewResolution[];
+    put(attestation: G2CandidateAttestation): G2CandidateAttestation;
+}

package/dist/constitution/g2Candidates.d.ts

@@ -0,0 +1,80 @@
+import { HunchStore } from "../store/hunchStore.js";
+import type { PolicyAssertion, PolicyScope } from "./schema.js";
+export type G2CandidateAttestationStatus = "human_grounded_exact" | "human_grounded_needs_selection" | "unattested_structural_coincidence";
+export type G2CandidateHumanDisposition = "selected" | "rejected";
+export interface G2CandidateReviewResolution {
+    id: string;
+    candidate_id: string;
+    candidate_hash: string;
+    review_hash: string;
+    disposition: G2CandidateHumanDisposition;
+    actor: string;
+    reason: string;
+    created_at: string;
+}
+export interface G2CandidateReviewItem {
+    id: string;
+    candidate_id: string;
+    commit: string;
+    commit_subject: string;
+    commit_date: string;
+    changed_files: string[];
+    sibling_candidates: number;
+    basis: "added-call" | "removed-call" | "added-symbol" | "removed-import" | "added-relative-import" | "removed-relative-import";
+    reason: string;
+    assertion: PolicyAssertion;
+    scope: PolicyScope;
+    proposed_corpus: {
+        known_bad: {
+            ref: string;
+            expected: "violated";
+        };
+        known_good: {
+            ref: string;
+            expected: "satisfied";
+        };
+        observed: false;
+    };
+    attestation: {
+        status: G2CandidateAttestationStatus;
+        decision_ids: string[];
+    };
+    human_review: G2CandidateReviewResolution | null;
+}
+export interface G2CandidateReviewReport {
+    id: string;
+    content_hash: string;
+    since: string;
+    max_commits: number;
+    limit: number;
+    scanned_fix_commits: number;
+    candidate_commits: number;
+    total_candidates: number;
+    human_grounded_exact: number;
+    human_grounded_needs_selection: number;
+    unattested_structural_coincidence: number;
+    selected_candidates: number;
+    rejected_candidates: number;
+    unreviewed_candidates: number;
+    extraction_failures: Array<{
+        commit: string;
+        error: string;
+    }>;
+    items: G2CandidateReviewItem[];
+    has_more: boolean;
+    data_class: "private";
+    authority: "none";
+    writes: "none";
+    proof_status: "not_run";
+}
+export interface G2CandidateReviewOptions {
+    since?: string;
+    maxCommits?: number;
+    limit?: number;
+}
+export declare function g2CandidateItemHash(item: G2CandidateReviewItem): string;
+export declare function g2CandidateReviewContentHash(report: G2CandidateReviewReport): string;
+export declare function positiveBound(value: number, label: string, max: number): number;
+/** Read-only review packet. Structural facts propose corpus pairs but cannot
+ * become policy evidence until an exact human judgment selects their semantics. */
+export declare function buildG2CandidateReview(store: HunchStore, root: string, opts?: G2CandidateReviewOptions, resolutions?: G2CandidateReviewResolution[]): G2CandidateReviewReport;

package/dist/constitution/g2Drills.d.ts

@@ -0,0 +1,33 @@
+import type { Runbook } from "../core/types.js";
+import type { G2Plan, G2RunbookCategory } from "./g2.js";
+interface DrillSpec {
+    file: string;
+    name: string;
+}
+export declare const G2_OPERATIONAL_DRILLS: Record<G2RunbookCategory, DrillSpec>;
+export interface G2OperationalDrillReceipt {
+    id: string;
+    content_hash: string;
+    category: G2RunbookCategory;
+    plan_id: string;
+    runbook_id: string;
+    runbook_hash: string;
+    test: DrillSpec & {
+        source_hash: string;
+    };
+    runner: {
+        name: "node-test-tsx";
+        isolation_flag: string;
+    };
+    result: "passed" | "failed" | "error";
+    exit_code: number | null;
+    selected_event: "passed" | "failed" | null;
+    error_code?: string;
+    log_hash: string;
+    data_class: "private";
+    authority: "none";
+    effects: "diagnostic_only";
+    writes: "none";
+}
+export declare function executeG2OperationalDrill(root: string, plan: G2Plan, runbook: Runbook, category: G2RunbookCategory, timeoutMs?: number): G2OperationalDrillReceipt;
+export {};