@voltro/workflow 0.33.0 → 0.35.0

package/dist/primitives.d.ts

@@ -3,6 +3,7 @@ import { DurableQueue as durableQueueModule } from '@effect/workflow';
 import { DurableRateLimiter as durableRateLimiterModule } from '@effect/workflow';
 import { Duration } from 'effect';
 import { Effect } from 'effect';
+import { FiberRef } from 'effect';
 import { Schema } from 'effect';
 import { Activity as stepModule } from '@effect/workflow';
 import { Workflow as workflowModule } from '@effect/workflow';
@@ -24,12 +25,25 @@ import { Workflow as workflowModule } from '@effect/workflow';
  */
 export declare const assertConsistentPools: (controls: ReadonlyArray<ResolvedFlowControl | undefined>) => void;
 
+/**
+ * The tracker for the CURRENT body entry, or `undefined` when there is nothing
+ * to compare against.
+ *
+ * Installed by `wrapWorkflowExecuteWithRunRecording` ONLY on a re-entry (a run
+ * whose row already exists). A first entry has no prior shape, so the whole
+ * mechanism costs one `FiberRef` read per step and nothing else.
+ */
+export declare const CurrentWorkflowReplayShape: FiberRef.FiberRef<ReplayShapeTracker | undefined>;
+
 /** The DECODED payload type. Mirrors `Workflow.make`'s own `idempotencyKey`
  *  parameter, so the two never disagree about what a payload is. */
 declare type DecodedPayload<P> = P extends Schema.Struct.Fields ? Schema.Struct.Type<P> : P extends {
     readonly Type: infer T;
 } ? T : never;
 
+/** 24 h — see {@link WorkflowScheduleDeclaration.maxRuntime}. */
+export declare const DEFAULT_WORKFLOW_SCHEDULE_MAX_RUNTIME_MS: number;
+
 /**
  * Controls that can DEFER a start rather than answer it immediately.
  *
@@ -66,6 +80,9 @@ export declare type FlowDuration = Duration.DurationInput;
  *  the path it took before this feature existed. */
 export declare const getWorkflowFlowControl: (value: unknown) => ResolvedFlowControl | undefined;
 
+/** The resolved schedule attached to a workflow definition, or undefined. */
+export declare const getWorkflowSchedule: (value: unknown) => ResolvedWorkflowSchedule | undefined;
+
 export declare const getWorkflowVersionMetadata: (value: unknown) => WorkflowVersionMetadata;
 
 /** `true` when this workflow declares at least one `cancelOn` entry — i.e. when
@@ -84,6 +101,34 @@ export declare const hasFlowControl: (control: ResolvedFlowControl | undefined)
 
 export declare const isWorkflowWorkerLayer: (value: unknown) => value is WorkflowWorkerLayerBrand;
 
+/**
+ * Build a tracker from the step rows this run recorded on EARLIER body entries.
+ *
+ * Pass the rows as they are: one row per step ATTEMPT, so a step that retried
+ * three times contributes three. Counting rows rather than distinct names is
+ * what makes the per-name sequence rule work, and the asymmetry is deliberate —
+ * only reaching a name MORE often than recorded is a finding. Fewer is normal
+ * (a crash mid-step records two rows for one logical reach).
+ */
+export declare const makeReplayShapeTracker: (recordedRows: ReadonlyArray<RecordedStepShape>) => ReplayShapeTracker;
+
+/** The `nondeterminism-suspected` event body. Kept here so the two emit sites
+ *  (the step wrapper, and the run wrapper's `settle`) cannot drift. */
+export declare const nondeterminismEventPayload: (finding: NondeterminismFinding) => Record<string, unknown>;
+
+export declare interface NondeterminismFinding {
+    readonly kind: NondeterminismKind;
+    readonly stepName: string;
+    /** How many rows this run recorded for `stepName` on EARLIER body entries. */
+    readonly recorded: number;
+    /** How many times the CURRENT body entry reached it. */
+    readonly reached: number;
+    /** One sentence an operator can act on, without opening the code. */
+    readonly detail: string;
+}
+
+export declare type NondeterminismKind = 'unreached-step' | 'extra-step-occurrence';
+
 declare type NormaliseWorkflowMessages<M extends WorkflowMessageSchemas | undefined> = {
     readonly signals: M extends {
         readonly signals: infer Signals;
@@ -91,11 +136,60 @@ declare type NormaliseWorkflowMessages<M extends WorkflowMessageSchemas | undefi
     readonly updates: M extends {
         readonly updates: infer Updates;
     } ? NonNullable<Updates> & Readonly<Record<string, WorkflowMessagePairSchemas>> : {};
-    readonly queries: M extends {
-        readonly queries: infer Queries;
-    } ? NonNullable<Queries> & Readonly<Record<string, WorkflowMessagePairSchemas>> : {};
 };
 
+/**
+ * Is a named change marker in effect for the run currently executing?
+ *
+ * This is the escape valve for the versioning trap. `compatibleWith` is
+ * all-or-nothing: leave an old version out and every in-flight run on it is
+ * terminally failed; leave it in and the old runs replay against the new body
+ * with no detection. `patch` is the third option — the body itself branches, so
+ * runs that started BEFORE the change keep taking the old path to completion
+ * while new runs take the new one.
+ *
+ * ```ts
+ * export const Charge = workflow({
+ *   name: 'billing.charge',
+ *   payload: { orderId: Schema.String },
+ *   idempotencyKey: ({ orderId }) => `billing.charge:${orderId}`,
+ *   patches: ['split-tax-calculation'],       // ← declare it
+ * })
+ *
+ * // inside the body:
+ * if (yield* patch('split-tax-calculation')) {
+ *   const net = yield* step({ name: 'net-total', execute })
+ *   const tax = yield* step({ name: 'tax', execute })
+ *   return net + tax
+ * }
+ * return yield* step({ name: 'total', execute })   // the pre-patch path
+ * ```
+ *
+ * ── The answer is pinned to the RUN, not to the code ────────────────────────
+ *
+ * `patches` is stamped onto `_voltro_workflow_runs.workflowPatches` when the
+ * run starts and read back from that row on every resume. So a run started
+ * before you added the marker answers `false` for the rest of its life,
+ * however many times it replays and whatever the deployed code says — which is
+ * the property that makes the branch deterministic across a redeploy.
+ *
+ * Under `@effect/workflow` the naive implementation does the opposite: an
+ * activity that is ABSENT from an old run's journal EXECUTES on replay (the
+ * journal is keyed name/attempt), so a marker journaled by an activity would
+ * answer `true` for exactly the old runs it must answer `false` for. Reading
+ * the run row sidesteps that entirely.
+ *
+ * ── Retiring a patch ───────────────────────────────────────────────────────
+ *
+ * Once no run predating the marker can still be in flight, delete the old
+ * branch and the entry from `patches`. Runs that stamped it keep the marker on
+ * their row for the audit trail; `patch()` simply stops being called.
+ *
+ * Outside a recorded workflow body (a unit test, a bare `step()` call) this is
+ * `false` — the pre-patch branch, which is the safe direction.
+ */
+export declare const patch: (id: string) => Effect.Effect<boolean>;
+
 /** The SCHEMA a payload input denotes — `Fields` lifted into a `Struct`. */
 declare type PayloadSchemaOf<P> = P extends Schema.Struct.Fields ? Schema.Struct<P> : P;
 
@@ -114,6 +208,39 @@ export declare const queueWorker: typeof durableQueueModule.worker;
 /** Durable rate limiter activity. Delays through the workflow clock. */
 export declare const rateLimit: typeof durableRateLimiterModule.rateLimit;
 
+/** The slice of a `_voltro_workflow_run_steps` row this needs. */
+export declare interface RecordedStepShape {
+    readonly stepName: string;
+}
+
+export declare interface ReplayShapeTracker {
+    /**
+     * The body reached `stepName`. Returns a finding the FIRST time that reach
+     * is anomalous, `undefined` otherwise — so a step in a hot loop reports once
+     * rather than once per iteration.
+     */
+    readonly reach: (stepName: string) => NondeterminismFinding | undefined;
+    /**
+     * The body ran to a COMPLETE outcome. Returns the set-membership findings —
+     * recorded names the body never reached.
+     *
+     * Call this ONLY on success/failure, never on a suspend: a suspended body
+     * stopped partway through on purpose, so everything after the suspension
+     * point is legitimately unreached.
+     */
+    readonly settle: () => ReadonlyArray<NondeterminismFinding>;
+}
+
+/**
+ * Emit findings from INSIDE the workflow body, where the run id and the
+ * recorder are only reachable through the fiber context.
+ *
+ * Best-effort in the strongest sense: no recorder, no run id, or a rejecting
+ * write all resolve to "nothing happened". A tripwire that can break the run it
+ * is watching is not a tripwire.
+ */
+export declare const reportNondeterminism: (findings: ReadonlyArray<NondeterminismFinding>) => Effect.Effect<void>;
+
 /** One resolved `cancelOn` entry. The schema is kept (not pre-compiled into a
  *  decoder) so the sweeper can report a decode failure naming the event, which
  *  is the difference between "the predicate said no" and "we could not read the
@@ -182,6 +309,18 @@ export declare interface ResolvedFlowControl {
     readonly cancelOn?: ReadonlyArray<ResolvedCancelOn>;
 }
 
+/** The declaration with defaults filled in — what the CLI lowering reads. */
+export declare interface ResolvedWorkflowSchedule {
+    readonly cron: string;
+    readonly timezone: string;
+    readonly payload?: unknown | ((fire: {
+        readonly scheduledAt: Date;
+    }) => unknown | Promise<unknown>);
+    readonly onOverlap: WorkflowScheduleOverlap;
+    readonly backfill: 'skip' | 'latest' | 'all';
+    readonly maxRuntimeMs: number;
+}
+
 /**
  * Durable sleep — wake time journaled in the cluster. Wrapper around
  * `DurableClock.sleep` that emits `timer-set` / `timer-fired` events
@@ -341,6 +480,14 @@ export declare interface ValidateFlowControlInput {
     readonly control: (WorkflowFlowControl<never> & WorkflowCancelOnDeclared) | undefined;
 }
 
+/**
+ * Validate at DEFINITION time — module load, i.e. boot — with a message naming
+ * the workflow and the field. Same posture as `validateFlowControl` and
+ * `defineSchedule`: a cron typo that surfaces as "never fired" three days in
+ * is the failure class this repo keeps paying for.
+ */
+export declare const validateWorkflowSchedule: (workflowName: string, declaration: WorkflowScheduleDeclaration<never> | undefined) => ResolvedWorkflowSchedule | undefined;
+
 /**
  * Add compensating (rollback) logic to a top-level effect in a workflow
  * body. The finalizer runs if the WHOLE workflow later fails — use it for
@@ -727,6 +874,12 @@ declare type WorkflowFn = <const Name extends string, Payload extends WorkflowPa
      *  type comes from its OWN `schema` — see {@link WorkflowCancelOnList} for
      *  why that needs a tuple type parameter rather than a plain array. */
     readonly cancelOn?: WorkflowCancelOnList<Cancels, DecodedPayload<Payload>>;
+    /** Run this workflow on a cron — the workflow-side spelling of a
+     *  `defineSchedule({ workflow })` target, with Temporal's overlap
+     *  vocabulary (`skip` / `buffer` / `cancelOther`). Lowered by the CLI into
+     *  a real schedule named `workflow:<name>`; see
+     *  {@link WorkflowScheduleDeclaration}. */
+    readonly schedule?: WorkflowScheduleDeclaration<DecodedPayload<Payload>>;
 } & Omit<WorkflowBaseOptions, 'name' | 'payload' | 'idempotencyKey' | 'success' | 'error'> & WorkflowVersionOptions & {
     readonly messages?: Messages;
 } & WorkflowFlowControl<DecodedPayload<Payload>>) => workflowModule.Workflow<Name, PayloadSchemaOf<Payload>, Success, Error> & WorkflowMessagesCarrier<NormaliseWorkflowMessages<Messages>>;
@@ -742,16 +895,24 @@ export declare interface WorkflowMessagesCarrier<M extends WorkflowMessagesMetad
     readonly [WorkflowMessagesProperty]: M;
 }
 
+/**
+ * The message channels a workflow declares.
+ *
+ * TWO, not three. `queries` used to sit here as a third channel and there was
+ * never a send path for it — no `sendWorkflowQuery`, no `awaitQuery`, nothing
+ * to receive one. It was normalised into metadata, projected into the generated
+ * rpcGroup and carried on the client's `WorkflowState`, so a user got a fully
+ * typed record they could not invoke from anywhere. Signals (fire-and-forget)
+ * and updates (synchronous, with a result) are the channels that exist.
+ */
 export declare interface WorkflowMessageSchemas {
     readonly signals?: Readonly<Record<string, Schema.Schema.Any>>;
     readonly updates?: Readonly<Record<string, WorkflowMessagePairSchemas>>;
-    readonly queries?: Readonly<Record<string, WorkflowMessagePairSchemas>>;
 }
 
 export declare interface WorkflowMessagesMetadata {
     readonly signals: Readonly<Record<string, Schema.Schema.Any>>;
     readonly updates: Readonly<Record<string, WorkflowMessagePairSchemas>>;
-    readonly queries: Readonly<Record<string, WorkflowMessagePairSchemas>>;
 }
 
 export declare const WorkflowMessagesProperty = "__voltroWorkflowMessages";
@@ -778,6 +939,68 @@ export declare interface WorkflowRateLimit<Payload> {
     readonly key?: (payload: Payload) => string;
 }
 
+export declare interface WorkflowScheduleDeclaration<Payload> {
+    /** Standard cron expression — 5-field or 6-field (leading seconds). */
+    readonly cron: string;
+    /** IANA timezone the expression is interpreted in. REQUIRED, like
+     *  `defineSchedule` — server-local time in a container is a bug factory. */
+    readonly timezone: string;
+    /**
+     * The payload each firing starts the workflow with. A value, or a function
+     * of the firing (`({ scheduledAt }) => …`) for payloads that carry the slot
+     * — a backfilled firing then computes against ITS instant, not "now".
+     * Omitted ⇒ `{}`, which only typechecks for workflows whose payload has no
+     * required fields; a mismatch fails the start with `WorkflowPayloadError`
+     * naming the missing fields, same as any other start.
+     */
+    readonly payload?: Payload | ((fire: {
+        readonly scheduledAt: Date;
+    }) => Payload | Promise<Payload>);
+    /** Default `'skip'` — Temporal's default too, and the only answer that is
+     *  safe for every job shape. */
+    readonly onOverlap?: WorkflowScheduleOverlap;
+    /** Boot catch-up policy for firings missed during downtime — the scheduler's
+     *  own vocabulary, unchanged. Default `'skip'`. For a RANGE older than boot
+     *  backfill reaches, use `voltro schedule backfill`. */
+    readonly backfill?: 'skip' | 'latest' | 'all';
+    /**
+     * Watchdog on ONE firing — which, for a workflow schedule, INCLUDES the
+     * awaited run (that await is what makes `onOverlap` bind on the run's
+     * duration). Default 24 hours rather than `defineSchedule`'s 30 minutes,
+     * because a durable run legitimately outlives a handler; set it above your
+     * slowest expected run. Past it the FIRING records `failed`/timeout and
+     * releases the overlap guard — the workflow run itself is NOT cancelled
+     * (declare flow-control `timeouts.finish` to bound the run).
+     */
+    readonly maxRuntime?: FlowDuration;
+}
+
+/**
+ * What happens when a firing arrives while the RUN from the previous firing is
+ * still going — Temporal Schedules' overlap vocabulary, applied to the
+ * workflow run (not merely to the handler invocation):
+ *
+ *   `'skip'`        — the new firing stands down; recorded as `skipped`.
+ *   `'buffer'`      — the new firing waits and runs after the previous one
+ *                     finishes; firings serialize, none is lost.
+ *   `'cancelOther'` — the new firing CANCELS the still-running previous run
+ *                     and starts fresh — for "recompute the latest state"
+ *                     jobs where the old run's partial work is worthless.
+ *
+ * The first two lower into the scheduler's own `onOverlap: 'skip' | 'queue'`;
+ * what makes them bind on the RUN's duration is that the synthesised handler
+ * AWAITS the workflow run to completion, so the schedule-run row is `running`
+ * for exactly as long as the workflow is.
+ */
+export declare type WorkflowScheduleOverlap = 'skip' | 'buffer' | 'cancelOther';
+
+/** Attached via `defineProperty` like the flow-control carrier — the value's
+ *  TYPE does not know about it, and the web bundle never reads it. A STRING
+ *  property rather than a symbol for the same reason as
+ *  `WorkflowFlowControlProperty`: the CLI's discovery reads it off a module
+ *  that crossed a bundler boundary, and symbols do not survive every one. */
+export declare const WorkflowScheduleProperty = "__voltroWorkflowSchedule";
+
 /**
  * At most one run per key. The newcomer either stands down or evicts.
  *
@@ -841,6 +1064,17 @@ export declare interface WorkflowVersionMetadata {
 export declare interface WorkflowVersionOptions {
     readonly version?: string | number;
     readonly compatibleWith?: ReadonlyArray<string | number>;
+    /**
+     * Named change markers this workflow's body may branch on, via
+     * {@link patch}. Declaring one here is what makes `yield* patch('id')`
+     * answer `true` for runs started from now on and `false` for runs that were
+     * already in flight — see {@link patch} for the semantics and the worked
+     * example.
+     *
+     * The declared set is stamped onto `_voltro_workflow_runs.workflowPatches`
+     * at run start and read back from THERE on every resume, so the answer is
+     * pinned to the run and cannot change under a redeploy.
+     */
     readonly patches?: ReadonlyArray<string>;
     /**
      * When `true`, a workflow whose top-level body FAILS does not become a

package/dist/primitives.js

@@ -1,2 +1,2 @@
-import { A as e, F as t, M as n, N as r, P as i, S as a, _ as o, a as s, b as c, c as l, d as u, f as d, g as f, h as p, i as m, j as h, l as g, m as _, n as v, o as y, p as b, r as x, s as S, t as C, u as w, v as T, x as E, y as D } from "./primitives-Bp98_F5L.js";
-export { e as DEFERRING_CONTROLS, C as WorkflowFlowControlProperty, v as WorkflowMessagesProperty, x as WorkflowVersionTypeId, m as WorkflowWorkerLayerTypeId, h as assertConsistentPools, n as deferringControlsOf, s as durableClock, y as durableQueue, S as durableQueueModule, l as durableRateLimiterModule, g as getWorkflowFlowControl, w as getWorkflowVersionMetadata, r as hasCancelOn, i as hasFlowControl, u as isWorkflowWorkerLayer, d as processQueue, b as queueWorker, _ as rateLimit, p as sleep, f as sleepUntil, o as step, T as stepIdempotencyKey, D as stepModule, t as validateFlowControl, c as withCompensation, E as workflow, a as workflowModule };
+import { A as e, B as t, C as n, D as r, E as i, G as a, H as o, O as s, S as c, T as l, U as u, V as d, W as f, _ as p, a as m, b as h, c as g, d as _, f as v, g as y, h as b, i as x, j as S, k as C, l as w, m as T, n as E, o as D, p as O, r as k, s as A, t as j, u as M, v as N, w as P, x as F, y as I } from "./primitives-CyQZeT1t.js";
+export { P as CurrentWorkflowReplayShape, s as DEFAULT_WORKFLOW_SCHEDULE_MAX_RUNTIME_MS, t as DEFERRING_CONTROLS, j as WorkflowFlowControlProperty, E as WorkflowMessagesProperty, C as WorkflowScheduleProperty, k as WorkflowVersionTypeId, x as WorkflowWorkerLayerTypeId, d as assertConsistentPools, o as deferringControlsOf, m as durableClock, D as durableQueue, A as durableQueueModule, g as durableRateLimiterModule, w as getWorkflowFlowControl, e as getWorkflowSchedule, M as getWorkflowVersionMetadata, u as hasCancelOn, f as hasFlowControl, _ as isWorkflowWorkerLayer, l as makeReplayShapeTracker, i as nondeterminismEventPayload, v as patch, O as processQueue, T as queueWorker, b as rateLimit, r as reportNondeterminism, y as sleep, p as sleepUntil, N as step, I as stepIdempotencyKey, h as stepModule, a as validateFlowControl, S as validateWorkflowSchedule, F as withCompensation, c as workflow, n as workflowModule };