tickmarkr 1.87.0 → 1.89.0

package/dist/run/protocol.d.ts

@@ -0,0 +1,460 @@
+import { z } from "zod";
+import { type GateName } from "../graph/schema.js";
+import { type GateOutcome } from "./outcome.js";
+/** The T31 outcome vocabulary, made executable and strict at the persistence boundary. */
+export declare const GateOutcomeSchema: z.ZodType<GateOutcome>;
+export declare const ROLE_INVOCATION_ROLES: readonly ["worker", "judge", "review", "consult"];
+export type RoleInvocationRole = (typeof ROLE_INVOCATION_ROLES)[number];
+export declare const ROLE_INVOCATION_OUTCOMES: readonly ["completed", "failed", "unavailable"];
+export type RoleInvocationOutcome = (typeof ROLE_INVOCATION_OUTCOMES)[number];
+export declare const RUN_TERMINAL_OUTCOMES: readonly ["completed", "failed", "incomplete"];
+export type RunTerminalOutcome = (typeof RUN_TERMINAL_OUTCOMES)[number];
+export declare const GatePhaseStartEventSchema: z.ZodObject<{
+    ts: z.ZodString;
+    event: z.ZodLiteral<"gate-phase-start">;
+    taskId: z.ZodString;
+    data: z.ZodObject<{
+        attempt: z.ZodNumber;
+        gate: z.ZodEnum<{
+            build: "build";
+            test: "test";
+            lint: "lint";
+            evidence: "evidence";
+            scope: "scope";
+            acceptance: "acceptance";
+            review: "review";
+        }>;
+        evidence: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export declare const GateTerminalEventSchema: z.ZodObject<{
+    ts: z.ZodString;
+    event: z.ZodLiteral<"gate-result">;
+    taskId: z.ZodString;
+    data: z.ZodObject<{
+        attempt: z.ZodNumber;
+        gate: z.ZodEnum<{
+            build: "build";
+            test: "test";
+            lint: "lint";
+            evidence: "evidence";
+            scope: "scope";
+            acceptance: "acceptance";
+            review: "review";
+        }>;
+        outcome: z.ZodType<GateOutcome, unknown, z.core.$ZodTypeInternals<GateOutcome, unknown>>;
+        details: z.ZodOptional<z.ZodString>;
+        load: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+            oneMinute: z.ZodNumber;
+            fiveMinute: z.ZodNumber;
+            cores: z.ZodNumber;
+        }, z.core.$strict>, z.ZodObject<{
+            unavailableReason: z.ZodString;
+        }, z.core.$strict>]>>;
+        evidence: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export declare const RoleInvocationStartEventSchema: z.ZodObject<{
+    ts: z.ZodString;
+    event: z.ZodLiteral<"role-invocation-start">;
+    taskId: z.ZodString;
+    data: z.ZodObject<{
+        attempt: z.ZodNumber;
+        role: z.ZodEnum<{
+            review: "review";
+            judge: "judge";
+            consult: "consult";
+            worker: "worker";
+        }>;
+        adapter: z.ZodOptional<z.ZodString>;
+        model: z.ZodOptional<z.ZodString>;
+        vendor: z.ZodOptional<z.ZodString>;
+        evidence: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export declare const RoleInvocationTerminalEventSchema: z.ZodObject<{
+    ts: z.ZodString;
+    event: z.ZodLiteral<"role-invocation-terminal">;
+    taskId: z.ZodString;
+    data: z.ZodObject<{
+        attempt: z.ZodNumber;
+        role: z.ZodEnum<{
+            review: "review";
+            judge: "judge";
+            consult: "consult";
+            worker: "worker";
+        }>;
+        adapter: z.ZodOptional<z.ZodString>;
+        model: z.ZodOptional<z.ZodString>;
+        vendor: z.ZodOptional<z.ZodString>;
+        evidence: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        outcome: z.ZodEnum<{
+            failed: "failed";
+            unavailable: "unavailable";
+            completed: "completed";
+        }>;
+        reason: z.ZodString;
+        tokens: z.ZodOptional<z.ZodObject<{
+            input: z.ZodNumber;
+            output: z.ZodNumber;
+            cacheRead: z.ZodOptional<z.ZodNumber>;
+            cacheWrite: z.ZodOptional<z.ZodNumber>;
+            reasoning: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>;
+        unmeteredReason: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export declare const RunTerminalEventSchema: z.ZodObject<{
+    ts: z.ZodString;
+    event: z.ZodLiteral<"run-end">;
+    data: z.ZodObject<{
+        outcome: z.ZodEnum<{
+            failed: "failed";
+            completed: "completed";
+            incomplete: "incomplete";
+        }>;
+        reason: z.ZodString;
+        runId: z.ZodString;
+        branch: z.ZodString;
+        done: z.ZodArray<z.ZodString>;
+        failed: z.ZodArray<z.ZodString>;
+        human: z.ZodArray<z.ZodString>;
+        blocked: z.ZodArray<z.ZodString>;
+        pending: z.ZodArray<z.ZodString>;
+        tipVerify: z.ZodOptional<z.ZodEnum<{
+            failed: "failed";
+            passed: "passed";
+        }>>;
+        lastMergedTask: z.ZodOptional<z.ZodString>;
+        approvalDisposition: z.ZodOptional<z.ZodEnum<{
+            complete: "complete";
+            outstanding: "outstanding";
+        }>>;
+        outstandingApprovals: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        phase: z.ZodOptional<z.ZodString>;
+        fatal: z.ZodOptional<z.ZodBoolean>;
+        error: z.ZodOptional<z.ZodString>;
+        evidence: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+/**
+ * The complete decision-event vocabulary. There is no catch-all object arm: an event claiming one of
+ * these names either validates as exactly one member or becomes a protocol issue on read.
+ */
+export declare const DecisionEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    ts: z.ZodString;
+    event: z.ZodLiteral<"gate-phase-start">;
+    taskId: z.ZodString;
+    data: z.ZodObject<{
+        attempt: z.ZodNumber;
+        gate: z.ZodEnum<{
+            build: "build";
+            test: "test";
+            lint: "lint";
+            evidence: "evidence";
+            scope: "scope";
+            acceptance: "acceptance";
+            review: "review";
+        }>;
+        evidence: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    ts: z.ZodString;
+    event: z.ZodLiteral<"gate-result">;
+    taskId: z.ZodString;
+    data: z.ZodObject<{
+        attempt: z.ZodNumber;
+        gate: z.ZodEnum<{
+            build: "build";
+            test: "test";
+            lint: "lint";
+            evidence: "evidence";
+            scope: "scope";
+            acceptance: "acceptance";
+            review: "review";
+        }>;
+        outcome: z.ZodType<GateOutcome, unknown, z.core.$ZodTypeInternals<GateOutcome, unknown>>;
+        details: z.ZodOptional<z.ZodString>;
+        load: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+            oneMinute: z.ZodNumber;
+            fiveMinute: z.ZodNumber;
+            cores: z.ZodNumber;
+        }, z.core.$strict>, z.ZodObject<{
+            unavailableReason: z.ZodString;
+        }, z.core.$strict>]>>;
+        evidence: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    ts: z.ZodString;
+    event: z.ZodLiteral<"role-invocation-start">;
+    taskId: z.ZodString;
+    data: z.ZodObject<{
+        attempt: z.ZodNumber;
+        role: z.ZodEnum<{
+            review: "review";
+            judge: "judge";
+            consult: "consult";
+            worker: "worker";
+        }>;
+        adapter: z.ZodOptional<z.ZodString>;
+        model: z.ZodOptional<z.ZodString>;
+        vendor: z.ZodOptional<z.ZodString>;
+        evidence: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    ts: z.ZodString;
+    event: z.ZodLiteral<"role-invocation-terminal">;
+    taskId: z.ZodString;
+    data: z.ZodObject<{
+        attempt: z.ZodNumber;
+        role: z.ZodEnum<{
+            review: "review";
+            judge: "judge";
+            consult: "consult";
+            worker: "worker";
+        }>;
+        adapter: z.ZodOptional<z.ZodString>;
+        model: z.ZodOptional<z.ZodString>;
+        vendor: z.ZodOptional<z.ZodString>;
+        evidence: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        outcome: z.ZodEnum<{
+            failed: "failed";
+            unavailable: "unavailable";
+            completed: "completed";
+        }>;
+        reason: z.ZodString;
+        tokens: z.ZodOptional<z.ZodObject<{
+            input: z.ZodNumber;
+            output: z.ZodNumber;
+            cacheRead: z.ZodOptional<z.ZodNumber>;
+            cacheWrite: z.ZodOptional<z.ZodNumber>;
+            reasoning: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>;
+        unmeteredReason: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    ts: z.ZodString;
+    event: z.ZodLiteral<"run-end">;
+    data: z.ZodObject<{
+        outcome: z.ZodEnum<{
+            failed: "failed";
+            completed: "completed";
+            incomplete: "incomplete";
+        }>;
+        reason: z.ZodString;
+        runId: z.ZodString;
+        branch: z.ZodString;
+        done: z.ZodArray<z.ZodString>;
+        failed: z.ZodArray<z.ZodString>;
+        human: z.ZodArray<z.ZodString>;
+        blocked: z.ZodArray<z.ZodString>;
+        pending: z.ZodArray<z.ZodString>;
+        tipVerify: z.ZodOptional<z.ZodEnum<{
+            failed: "failed";
+            passed: "passed";
+        }>>;
+        lastMergedTask: z.ZodOptional<z.ZodString>;
+        approvalDisposition: z.ZodOptional<z.ZodEnum<{
+            complete: "complete";
+            outstanding: "outstanding";
+        }>>;
+        outstandingApprovals: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        phase: z.ZodOptional<z.ZodString>;
+        fatal: z.ZodOptional<z.ZodBoolean>;
+        error: z.ZodOptional<z.ZodString>;
+        evidence: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strict>;
+}, z.core.$strict>], "event">;
+export type DecisionEvent = z.infer<typeof DecisionEventSchema>;
+export declare const DecisionEventWriteSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    data: z.ZodObject<{
+        attempt: z.ZodNumber;
+        gate: z.ZodEnum<{
+            build: "build";
+            test: "test";
+            lint: "lint";
+            evidence: "evidence";
+            scope: "scope";
+            acceptance: "acceptance";
+            review: "review";
+        }>;
+        evidence: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strict>;
+    taskId: z.ZodString;
+    event: z.ZodLiteral<"gate-phase-start">;
+}, z.core.$strict>, z.ZodObject<{
+    data: z.ZodObject<{
+        attempt: z.ZodNumber;
+        gate: z.ZodEnum<{
+            build: "build";
+            test: "test";
+            lint: "lint";
+            evidence: "evidence";
+            scope: "scope";
+            acceptance: "acceptance";
+            review: "review";
+        }>;
+        outcome: z.ZodType<GateOutcome, unknown, z.core.$ZodTypeInternals<GateOutcome, unknown>>;
+        details: z.ZodOptional<z.ZodString>;
+        load: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+            oneMinute: z.ZodNumber;
+            fiveMinute: z.ZodNumber;
+            cores: z.ZodNumber;
+        }, z.core.$strict>, z.ZodObject<{
+            unavailableReason: z.ZodString;
+        }, z.core.$strict>]>>;
+        evidence: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strict>;
+    taskId: z.ZodString;
+    event: z.ZodLiteral<"gate-result">;
+}, z.core.$strict>, z.ZodObject<{
+    data: z.ZodObject<{
+        attempt: z.ZodNumber;
+        role: z.ZodEnum<{
+            review: "review";
+            judge: "judge";
+            consult: "consult";
+            worker: "worker";
+        }>;
+        adapter: z.ZodOptional<z.ZodString>;
+        model: z.ZodOptional<z.ZodString>;
+        vendor: z.ZodOptional<z.ZodString>;
+        evidence: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strict>;
+    taskId: z.ZodString;
+    event: z.ZodLiteral<"role-invocation-start">;
+}, z.core.$strict>, z.ZodObject<{
+    data: z.ZodObject<{
+        attempt: z.ZodNumber;
+        role: z.ZodEnum<{
+            review: "review";
+            judge: "judge";
+            consult: "consult";
+            worker: "worker";
+        }>;
+        adapter: z.ZodOptional<z.ZodString>;
+        model: z.ZodOptional<z.ZodString>;
+        vendor: z.ZodOptional<z.ZodString>;
+        evidence: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        outcome: z.ZodEnum<{
+            failed: "failed";
+            unavailable: "unavailable";
+            completed: "completed";
+        }>;
+        reason: z.ZodString;
+        tokens: z.ZodOptional<z.ZodObject<{
+            input: z.ZodNumber;
+            output: z.ZodNumber;
+            cacheRead: z.ZodOptional<z.ZodNumber>;
+            cacheWrite: z.ZodOptional<z.ZodNumber>;
+            reasoning: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>;
+        unmeteredReason: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    taskId: z.ZodString;
+    event: z.ZodLiteral<"role-invocation-terminal">;
+}, z.core.$strict>, z.ZodObject<{
+    data: z.ZodObject<{
+        outcome: z.ZodEnum<{
+            failed: "failed";
+            completed: "completed";
+            incomplete: "incomplete";
+        }>;
+        reason: z.ZodString;
+        runId: z.ZodString;
+        branch: z.ZodString;
+        done: z.ZodArray<z.ZodString>;
+        failed: z.ZodArray<z.ZodString>;
+        human: z.ZodArray<z.ZodString>;
+        blocked: z.ZodArray<z.ZodString>;
+        pending: z.ZodArray<z.ZodString>;
+        tipVerify: z.ZodOptional<z.ZodEnum<{
+            failed: "failed";
+            passed: "passed";
+        }>>;
+        lastMergedTask: z.ZodOptional<z.ZodString>;
+        approvalDisposition: z.ZodOptional<z.ZodEnum<{
+            complete: "complete";
+            outstanding: "outstanding";
+        }>>;
+        outstandingApprovals: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        phase: z.ZodOptional<z.ZodString>;
+        fatal: z.ZodOptional<z.ZodBoolean>;
+        error: z.ZodOptional<z.ZodString>;
+        evidence: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strict>;
+    event: z.ZodLiteral<"run-end">;
+}, z.core.$strict>], "event">;
+export type DecisionEventWrite = z.infer<typeof DecisionEventWriteSchema>;
+export declare const DECISION_EVENT_NAMES: readonly ["gate-phase-start", "gate-result", "role-invocation-start", "role-invocation-terminal", "run-end"];
+type AssertNever<T extends never> = T;
+export type UntabledDecisionEventName = AssertNever<Exclude<DecisionEvent["event"], (typeof DECISION_EVENT_NAMES)[number]>>;
+export interface JournalSourceRow {
+    /** Zero-based physical JSONL line index. Blank and torn lines retain their place in this index. */
+    sourceIndex: number;
+    raw: unknown;
+}
+export interface InterpretedDecisionEvent {
+    kind: "decision";
+    runId: string;
+    sourceIndex: number;
+    event: DecisionEvent;
+    /** Original parsed JSON, retained even when a legacy row was normalized for interpretation. */
+    raw: unknown;
+    rawData: unknown;
+}
+/**
+ * Compatibility is deliberately opaque for event names outside the decision vocabulary. Arbitrary
+ * historical payloads survive byte-for-byte through `raw`; no unknown type can be mistaken for a
+ * successful decision merely because it happened to contain pass-like fields.
+ */
+export interface HistoricalUnknownEvent {
+    kind: "historical-unknown";
+    runId: string;
+    sourceIndex: number;
+    eventType?: string;
+    raw: unknown;
+    rawData: unknown;
+}
+export interface ProtocolIssue {
+    kind: "protocol-issue";
+    runId: string;
+    sourceIndex: number;
+    eventType: DecisionEvent["event"];
+    issues: string[];
+    raw: unknown;
+    rawData: unknown;
+}
+/** Closed tracked-reader result: decision, opaque historical unknown, or visible protocol failure. */
+export type TrackedJournalRow = InterpretedDecisionEvent | HistoricalUnknownEvent | ProtocolIssue;
+/** Interpret every parseable JSONL row without dropping unknown or malformed-known events. */
+export declare function trackJournalRows(runId: string, sourceRows: readonly JournalSourceRow[]): TrackedJournalRow[];
+export type PairRole = RoleInvocationRole | `gate:${GateName}`;
+export interface PairIdentity {
+    runId: string;
+    taskId: string;
+    attempt: number;
+    role: PairRole;
+}
+export interface PairIntegrityRecord {
+    identity: PairIdentity;
+    state: "closed" | "open" | "invalid";
+    startSourceIndexes: number[];
+    terminalSourceIndexes: number[];
+}
+export interface PairIntegrityIssue {
+    kind: "duplicate-start" | "duplicate-terminal" | "terminal-without-start" | "malformed-decision";
+    identity?: PairIdentity;
+    sourceIndexes: number[];
+    reason: string;
+}
+export interface PairIntegrityFold {
+    pairs: PairIntegrityRecord[];
+    issues: PairIntegrityIssue[];
+}
+/**
+ * Structural pair fold only. It does not reduce task or run state. An open start remains observable as
+ * open; duplicate starts/terminals and orphan terminals are invalid and never count as a closed pair.
+ */
+export declare function foldPairIntegrity(rows: readonly TrackedJournalRow[]): PairIntegrityFold;
+export {};