@davesheffer/hunch 1.31.1 → 1.32.0

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 {};