@sanity/workflow-engine 0.6.0 → 0.7.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
@@ -2591,6 +2611,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
@@ -4157,6 +4204,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
@@ -6021,6 +6103,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?:
@@ -6769,6 +6856,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 +6989,6 @@ export declare interface DiagnoseInput {
   instance: Pick<
     WorkflowInstance,
     | "currentStage"
-    | "stages"
     | "completedAt"
     | "abortedAt"
     | "effectHistory"
@@ -6901,6 +6997,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 +7009,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 +7035,12 @@ export declare type Diagnosis =
       assignees: Assignee[];
       actions: string[];
     }
+  | {
+      state: "blocked";
+      task: string;
+      requirements: string[];
+      assignees: Assignee[];
+    }
   | {
       state: "completed";
       at: string;
@@ -7004,6 +7110,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 {
@@ -8372,12 +8490,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. */
@@ -8534,6 +8646,30 @@ 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";
+
 /**
  * Resolve the engine's `WorkflowAccess` for a client. Override wins
  * outright; otherwise both halves are fetched in parallel and
@@ -9365,6 +9501,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
@@ -10609,6 +10772,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
@@ -11658,6 +11848,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 +11974,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 +12023,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 +12048,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 +12071,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<
@@ -12269,6 +12504,7 @@ export declare interface WorkflowClient {
     },
   >(
     doc: T,
+    options?: WorkflowCommitOptions,
   ) => Promise<T>;
   /**
    * Build a multi-document transaction. All operations succeed or fail
@@ -12321,6 +12557,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
 >;
@@ -12463,6 +12714,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
@@ -13747,6 +14033,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?:
@@ -14225,7 +14516,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>;
 }
 
 /**
@@ -14326,7 +14617,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 {};