@sanity/workflow-engine 0.6.0 → 0.8.0

package/dist/index.d.cts

@@ -136,13 +136,6 @@ export declare type Assignee =
       role: string;
     };
 
-/** The assignees recorded for a task in a stage — the runtime half of the
- *  "who is this waiting on" answer. Empty when the task is unassigned. */
-export declare function assigneesOf(
-  stage: StageEntry | undefined,
-  taskName: string,
-): Assignee[];
-
 /**
  * Persisted document and effect-queue `_type` discriminators.
  */
@@ -771,6 +764,33 @@ declare const AuthoringStageSchema: v.StrictObjectSchema<
               >,
               undefined
             >;
+            /**
+             * Readiness gates, by name — conditions over the rendered scope that must
+             * hold for the task to be *executable*, orthogonal to `filter`
+             * (visibility). An unmet requirement keeps the task visible but disables
+             * its actions with a `requirements-unmet` verdict naming the unmet keys;
+             * all must hold (any-of lives inside one condition). Advisory like every
+             * engine gate — the lake still enforces. Distinct from ACL (authorization)
+             * and guards (content-write locks).
+             */
+            requirements: v.OptionalSchema<
+              v.RecordSchema<
+                v.SchemaWithPipe<
+                  readonly [
+                    v.StringSchema<undefined>,
+                    v.MinLengthAction<string, 1, "must be a non-empty string">,
+                  ]
+                >,
+                v.SchemaWithPipe<
+                  readonly [
+                    v.StringSchema<undefined>,
+                    v.MinLengthAction<string, 1, "must be a non-empty string">,
+                  ]
+                >,
+                undefined
+              >,
+              undefined
+            >;
             /**
              * Auto-completion condition — evaluated at activation and on every
              * cascade; truthy flips the task to `done` with a system actor. On a
@@ -1923,6 +1943,17 @@ declare const AuthoringStageSchema: v.StrictObjectSchema<
                           v.StringSchema<undefined>,
                           undefined
                         >;
+                        /**
+                         * When true, the caller MUST supply this entry at start (via
+                         * `initialState`) or spawn (via the parent's `subworkflows.with`). A
+                         * missing required entry throws rather than silently defaulting to
+                         * `null`/`[]` — the same fail-fast an action's `required` param gets.
+                         * Valid only on a workflow-scope `init`-sourced entry (deploy invariant).
+                         */
+                        readonly required: v.OptionalSchema<
+                          v.BooleanSchema<undefined>,
+                          undefined
+                        >;
                         readonly source: v.GenericSchema<SourceInternal>;
                       },
                       undefined
@@ -2472,6 +2503,17 @@ declare const AuthoringStageSchema: v.StrictObjectSchema<
                   v.StringSchema<undefined>,
                   undefined
                 >;
+                /**
+                 * When true, the caller MUST supply this entry at start (via
+                 * `initialState`) or spawn (via the parent's `subworkflows.with`). A
+                 * missing required entry throws rather than silently defaulting to
+                 * `null`/`[]` — the same fail-fast an action's `required` param gets.
+                 * Valid only on a workflow-scope `init`-sourced entry (deploy invariant).
+                 */
+                readonly required: v.OptionalSchema<
+                  v.BooleanSchema<undefined>,
+                  undefined
+                >;
                 readonly source: v.GenericSchema<SourceInternal>;
               },
               undefined
@@ -2541,6 +2583,17 @@ declare const AuthoringStateEntrySchema: v.UnionSchema<
           v.StringSchema<undefined>,
           undefined
         >;
+        /**
+         * When true, the caller MUST supply this entry at start (via
+         * `initialState`) or spawn (via the parent's `subworkflows.with`). A
+         * missing required entry throws rather than silently defaulting to
+         * `null`/`[]` — the same fail-fast an action's `required` param gets.
+         * Valid only on a workflow-scope `init`-sourced entry (deploy invariant).
+         */
+        readonly required: v.OptionalSchema<
+          v.BooleanSchema<undefined>,
+          undefined
+        >;
         readonly source: v.GenericSchema<SourceInternal>;
       },
       undefined
@@ -2591,6 +2644,33 @@ declare const AuthoringTaskSchema: v.StrictObjectSchema<
       >,
       undefined
     >;
+    /**
+     * Readiness gates, by name — conditions over the rendered scope that must
+     * hold for the task to be *executable*, orthogonal to `filter`
+     * (visibility). An unmet requirement keeps the task visible but disables
+     * its actions with a `requirements-unmet` verdict naming the unmet keys;
+     * all must hold (any-of lives inside one condition). Advisory like every
+     * engine gate — the lake still enforces. Distinct from ACL (authorization)
+     * and guards (content-write locks).
+     */
+    requirements: v.OptionalSchema<
+      v.RecordSchema<
+        v.SchemaWithPipe<
+          readonly [
+            v.StringSchema<undefined>,
+            v.MinLengthAction<string, 1, "must be a non-empty string">,
+          ]
+        >,
+        v.SchemaWithPipe<
+          readonly [
+            v.StringSchema<undefined>,
+            v.MinLengthAction<string, 1, "must be a non-empty string">,
+          ]
+        >,
+        undefined
+      >,
+      undefined
+    >;
     /**
      * Auto-completion condition — evaluated at activation and on every
      * cascade; truthy flips the task to `done` with a system actor. On a
@@ -3658,6 +3738,17 @@ declare const AuthoringTaskSchema: v.StrictObjectSchema<
                   v.StringSchema<undefined>,
                   undefined
                 >;
+                /**
+                 * When true, the caller MUST supply this entry at start (via
+                 * `initialState`) or spawn (via the parent's `subworkflows.with`). A
+                 * missing required entry throws rather than silently defaulting to
+                 * `null`/`[]` — the same fail-fast an action's `required` param gets.
+                 * Valid only on a workflow-scope `init`-sourced entry (deploy invariant).
+                 */
+                readonly required: v.OptionalSchema<
+                  v.BooleanSchema<undefined>,
+                  undefined
+                >;
                 readonly source: v.GenericSchema<SourceInternal>;
               },
               undefined
@@ -4022,6 +4113,22 @@ declare const AuthoringWorkflowSchema: v.StrictObjectSchema<
       ]
     >;
     description: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    /**
+     * Whether a human may start this workflow standalone. `'child'` marks a
+     * spawn-only definition — instantiated by a parent via `task.subworkflows`,
+     * never started cold from a picker. Omitted ⇒ `'workflow'` (startable).
+     * Advisory: consumers filter their start pickers on it (see
+     * {@link isStartableDefinition}); the engine does NOT refuse a
+     * `startInstance` on a `'child'` def — load-bearing `required` state is the
+     * runtime backstop.
+     */
+    role: v.OptionalSchema<
+      v.PicklistSchema<
+        readonly ["workflow", "child"],
+        `Invalid option: expected one of ${string}`
+      >,
+      undefined
+    >;
     /** Reference field: named for the target, holds the stage's `name`. */
     initialStage: v.SchemaWithPipe<
       readonly [
@@ -4068,6 +4175,17 @@ declare const AuthoringWorkflowSchema: v.StrictObjectSchema<
                   v.StringSchema<undefined>,
                   undefined
                 >;
+                /**
+                 * When true, the caller MUST supply this entry at start (via
+                 * `initialState`) or spawn (via the parent's `subworkflows.with`). A
+                 * missing required entry throws rather than silently defaulting to
+                 * `null`/`[]` — the same fail-fast an action's `required` param gets.
+                 * Valid only on a workflow-scope `init`-sourced entry (deploy invariant).
+                 */
+                readonly required: v.OptionalSchema<
+                  v.BooleanSchema<undefined>,
+                  undefined
+                >;
                 readonly source: v.GenericSchema<SourceInternal>;
               },
               undefined
@@ -4157,6 +4275,41 @@ declare const AuthoringWorkflowSchema: v.StrictObjectSchema<
                         >,
                         undefined
                       >;
+                      /**
+                       * Readiness gates, by name — conditions over the rendered scope that must
+                       * hold for the task to be *executable*, orthogonal to `filter`
+                       * (visibility). An unmet requirement keeps the task visible but disables
+                       * its actions with a `requirements-unmet` verdict naming the unmet keys;
+                       * all must hold (any-of lives inside one condition). Advisory like every
+                       * engine gate — the lake still enforces. Distinct from ACL (authorization)
+                       * and guards (content-write locks).
+                       */
+                      requirements: v.OptionalSchema<
+                        v.RecordSchema<
+                          v.SchemaWithPipe<
+                            readonly [
+                              v.StringSchema<undefined>,
+                              v.MinLengthAction<
+                                string,
+                                1,
+                                "must be a non-empty string"
+                              >,
+                            ]
+                          >,
+                          v.SchemaWithPipe<
+                            readonly [
+                              v.StringSchema<undefined>,
+                              v.MinLengthAction<
+                                string,
+                                1,
+                                "must be a non-empty string"
+                              >,
+                            ]
+                          >,
+                          undefined
+                        >,
+                        undefined
+                      >;
                       /**
                        * Auto-completion condition — evaluated at activation and on every
                        * cascade; truthy flips the task to `done` with a system actor. On a
@@ -5361,6 +5514,17 @@ declare const AuthoringWorkflowSchema: v.StrictObjectSchema<
                                     v.StringSchema<undefined>,
                                     undefined
                                   >;
+                                  /**
+                                   * When true, the caller MUST supply this entry at start (via
+                                   * `initialState`) or spawn (via the parent's `subworkflows.with`). A
+                                   * missing required entry throws rather than silently defaulting to
+                                   * `null`/`[]` — the same fail-fast an action's `required` param gets.
+                                   * Valid only on a workflow-scope `init`-sourced entry (deploy invariant).
+                                   */
+                                  readonly required: v.OptionalSchema<
+                                    v.BooleanSchema<undefined>,
+                                    undefined
+                                  >;
                                   readonly source: v.GenericSchema<SourceInternal>;
                                 },
                                 undefined
@@ -5973,6 +6137,17 @@ declare const AuthoringWorkflowSchema: v.StrictObjectSchema<
                             v.StringSchema<undefined>,
                             undefined
                           >;
+                          /**
+                           * When true, the caller MUST supply this entry at start (via
+                           * `initialState`) or spawn (via the parent's `subworkflows.with`). A
+                           * missing required entry throws rather than silently defaulting to
+                           * `null`/`[]` — the same fail-fast an action's `required` param gets.
+                           * Valid only on a workflow-scope `init`-sourced entry (deploy invariant).
+                           */
+                          readonly required: v.OptionalSchema<
+                            v.BooleanSchema<undefined>,
+                            undefined
+                          >;
                           readonly source: v.GenericSchema<SourceInternal>;
                         },
                         undefined
@@ -6021,6 +6196,11 @@ declare const AuthoringWorkflowSchema: v.StrictObjectSchema<
                   description?: string | undefined;
                   activation?: "auto" | "manual" | undefined;
                   filter?: string | undefined;
+                  requirements?:
+                    | {
+                        [x: string]: string;
+                      }
+                    | undefined;
                   completeWhen?: string | undefined;
                   failWhen?: string | undefined;
                   ops?:
@@ -6339,6 +6519,7 @@ declare const AuthoringWorkflowSchema: v.StrictObjectSchema<
                             name: string;
                             title?: string | undefined;
                             description?: string | undefined;
+                            required?: boolean | undefined;
                             source: SourceInternal;
                           }
                         | {
@@ -6480,6 +6661,7 @@ declare const AuthoringWorkflowSchema: v.StrictObjectSchema<
                       name: string;
                       title?: string | undefined;
                       description?: string | undefined;
+                      required?: boolean | undefined;
                       source: SourceInternal;
                     }
                   | {
@@ -6769,6 +6951,16 @@ export declare function datasetResourceParts(id: string): {
   dataset: string;
 };
 
+/**
+ * The perspective a content read falls back to when the instance has no
+ * explicit release perspective: `drafts` overlay published (Sanity
+ * draft-precedence), so an unpublished or in-flight subject is what the engine
+ * — and the reactive adapters — evaluate, never a published-only read that
+ * silently misses the draft. The single home for the draft-precedence default;
+ * every content read uses `instance.perspective ?? DEFAULT_CONTENT_PERSPECTIVE`.
+ */
+export declare const DEFAULT_CONTENT_PERSPECTIVE = "drafts";
+
 /**
  * Default LoggerFactory — writes through the global `console`. Exposed
  * so callers outside `createEngine` (drive scripts, the
@@ -6892,7 +7084,6 @@ export declare interface DiagnoseInput {
   instance: Pick<
     WorkflowInstance,
     | "currentStage"
-    | "stages"
     | "completedAt"
     | "abortedAt"
     | "effectHistory"
@@ -6901,6 +7092,7 @@ export declare interface DiagnoseInput {
   >;
   tasks: TaskEvaluation[];
   transitions: TransitionEvaluation[];
+  assignees: Record<string, Assignee[]>;
 }
 
 /** Narrow a full {@link WorkflowEvaluation} to the {@link DiagnoseInput} the
@@ -6912,17 +7104,20 @@ export declare function diagnoseInputFromEvaluation(
 /**
  * Classify an instance. Terminal states win first; then the genuine stuck
  * causes (nothing advances on its own or via a normal action); then `waiting`
- * (an action is available — healthy); else `progressing` (a transition is
- * already satisfied and will cascade).
+ * (an action is available — healthy); then `blocked` (an active task held by
+ * an unmet requirement — healthy, not yet actionable); else `progressing` (a
+ * transition is already satisfied and will cascade).
  */
 export declare function diagnoseInstance(input: DiagnoseInput): Diagnosis;
 
-/** The `workflow.diagnose` result — the verdict plus the evaluation it was
+/** The `workflow.diagnose` result — the verdict, the structured remediations
+ *  that would unstick it (empty unless `stuck`), and the evaluation it was
  *  derived from, so a consumer can render the supporting evidence (current
  *  stage tasks + transitions) without a second projection. */
 export declare interface DiagnoseResult {
   evaluation: WorkflowEvaluation;
   diagnosis: Diagnosis;
+  remediations: SuggestedRemediation[];
 }
 
 export declare type Diagnosis =
@@ -6935,6 +7130,12 @@ export declare type Diagnosis =
       assignees: Assignee[];
       actions: string[];
     }
+  | {
+      state: "blocked";
+      task: string;
+      requirements: string[];
+      assignees: Assignee[];
+    }
   | {
       state: "completed";
       at: string;
@@ -7004,6 +7205,18 @@ export declare type DisabledReason =
   | {
       kind: "instance-completed";
       completedAt: string;
+    }
+  | {
+      /**
+       * The task's declared {@link Task.requirements} aren't all satisfied —
+       * the readiness axis. The task is visible and the actor authorized, but
+       * its own preconditions don't hold yet. `unmetRequirements` names the
+       * failing keys so a consumer can disable the affirmative control and say
+       * which precondition is outstanding. Distinct from `filter-failed`
+       * (visibility/authorization) and `mutation-guard-denied` (content-write).
+       */
+      kind: "requirements-unmet";
+      unmetRequirements: string[];
     };
 
 export declare interface DispatchResult {
@@ -8143,6 +8356,18 @@ export declare function isDefinitionUnchanged(
 /** Type filter for GDR shape. */
 export declare function isGdr(value: unknown): value is GlobalDocumentReference;
 
+/**
+ * Whether a human may start this definition standalone (the default). A
+ * `role: 'child'` definition is spawn-only — instantiated by a parent via
+ * `task.subworkflows`, so consumers exclude it from top-level start pickers.
+ * Advisory: the engine does not enforce it (see the `required`-state backstop
+ * for load-bearing init slots). Accepts any definition-shaped value (authored,
+ * stored, deployed, or a projected list row).
+ */
+export declare function isStartableDefinition(definition: {
+  role?: WorkflowRole | undefined;
+}): boolean;
+
 /**
  * A stage with no transitions out IS terminal — structural, not declared.
  * Reaching one completes the instance.
@@ -8372,12 +8597,6 @@ export declare interface OpAppliedSummary {
   resolved?: Record<string, unknown>;
 }
 
-/** The instance's current, not-yet-exited {@link StageEntry}, if it has one —
- *  the engine's canonical {@link findOpenStageEntry}, over the diagnosis input. */
-export declare function openStage(
-  instance: Pick<WorkflowInstance, "currentStage" | "stages">,
-): StageEntry | undefined;
-
 export declare interface OperationArgs {
   client: WorkflowClient;
   /** Engine-scope environment partition — required. */
@@ -8434,6 +8653,20 @@ export declare interface ParsedGdr {
  */
 export declare function parseGdr(uri: string): ParsedGdr;
 
+/**
+ * A stage's multi-guard deploy failed *after* at least one guard already landed.
+ * Those partial locks can't be cleanly undone (guard docs have no transactional
+ * deploy). Inside the engine {@link deployOrRollback} rolls the state move back
+ * and escalates this to a loud {@link WorkflowStateDivergedError}; a caller that
+ * invokes {@link deployStageGuards} directly (without that rollback wrapper) can
+ * also see it, so it's exported to be catchable by type.
+ */
+export declare class PartialGuardDeployError extends Error {
+  readonly stageName: string;
+  readonly deployed: number;
+  constructor(args: { stageName: string; deployed: number; cause: unknown });
+}
+
 export declare interface PendingEffect {
   _key: string;
   _type?: "pendingEffect";
@@ -8534,6 +8767,52 @@ export declare interface ReleaseRef extends GlobalDocumentReference {
   releaseName: string;
 }
 
+/**
+ * The remediations that would unstick a diagnosis — the *what to do about it*
+ * half. Empty unless the instance is `stuck`: a `waiting` instance advances on
+ * its own next action (see `availableActions`), and terminal or `progressing`
+ * ones need nothing. Each verb is flagged
+ * {@link SuggestedRemediation.available} from {@link RUNNABLE_VERBS}.
+ */
+export declare function remediationsFor(
+  diagnosis: Diagnosis,
+): SuggestedRemediation[];
+
+/**
+ * A verb that would unstick a {@link StuckCause} — the *what to do about it*
+ * half of a diagnosis. Surface-neutral identifiers; a consumer maps each to
+ * its own command or button. `retry-effect`, `drain-effects` and `reset-task`
+ * are not yet callable engine operations — see {@link SuggestedRemediation.available}.
+ */
+export declare type RemediationVerb =
+  | "retry-effect"
+  | "drain-effects"
+  | "reset-task"
+  | "set-stage"
+  | "abort";
+
+/**
+ * Thrown when a workflow is started (or a child spawned) without a value for
+ * a state entry marked `required`. Mirrors {@link ActionParamsInvalidError}:
+ * the engine has NOT created the instance — a missing load-bearing slot
+ * (e.g. the subject of a review) screams here rather than silently defaulting
+ * to `null`/`[]` and birthing a half-formed instance mid-process.
+ */
+export declare class RequiredStateNotProvidedError extends Error {
+  readonly definition?: string;
+  readonly missing: {
+    name: string;
+    type: string;
+  }[];
+  constructor(args: {
+    definition?: string;
+    missing: {
+      name: string;
+      type: string;
+    }[];
+  });
+}
+
 /**
  * Resolve the engine's `WorkflowAccess` for a client. Override wins
  * outright; otherwise both halves are fetched in parallel and
@@ -8892,6 +9171,14 @@ declare const StateEntrySchema: v.StrictObjectSchema<
       v.StringSchema<undefined>,
       undefined
     >;
+    /**
+     * When true, the caller MUST supply this entry at start (via
+     * `initialState`) or spawn (via the parent's `subworkflows.with`). A
+     * missing required entry throws rather than silently defaulting to
+     * `null`/`[]` — the same fail-fast an action's `required` param gets.
+     * Valid only on a workflow-scope `init`-sourced entry (deploy invariant).
+     */
+    readonly required: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
     readonly source: v.GenericSchema<SourceInternal>;
   },
   undefined
@@ -9365,6 +9652,33 @@ declare const StoredStageSchema: v.StrictObjectSchema<
               >,
               undefined
             >;
+            /**
+             * Readiness gates, by name — conditions over the rendered scope that must
+             * hold for the task to be *executable*, orthogonal to `filter`
+             * (visibility). An unmet requirement keeps the task visible but disables
+             * its actions with a `requirements-unmet` verdict naming the unmet keys;
+             * all must hold (any-of lives inside one condition). Advisory like every
+             * engine gate — the lake still enforces. Distinct from ACL (authorization)
+             * and guards (content-write locks).
+             */
+            requirements: v.OptionalSchema<
+              v.RecordSchema<
+                v.SchemaWithPipe<
+                  readonly [
+                    v.StringSchema<undefined>,
+                    v.MinLengthAction<string, 1, "must be a non-empty string">,
+                  ]
+                >,
+                v.SchemaWithPipe<
+                  readonly [
+                    v.StringSchema<undefined>,
+                    v.MinLengthAction<string, 1, "must be a non-empty string">,
+                  ]
+                >,
+                undefined
+              >,
+              undefined
+            >;
             /**
              * Auto-completion condition — evaluated at activation and on every
              * cascade; truthy flips the task to `done` with a system actor. On a
@@ -10110,6 +10424,17 @@ declare const StoredStageSchema: v.StrictObjectSchema<
                       v.StringSchema<undefined>,
                       undefined
                     >;
+                    /**
+                     * When true, the caller MUST supply this entry at start (via
+                     * `initialState`) or spawn (via the parent's `subworkflows.with`). A
+                     * missing required entry throws rather than silently defaulting to
+                     * `null`/`[]` — the same fail-fast an action's `required` param gets.
+                     * Valid only on a workflow-scope `init`-sourced entry (deploy invariant).
+                     */
+                    readonly required: v.OptionalSchema<
+                      v.BooleanSchema<undefined>,
+                      undefined
+                    >;
                     readonly source: v.GenericSchema<SourceInternal>;
                   },
                   undefined
@@ -10553,6 +10878,17 @@ declare const StoredStageSchema: v.StrictObjectSchema<
               v.StringSchema<undefined>,
               undefined
             >;
+            /**
+             * When true, the caller MUST supply this entry at start (via
+             * `initialState`) or spawn (via the parent's `subworkflows.with`). A
+             * missing required entry throws rather than silently defaulting to
+             * `null`/`[]` — the same fail-fast an action's `required` param gets.
+             * Valid only on a workflow-scope `init`-sourced entry (deploy invariant).
+             */
+            readonly required: v.OptionalSchema<
+              v.BooleanSchema<undefined>,
+              undefined
+            >;
             readonly source: v.GenericSchema<SourceInternal>;
           },
           undefined
@@ -10609,6 +10945,33 @@ declare const StoredTaskSchema: v.StrictObjectSchema<
       >,
       undefined
     >;
+    /**
+     * Readiness gates, by name — conditions over the rendered scope that must
+     * hold for the task to be *executable*, orthogonal to `filter`
+     * (visibility). An unmet requirement keeps the task visible but disables
+     * its actions with a `requirements-unmet` verdict naming the unmet keys;
+     * all must hold (any-of lives inside one condition). Advisory like every
+     * engine gate — the lake still enforces. Distinct from ACL (authorization)
+     * and guards (content-write locks).
+     */
+    requirements: v.OptionalSchema<
+      v.RecordSchema<
+        v.SchemaWithPipe<
+          readonly [
+            v.StringSchema<undefined>,
+            v.MinLengthAction<string, 1, "must be a non-empty string">,
+          ]
+        >,
+        v.SchemaWithPipe<
+          readonly [
+            v.StringSchema<undefined>,
+            v.MinLengthAction<string, 1, "must be a non-empty string">,
+          ]
+        >,
+        undefined
+      >,
+      undefined
+    >;
     /**
      * Auto-completion condition — evaluated at activation and on every
      * cascade; truthy flips the task to `done` with a system actor. On a
@@ -11280,6 +11643,17 @@ declare const StoredTaskSchema: v.StrictObjectSchema<
               v.StringSchema<undefined>,
               undefined
             >;
+            /**
+             * When true, the caller MUST supply this entry at start (via
+             * `initialState`) or spawn (via the parent's `subworkflows.with`). A
+             * missing required entry throws rather than silently defaulting to
+             * `null`/`[]` — the same fail-fast an action's `required` param gets.
+             * Valid only on a workflow-scope `init`-sourced entry (deploy invariant).
+             */
+            readonly required: v.OptionalSchema<
+              v.BooleanSchema<undefined>,
+              undefined
+            >;
             readonly source: v.GenericSchema<SourceInternal>;
           },
           undefined
@@ -11658,6 +12032,17 @@ export declare type StuckCause =
     }
   | {
       kind: "no-transition-fires";
+    }
+  /**
+   * Every task resolved, but an exit transition's filter is *unevaluable*
+   * (GROQ `null` — a referenced operand is missing/unreadable), so selection
+   * halts. Unlike {@link StuckCause} `no-transition-fires` this is recoverable:
+   * the cascade re-fires once the operand resolves (e.g. the subject is
+   * published or the field is filled). Carries the undecidable transitions.
+   */
+  | {
+      kind: "transition-unevaluable";
+      transitions: string[];
     };
 
 /**
@@ -11773,6 +12158,17 @@ declare const SubworkflowsSchema: v.StrictObjectSchema<
   undefined
 >;
 
+export declare interface SuggestedRemediation {
+  verb: RemediationVerb;
+  /** True iff a consumer can run this as an engine operation today. `false`
+   *  marks a remediation we can name but not yet execute — a planned verb, or
+   *  an operational step (re-running the effect drainer). */
+  available: boolean;
+  /** Surface-neutral one-line rationale — no color or terminal symbols; a
+   *  consumer decorates it for its own surface. */
+  rationale: string;
+}
+
 /**
  * The engine's read-partition invariant as a GROQ predicate: a document is
  * visible when its `tag` equals the caller's `$tag` param. The single
@@ -11811,6 +12207,13 @@ export declare interface TaskEntry {
   filterEvaluation?: {
     at: string;
     truthy: boolean;
+    /**
+     * The filter evaluated to GROQ `null` — a referenced operand was missing
+     * or incomparable, so it couldn't be decided. The engine fails closed
+     * (keeps the task in scope) rather than reading this as a deliberate
+     * `false`; `truthy` is `false` here but the task is NOT skipped.
+     */
+    unevaluable?: boolean;
     detail?: string;
   };
   /**
@@ -11829,6 +12232,13 @@ export declare interface TaskEvaluation {
   status: TaskStatus;
   /** Whether this task is the current actor's responsibility right now. */
   pendingOnActor: boolean;
+  /**
+   * The task's unmet {@link Task.requirements}, by name — present iff at least
+   * one is unmet. The task's own readiness summary: a consumer can explain why
+   * the whole task is gated without inspecting each action (every action also
+   * carries the matching `requirements-unmet` `disabledReason`).
+   */
+  unmetRequirements?: string[];
   actions: ActionEvaluation[];
 }
 
@@ -11845,8 +12255,17 @@ export declare type Transition = v.InferOutput<typeof StoredTransitionSchema>;
 
 export declare interface TransitionEvaluation {
   transition: Transition;
-  /** Result of evaluating the transition's filter at read time. */
+  /** Whether the transition's filter is definitively satisfied at read time. */
   filterSatisfied: boolean;
+  /**
+   * The filter evaluated to GROQ `null` — a referenced operand was missing or
+   * incomparable, so it couldn't be decided. `filterSatisfied` is `false`, but
+   * this is a *recoverable hold*, not a deliberate `false`: the engine halts
+   * selection (it won't fall through to a later transition) and the cascade
+   * re-fires once the operand resolves. Lets a diagnosis tell an undecidable
+   * hold apart from a genuine routing dead-end.
+   */
+  unevaluable: boolean;
 }
 
 export declare type TransitionOp = v.InferOutput<
@@ -12209,6 +12628,8 @@ export declare const WORKFLOW_DEFINITION_TYPE = "sanity.workflow.definition";
  */
 export declare const WORKFLOW_INSTANCE_TYPE = "sanity.workflow.instance";
 
+declare const WORKFLOW_ROLES: readonly ["workflow", "child"];
+
 /**
  * The engine's view of "who am I, what can I do?". `actor` is who
  * the engine stamps onto history / `completedBy` / `Source.actor`.
@@ -12269,6 +12690,7 @@ export declare interface WorkflowClient {
     },
   >(
     doc: T,
+    options?: WorkflowCommitOptions,
   ) => Promise<T>;
   /**
    * Build a multi-document transaction. All operations succeed or fail
@@ -12321,6 +12743,21 @@ export declare interface WorkflowClient {
   }) => Promise<T>;
 }
 
+export declare interface WorkflowCommitOptions {
+  /**
+   * When the mutation becomes visible to subsequent queries. The engine
+   * reads its own writes back through GROQ (`fetch`) — a freshly-spawned
+   * child listed by id, a just-deployed definition — so single-document
+   * writes (`create`, `patch().commit()`) commit `'sync'`: the change is
+   * query-visible before the call resolves and the next read can't miss it.
+   * `@sanity/client` already defaults to `'sync'`, but the engine states it
+   * rather than depend on a transport default a consumer's client config
+   * could change underneath it. (Transactions ride that same default — see
+   * {@link WorkflowTransaction.commit}.)
+   */
+  visibility?: WorkflowVisibility;
+}
+
 export declare type WorkflowDefinition = v.InferOutput<
   typeof WorkflowDefinitionSchema
 >;
@@ -12353,6 +12790,22 @@ declare const WorkflowDefinitionSchema: v.StrictObjectSchema<
       ]
     >;
     description: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    /**
+     * Whether a human may start this workflow standalone. `'child'` marks a
+     * spawn-only definition — instantiated by a parent via `task.subworkflows`,
+     * never started cold from a picker. Omitted ⇒ `'workflow'` (startable).
+     * Advisory: consumers filter their start pickers on it (see
+     * {@link isStartableDefinition}); the engine does NOT refuse a
+     * `startInstance` on a `'child'` def — load-bearing `required` state is the
+     * runtime backstop.
+     */
+    role: v.OptionalSchema<
+      v.PicklistSchema<
+        readonly ["workflow", "child"],
+        `Invalid option: expected one of ${string}`
+      >,
+      undefined
+    >;
     /** Reference field: named for the target, holds the stage's `name`. */
     initialStage: v.SchemaWithPipe<
       readonly [
@@ -12397,6 +12850,17 @@ declare const WorkflowDefinitionSchema: v.StrictObjectSchema<
               v.StringSchema<undefined>,
               undefined
             >;
+            /**
+             * When true, the caller MUST supply this entry at start (via
+             * `initialState`) or spawn (via the parent's `subworkflows.with`). A
+             * missing required entry throws rather than silently defaulting to
+             * `null`/`[]` — the same fail-fast an action's `required` param gets.
+             * Valid only on a workflow-scope `init`-sourced entry (deploy invariant).
+             */
+            readonly required: v.OptionalSchema<
+              v.BooleanSchema<undefined>,
+              undefined
+            >;
             readonly source: v.GenericSchema<SourceInternal>;
           },
           undefined
@@ -12463,6 +12927,41 @@ declare const WorkflowDefinitionSchema: v.StrictObjectSchema<
                         >,
                         undefined
                       >;
+                      /**
+                       * Readiness gates, by name — conditions over the rendered scope that must
+                       * hold for the task to be *executable*, orthogonal to `filter`
+                       * (visibility). An unmet requirement keeps the task visible but disables
+                       * its actions with a `requirements-unmet` verdict naming the unmet keys;
+                       * all must hold (any-of lives inside one condition). Advisory like every
+                       * engine gate — the lake still enforces. Distinct from ACL (authorization)
+                       * and guards (content-write locks).
+                       */
+                      requirements: v.OptionalSchema<
+                        v.RecordSchema<
+                          v.SchemaWithPipe<
+                            readonly [
+                              v.StringSchema<undefined>,
+                              v.MinLengthAction<
+                                string,
+                                1,
+                                "must be a non-empty string"
+                              >,
+                            ]
+                          >,
+                          v.SchemaWithPipe<
+                            readonly [
+                              v.StringSchema<undefined>,
+                              v.MinLengthAction<
+                                string,
+                                1,
+                                "must be a non-empty string"
+                              >,
+                            ]
+                          >,
+                          undefined
+                        >,
+                        undefined
+                      >;
                       /**
                        * Auto-completion condition — evaluated at activation and on every
                        * cascade; truthy flips the task to `done` with a system actor. On a
@@ -13246,6 +13745,17 @@ declare const WorkflowDefinitionSchema: v.StrictObjectSchema<
                                 v.StringSchema<undefined>,
                                 undefined
                               >;
+                              /**
+                               * When true, the caller MUST supply this entry at start (via
+                               * `initialState`) or spawn (via the parent's `subworkflows.with`). A
+                               * missing required entry throws rather than silently defaulting to
+                               * `null`/`[]` — the same fail-fast an action's `required` param gets.
+                               * Valid only on a workflow-scope `init`-sourced entry (deploy invariant).
+                               */
+                              readonly required: v.OptionalSchema<
+                                v.BooleanSchema<undefined>,
+                                undefined
+                              >;
                               readonly source: v.GenericSchema<SourceInternal>;
                             },
                             undefined
@@ -13722,6 +14232,17 @@ declare const WorkflowDefinitionSchema: v.StrictObjectSchema<
                         v.StringSchema<undefined>,
                         undefined
                       >;
+                      /**
+                       * When true, the caller MUST supply this entry at start (via
+                       * `initialState`) or spawn (via the parent's `subworkflows.with`). A
+                       * missing required entry throws rather than silently defaulting to
+                       * `null`/`[]` — the same fail-fast an action's `required` param gets.
+                       * Valid only on a workflow-scope `init`-sourced entry (deploy invariant).
+                       */
+                      readonly required: v.OptionalSchema<
+                        v.BooleanSchema<undefined>,
+                        undefined
+                      >;
                       readonly source: v.GenericSchema<SourceInternal>;
                     },
                     undefined
@@ -13747,6 +14268,11 @@ declare const WorkflowDefinitionSchema: v.StrictObjectSchema<
                   description?: string | undefined;
                   activation?: "auto" | "manual" | undefined;
                   filter?: string | undefined;
+                  requirements?:
+                    | {
+                        [x: string]: string;
+                      }
+                    | undefined;
                   completeWhen?: string | undefined;
                   failWhen?: string | undefined;
                   ops?:
@@ -13955,6 +14481,7 @@ declare const WorkflowDefinitionSchema: v.StrictObjectSchema<
                         name: string;
                         title?: string | undefined;
                         description?: string | undefined;
+                        required?: boolean | undefined;
                         source: SourceInternal;
                       }[]
                     | undefined;
@@ -14074,6 +14601,7 @@ declare const WorkflowDefinitionSchema: v.StrictObjectSchema<
                   name: string;
                   title?: string | undefined;
                   description?: string | undefined;
+                  required?: boolean | undefined;
                   source: SourceInternal;
                 }[]
               | undefined;
@@ -14225,7 +14753,7 @@ export declare interface WorkflowPatch {
   setIfMissing: (props: Record<string, unknown>) => WorkflowPatch;
   unset: (paths: string[]) => WorkflowPatch;
   ifRevisionId: (rev: string) => WorkflowPatch;
-  commit: () => Promise<SanityDocument>;
+  commit: (options?: WorkflowCommitOptions) => Promise<SanityDocument>;
 }
 
 /**
@@ -14270,13 +14798,18 @@ export declare type WorkflowResource =
       id: string;
     };
 
+/** A definition's lifecycle role. `'child'` is spawn-only — see {@link isStartableDefinition}. */
+export declare type WorkflowRole = (typeof WORKFLOW_ROLES)[number];
+
 /**
  * Thrown when a guard deploy fails *after* its state move committed and the
- * engine could not restore the instance to its pre-move state — either the
- * rollback write itself failed, or the move created sibling docs (spawn) that a
- * parent-only rollback cannot undo. The workflow's persisted state and its
- * deployed guards are now divergent and need manual reconciliation; the engine
- * screams rather than leaving the inconsistency silent.
+ * engine could not cleanly undo the result — any of: the rollback write itself
+ * failed; the move created sibling docs (spawn) that a parent-only rollback
+ * cannot undo; or a multi-guard deploy partially applied, so even a clean state
+ * rollback leaves the earlier guards orphaned ({@link PartialGuardDeployError}).
+ * The workflow's persisted state and its deployed guards are now divergent and
+ * need manual reconciliation; the engine screams rather than leaving the
+ * inconsistency silent.
  */
 export declare class WorkflowStateDivergedError extends Error {
   readonly instanceId: string;
@@ -14326,7 +14859,20 @@ export declare interface WorkflowTransaction {
    * carry this shape.
    */
   delete: (id: string) => WorkflowTransaction;
+  /**
+   * Commit the batch. No options — a transaction rides the client's *default*
+   * `visibility`: `'sync'` in `@sanity/client` (so a post-spawn `listInstances`
+   * GROQ sees freshly-created children), immediate in the in-memory test fake.
+   * This is a standing engine assumption — a consumer that configured an
+   * `async` default would make spawn read-backs racy. Single-document writes
+   * state `'sync'` explicitly via {@link WorkflowCommitOptions}; transactions
+   * can't (yet) — the test fake's commit options don't carry `visibility`, and
+   * per repo convention that gap is closed upstream in the fake, not worked
+   * around here.
+   */
   commit: () => Promise<unknown>;
 }
 
+export declare type WorkflowVisibility = "sync" | "async" | "deferred";
+
 export {};