@skastr0/prism-linux-x64 0.5.1 → 0.7.1

package/types/workflow-store.d.ts

@@ -1,7 +1,7 @@
 import { type WorkflowRetentionCleanupReport, type WorkflowRunArtifactCounts, type WorkflowRunDeletionReport } from "./workflow-data-governance.js";
 import type { WorkflowJudgeVerdict } from "./workflows.js";
-import type { WorkflowJudgeIdentity, WorkflowRunTaskSnapshot, WorkflowTaskIdentity } from "./workflow-identity.js";
-export { workflowRunTaskSnapshotForTask, workflowTaskIdentity, type WorkflowJudgeIdentity, type WorkflowRunTaskSnapshot, type WorkflowTaskIdentity } from "./workflow-identity.js";
+import type { WorkflowJudgeIdentity, WorkflowRunTaskSnapshot, WorkflowRunTaskSnapshotInput, WorkflowTaskIdentity } from "./workflow-identity.js";
+export { workflowRunTaskSnapshotForTask, workflowTaskIdentity, type JevRunTaskSnapshot, type WorkflowJudgeIdentity, type WorkflowRunTaskSnapshot, type WorkflowRunTaskSnapshotInput, type WorkflowTaskIdentity, type WorkflowWorkerRunTaskSnapshot, } from "./workflow-identity.js";
 import { type WorkflowDatabase } from "./workflow-runtime.js";
 import type { WorkflowSpanRecord } from "./workflow-tracing.js";
 import { type WorkflowUsage, type WorkflowUsageTotals } from "./workflow-usage.js";
@@ -200,11 +200,73 @@ export type WorkflowRunStatus = "running" | "completed" | "failed" | "escalated"
  * A run's persisted status can read "completed" while carrying isolated task failures: the
  * dynamic runtime's fault-isolation contract (PQ-166) lets an author's `run` program finish
  * successfully after recovering from a task that itself failed or escalated (e.g. via
- * `Effect.either`). That is not a caller-visible success — a caller gating on `$?` (the CLI)
+ * `Effect.result`). That is not a caller-visible success — a caller gating on `$?` (the CLI)
  * must still see the partial failure. Success requires both: the run itself reached
  * "completed", and every recorded task did too.
  */
 export declare function isWorkflowRunOutcomeSuccessful(runStatus: WorkflowRunStatus, taskStatuses: ReadonlyArray<WorkflowRunTaskProgressStatus>): boolean;
+/**
+ * Provenance for a run the scheduler launched, rather than one a human started.
+ *
+ * Absent on a hand-run workflow. That absence is the honest answer — there was
+ * no execution and no occurrence — so it is modelled as an optional parameter
+ * and a nullable column, not as a sentinel string.
+ */
+export interface WorkflowRunScheduling {
+    /** The scheduler execution that launched this run. */
+    readonly executionId: string;
+    /** The installed schedule the execution belongs to. */
+    readonly scheduleId: string;
+    /** The cron occurrence this run represents, as an ISO-8601 instant. */
+    readonly scheduledFor: string | null;
+}
+/** The triple that identifies a runner process without relying on the pid alone. */
+export interface WorkflowRunRunnerIdentity {
+    readonly pid: number;
+    readonly bootId: string | null;
+    readonly startId: string | null;
+}
+/**
+ * The scheduler's read-only view of a run it owns.
+ *
+ * Purpose-built rather than reusing `WorkflowRunRecord`: reconciliation needs
+ * the runner identity and the launch-authorization state, which are internal to
+ * the scheduling protocol and not part of the general run surface.
+ */
+export interface WorkflowScheduledRunState {
+    readonly runId: string;
+    readonly workflow: string;
+    readonly status: WorkflowRunStatus;
+    readonly schedulingExecutionId: string | null;
+    readonly schedulingScheduleId: string | null;
+    readonly scheduledFor: string | null;
+    readonly runner: WorkflowRunRunnerIdentity | null;
+    /**
+     * Whether a runner consumed this run's launch authorization.
+     *
+     * Meaningful only when `schedulingExecutionId` is set. The scheduler always
+     * issues an authorization token before spawning, so for a scheduled run a
+     * present token means no runner ever consumed it, and a consumed token means
+     * a runner did. A hand-run workflow has no token to consume and no execution
+     * to reconcile, so this field is not consulted for one.
+     */
+    readonly launchAuthorized: boolean;
+    readonly terminalCause: WorkflowRunTerminalCause | null;
+    readonly finishedAt: string | null;
+    readonly heartbeatAt: string | null;
+}
+/** The outcome of a runner attempting to consume its launch authorization. */
+export type WorkflowRunLaunchAuthorization = {
+    readonly kind: "authorized";
+} | {
+    readonly kind: "not-found";
+} | {
+    readonly kind: "unauthorized";
+    readonly reason: string;
+} | {
+    readonly kind: "terminal";
+    readonly status: WorkflowRunStatus;
+};
 export interface WorkflowEventRecord {
     readonly sequence: number;
     readonly runId: string;
@@ -292,7 +354,7 @@ export interface WorkflowTaskAttemptRecord {
 }
 export declare const projectWorkflowStoreDir: (prismHome: string, cwd?: string) => string;
 export declare const defaultWorkflowStorePath: (prismHome: string, cwd?: string) => string;
-export declare const WORKFLOW_STORE_SCHEMA_VERSION = 6;
+export declare const WORKFLOW_STORE_SCHEMA_VERSION = 8;
 /**
  * Surfaces the one-time soft-divergence direction (WFE-007): a pre-existing store opened at a
  * schema version older than the binary's `WORKFLOW_STORE_SCHEMA_VERSION` migrates in place inside
@@ -352,17 +414,78 @@ export declare class WorkflowStore {
         readonly cacheKey?: string;
         readonly promptHash?: string;
     }): WorkflowCacheRecord[];
-    createRun(workflow: string, runId?: string): string;
+    /**
+     * Create a run row.
+     *
+     * `scheduling` records provenance for a run the scheduler launched. It is
+     * written in the same transaction as the row itself, because a run that
+     * exists without its provenance would be a run the scheduler cannot claim
+     * during reconciliation.
+     */
+    createRun(workflow: string, runId?: string, scheduling?: WorkflowRunScheduling): string;
+    /**
+     * Consume a run's launch authorization and record the runner's identity.
+     *
+     * This is the linearization point of the launch protocol, and it is one
+     * transaction on purpose. "A runner was authorized" and "here is the runner's
+     * identity" must not be able to disagree, or reconciliation would face a
+     * window where a runner may have imported user code but left no identity to
+     * observe — an ambiguity with no honest resolution.
+     *
+     * The token comparison is timing-safe and the update is a compare-and-set on
+     * the token column, so two runners racing for the same authorization produce
+     * exactly one winner and one `unauthorized`.
+     *
+     * This deliberately does **not** touch `heartbeat_at`. The heartbeat is the
+     * *readiness* marker a detached launcher waits on, and readiness means "the
+     * runner is executing", not "the runner claimed the run" — so it is published
+     * by `markRunRunnerStarted` after the workflow module has loaded. Publishing it
+     * here would make a workflow whose top-level code exits look like a successful
+     * start, because authorization now happens before the import.
+     */
+    beginScheduledRun(input: {
+        readonly runId: string;
+        readonly token: string;
+        readonly runnerPid: number;
+        readonly runnerBootId: string | null;
+        readonly runnerStartId: string | null;
+    }): WorkflowRunLaunchAuthorization;
+    /**
+     * The scheduler's reconciliation view of one run. Null when the run does not
+     * exist — which is itself meaningful, since the scheduler creates the run
+     * before it spawns anything.
+     */
+    scheduledRunState(runId: string): WorkflowScheduledRunState | null;
+    /**
+     * Terminalize a scheduled run the scheduler has established cannot continue.
+     *
+     * Returns whether it wrote, so the caller can tell "we closed it" from "the
+     * runner claimed it first". The ledger keeps its existing status vocabulary —
+     * `crashed` for a worker that died mid-run, `stopped` for one that never
+     * received its authorization — while the scheduler's more specific knowledge
+     * lives on the execution row and in the event stream. Widening
+     * `WorkflowRunStatus` for the scheduler's benefit would put a new state in
+     * front of every consumer of run history for no gain.
+     *
+     * The update is guarded on `status = 'running'`, so it is a compare-and-set
+     * against a runner claiming the run concurrently: exactly one wins.
+     */
+    interruptScheduledRun(input: {
+        readonly runId: string;
+        readonly kind: "interrupted" | "cancelled";
+        readonly reason: string;
+        readonly runnerPid?: number | null;
+        readonly heartbeatAt?: string | null;
+    }): boolean;
     recordRunSnapshot(input: {
         readonly runId: string;
         readonly workflowFile: string;
         readonly options?: Record<string, unknown>;
     }): void;
     getRunSnapshot(runId: string): WorkflowRunSnapshot | null;
-    recordRunTaskSnapshot(input: Omit<WorkflowRunTaskSnapshot, "createdAt">): void;
+    recordRunTaskSnapshot(input: WorkflowRunTaskSnapshotInput): void;
     listRunTaskSnapshots(runId: string): WorkflowRunTaskSnapshot[];
     setRunHandoffToken(runId: string, token: string): void;
-    consumeRunHandoffToken(runId: string, token: string): boolean;
     markRunRunnerStarted(runId: string, runnerPid: number): void;
     heartbeatRun(runId: string): void;
     recordTaskAttemptStarted(input: WorkflowTaskAttemptStartedInput): void;
@@ -380,6 +503,18 @@ export declare class WorkflowStore {
         readonly reason?: string;
         readonly mode?: string;
     }): WorkflowRunRecord | null;
+    /**
+     * Read a run **without** observer reconciliation.
+     *
+     * The detached launcher polls its own run while it waits for the readiness
+     * handshake, and during startup it is the authority on that run. `getRun`
+     * runs `failDeadPidRuns` first, so a launcher polling its own child would
+     * terminalize the run as `dead-runner-pid` the instant the child died —
+     * preempting the launcher's own, more specific `runner-start-failed` cause and
+     * the stderr evidence it captured. Reconciliation is for observers, not for
+     * the process that owns the handshake.
+     */
+    peekRun(runId: string): WorkflowRunRecord | null;
     getRun(runId: string): WorkflowRunRecord | null;
     recordEvent(input: {
         readonly runId: string;

package/types/workflows.d.ts

@@ -1,8 +1,9 @@
-import { Effect, Schema } from "effect";
-import type { Either } from "effect/Either";
-import type { ParseError } from "effect/ParseResult";
+import { Effect, Result, Schema, type SchemaAST } from "effect";
 import { type WorkflowRuntimeError } from "./workflow-errors.js";
+import { type WorkflowSchedule } from "./workflow-scheduler/schedule.js";
+import { type JevEntry, type JevQuestions, type JevRequest, type JevResult, type JevResultCodec } from "./jev.js";
 export type { WorkflowRuntimeError } from "./workflow-errors.js";
+export { WORKFLOW_SCHEDULE_MISSED_RUN_POLICIES, WORKFLOW_SCHEDULE_OVERLAP_POLICIES, isWorkflowSchedule, parseWorkflowSchedule, type WorkflowSchedule, type WorkflowScheduleMissedRuns, type WorkflowScheduleOverlap, } from "./workflow-scheduler/schedule.js";
 export interface WorkflowModelRef {
     readonly modelspace?: string;
     readonly profile?: string;
@@ -42,7 +43,19 @@ export interface WorkflowValidationSummary {
     readonly tasks: ReadonlyArray<WorkflowTaskSummary>;
     readonly dynamic: boolean;
 }
-export type WorkflowOutputSchema = Schema.Schema.AnyNoContext;
+/**
+ * Constraint for a workflow task's output schema.
+ *
+ * The load-bearing part is `never, never`: a task output schema must decode and
+ * encode without services. `Type` stays `unknown` so the generic bound cannot
+ * silently turn decoded values into `any`.
+ *
+ * `WorkflowFinishOptions` consumes `Output` in contravariant callback positions,
+ * which makes a task invariant in its output type. A heterogeneous task tuple is
+ * therefore accepted only where the output type is erased, which happens at
+ * `AnyWorkflowTask` rather than here.
+ */
+export type WorkflowOutputSchema = Schema.Codec<unknown, unknown, never, never>;
 export type WorkflowFinishCriterionError = Error;
 export type WorkflowWorkerId = "amp-code" | "antigravity-cli" | "claude-code" | "codex-cli" | "cursor" | "devin" | "grok" | "hermes" | "kimi-code" | "opencode" | "opencode2" | "omp";
 /**
@@ -139,11 +152,11 @@ export interface WorkflowTaskModelResolution {
  * `undefined` so per-worker CLIs that tolerate an omitted --model flag
  * (e.g. opencode) keep doing so.
  */
-export declare const resolveWorkflowTaskModelResolution: (task: AnyWorkflowTask, options?: {
+export declare const resolveWorkflowTaskModelResolution: (task: AnyWorkflowWorkerTask, options?: {
     readonly worker?: string;
     readonly fallbackModel?: string;
 }) => WorkflowTaskModelResolution | undefined;
-export declare const resolveWorkflowTaskModel: (task: AnyWorkflowTask, options?: {
+export declare const resolveWorkflowTaskModel: (task: AnyWorkflowWorkerTask, options?: {
     readonly worker?: string;
     readonly fallbackModel?: string;
 }) => string | undefined;
@@ -215,20 +228,66 @@ export interface WorkflowTaskDefinition<Id extends string, Output extends Workfl
     readonly phase?: string;
     readonly cacheKey?: string;
     readonly worker?: WorkflowTaskWorkerOptions;
-    readonly finish?: WorkflowFinishOptions<Schema.Schema.Type<Output>>;
+    readonly finish?: WorkflowFinishOptions<Output["Type"]>;
 }
 export type WorkflowTask<Id extends string = string, Output extends WorkflowOutputSchema = WorkflowOutputSchema> = WorkflowTaskDefinition<Id, Output> & {
     readonly kind: "workflow-task";
 };
-export type AnyWorkflowTask = WorkflowTask<string, WorkflowOutputSchema>;
-export type WorkflowTaskOutput<Task extends AnyWorkflowTask> = Schema.Schema.Type<Task["output"]>;
-export declare const resolveWorkflowTaskSessionPersistence: (task: Pick<AnyWorkflowTask, "worker">, effectiveWorker?: string | undefined) => WorkflowSessionPersistence | undefined;
-export declare const assertWorkflowTaskSessionPersistence: (task: AnyWorkflowTask) => void;
+/**
+ * A workflow task whose output type is erased.
+ *
+ * A task is invariant in its output type (`WorkflowFinishOptions` consumes it in
+ * callback positions), so `defineWorkflow({ tasks: [build, review] })` only
+ * accepts a heterogeneous tuple when the element bound erases that type. The
+ * erasure is deliberately local to this bound: `WorkflowOutputSchema` keeps
+ * `unknown` so ordinary authoring and `defineTask` inference stay precise, and
+ * `WorkflowTaskOutput<Task>` still reads the concrete output of a concrete task.
+ *
+ * The encoded side and the service-free requirement (`never, never`) are not
+ * erased. This is a deliberate loss of proof at the task-collection boundary,
+ * not sound existential quantification.
+ */
+export type AnyWorkflowWorkerTask = WorkflowTask<string, Schema.Codec<any, unknown, never, never>>;
+/**
+ * A Jev task whose question types are erased. Like the worker erasure above,
+ * this keeps heterogeneous `tasks: [...] tuples writable while concrete
+ * `jev(...)` calls keep their precise inferred output.
+ */
+export type AnyJevTask = JevTask<string, any>;
+export type AnyWorkflowTask = AnyWorkflowWorkerTask | AnyJevTask;
+export type WorkflowTaskOutput<Task extends AnyWorkflowTask> = Task["output"]["Type"];
+export interface JevTaskDefinition<Id extends string, Q extends JevQuestions> extends JevRequest<Q> {
+    readonly id: Id;
+    /** Per-HTTP-attempt timeout override passed to the JevClient call. */
+    readonly timeoutMs?: number;
+    readonly phase?: string;
+    readonly cacheKey?: string;
+}
+export type JevTask<Id extends string = string, Q extends JevQuestions = JevQuestions> = JevTaskDefinition<Id, Q> & {
+    readonly kind: "jev";
+    readonly output: JevResultCodec<Q>;
+};
+/**
+ * Construct a native Jev decision task. The state/questions are validated,
+ * deep-copied, and frozen immediately so identity hashing and execution can
+ * never disagree, and the output codec is derived from the questions.
+ */
+export declare const jev: <const Id extends string, const Q extends JevQuestions>(definition: JevTaskDefinition<Id, Q>) => JevTask<Id, Q>;
+export declare const resolveWorkflowTaskSessionPersistence: (task: Pick<AnyWorkflowWorkerTask, "worker">, effectiveWorker?: string | undefined) => WorkflowSessionPersistence | undefined;
+export declare const assertWorkflowTaskSessionPersistence: (task: AnyWorkflowWorkerTask) => void;
+export declare const isWorkflowWorkerTask: (value: unknown) => value is AnyWorkflowWorkerTask;
+export declare const isJevTask: (value: unknown) => value is AnyJevTask;
 export declare const isWorkflowTask: (value: unknown) => value is AnyWorkflowTask;
 export interface WorkflowDefinition<Name extends string, Tasks extends ReadonlyArray<AnyWorkflowTask>> {
     readonly kind: "workflow";
     readonly name: Name;
     readonly tasks: Tasks;
+    /**
+     * Inert scheduling policy. Declaring it registers nothing; only
+     * `prism workflow schedule install` activates a schedule. See
+     * `workflow-scheduler/schedule.ts`.
+     */
+    readonly schedule?: WorkflowSchedule;
 }
 export interface PhaseFraming {
     readonly purpose?: string;
@@ -254,21 +313,37 @@ export type PhaseTaskFinishOptions<Output> = WorkflowFinishOptions<Output> & {
     readonly inherit?: boolean;
 };
 /** Decoded TypeScript value of a phase input contract (unknown when no contract). */
-export type PhaseTaskInputValue<Input extends WorkflowOutputSchema | undefined> = Input extends WorkflowOutputSchema ? Schema.Schema.Type<Input> : unknown;
+export type PhaseTaskInputValue<Input extends WorkflowOutputSchema | undefined> = Input extends WorkflowOutputSchema ? Input["Type"] : unknown;
 export type PhaseTaskDefinition<Id extends string, Input extends WorkflowOutputSchema | undefined = undefined, Output extends WorkflowOutputSchema = WorkflowOutputSchema> = Omit<WorkflowTaskDefinition<Id, Output>, "output" | "phase" | "finish"> & {
     readonly input?: PhaseTaskInputValue<Input>;
     readonly output?: Output;
     readonly phase?: string;
-    readonly finish?: PhaseTaskFinishOptions<Schema.Schema.Type<Output>>;
+    readonly finish?: PhaseTaskFinishOptions<Output["Type"]>;
     readonly brief?: boolean;
 };
 export type PhaseCtxTask<Input extends WorkflowOutputSchema | undefined, DefaultOutput extends WorkflowOutputSchema | undefined> = <const Id extends string, const TaskOutput extends WorkflowOutputSchema = Extract<DefaultOutput, WorkflowOutputSchema>>(def: PhaseTaskDefinition<Id, Input, TaskOutput>) => Effect.Effect<WorkflowTaskOutput<WorkflowTask<Id, TaskOutput>>, WorkflowRuntimeError>;
+/**
+ * A `ctx.jev(...)` definition. When the phase binds an input contract, the
+ * Jev state is that contract's decoded value (it must still be a valid System
+ * One entry — schemas describing functions or class instances do not belong
+ * in state and will fail entry validation at run time).
+ */
+export type PhaseJevTaskDefinition<Id extends string, Input extends WorkflowOutputSchema | undefined, Q extends JevQuestions> = Omit<JevTaskDefinition<Id, Q>, "state"> & {
+    readonly state: Input extends WorkflowOutputSchema ? Input["Type"] & JevEntry : JevEntry;
+};
+export type PhaseCtxJev<Input extends WorkflowOutputSchema | undefined> = <const Id extends string, const Q extends JevQuestions>(definition: PhaseJevTaskDefinition<Id, Input, Q>) => Effect.Effect<JevResult<Q>, WorkflowRuntimeError>;
 export interface PhaseCtx<Name extends string, Input extends WorkflowOutputSchema | undefined, DefaultOutput extends WorkflowOutputSchema | undefined> {
     readonly name: Name;
     readonly sop: string;
     readonly plugin: string;
     readonly phase: string;
     readonly task: PhaseCtxTask<Input, DefaultOutput>;
+    /**
+     * Run a native Jev decision inside this phase. Unlike `ctx.task`, no prompt
+     * framing, serialized-input block, finish criteria, or phase output schema
+     * is applied — a decision is defined by its state and questions alone.
+     */
+    readonly jev: PhaseCtxJev<Input>;
 }
 export declare const phase: <const Name extends string, const Input extends WorkflowOutputSchema | undefined, const Output extends WorkflowOutputSchema | undefined, Result, Err = WorkflowRuntimeError>(runtime: Pick<WorkflowRuntime, "runTask">, contract: PhaseContract<Name, Input, Output>, fn: (ctx: PhaseCtx<Name, Input, Output>) => Effect.Effect<Result, Err, never>) => Effect.Effect<Result, Err | WorkflowRuntimeError, never>;
 export interface WorkflowRuntime {
@@ -285,6 +360,8 @@ export interface DynamicWorkflowDefinition<Name extends string, Result = unknown
     readonly name: Name;
     readonly tasks: readonly [];
     readonly run: (runtime: WorkflowRuntime) => Effect.Effect<Result, Err, never>;
+    /** Inert scheduling policy; see `WorkflowDefinition.schedule`. */
+    readonly schedule?: WorkflowSchedule;
 }
 export type AnyWorkflowDefinition = WorkflowDefinition<string, ReadonlyArray<AnyWorkflowTask>> | DynamicWorkflowDefinition<string>;
 export declare const isWorkflowDefinition: (value: unknown) => value is AnyWorkflowDefinition;
@@ -293,9 +370,11 @@ export declare const defineTask: <const Id extends string, const Output extends
 export declare function defineWorkflow<const Name extends string, const Tasks extends ReadonlyArray<AnyWorkflowTask>>(definition: {
     readonly name: Name;
     readonly tasks: Tasks;
+    readonly schedule?: WorkflowSchedule;
 }): WorkflowDefinition<Name, Tasks>;
 export declare function defineWorkflow<const Name extends string, Result, Err = WorkflowRuntimeError>(definition: {
     readonly name: Name;
     readonly run: (runtime: WorkflowRuntime) => Effect.Effect<Result, Err, never>;
+    readonly schedule?: WorkflowSchedule;
 }): DynamicWorkflowDefinition<Name, Result, Err>;
-export declare const decodeTaskOutput: <Task extends AnyWorkflowTask>(task: Task, value: unknown) => Either<Schema.Schema.Type<Task["output"]>, ParseError>;
+export declare const decodeTaskOutput: <Task extends AnyWorkflowTask | AnyJevTask>(task: Task, value: unknown, options?: SchemaAST.ParseOptions) => Result.Result<Task["output"]["Type"], Schema.SchemaError>;