@claudexor/schema 3.1.2 → 3.3.7-rc.0

package/dist/run-facts.d.ts

@@ -0,0 +1,628 @@
+import { z } from "zod/v3";
+import { RunOutcomeFacts } from "./decision.js";
+/**
+ * Canonical role of one model invocation in a terminal run. In particular,
+ * council draft lanes are planners while the synthesis invocation is a merge;
+ * reviewer and merge invocations can therefore never inflate planner counts.
+ */
+export declare const RunParticipantRole: z.ZodEnum<["planner", "merge", "candidate", "scout", "reducer", "reviewer"]>;
+export type RunParticipantRole = z.infer<typeof RunParticipantRole>;
+export declare const RunParticipantStatus: z.ZodEnum<["success", "success_with_warnings", "blocked", "failed"]>;
+export type RunParticipantStatus = z.infer<typeof RunParticipantStatus>;
+export declare const RunParticipant: z.ZodObject<{
+    attempt_id: z.ZodNullable<z.ZodString>;
+    harness_id: z.ZodString;
+    role: z.ZodEnum<["planner", "merge", "candidate", "scout", "reducer", "reviewer"]>;
+    deliverable_present: z.ZodDefault<z.ZodBoolean>;
+    status: z.ZodDefault<z.ZodNullable<z.ZodEnum<["success", "success_with_warnings", "blocked", "failed"]>>>;
+}, "strict", z.ZodTypeAny, {
+    attempt_id: string | null;
+    harness_id: string;
+    role: "candidate" | "merge" | "planner" | "reducer" | "reviewer" | "scout";
+    deliverable_present: boolean;
+    status: "blocked" | "failed" | "success" | "success_with_warnings" | null;
+}, {
+    attempt_id: string | null;
+    harness_id: string;
+    role: "candidate" | "merge" | "planner" | "reducer" | "reviewer" | "scout";
+    deliverable_present?: boolean | undefined;
+    status?: "blocked" | "failed" | "success" | "success_with_warnings" | null | undefined;
+}>;
+export type RunParticipant = z.infer<typeof RunParticipant>;
+export declare const RunDeliverableFacts: z.ZodObject<{
+    present: z.ZodBoolean;
+    kind: z.ZodNullable<z.ZodEnum<["answer", "report", "plan", "patch", "structured_output"]>>;
+    path: z.ZodNullable<z.ZodString>;
+    producer_attempt_id: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+}, "strict", z.ZodTypeAny, {
+    present: boolean;
+    kind: "answer" | "patch" | "plan" | "report" | "structured_output" | null;
+    path: string | null;
+    producer_attempt_id: string | null;
+}, {
+    present: boolean;
+    kind: "answer" | "patch" | "plan" | "report" | "structured_output" | null;
+    path: string | null;
+    producer_attempt_id?: string | null | undefined;
+}>;
+export type RunDeliverableFacts = z.infer<typeof RunDeliverableFacts>;
+export declare const RunParticipantsFacts: z.ZodObject<{
+    planners: z.ZodNumber;
+    attempts: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        attempt_id: z.ZodNullable<z.ZodString>;
+        harness_id: z.ZodString;
+        role: z.ZodEnum<["planner", "merge", "candidate", "scout", "reducer", "reviewer"]>;
+        deliverable_present: z.ZodDefault<z.ZodBoolean>;
+        status: z.ZodDefault<z.ZodNullable<z.ZodEnum<["success", "success_with_warnings", "blocked", "failed"]>>>;
+    }, "strict", z.ZodTypeAny, {
+        attempt_id: string | null;
+        harness_id: string;
+        role: "candidate" | "merge" | "planner" | "reducer" | "reviewer" | "scout";
+        deliverable_present: boolean;
+        status: "blocked" | "failed" | "success" | "success_with_warnings" | null;
+    }, {
+        attempt_id: string | null;
+        harness_id: string;
+        role: "candidate" | "merge" | "planner" | "reducer" | "reviewer" | "scout";
+        deliverable_present?: boolean | undefined;
+        status?: "blocked" | "failed" | "success" | "success_with_warnings" | null | undefined;
+    }>, "many">>;
+}, "strict", z.ZodTypeAny, {
+    planners: number;
+    attempts: {
+        attempt_id: string | null;
+        harness_id: string;
+        role: "candidate" | "merge" | "planner" | "reducer" | "reviewer" | "scout";
+        deliverable_present: boolean;
+        status: "blocked" | "failed" | "success" | "success_with_warnings" | null;
+    }[];
+}, {
+    planners: number;
+    attempts?: {
+        attempt_id: string | null;
+        harness_id: string;
+        role: "candidate" | "merge" | "planner" | "reducer" | "reviewer" | "scout";
+        deliverable_present?: boolean | undefined;
+        status?: "blocked" | "failed" | "success" | "success_with_warnings" | null | undefined;
+    }[] | undefined;
+}>;
+export type RunParticipantsFacts = z.infer<typeof RunParticipantsFacts>;
+export declare const RunGateState: z.ZodEnum<["not_configured", "passed", "failed", "skipped"]>;
+export type RunGateState = z.infer<typeof RunGateState>;
+export declare const RunGateFacts: z.ZodObject<{
+    configured: z.ZodBoolean;
+    required: z.ZodNumber;
+    total: z.ZodNumber;
+    executed: z.ZodBoolean;
+    state: z.ZodEnum<["not_configured", "passed", "failed", "skipped"]>;
+    receipt_attempt_id: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+}, "strict", z.ZodTypeAny, {
+    configured: boolean;
+    required: number;
+    total: number;
+    executed: boolean;
+    state: "failed" | "not_configured" | "passed" | "skipped";
+    receipt_attempt_id: string | null;
+}, {
+    configured: boolean;
+    required: number;
+    total: number;
+    executed: boolean;
+    state: "failed" | "not_configured" | "passed" | "skipped";
+    receipt_attempt_id?: string | null | undefined;
+}>;
+export type RunGateFacts = z.infer<typeof RunGateFacts>;
+export declare const RunReviewFacts: z.ZodObject<{
+    state: z.ZodEnum<["approved", "blocked", "not_run"]>;
+    blocker_ids: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    blockers: z.ZodNumber;
+}, "strict", z.ZodTypeAny, {
+    state: "approved" | "blocked" | "not_run";
+    blocker_ids: string[];
+    blockers: number;
+}, {
+    state: "approved" | "blocked" | "not_run";
+    blocker_ids?: string[] | undefined;
+    blockers: number;
+}>;
+export type RunReviewFacts = z.infer<typeof RunReviewFacts>;
+export declare const RunApplyFacts: z.ZodObject<{
+    eligibility: z.ZodDefault<z.ZodNullable<z.ZodObject<{
+        eligible: z.ZodBoolean;
+        state: z.ZodNullable<z.ZodString>;
+        reason: z.ZodNullable<z.ZodString>;
+        requiredAction: z.ZodNullable<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        eligible: boolean;
+        state: string | null;
+        reason: string | null;
+        requiredAction: string | null;
+    }, {
+        eligible: boolean;
+        state: string | null;
+        reason: string | null;
+        requiredAction: string | null;
+    }>>>;
+    operator_decision_present: z.ZodDefault<z.ZodBoolean>;
+}, "strict", z.ZodTypeAny, {
+    eligibility: {
+        eligible: boolean;
+        state: string | null;
+        reason: string | null;
+        requiredAction: string | null;
+    } | null;
+    operator_decision_present: boolean;
+}, {
+    eligibility?: {
+        eligible: boolean;
+        state: string | null;
+        reason: string | null;
+        requiredAction: string | null;
+    } | null | undefined;
+    operator_decision_present?: boolean | undefined;
+}>;
+export type RunApplyFacts = z.infer<typeof RunApplyFacts>;
+export declare const RunPresentationPrimary: z.ZodObject<{
+    kind: z.ZodEnum<["answer", "report", "plan", "patch", "structured_output", "diagnostic"]>;
+    path: z.ZodEffects<z.ZodString, string, string>;
+}, "strict", z.ZodTypeAny, {
+    kind: "answer" | "diagnostic" | "patch" | "plan" | "report" | "structured_output";
+    path: string;
+}, {
+    kind: "answer" | "diagnostic" | "patch" | "plan" | "report" | "structured_output";
+    path: string;
+}>;
+export type RunPresentationPrimary = z.infer<typeof RunPresentationPrimary>;
+export declare const RunPresentationFacts: z.ZodObject<{
+    state: z.ZodEnum<["ready", "diagnostic"]>;
+    primary: z.ZodNullable<z.ZodObject<{
+        kind: z.ZodEnum<["answer", "report", "plan", "patch", "structured_output", "diagnostic"]>;
+        path: z.ZodEffects<z.ZodString, string, string>;
+    }, "strict", z.ZodTypeAny, {
+        kind: "answer" | "diagnostic" | "patch" | "plan" | "report" | "structured_output";
+        path: string;
+    }, {
+        kind: "answer" | "diagnostic" | "patch" | "plan" | "report" | "structured_output";
+        path: string;
+    }>>;
+}, "strict", z.ZodTypeAny, {
+    state: "diagnostic" | "ready";
+    primary: {
+        kind: "answer" | "diagnostic" | "patch" | "plan" | "report" | "structured_output";
+        path: string;
+    } | null;
+}, {
+    state: "diagnostic" | "ready";
+    primary: {
+        kind: "answer" | "diagnostic" | "patch" | "plan" | "report" | "structured_output";
+        path: string;
+    } | null;
+}>;
+export type RunPresentationFacts = z.infer<typeof RunPresentationFacts>;
+/**
+ * Immutable terminal RunFacts receipt (GH #29). The orchestrator builds this
+ * once from the attempt graph and canonical artifacts, validates its cross-axis
+ * invariants, then persists the exact object consumed by machine surfaces.
+ */
+export declare const RunFacts: z.ZodObject<{
+    schema_version: z.ZodLiteral<2>;
+    run_id: z.ZodString;
+    task_id: z.ZodString;
+    mode: z.ZodEnum<["ask", "plan", "agent"]>;
+    outcome: z.ZodObject<{
+        lifecycle: z.ZodEnum<["succeeded", "failed", "cancelled", "interrupted"]>;
+        noChanges: z.ZodDefault<z.ZodBoolean>;
+        checks: z.ZodDefault<z.ZodEnum<["passed", "failed", "not_configured"]>>;
+        review: z.ZodDefault<z.ZodEnum<["approved", "blocked", "not_run"]>>;
+        reason: z.ZodDefault<z.ZodNullable<z.ZodEnum<["harness_failed", "no_changes", "review_blocked", "checks_failed", "budget_exhausted", "budget_overshoot", "cost_unverifiable", "not_converged", "stuck_no_progress", "wall_clock_exceeded", "user_cancelled", "crash_interrupted", "workspace_unavailable", "input_required", "work_incomplete", "context_capacity_exhausted", "work_report_contract"]>>>;
+        work_state: z.ZodOptional<z.ZodObject<{
+            state: z.ZodEnum<["completed", "needs_input", "incomplete", "unverified"]>;
+            source: z.ZodEnum<["constrained", "validated", "absent"]>;
+            required_inputs: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                kind: z.ZodEnum<["file", "context", "credential", "permission", "decision", "external_dependency"]>;
+                locator: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+                description: z.ZodString;
+            }, "strip", z.ZodTypeAny, {
+                kind: "context" | "credential" | "decision" | "external_dependency" | "file" | "permission";
+                locator: string | null;
+                description: string;
+            }, {
+                kind: "context" | "credential" | "decision" | "external_dependency" | "file" | "permission";
+                locator?: string | null | undefined;
+                description: string;
+            }>, "many">>;
+        }, "strip", z.ZodTypeAny, {
+            state: "completed" | "incomplete" | "needs_input" | "unverified";
+            source: "absent" | "constrained" | "validated";
+            required_inputs?: {
+                kind: "context" | "credential" | "decision" | "external_dependency" | "file" | "permission";
+                locator: string | null;
+                description: string;
+            }[] | undefined;
+        }, {
+            state: "completed" | "incomplete" | "needs_input" | "unverified";
+            source: "absent" | "constrained" | "validated";
+            required_inputs?: {
+                kind: "context" | "credential" | "decision" | "external_dependency" | "file" | "permission";
+                locator?: string | null | undefined;
+                description: string;
+            }[] | undefined;
+        }>>;
+    }, "strict", z.ZodTypeAny, {
+        lifecycle: "cancelled" | "failed" | "interrupted" | "succeeded";
+        noChanges: boolean;
+        checks: "failed" | "not_configured" | "passed";
+        review: "approved" | "blocked" | "not_run";
+        reason: "budget_exhausted" | "budget_overshoot" | "checks_failed" | "context_capacity_exhausted" | "cost_unverifiable" | "crash_interrupted" | "harness_failed" | "input_required" | "no_changes" | "not_converged" | "review_blocked" | "stuck_no_progress" | "user_cancelled" | "wall_clock_exceeded" | "work_incomplete" | "work_report_contract" | "workspace_unavailable" | null;
+        work_state?: {
+            state: "completed" | "incomplete" | "needs_input" | "unverified";
+            source: "absent" | "constrained" | "validated";
+            required_inputs?: {
+                kind: "context" | "credential" | "decision" | "external_dependency" | "file" | "permission";
+                locator: string | null;
+                description: string;
+            }[] | undefined;
+        } | undefined;
+    }, {
+        lifecycle: "cancelled" | "failed" | "interrupted" | "succeeded";
+        noChanges?: boolean | undefined;
+        checks?: "failed" | "not_configured" | "passed" | undefined;
+        review?: "approved" | "blocked" | "not_run" | undefined;
+        reason?: "budget_exhausted" | "budget_overshoot" | "checks_failed" | "context_capacity_exhausted" | "cost_unverifiable" | "crash_interrupted" | "harness_failed" | "input_required" | "no_changes" | "not_converged" | "review_blocked" | "stuck_no_progress" | "user_cancelled" | "wall_clock_exceeded" | "work_incomplete" | "work_report_contract" | "workspace_unavailable" | null | undefined;
+        work_state?: {
+            state: "completed" | "incomplete" | "needs_input" | "unverified";
+            source: "absent" | "constrained" | "validated";
+            required_inputs?: {
+                kind: "context" | "credential" | "decision" | "external_dependency" | "file" | "permission";
+                locator?: string | null | undefined;
+                description: string;
+            }[] | undefined;
+        } | undefined;
+    }>;
+    deliverable: z.ZodObject<{
+        present: z.ZodBoolean;
+        kind: z.ZodNullable<z.ZodEnum<["answer", "report", "plan", "patch", "structured_output"]>>;
+        path: z.ZodNullable<z.ZodString>;
+        producer_attempt_id: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    }, "strict", z.ZodTypeAny, {
+        present: boolean;
+        kind: "answer" | "patch" | "plan" | "report" | "structured_output" | null;
+        path: string | null;
+        producer_attempt_id: string | null;
+    }, {
+        present: boolean;
+        kind: "answer" | "patch" | "plan" | "report" | "structured_output" | null;
+        path: string | null;
+        producer_attempt_id?: string | null | undefined;
+    }>;
+    presentation: z.ZodOptional<z.ZodObject<{
+        state: z.ZodEnum<["ready", "diagnostic"]>;
+        primary: z.ZodNullable<z.ZodObject<{
+            kind: z.ZodEnum<["answer", "report", "plan", "patch", "structured_output", "diagnostic"]>;
+            path: z.ZodEffects<z.ZodString, string, string>;
+        }, "strict", z.ZodTypeAny, {
+            kind: "answer" | "diagnostic" | "patch" | "plan" | "report" | "structured_output";
+            path: string;
+        }, {
+            kind: "answer" | "diagnostic" | "patch" | "plan" | "report" | "structured_output";
+            path: string;
+        }>>;
+    }, "strict", z.ZodTypeAny, {
+        state: "diagnostic" | "ready";
+        primary: {
+            kind: "answer" | "diagnostic" | "patch" | "plan" | "report" | "structured_output";
+            path: string;
+        } | null;
+    }, {
+        state: "diagnostic" | "ready";
+        primary: {
+            kind: "answer" | "diagnostic" | "patch" | "plan" | "report" | "structured_output";
+            path: string;
+        } | null;
+    }>>;
+    participants: z.ZodObject<{
+        planners: z.ZodNumber;
+        attempts: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            attempt_id: z.ZodNullable<z.ZodString>;
+            harness_id: z.ZodString;
+            role: z.ZodEnum<["planner", "merge", "candidate", "scout", "reducer", "reviewer"]>;
+            deliverable_present: z.ZodDefault<z.ZodBoolean>;
+            status: z.ZodDefault<z.ZodNullable<z.ZodEnum<["success", "success_with_warnings", "blocked", "failed"]>>>;
+        }, "strict", z.ZodTypeAny, {
+            attempt_id: string | null;
+            harness_id: string;
+            role: "candidate" | "merge" | "planner" | "reducer" | "reviewer" | "scout";
+            deliverable_present: boolean;
+            status: "blocked" | "failed" | "success" | "success_with_warnings" | null;
+        }, {
+            attempt_id: string | null;
+            harness_id: string;
+            role: "candidate" | "merge" | "planner" | "reducer" | "reviewer" | "scout";
+            deliverable_present?: boolean | undefined;
+            status?: "blocked" | "failed" | "success" | "success_with_warnings" | null | undefined;
+        }>, "many">>;
+    }, "strict", z.ZodTypeAny, {
+        planners: number;
+        attempts: {
+            attempt_id: string | null;
+            harness_id: string;
+            role: "candidate" | "merge" | "planner" | "reducer" | "reviewer" | "scout";
+            deliverable_present: boolean;
+            status: "blocked" | "failed" | "success" | "success_with_warnings" | null;
+        }[];
+    }, {
+        planners: number;
+        attempts?: {
+            attempt_id: string | null;
+            harness_id: string;
+            role: "candidate" | "merge" | "planner" | "reducer" | "reviewer" | "scout";
+            deliverable_present?: boolean | undefined;
+            status?: "blocked" | "failed" | "success" | "success_with_warnings" | null | undefined;
+        }[] | undefined;
+    }>;
+    gates: z.ZodObject<{
+        configured: z.ZodBoolean;
+        required: z.ZodNumber;
+        total: z.ZodNumber;
+        executed: z.ZodBoolean;
+        state: z.ZodEnum<["not_configured", "passed", "failed", "skipped"]>;
+        receipt_attempt_id: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    }, "strict", z.ZodTypeAny, {
+        configured: boolean;
+        required: number;
+        total: number;
+        executed: boolean;
+        state: "failed" | "not_configured" | "passed" | "skipped";
+        receipt_attempt_id: string | null;
+    }, {
+        configured: boolean;
+        required: number;
+        total: number;
+        executed: boolean;
+        state: "failed" | "not_configured" | "passed" | "skipped";
+        receipt_attempt_id?: string | null | undefined;
+    }>;
+    review: z.ZodObject<{
+        state: z.ZodEnum<["approved", "blocked", "not_run"]>;
+        blocker_ids: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        blockers: z.ZodNumber;
+    }, "strict", z.ZodTypeAny, {
+        state: "approved" | "blocked" | "not_run";
+        blocker_ids: string[];
+        blockers: number;
+    }, {
+        state: "approved" | "blocked" | "not_run";
+        blocker_ids?: string[] | undefined;
+        blockers: number;
+    }>;
+    apply: z.ZodObject<{
+        eligibility: z.ZodDefault<z.ZodNullable<z.ZodObject<{
+            eligible: z.ZodBoolean;
+            state: z.ZodNullable<z.ZodString>;
+            reason: z.ZodNullable<z.ZodString>;
+            requiredAction: z.ZodNullable<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            eligible: boolean;
+            state: string | null;
+            reason: string | null;
+            requiredAction: string | null;
+        }, {
+            eligible: boolean;
+            state: string | null;
+            reason: string | null;
+            requiredAction: string | null;
+        }>>>;
+        operator_decision_present: z.ZodDefault<z.ZodBoolean>;
+    }, "strict", z.ZodTypeAny, {
+        eligibility: {
+            eligible: boolean;
+            state: string | null;
+            reason: string | null;
+            requiredAction: string | null;
+        } | null;
+        operator_decision_present: boolean;
+    }, {
+        eligibility?: {
+            eligible: boolean;
+            state: string | null;
+            reason: string | null;
+            requiredAction: string | null;
+        } | null | undefined;
+        operator_decision_present?: boolean | undefined;
+    }>;
+    required_actions: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodEnum<["provide_required_input", "complete_incomplete_work", "resolve_review_block", "fix_failed_checks", "record_operator_decision"]>;
+        detail: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        id: "complete_incomplete_work" | "fix_failed_checks" | "provide_required_input" | "record_operator_decision" | "resolve_review_block";
+        detail: string;
+    }, {
+        id: "complete_incomplete_work" | "fix_failed_checks" | "provide_required_input" | "record_operator_decision" | "resolve_review_block";
+        detail: string;
+    }>, "many">>;
+    generated_at: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    schema_version: 2;
+    run_id: string;
+    task_id: string;
+    mode: "agent" | "ask" | "plan";
+    outcome: {
+        lifecycle: "cancelled" | "failed" | "interrupted" | "succeeded";
+        noChanges: boolean;
+        checks: "failed" | "not_configured" | "passed";
+        review: "approved" | "blocked" | "not_run";
+        reason: "budget_exhausted" | "budget_overshoot" | "checks_failed" | "context_capacity_exhausted" | "cost_unverifiable" | "crash_interrupted" | "harness_failed" | "input_required" | "no_changes" | "not_converged" | "review_blocked" | "stuck_no_progress" | "user_cancelled" | "wall_clock_exceeded" | "work_incomplete" | "work_report_contract" | "workspace_unavailable" | null;
+        work_state?: {
+            state: "completed" | "incomplete" | "needs_input" | "unverified";
+            source: "absent" | "constrained" | "validated";
+            required_inputs?: {
+                kind: "context" | "credential" | "decision" | "external_dependency" | "file" | "permission";
+                locator: string | null;
+                description: string;
+            }[] | undefined;
+        } | undefined;
+    };
+    deliverable: {
+        present: boolean;
+        kind: "answer" | "patch" | "plan" | "report" | "structured_output" | null;
+        path: string | null;
+        producer_attempt_id: string | null;
+    };
+    presentation?: {
+        state: "diagnostic" | "ready";
+        primary: {
+            kind: "answer" | "diagnostic" | "patch" | "plan" | "report" | "structured_output";
+            path: string;
+        } | null;
+    } | undefined;
+    participants: {
+        planners: number;
+        attempts: {
+            attempt_id: string | null;
+            harness_id: string;
+            role: "candidate" | "merge" | "planner" | "reducer" | "reviewer" | "scout";
+            deliverable_present: boolean;
+            status: "blocked" | "failed" | "success" | "success_with_warnings" | null;
+        }[];
+    };
+    gates: {
+        configured: boolean;
+        required: number;
+        total: number;
+        executed: boolean;
+        state: "failed" | "not_configured" | "passed" | "skipped";
+        receipt_attempt_id: string | null;
+    };
+    review: {
+        state: "approved" | "blocked" | "not_run";
+        blocker_ids: string[];
+        blockers: number;
+    };
+    apply: {
+        eligibility: {
+            eligible: boolean;
+            state: string | null;
+            reason: string | null;
+            requiredAction: string | null;
+        } | null;
+        operator_decision_present: boolean;
+    };
+    required_actions: {
+        id: "complete_incomplete_work" | "fix_failed_checks" | "provide_required_input" | "record_operator_decision" | "resolve_review_block";
+        detail: string;
+    }[];
+    generated_at: string;
+}, {
+    schema_version: 2;
+    run_id: string;
+    task_id: string;
+    mode: "agent" | "ask" | "plan";
+    outcome: {
+        lifecycle: "cancelled" | "failed" | "interrupted" | "succeeded";
+        noChanges?: boolean | undefined;
+        checks?: "failed" | "not_configured" | "passed" | undefined;
+        review?: "approved" | "blocked" | "not_run" | undefined;
+        reason?: "budget_exhausted" | "budget_overshoot" | "checks_failed" | "context_capacity_exhausted" | "cost_unverifiable" | "crash_interrupted" | "harness_failed" | "input_required" | "no_changes" | "not_converged" | "review_blocked" | "stuck_no_progress" | "user_cancelled" | "wall_clock_exceeded" | "work_incomplete" | "work_report_contract" | "workspace_unavailable" | null | undefined;
+        work_state?: {
+            state: "completed" | "incomplete" | "needs_input" | "unverified";
+            source: "absent" | "constrained" | "validated";
+            required_inputs?: {
+                kind: "context" | "credential" | "decision" | "external_dependency" | "file" | "permission";
+                locator?: string | null | undefined;
+                description: string;
+            }[] | undefined;
+        } | undefined;
+    };
+    deliverable: {
+        present: boolean;
+        kind: "answer" | "patch" | "plan" | "report" | "structured_output" | null;
+        path: string | null;
+        producer_attempt_id?: string | null | undefined;
+    };
+    presentation?: {
+        state: "diagnostic" | "ready";
+        primary: {
+            kind: "answer" | "diagnostic" | "patch" | "plan" | "report" | "structured_output";
+            path: string;
+        } | null;
+    } | undefined;
+    participants: {
+        planners: number;
+        attempts?: {
+            attempt_id: string | null;
+            harness_id: string;
+            role: "candidate" | "merge" | "planner" | "reducer" | "reviewer" | "scout";
+            deliverable_present?: boolean | undefined;
+            status?: "blocked" | "failed" | "success" | "success_with_warnings" | null | undefined;
+        }[] | undefined;
+    };
+    gates: {
+        configured: boolean;
+        required: number;
+        total: number;
+        executed: boolean;
+        state: "failed" | "not_configured" | "passed" | "skipped";
+        receipt_attempt_id?: string | null | undefined;
+    };
+    review: {
+        state: "approved" | "blocked" | "not_run";
+        blocker_ids?: string[] | undefined;
+        blockers: number;
+    };
+    apply: {
+        eligibility?: {
+            eligible: boolean;
+            state: string | null;
+            reason: string | null;
+            requiredAction: string | null;
+        } | null | undefined;
+        operator_decision_present?: boolean | undefined;
+    };
+    required_actions?: {
+        id: "complete_incomplete_work" | "fix_failed_checks" | "provide_required_input" | "record_operator_decision" | "resolve_review_block";
+        detail: string;
+    }[] | undefined;
+    generated_at: string;
+}>;
+export type RunFacts = z.infer<typeof RunFacts>;
+/** Identity a canonical receipt must match before any surface may serve it:
+ * the daemon/CLI-known run and task ids plus, when the caller holds a settled
+ * terminal state, the exact lifecycle. Undefined fields are simply not
+ * asserted (e.g. a legacy caller that knows only the run id). */
+export interface ExpectedRunFactsIdentity {
+    runId?: string;
+    taskId?: string;
+    lifecycle?: RunOutcomeFacts["lifecycle"];
+}
+/** Typed refusal for a PRESENT-but-untrustworthy canonical receipt: wrong
+ * shape, violated cross-axis invariants, or an identity that contradicts the
+ * caller's authority. The pure core carries the stable machine fields
+ * (code/retryable/evidenceRefs); each surface adds its own transport mapping
+ * (control-api: HTTP 500 + requiredActions; CLI: renderCliFailure exit). */
+export declare class RunFactsInvalidError extends Error {
+    readonly code = "run_facts_invalid";
+    readonly retryable = false;
+    readonly evidenceRefs: string[];
+    constructor();
+}
+/**
+ * THE shared pure validation owner for reading a canonical receipt back on any
+ * surface: wire shape, cross-axis invariants, and identity binding in one
+ * place. Filesystem access, root resolution, and transport/error mapping stay
+ * with the callers — this function never touches disk.
+ */
+export declare function validateRunFactsReceipt(value: unknown, expected?: ExpectedRunFactsIdentity): RunFacts;
+/** Typed invariant refusal raised before a contradictory RunFacts receipt can
+ * be persisted. `violations` is stable diagnostic evidence for tests/logs; it
+ * is not a surface vocabulary. */
+export declare class RunFactsInvariantError extends Error {
+    readonly violations: string[];
+    readonly code = "run_facts_invariant";
+    constructor(violations: string[]);
+}
+/**
+ * Validate both the RunFacts wire shape and the relationships its individual
+ * Zod fields cannot express. Returns the parsed/defaulted receipt on success.
+ */
+export declare function validateRunFactsInvariants(value: unknown): RunFacts;
+//# sourceMappingURL=run-facts.d.ts.map

package/dist/run-facts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-facts.d.ts","sourceRoot":"","sources":["../src/run-facts.ts"],"names":[],"mappings":"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"}