@davesheffer/hunch 1.31.0 → 1.32.0

package/dist/core/stats.d.ts

@@ -0,0 +1,88 @@
+/** `hunch stats` — the ONE data contract (dec_6253f7e6d6). A pure aggregation over
+ *  the graph Hunch already builds plus the append-only catch-log (core/events.ts):
+ *  STOCK (what's accumulated) → RETURN (what that stock caught) → COMPOUNDING (the
+ *  ratio that should climb). Every surface — CLI receipt, VS Code extension, the
+ *  public proof-curve — is a read-only pane of glass over this object; if a number
+ *  can't come from here it doesn't exist.
+ *
+ *  HONESTY (the red-team baked into the decision): nothing here fabricates a number
+ *  the live graph can't produce. `coverage.pct` is 0 until decisions actually carry
+ *  `related_components`; `bugs_reprevented` is 0 until a bug reaches `regressed`;
+ *  catches come only from real gate events, never a hypothetical. A skeptic running
+ *  this on a young graph SHOULD see zeros — that's the honest state, not a bug. */
+import type { Bug, Constraint, Decision } from "./types.js";
+import type { HunchEvent } from "./events.js";
+export interface StatsInput {
+    decisions: Decision[];
+    constraints: Constraint[];
+    bugs: Bug[];
+    /** Component ids in the graph (for coverage = decisions-touching ÷ total). */
+    componentIds: string[];
+    runbooksCount: number;
+    events: HunchEvent[];
+    /** Count of constraints whose guarded code moved since last verified (from the
+     *  store's staleness walk — passed in so this module stays pure). */
+    staleConstraints: number;
+    /** ms epoch "now" and the start of the recent window (now − since). */
+    now: number;
+    windowStart: number;
+    windowLabel: string;
+}
+export interface StatsReturn {
+    violations_caught: number;
+    drifts_flagged: number;
+    bugs_reprevented: number;
+    vetoes_fired: number;
+}
+export interface Stats {
+    schema: "hunch.stats/1";
+    generated_at: string;
+    window: {
+        since: string;
+        from: string;
+        to: string;
+    };
+    stock: {
+        decisions: {
+            total: number;
+            accepted: number;
+            superseded: number;
+            proposed: number;
+            rejected: number;
+        };
+        invariants: {
+            total: number;
+            locked: number;
+            advisory: number;
+            stale: number;
+        };
+        components: number;
+        bugs: {
+            total: number;
+            open: number;
+            investigating: number;
+            fixed: number;
+            regressed: number;
+        };
+        runbooks: number;
+        coverage: {
+            components_with_decision: number;
+            components_total: number;
+            pct: number;
+        };
+    };
+    return: {
+        window: StatsReturn;
+        lifetime: StatsReturn;
+    };
+    compounding: {
+        rules_recorded: number;
+        catches_lifetime: number;
+        payback_ratio: number;
+    };
+}
+export declare function computeStats(input: StatsInput): Stats;
+/** Human-readable receipt for the terminal (the CLI's default, non-`--json` output).
+ *  Same three blocks as the JSON: stock → return → compounding. Honest zeros are
+ *  shown plainly, never hidden — a young graph reads as young, not as broken. */
+export declare function formatStats(s: Stats): string;

package/dist/core/strictgate.d.ts

@@ -0,0 +1,33 @@
+export declare const STRICT_MIN_CONFIDENCE = 0.8;
+/** Is a provenance source HUMAN-CONFIRMED? Token-aware, so a composite source like
+ *  "llm_draft+human_confirmed" counts, but a lookalike ("not_human_confirmed",
+ *  "human_confirmed_pending") does not. The sources Hunch writes are "+"-joined. */
+export declare function isHumanConfirmed(source: string | undefined): boolean;
+export interface StrictConstraint {
+    severity?: string;
+    provenance?: {
+        confidence?: number;
+        source?: string;
+    };
+}
+/** May this invariant FAIL a commit under --strict? Requires blocking severity,
+ *  a fresh (non-stale) record, and either high provenance confidence or a
+ *  human-confirmed source (a person vouched for it). Near/blast-radius hits never
+ *  reach here — the caller passes only directly-scoped invariants. */
+export declare function isStrictBlocker(c: StrictConstraint, stale: boolean): boolean;
+export type VetoTier = "dep" | "symbol" | "pattern" | "semantic";
+/** May a VETO fail a commit? Sibling of isStrictBlocker, but keys on the TRIPWIRE's
+ *  trust — not the rejecting decision's — and uses ONE rule for every tier: only a
+ *  `human_confirmed` tripwire blocks. An llm_draft tripwire never blocks regardless
+ *  of confidence (an LLM self-score is not a licence to fail a commit); it only
+ *  warns. Semantic similarity never blocks. In-force + non-stale gates run first.
+ *  This is what makes the "day-one is advisory" DX true (dec_a466655539). */
+export declare function isVetoBlocker(d: {
+    status?: string;
+    superseded_by?: string | null;
+    valid_to?: string | null;
+}, tw: {
+    provenance?: {
+        source?: string;
+    };
+}, tier: VetoTier, stale: boolean): boolean;

package/dist/core/taskReport.d.ts

@@ -0,0 +1,226 @@
+import { z } from "zod";
+import { type DeliveryEnvelope } from "./delivery.js";
+export declare const TASK_REPORT_SCHEMA: "hunch.task-report/1";
+export declare const TaskIdSchema: z.ZodString;
+export declare function reportHash(value: unknown): string;
+export declare const ReportRecordSchema: z.ZodObject<{
+    record_id: z.ZodString;
+    kind: z.ZodString;
+    content_hash: z.ZodString;
+    title: z.ZodString;
+    lesson: z.ZodString;
+    recorded_at: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export type ReportRecord = z.infer<typeof ReportRecordSchema>;
+export declare const ReportClaimSchema: z.ZodObject<{
+    occurrence_id: z.ZodString;
+    record_id: z.ZodString;
+    content_hash: z.ZodString;
+    action: z.ZodString;
+}, z.core.$strict>;
+export type ReportClaim = z.infer<typeof ReportClaimSchema>;
+export declare const ReportCheckSchema: z.ZodObject<{
+    check_id: z.ZodOptional<z.ZodString>;
+    label: z.ZodString;
+    command: z.ZodArray<z.ZodString>;
+    exit_code: z.ZodNullable<z.ZodNumber>;
+    output_hash: z.ZodString;
+    before_snapshot: z.ZodNullable<z.ZodString>;
+    after_snapshot: z.ZodNullable<z.ZodString>;
+    snapshot_limitations: z.ZodArray<z.ZodString>;
+    timed_out: z.ZodBoolean;
+    cancelled: z.ZodOptional<z.ZodBoolean>;
+    source: z.ZodLiteral<"local-command-runner">;
+}, z.core.$strict>;
+export type ReportCheck = z.infer<typeof ReportCheckSchema>;
+export declare const ReportSaveSchema: z.ZodObject<{
+    source: z.ZodLiteral<"store-write">;
+    record: z.ZodObject<{
+        record_id: z.ZodString;
+        kind: z.ZodString;
+        content_hash: z.ZodString;
+        title: z.ZodString;
+        lesson: z.ZodString;
+        recorded_at: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>;
+    home: z.ZodEnum<{
+        public: "public";
+        private: "private";
+    }>;
+    operation: z.ZodEnum<{
+        updated: "updated";
+        created: "created";
+    }>;
+}, z.core.$strict>;
+export type ReportSave = z.infer<typeof ReportSaveSchema>;
+export declare const ReportDurabilitySchema: z.ZodObject<{
+    save_id: z.ZodString;
+    durability: z.ZodEnum<{
+        committed: "committed";
+        pushed: "pushed";
+    }>;
+    commit: z.ZodString;
+    record_hash: z.ZodString;
+    source: z.ZodLiteral<"git-record-proof">;
+    publication: z.ZodOptional<z.ZodObject<{
+        ref: z.ZodString;
+        basis: z.ZodEnum<{
+            "push-status": "push-status";
+            "remote-ref-confirmed": "remote-ref-confirmed";
+        }>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type ReportDurability = z.infer<typeof ReportDurabilitySchema>;
+export declare const ReportRefusalSchema: z.ZodObject<{
+    source: z.ZodLiteral<"native-edit-gate">;
+    outcome: z.ZodLiteral<"denial-emitted">;
+    kind: z.ZodEnum<{
+        constraint: "constraint";
+        veto: "veto";
+    }>;
+    record_id: z.ZodString;
+    target: z.ZodString;
+    reason_hash: z.ZodString;
+}, z.core.$strict>;
+export type ReportRefusal = z.infer<typeof ReportRefusalSchema>;
+/** Hunch's own deterministic evaluation of a delivered lesson's DECLARED rule
+ * (a constraint's forbids matcher or a decision's conformance predicate) against
+ * the files this task changed. Only the local runner writes it; an agent cannot
+ * submit one. File overlap alone never yields "satisfied": a lesson with no
+ * machine-checkable rule stays `unavailable`, and a rule whose scope this task
+ * never touched stays `not-exercised`. */
+export declare const ReportConformanceSchema: z.ZodObject<{
+    source: z.ZodLiteral<"local-rule-check">;
+    record_id: z.ZodString;
+    kind: z.ZodEnum<{
+        decisions: "decisions";
+        constraints: "constraints";
+    }>;
+    content_hash: z.ZodString;
+    rule: z.ZodEnum<{
+        "constraint-forbids": "constraint-forbids";
+        "decision-conformance": "decision-conformance";
+    }>;
+    outcome: z.ZodEnum<{
+        satisfied: "satisfied";
+        violated: "violated";
+        "not-exercised": "not-exercised";
+        unavailable: "unavailable";
+    }>;
+    files: z.ZodArray<z.ZodString>;
+    snapshot: z.ZodNullable<z.ZodString>;
+    detail: z.ZodString;
+}, z.core.$strict>;
+export type ReportConformance = z.infer<typeof ReportConformanceSchema>;
+declare const TaskSchema: z.ZodObject<{
+    task_id: z.ZodString;
+    scope: z.ZodString;
+    title: z.ZodString;
+    started_at: z.ZodString;
+    finished_at: z.ZodNullable<z.ZodString>;
+    state: z.ZodEnum<{
+        open: "open";
+        completed: "completed";
+        interrupted: "interrupted";
+    }>;
+}, z.core.$strict>;
+export type ReportTask = z.infer<typeof TaskSchema>;
+export interface TaskDelivery {
+    occurrence_id: string;
+    at: string;
+    receipt_id: string;
+    envelope_hash: string;
+    envelope: DeliveryEnvelope;
+    records: ReportRecord[];
+}
+export interface TaskReport {
+    schema: typeof TASK_REPORT_SCHEMA;
+    task: ReportTask;
+    deliveries: TaskDelivery[];
+    /** `supported_by` names a current, satisfied rule evaluation of the SAME record
+     * revision; the attribution itself stays the agent's. */
+    claims: Array<ReportClaim & {
+        at: string;
+        attribution: "agent-reported";
+        supported_by: string | null;
+    }>;
+    checks: Array<ReportCheck & {
+        at: string;
+        current: boolean;
+    }>;
+    conformance: Array<ReportConformance & {
+        event_id: string;
+        at: string;
+        current: boolean;
+    }>;
+    saves: Array<ReportSave & {
+        event_id: string;
+        at: string;
+        durability: "local" | "committed" | "pushed";
+        proofs: Array<ReportDurability & {
+            at: string;
+        }>;
+    }>;
+    refusals: Array<ReportRefusal & {
+        event_id: string;
+        at: string;
+    }>;
+    coverage: "no-delivery-observed" | "no-relevant-memory" | "delivered";
+    unknowns: string[];
+    content_hash: string;
+}
+export declare const LessonReferenceSchema: z.ZodObject<{
+    kind: z.ZodString;
+    record_id: z.ZodString;
+    content_hash: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type LessonReference = z.infer<typeof LessonReferenceSchema>;
+export interface LessonHistory {
+    schema: "hunch.lesson-history/1";
+    reference: LessonReference;
+    entries: Array<{
+        task: ReportTask;
+        event_id: string;
+        at: string;
+        event: "delivery" | "save";
+        record: ReportRecord;
+        receipt_id: string | null;
+    }>;
+    index_complete: boolean;
+    truncated: boolean;
+    next_before: number | null;
+}
+/** The lookup is derived, never evidence. Backfill at most 64 events and
+ * 512 KB per read. Parse outside the writer transaction so a history view cannot
+ * hold the writer lock while validating a large legacy ledger. */
+export declare function readLessonHistory(root: string, reference: LessonReference, options?: {
+    limit?: number;
+    before?: number;
+}): LessonHistory;
+export declare function startReportTask(root: string, title: string, taskId?: string): ReportTask;
+/** Strict operation for explicit callers. Passive integrations catch failure
+ * and disclose it without blocking context delivery. Empty envelopes count. */
+export declare function recordTaskDelivery(root: string, taskId: string, envelope: DeliveryEnvelope, records: ReportRecord[], occurrenceId?: string): string;
+export declare function recordReportClaim(root: string, taskId: string, claim: ReportClaim): string;
+/** Internal write-path observers; no MCP endpoint accepts fabricated saves or
+ * publication claims. Retained observations never authorize memory mutations. */
+export declare function recordReportSave(root: string, taskId: string, save: ReportSave): string;
+export declare function recordReportDurability(root: string, taskId: string, proof: ReportDurability): string;
+/** Internal observer of an actual emitted edit denial. This is not a model
+ * assertion and does not establish that the host honored the response. */
+export declare function recordReportRefusal(root: string, taskId: string, refusal: ReportRefusal): string;
+/** Only the local rule runner calls this; no MCP endpoint accepts a submitted
+ * outcome. The evaluated revision must be one this task actually received. */
+export declare function recordReportConformance(root: string, taskId: string, conformance: ReportConformance): string;
+/** Only the local runner calls this. MCP never accepts a claimed successful check. */
+export declare function recordReportCheck(root: string, taskId: string, check: ReportCheck): string;
+export declare function beginReportCheck(root: string, taskId: string, label: string): string;
+export declare function finishReportTask(root: string, taskId: string, state?: "completed" | "interrupted"): ReportTask;
+export declare function listReportTasks(root: string): ReportTask[];
+export declare function reportActivity(root: string): string;
+/** Exact task deletion is a user-invoked operation, never a memory deletion. */
+export declare function forgetReportTask(root: string, taskId: string): void;
+export declare function pruneReportHistory(root: string, olderThanDays?: number): number;
+export declare function reportPresentationEnabled(root: string): boolean;
+export declare function readTaskReport(root: string, taskId: string, currentSnapshot?: string | null): TaskReport;
+export {};