@sanity/workflow-engine 0.7.0 → 0.8.0

package/dist/index.d.cts

@@ -1943,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
@@ -2492,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
@@ -2561,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
@@ -3705,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
@@ -4069,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 [
@@ -4115,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
@@ -5443,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
@@ -6055,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
@@ -6426,6 +6519,7 @@ declare const AuthoringWorkflowSchema: v.StrictObjectSchema<
                             name: string;
                             title?: string | undefined;
                             description?: string | undefined;
+                            required?: boolean | undefined;
                             source: SourceInternal;
                           }
                         | {
@@ -6567,6 +6661,7 @@ declare const AuthoringWorkflowSchema: v.StrictObjectSchema<
                       name: string;
                       title?: string | undefined;
                       description?: string | undefined;
+                      required?: boolean | undefined;
                       source: SourceInternal;
                     }
                   | {
@@ -8261,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.
@@ -8546,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";
@@ -8670,6 +8791,28 @@ export declare type RemediationVerb =
   | "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
@@ -9028,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
@@ -10273,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
@@ -10716,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
@@ -11470,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
@@ -12444,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`.
@@ -12604,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 [
@@ -12648,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
@@ -13532,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
@@ -14008,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
@@ -14246,6 +14481,7 @@ declare const WorkflowDefinitionSchema: v.StrictObjectSchema<
                         name: string;
                         title?: string | undefined;
                         description?: string | undefined;
+                        required?: boolean | undefined;
                         source: SourceInternal;
                       }[]
                     | undefined;
@@ -14365,6 +14601,7 @@ declare const WorkflowDefinitionSchema: v.StrictObjectSchema<
                   name: string;
                   title?: string | undefined;
                   description?: string | undefined;
+                  required?: boolean | undefined;
                   source: SourceInternal;
                 }[]
               | undefined;
@@ -14561,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;