@sanity/workflow-engine 0.18.0 → 0.19.0

package/dist/index.d.ts

@@ -140,6 +140,19 @@ export declare interface ActionEvaluation {
   triggered?: true;
   /** Present iff `allowed === false`. The first failing gate wins. */
   disabledReason?: DisabledReason;
+  /**
+   * What firing this action would do to the flow RIGHT NOW — the fire
+   * replayed in memory on the engine's own machinery (ops, the triggered
+   * fixpoint, transition selection) against this projection's state, and
+   * conditional on the commit landing (rejectability is `allowed` /
+   * `disabledReason`'s story). Omitted when the consequence depends on
+   * inputs the projection doesn't hold — caller params, a spawn's
+   * dataset-driven fan-out, a terminal instance, a stage visit whose
+   * entries have diverged from the pinned definition — and on cascade-fired
+   * actions, which are never a caller's to fire. Advisory like every
+   * derived verdict: a placement/phrasing hint, never a gate.
+   */
+  firing?: FiringConsequence;
   /** Derived state of the action's `filter` gate — why it holds or fails,
    *  atom by atom. Present iff the action declares a filter. */
   insight?: ConditionInsight;
@@ -1672,6 +1685,42 @@ declare type Clocked<T> = T & {
   clock?: Clock;
 };
 
+declare interface CommitEffectOpsArgs extends DedupableOperationArgs {
+  /** The `_key` of the pending effect being reported on. */
+  effectKey: string;
+  /**
+   * Required here, unlike the other dedupable verbs: the engine cannot
+   * assume a supplied field op is idempotent, so every mid-dispatch report
+   * must be retry-safe. (The runtime check remains for untyped callers.)
+   */
+  idempotencyKey: string;
+  /**
+   * The exact-claim identity handed to the reporting dispatch. The commit
+   * re-reads the instance and rejects (writing nothing) unless the entry's
+   * live claim carries this token unexpired — so an expired, released, or
+   * superseded handler cannot update state. A successful commit renews the
+   * claim's lease.
+   */
+  claimToken: string;
+  /**
+   * Mid-dispatch field state, `field.*` ops only — validated and applied
+   * exactly like completion ops (same applier, same target resolution
+   * against the current open stage, workflow-/stage-scope only, never
+   * `status.set`). Must be non-empty. Completion ops remain the final
+   * atomic result committed when the handler returns; these are separately
+   * committed and observable before it.
+   */
+  ops: FieldOp[];
+  /** Lease duration the successful commit renews the claim to — the
+   *  drain's `effectLeaseMs`. Default `DEFAULT_EFFECT_LEASE_MS` (5 min). */
+  leaseMs?: number;
+}
+
+export declare interface CommitOpsRequest {
+  ops: FieldOp[];
+  idempotencyKey: string;
+}
+
 export { ComparisonOp };
 
 /**
@@ -1749,6 +1798,20 @@ export declare function computeDiffEntries<
   target: DeployTarget;
 }): Promise<DiffEntry[]>;
 
+/** {@link ConcurrentCompleteEffectError}'s mid-dispatch sibling: a
+ *  `commitEffectOps` commit lost every optimistic-locking attempt. Nothing
+ *  was written; the report may be retried under the same idempotency key. */
+export declare class ConcurrentCommitEffectOpsError extends WorkflowError<"concurrent-commit-effect-ops"> {
+  readonly instanceId: string;
+  readonly effectKey: string;
+  readonly attempts: number;
+  constructor(args: {
+    instanceId: string;
+    effectKey: string;
+    attempts: number;
+  });
+}
+
 /**
  * Completion twin of {@link ConcurrentFireActionError}: a `completeEffect`
  * commit lost the optimistic-locking race on every attempt. Same contract —
@@ -2221,6 +2284,24 @@ export declare const DATA_MODEL_CHANGES: readonly [
     applicability: "detectable";
     summary: "String, text, and number values may carry persisted inclusive bounds.";
   }>,
+  Readonly<{
+    id: "progress-field-kind";
+    introducedInModel: 3;
+    minReaderModel: 0;
+    documentTypes: readonly ["definition", "instance"];
+    compatibility: "additive";
+    applicability: "detectable";
+    summary: "A progress field kind carries application-defined 0–100 completion.";
+  }>,
+  Readonly<{
+    id: "effect-claim-tokens";
+    introducedInModel: 3;
+    minReaderModel: 0;
+    documentTypes: readonly ["instance"];
+    compatibility: "additive";
+    applicability: "detectable";
+    summary: "Pending-effect claims carry an exact-claim token gating mid-dispatch state reports.";
+  }>,
 ];
 
 /**
@@ -2245,7 +2326,7 @@ export declare const DATA_MODEL_MIN_READER = 2;
  * job. Declare every bump in `DATAMODEL.md`; the model-surface snapshot test
  * keeps undeclared drift red.
  */
-export declare const DATA_MODEL_VERSION = 2;
+export declare const DATA_MODEL_VERSION = 3;
 
 export declare interface DataModelChange {
   readonly id: string;
@@ -2278,9 +2359,10 @@ export declare type DeclaredExecutionContext = Pick<
 
 /**
  * The {@link OperationArgs} of the verbs that own a discrete commit —
- * `fireAction`, `editField`, `completeEffect`, `setStage`, `abortInstance`.
- * `tick` deliberately takes the plain base: it owns no commit of its own and
- * re-derives everything, so retrying it blind is already safe.
+ * `fireAction`, `editField`, `completeEffect`, `commitEffectOps`, `setStage`,
+ * `abortInstance`. `tick` deliberately takes the plain base: it owns no
+ * commit of its own and re-derives everything, so retrying it blind is
+ * already safe.
  */
 export declare interface DedupableOperationArgs extends OperationArgs {
   /**
@@ -3285,6 +3367,16 @@ export declare type EditMode = "set" | "append" | "unset";
 
 export declare type Effect = v.InferOutput<typeof EffectSchema>;
 
+/** Total commits one dispatch may make — the runaway-handler bound: without
+ *  it, a looping reporter renews its own lease and appends history forever.
+ *  2× the ceiling of 1%-granularity progress reporting. */
+export declare const EFFECT_COMMIT_DISPATCH_CAP = 200;
+
+/** Pending mid-dispatch commits one dispatch may hold before `commitOps` /
+ *  `setProgress` throws synchronously. An awaiting handler never reaches it
+ *  (its queue depth stays ≤ 1). */
+export declare const EFFECT_COMMIT_QUEUE_DEPTH = 32;
+
 /**
  * Every terminal state an effect run can record. `done` and `failed` are
  * reported through completion ({@link EffectCompletionStatus}); `cancelled`
@@ -3294,6 +3386,22 @@ export declare type Effect = v.InferOutput<typeof EffectSchema>;
  */
 declare const EFFECT_RUN_STATUSES: readonly ["done", "failed", "cancelled"];
 
+/**
+ * A `ctx.commitOps` / `ctx.setProgress` call hit one of the dispatch's
+ * bounds. Thrown synchronously at the call site — see the module doc for why
+ * a rejection would be invisible to exactly the caller the bound exists for.
+ */
+export declare class EffectCommitQueueOverflowError extends WorkflowError<"effect-commit-queue-overflow"> {
+  readonly effectKey: string;
+  readonly bound: "queue-depth" | "dispatch-cap";
+  readonly limit: number;
+  constructor(args: {
+    effectKey: string;
+    bound: "queue-depth" | "dispatch-cap";
+    limit: number;
+  });
+}
+
 /** The outcomes a completer may report through `completeEffect` — a run
  *  either succeeded or failed. `cancelled` is not reportable: only an abort
  *  stamps it, on entries that never dispatched. */
@@ -3378,6 +3486,34 @@ declare type EffectHandlerContext<Client extends WorkflowClient> = {
   instanceId: string;
   effectKey: string;
   log: (message: string, extra?: Record<string, unknown>) => void;
+  /**
+   * Commit mid-dispatch field state as a real engine transaction —
+   * validated like completion ops (`field.*` only, never `status.set`),
+   * gated on THIS dispatch's exact claim (a stale/superseded claim
+   * rejects before writing), history + idempotency recorded, guards
+   * refreshed, cascade run, and the claim's lease renewed in the same
+   * commit. Calls enqueue synchronously into a bounded per-dispatch FIFO
+   * and execute strictly in call order, one at a time — forgetting to
+   * `await` cannot create same-handler write races, and overflow (or the
+   * per-dispatch commit cap) throws synchronously at the call site.
+   * Await each call anyway: that is where errors surface promptly and
+   * engine commit latency paces the reporter. `idempotencyKey` is
+   * required — the engine does not assume a supplied op is idempotent.
+   * An accepted-but-unawaited commit that fails still fails the effect
+   * at settlement; the final completion always waits for this queue to
+   * drain. Never coalesced.
+   */
+  commitOps: (req: CommitOpsRequest) => Promise<void>;
+  /**
+   * Report absolute progress — sugar over {@link commitOps} that
+   * `field.set`s a number (a `progress` field's 0–100 contract is
+   * enforced by the engine at commit). A bare string targets a
+   * workflow-scope field; pass `{scope: 'stage', field}` for stage
+   * scope. Unlike `commitOps`, PENDING sets to the same field coalesce
+   * (latest value wins, one commit), so a tight reporting loop is safe
+   * by construction; idempotency keys are engine-derived.
+   */
+  setProgress: (target: ProgressTarget, value: number) => Promise<void>;
 };
 
 export declare interface EffectHistoryEntry {
@@ -3579,6 +3715,10 @@ export declare interface Engine {
    *  reassign / reschedule / claim-by-hand / append-to-log, then cascade. */
   editField: (args: EditFieldArgs) => Promise<OperationResult>;
   completeEffect: (args: CompleteEffectArgs) => Promise<OperationResult>;
+  /** Commit mid-dispatch field state from a running effect handler — the
+   *  verb behind `ctx.commitOps`. Gated on the dispatch's exact claim token;
+   *  a successful commit renews the claim's lease. */
+  commitEffectOps: (args: CommitEffectOpsArgs) => Promise<OperationResult>;
   tick: (args: OperationArgs) => Promise<OperationResult>;
   /** Project the instance from an actor's perspective — per-action verdicts
    *  with structured disabled reasons. Pure read. */
@@ -4117,6 +4257,10 @@ export declare const FIELD_KIND_DISPLAY: {
     title: string;
     description: string;
   };
+  progress: {
+    title: string;
+    description: string;
+  };
   boolean: {
     title: string;
     description: string;
@@ -4174,6 +4318,7 @@ declare const FIELD_VALUE_KINDS: readonly [
   "string",
   "text",
   "number",
+  "progress",
   "boolean",
   "date",
   "datetime",
@@ -4314,6 +4459,10 @@ export declare interface FieldValueMap {
   /** Multiline string — same value as {@link FieldValueMap.string}, distinct kind for rendering. */
   text: string | null;
   number: number | null;
+  /** Application-defined 0–100 completion — same stored value as
+   *  {@link FieldValueMap.number}, distinct kind so surfaces can elevate it;
+   *  always finite and within 0–100 inclusive (fractions allowed). */
+  progress: number | null;
   boolean: boolean | null;
   /** Date-only (`YYYY-MM-DD`), no time component. */
   date: string | null;
@@ -4411,6 +4560,20 @@ export declare interface FireActionArgs extends DedupableOperationArgs {
   idempotent?: boolean;
 }
 
+/**
+ * The flow consequence of one caller fire, computed by replaying it in
+ * memory through the same machinery a real commit runs — never by a
+ * parallel model of it. State-dependent: it answers "now", not "always".
+ */
+export declare interface FiringConsequence {
+  /** The replayed commit's cascade exits the current stage in its first
+   *  hop. `false` is a definite answer for the current state — including
+   *  a selection halted by an unevaluable trigger, which holds the stage. */
+  exitsStage: boolean;
+  /** The transition the selection picked, present iff `exitsStage`. */
+  transition?: string;
+}
+
 export { formatRead };
 
 /**
@@ -6335,6 +6498,16 @@ export declare interface PendingEffectClaim {
    * live claim), and a field would drift from that trail across releases.
    */
   leaseExpiresAt?: string;
+  /**
+   * The exact-claim identity a mid-dispatch state report must present.
+   * `effectKey` cannot serve: a lease takeover keeps the same key, so a
+   * superseded handler holding only the key could still write. The token is
+   * minted fresh on every claim and takeover; `commitEffectOps` rejects a
+   * report whose token no longer matches before writing anything. Absent
+   * only on claims persisted before tokens existed — those never match, so
+   * their dispatches simply cannot report mid-flight.
+   */
+  claimToken?: string;
 }
 
 /**
@@ -6400,6 +6573,15 @@ export declare function processShellUserProperties<
   runtimeVersion: string;
 };
 
+/** `setProgress`'s field addressing: a bare name targets the workflow scope;
+ *  pass `{scope: 'stage', field}` for a stage-scope progress field. */
+export declare type ProgressTarget =
+  | string
+  | {
+      scope: "workflow" | "stage";
+      field: string;
+    };
+
 /**
  * Project a store-resolved doc onto its watch ref's identity, the way the
  * lake's perspective reads do: the published-form id becomes `_id` (the form
@@ -6457,7 +6639,7 @@ export declare class ReaderModelAcknowledgementError extends WorkflowError<"read
   readonly code = "WORKFLOW_READER_MODEL_ACKNOWLEDGEMENT_MISMATCH";
   readonly expectedMinReaderModel: unknown;
   readonly engineMinReaderModel = 2;
-  readonly engineModelVersion = 2;
+  readonly engineModelVersion = 3;
   readonly documentationUrl =
     "https://github.com/sanity-io/workflows/blob/main/docs/reader-model-rollout.md";
   constructor(expectedMinReaderModel: unknown, context?: string);
@@ -7079,6 +7261,32 @@ declare interface StageGuardArgs {
 
 export declare type StageName = string;
 
+/** Why a mid-dispatch report's claim no longer authorises it — see
+ *  {@link StaleEffectClaimError}. */
+export declare type StaleClaimReason =
+  | "unclaimed"
+  | "claim-superseded"
+  | "lease-expired";
+
+/**
+ * Thrown when a mid-dispatch state report (`commitEffectOps`) presents a
+ * claim token that no longer authorises writing: the entry's claim was
+ * released, taken over by another dispatch (`claim-superseded`), or its
+ * lease lapsed. Nothing was written — the gate runs before any mutation.
+ * The handler should stop reporting; its completion still follows the
+ * normal first-writer-wins completion semantics.
+ */
+export declare class StaleEffectClaimError extends WorkflowError<"stale-effect-claim"> {
+  readonly instanceId: string;
+  readonly effectKey: string;
+  readonly reason: StaleClaimReason;
+  constructor(args: {
+    instanceId: string;
+    effectKey: string;
+    reason: StaleClaimReason;
+  });
+}
+
 /**
  * The vars a definition's `start.allowed` reads — the start-time permission
  * dialect: everything the filter context binds ({@link START_FILTER_VARS})
@@ -8527,6 +8735,23 @@ export declare const workflow: {
   completeEffect: (
     rawArgs: Clocked<Telemetered<CompleteEffectArgs & EngineScopeArgs>>,
   ) => Promise<OperationResult>;
+  /**
+   * Commit mid-dispatch field state from a running effect handler — the
+   * engine verb behind `ctx.commitOps`. Gates on the dispatch's exact claim
+   * (token match + unexpired lease; a stale report throws
+   * `StaleEffectClaimError` and writes nothing), validates and applies the
+   * `field.*` ops through the shared op applier, records history and the
+   * mandatory idempotency key, renews the claim's lease in the same
+   * compare-and-swap commit, refreshes the stage's guards, then cascades —
+   * a report that satisfies a transition moves the instance, by design.
+   *
+   * Completion (`completeEffect`) remains the authoritative final result
+   * and stays claim-blind; this verb only protects the mid-dispatch write
+   * channel from superseded handlers.
+   */
+  commitEffectOps: (
+    rawArgs: Clocked<Telemetered<CommitEffectOpsArgs & EngineScopeArgs>>,
+  ) => Promise<OperationResult>;
   /**
    * Run the cascade until stable — triggered actions fire, transitions move.
    *
@@ -8979,7 +9204,11 @@ declare const WorkflowConfigSchema: v.ObjectSchema<
               readonly name: v.SchemaWithPipe<
                 readonly [
                   v.StringSchema<undefined>,
-                  v.NonEmptyAction<string, "must not be empty">,
+                  v.NonEmptyAction<string, undefined>,
+                  v.CheckAction<
+                    string,
+                    `invalid ${string} \u2014 ASCII lowercase + digits + dashes, no leading dash, no dots`
+                  >,
                 ]
               >;
               readonly expectedMinReaderModel: v.OptionalSchema<
@@ -8992,7 +9221,7 @@ declare const WorkflowConfigSchema: v.ObjectSchema<
                   v.NonEmptyAction<string, undefined>,
                   v.CheckAction<
                     string,
-                    "invalid tag — lowercase letters, digits and dashes only, no leading dash, no dots"
+                    `invalid ${string} \u2014 ASCII lowercase + digits + dashes, no leading dash, no dots`
                   >,
                 ]
               >;
@@ -9193,7 +9422,30 @@ declare const WorkflowConfigSchema: v.ObjectSchema<
                               id: string;
                             };
                       }[],
-                      "duplicate resource handle name — each binding name must be unique within a deployment"
+                      (
+                        issue: v.CheckIssue<
+                          {
+                            name: string;
+                            resource:
+                              | {
+                                  type: "dataset";
+                                  id: string;
+                                }
+                              | {
+                                  type: "canvas";
+                                  id: string;
+                                }
+                              | {
+                                  type: "media-library";
+                                  id: string;
+                                }
+                              | {
+                                  type: "dashboard";
+                                  id: string;
+                                };
+                          }[]
+                        >,
+                      ) => string
                     >,
                   ]
                 >,
@@ -9363,7 +9615,187 @@ declare const WorkflowConfigSchema: v.ObjectSchema<
               roleAliases?: RoleAliases | undefined;
             }[];
           }[],
-          "duplicate deployment tag — each deployment must use a unique tag"
+          (
+            issue: v.CheckIssue<
+              {
+                name: string;
+                expectedMinReaderModel?: 2 | undefined;
+                tag: string;
+                workflowResource:
+                  | {
+                      type: "dataset";
+                      id: string;
+                    }
+                  | {
+                      type: "canvas";
+                      id: string;
+                    }
+                  | {
+                      type: "media-library";
+                      id: string;
+                    }
+                  | {
+                      type: "dashboard";
+                      id: string;
+                    };
+                resourceAliases?:
+                  | {
+                      name: string;
+                      resource:
+                        | {
+                            type: "dataset";
+                            id: string;
+                          }
+                        | {
+                            type: "canvas";
+                            id: string;
+                          }
+                        | {
+                            type: "media-library";
+                            id: string;
+                          }
+                        | {
+                            type: "dashboard";
+                            id: string;
+                          };
+                    }[]
+                  | undefined;
+                definitions: {
+                  name: string;
+                  title: string;
+                  description?: string | undefined;
+                  groups?: Group[] | undefined;
+                  lifecycle?: WorkflowLifecycle | undefined;
+                  start?: StartBlock | undefined;
+                  initialStage: string;
+                  fields?: FieldEntry[] | undefined;
+                  stages: Stage[];
+                  predicates?: Record<string, string> | undefined;
+                  roleAliases?: RoleAliases | undefined;
+                }[];
+              }[]
+            >,
+          ) => string
+        >,
+        v.CheckAction<
+          {
+            name: string;
+            expectedMinReaderModel?: 2 | undefined;
+            tag: string;
+            workflowResource:
+              | {
+                  type: "dataset";
+                  id: string;
+                }
+              | {
+                  type: "canvas";
+                  id: string;
+                }
+              | {
+                  type: "media-library";
+                  id: string;
+                }
+              | {
+                  type: "dashboard";
+                  id: string;
+                };
+            resourceAliases?:
+              | {
+                  name: string;
+                  resource:
+                    | {
+                        type: "dataset";
+                        id: string;
+                      }
+                    | {
+                        type: "canvas";
+                        id: string;
+                      }
+                    | {
+                        type: "media-library";
+                        id: string;
+                      }
+                    | {
+                        type: "dashboard";
+                        id: string;
+                      };
+                }[]
+              | undefined;
+            definitions: {
+              name: string;
+              title: string;
+              description?: string | undefined;
+              groups?: Group[] | undefined;
+              lifecycle?: WorkflowLifecycle | undefined;
+              start?: StartBlock | undefined;
+              initialStage: string;
+              fields?: FieldEntry[] | undefined;
+              stages: Stage[];
+              predicates?: Record<string, string> | undefined;
+              roleAliases?: RoleAliases | undefined;
+            }[];
+          }[],
+          (
+            issue: v.CheckIssue<
+              {
+                name: string;
+                expectedMinReaderModel?: 2 | undefined;
+                tag: string;
+                workflowResource:
+                  | {
+                      type: "dataset";
+                      id: string;
+                    }
+                  | {
+                      type: "canvas";
+                      id: string;
+                    }
+                  | {
+                      type: "media-library";
+                      id: string;
+                    }
+                  | {
+                      type: "dashboard";
+                      id: string;
+                    };
+                resourceAliases?:
+                  | {
+                      name: string;
+                      resource:
+                        | {
+                            type: "dataset";
+                            id: string;
+                          }
+                        | {
+                            type: "canvas";
+                            id: string;
+                          }
+                        | {
+                            type: "media-library";
+                            id: string;
+                          }
+                        | {
+                            type: "dashboard";
+                            id: string;
+                          };
+                    }[]
+                  | undefined;
+                definitions: {
+                  name: string;
+                  title: string;
+                  description?: string | undefined;
+                  groups?: Group[] | undefined;
+                  lifecycle?: WorkflowLifecycle | undefined;
+                  start?: StartBlock | undefined;
+                  initialStage: string;
+                  fields?: FieldEntry[] | undefined;
+                  stages: Stage[];
+                  predicates?: Record<string, string> | undefined;
+                  roleAliases?: RoleAliases | undefined;
+                }[];
+              }[]
+            >,
+          ) => string
         >,
       ]
     >;
@@ -9506,6 +9938,17 @@ export declare interface WorkflowEffectsDrainedData extends InstanceScopedEventD
   drainedEffects: EffectName[];
 }
 
+export declare const WorkflowEffectStateReported: WorkflowTelemetryEvent<WorkflowEffectStateReportedData>;
+
+export declare interface WorkflowEffectStateReportedData extends InstanceScopedEventData {
+  /** The reporting effect's author-chosen name — one of the payload policy's
+   *  two deliberate customer-string exceptions (module doc). */
+  effect: EffectName;
+  /** Auto-transitions fired during the post-report cascade — a report that
+   *  satisfies a transition moves the instance. */
+  cascaded: number;
+}
+
 /**
  * Base class of the engine's structured errors. `kind` is the stable
  * discriminant — render on it; `name` mirrors the concrete class for logs.
@@ -9538,6 +9981,9 @@ export declare type WorkflowErrorKind =
   | "concurrent-fire-action"
   | "concurrent-edit-field"
   | "concurrent-complete-effect"
+  | "concurrent-commit-effect-ops"
+  | "stale-effect-claim"
+  | "effect-commit-queue-overflow"
   | "cascade-limit"
   | "field-value-shape"
   | "ref-resource-undeclared"