@sanity/workflow-engine 0.5.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?:
@@ -6547,10 +6634,10 @@ export declare interface AvailableActionsResult {
 declare type Bound<
   Args extends {
     client: WorkflowClient;
-    tags: string[];
+    tag: string;
     workflowResource: WorkflowResource;
   },
-> = Omit<Args, "client" | "tags" | "workflowResource">;
+> = Omit<Args, "client" | "tag" | "workflowResource">;
 
 /**
  * Build a snapshot from a set of loaded docs. Pure transform.
@@ -6570,8 +6657,6 @@ export declare function buildSnapshot(args: {
   docs: LoadedDoc[];
 }): HydratedSnapshot;
 
-export declare function canonicalTag(tags: string[]): string;
-
 /**
  * Thrown when auto-transitions on an instance fail to stabilise within
  * {@link CascadeLimitError.limit} passes — the signature of a runaway
@@ -6713,10 +6798,11 @@ export declare function contentReleaseName(args: {
 }): string | undefined;
 
 /**
- * Construct an engine bound to a workflow resource + tags. The returned
+ * Construct an engine bound to a workflow resource + tag. The returned
  * object exposes the same verbs as the `workflow.*` namespace, minus
- * the boilerplate config arguments (client / tags / workflowResource)
- * which are pinned at construction.
+ * the boilerplate config arguments (client / tag / workflowResource)
+ * which are pinned at construction. The `tag` is required — see
+ * {@link validateTag} for the accepted shape.
  *
  * Effect handlers + missingHandler are stored for future drain wiring
  * (Step 10). They have no effect on `fireAction` / `tick` /
@@ -6728,7 +6814,14 @@ export declare function createEngine(args: CreateEngineArgs): Engine;
 export declare interface CreateEngineArgs {
   client: WorkflowClient;
   workflowResource: WorkflowResource;
-  tags: string[];
+  /**
+   * Engine-scope environment partition (e.g. `"test"`, `"prod"`). Every
+   * definition/instance the engine writes is stamped with this tag and
+   * every read is scoped to it. Required and never defaulted — the engine
+   * enforces nothing, so the partition is the only thing keeping reads and
+   * writes off the wrong environment.
+   */
+  tag: string;
   /**
    * Optional routing for cross-resource reads. When the engine needs
    * a doc whose GDR points at a resource other than its own, it calls
@@ -6763,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
@@ -6774,8 +6877,8 @@ export declare const defaultLoggerFactory: LoggerFactory;
 
 export declare interface DeleteDefinitionArgs {
   client: WorkflowClient;
-  /** Engine-scope tags — required. See `validateTags` + `tags.ts`. */
-  tags: string[];
+  /** Engine-scope environment partition — required. See {@link validateTag} + `tags.ts`. */
+  tag: string;
   /** The Sanity resource the engine's own data lives in. */
   workflowResource: WorkflowResource;
   /** Cross-resource routing — see `StartInstanceArgs.resourceClients`. */
@@ -6837,8 +6940,8 @@ export declare interface DeployDefinitionResult {
 
 export declare interface DeployDefinitionsArgs {
   client: WorkflowClient;
-  /** Engine-scope tags — required. See `validateTags` + `tags.ts`. */
-  tags: string[];
+  /** Engine-scope environment partition — required. See {@link validateTag} + `tags.ts`. */
+  tag: string;
   /**
    * The Sanity resource the engine's own data lives in. Used to mint
    * GDR URIs for every doc the engine writes (definitions, instances,
@@ -6868,11 +6971,11 @@ export declare interface DeployDefinitionsResult {
  */
 export declare function deployStageGuards(args: StageGuardArgs): Promise<void>;
 
-/** Where a definition deploys: the engine tags it partitions under, and the
+/** Where a definition deploys: the engine tag it partitions under, and the
  *  workflow resource it belongs to. Structurally what `deployDefinitions`
  *  receives, minus the definitions themselves. */
 export declare interface DeployTarget {
-  tags: string[];
+  tag: string;
   workflowResource: WorkflowResource;
 }
 
@@ -6886,7 +6989,6 @@ export declare interface DiagnoseInput {
   instance: Pick<
     WorkflowInstance,
     | "currentStage"
-    | "stages"
     | "completedAt"
     | "abortedAt"
     | "effectHistory"
@@ -6895,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
@@ -6906,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 =
@@ -6929,6 +7035,12 @@ export declare type Diagnosis =
       assignees: Assignee[];
       actions: string[];
     }
+  | {
+      state: "blocked";
+      task: string;
+      requirements: string[];
+      assignees: Assignee[];
+    }
   | {
       state: "completed";
       at: string;
@@ -6998,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 {
@@ -7239,7 +7363,7 @@ export declare interface Engine {
    *  (e.g. test bench, drain workers) that need them; the verbs already
    *  thread them through internally. */
   readonly client: WorkflowClient;
-  readonly tags: readonly string[];
+  readonly tag: string;
   readonly workflowResource: WorkflowResource;
   readonly effectHandlers: Readonly<Record<string, EffectHandler>>;
   readonly missingHandler: MissingHandlerPolicy;
@@ -7316,8 +7440,8 @@ export declare interface Engine {
     instanceId: string;
     task?: string;
   }) => Promise<WorkflowInstance[]>;
-  /** GROQ query against the engine's workflow resource. `$engineTags`
-   *  is bound for tag-aware filtering. */
+  /** GROQ query against the engine's workflow resource. `$tag`
+   *  is bound for tag-scoped filtering. */
   query: <T = unknown>(args: {
     groq: string;
     params?: Record<string, unknown>;
@@ -7351,7 +7475,7 @@ export declare interface Engine {
     access?: WorkflowAccessOverride;
   }) => Promise<DrainEffectsResult>;
   /**
-   * Inspect every deployed definition in the engine's tags and apply
+   * Inspect every deployed definition in the engine's tag and apply
    * the configured missingHandler policy at `phase: "deploy"` for any
    * effect name without a registered handler. Catches "definition
    * shipped, handler removed" misconfigurations at startup instead of
@@ -7371,8 +7495,8 @@ export declare interface EngineLogger {
 
 export declare interface EvaluateArgs {
   client: WorkflowClient;
-  /** Engine-scope tags — required. */
-  tags: string[];
+  /** Engine-scope environment partition — required. */
+  tag: string;
   /** Engine workflow resource — required. */
   workflowResource: WorkflowResource;
   instanceId: string;
@@ -8366,16 +8490,10 @@ 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 tags — required. */
-  tags: string[];
+  /** Engine-scope environment partition — required. */
+  tag: string;
   /** The Sanity resource the engine's own data lives in. */
   workflowResource: WorkflowResource;
   /** Cross-resource routing — see `StartInstanceArgs.resourceClients`. */
@@ -8528,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
@@ -8714,8 +8856,8 @@ export declare type StageName = string;
 
 export declare interface StartInstanceArgs {
   client: WorkflowClient;
-  /** Engine-scope tags — required. */
-  tags: string[];
+  /** Engine-scope environment partition — required. */
+  tag: string;
   /** The Sanity resource the engine's own data lives in. */
   workflowResource: WorkflowResource;
   /**
@@ -9359,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
@@ -10603,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
@@ -11652,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[];
     };
 
 /**
@@ -11767,15 +11974,24 @@ 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 `tags[]` intersect the caller's tag set.
- *
- * @param param - GROQ parameter holding the caller's tags. Defaults to
- *   `engineTags`, matching the `workflow.query` guard so any query built with
- *   it stays tag-scoped.
+ * visible when its `tag` equals the caller's `$tag` param. The single
+ * definition of "tag-scoped" shared by the engine's internal lookups, the
+ * `workflow.query` guard, and the CLI/MCP read helpers.
  */
-export declare function tagScopeFilter(param?: string): string;
+export declare function tagScopeFilter(): string;
 
 export declare type Task = v.InferOutput<typeof StoredTaskSchema>;
 
@@ -11807,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;
   };
   /**
@@ -11825,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[];
 }
 
@@ -11841,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<
@@ -11865,18 +12104,25 @@ export declare function validateDefinition(
 ): void;
 
 /**
- * Engine-scope tags — the multi-tenant isolation primitive.
+ * Engine-scope tag — the environment partition primitive.
  *
- * Every engine takes a required `tags: string[]` set at construction.
- * Tags must be Sanity-ID-compatible since they're joined into IDs with
- * `.` — ASCII lowercase + digits + dashes, no leading dash, no dots.
+ * Every engine operates against exactly one `tag` ("test", "prod", …).
+ * The tag partitions definitions and instances within a single workflow
+ * resource: `deploy(def, tag: "test")` and `deploy(def, tag: "prod")` are
+ * separate deployed workflows with independent lifecycles, and every read
+ * is scoped to one tag so test runs never surface in prod.
  *
- * The first tag in the array is the *canonical* tag, used as the ID
- * prefix when the engine writes new definitions or instances. The full
- * tag set goes onto every written doc and is the basis for read
- * filtering (tag intersection between engine and doc).
+ * The tag must be Sanity-ID-compatible since it's joined into IDs with
+ * `.` — ASCII lowercase + digits + dashes, no leading dash, no dots. It
+ * is also the ID prefix for every definition/instance the engine writes.
+ *
+ * There is no default. The tag selects which environment the engine reads
+ * and writes, and the engine enforces nothing — so the partition is the
+ * only thing keeping test runs out of prod. Every entry point
+ * (`createEngine`, the CLI, the MCP server) requires it explicitly and
+ * fails when it's absent rather than guessing an environment.
  */
-export declare function validateTags(tags: string[]): void;
+export declare function validateTag(tag: string): void;
 
 /**
  * The guards allowed to influence this instance's verdicts, read from the
@@ -12032,44 +12278,43 @@ export declare const workflow: {
    */
   abortInstance: (args: Clocked<AbortInstanceArgs>) => Promise<DispatchResult>;
   /**
-   * Fetch a workflow instance by id, scoped to the engine's tags.
+   * Fetch a workflow instance by id, scoped to the engine's tag.
    * Throws when the instance doesn't exist or isn't visible to this
    * engine.
    */
   getInstance: (args: {
     client: WorkflowClient;
-    tags: string[];
+    tag: string;
     workflowResource: WorkflowResource;
     instanceId: string;
   }) => Promise<WorkflowInstance>;
   guardsForInstance: (args: {
     client: WorkflowClient;
-    tags: string[];
+    tag: string;
     workflowResource: WorkflowResource;
     instanceId: string;
     resourceClients?: ResourceClientResolver;
   }) => Promise<MutationGuardDoc[]>;
   guardsForDefinition: (args: {
     client: WorkflowClient;
-    tags: string[];
+    tag: string;
     workflowResource: WorkflowResource;
     /** The definition's `name`. */
     definition: string;
     resourceClients?: ResourceClientResolver;
   }) => Promise<MutationGuardDoc[]>;
   /**
-   * Run a caller-supplied GROQ query with the engine's tags bound as
-   * `$engineTags`. This does NOT rewrite the query — arbitrary GROQ
+   * Run a caller-supplied GROQ query with the engine's tag bound as
+   * `$tag`. This does NOT rewrite the query — arbitrary GROQ
    * can't be safely tag-scoped after the fact — so the CALLER MUST
-   * filter on `$engineTags` (e.g.
-   * `count(tags[@ in $engineTags]) > 0`). To guard against accidental
-   * cross-tenant reads, a query that never references `$engineTags` is
+   * filter on `$tag` (e.g. `tag == $tag`). To guard against accidental
+   * cross-partition reads, a query that never references `$tag` is
    * rejected before it reaches the lake. Caller is responsible for type
    * narrowing the result.
    */
   query: <T = unknown>(args: {
     client: WorkflowClient;
-    tags: string[];
+    tag: string;
     workflowResource: WorkflowResource;
     groq: string;
     params?: Record<string, unknown>;
@@ -12093,7 +12338,7 @@ export declare const workflow: {
   queryInScope: <T = unknown>(
     args: Clocked<{
       client: WorkflowClient;
-      tags: string[];
+      tag: string;
       workflowResource: WorkflowResource;
       resourceClients?: ResourceClientResolver;
       instanceId: string;
@@ -12107,7 +12352,7 @@ export declare const workflow: {
    */
   listPendingEffects: (args: {
     client: WorkflowClient;
-    tags: string[];
+    tag: string;
     workflowResource: WorkflowResource;
     instanceId: string;
   }) => Promise<PendingEffect[]>;
@@ -12118,7 +12363,7 @@ export declare const workflow: {
    */
   findPendingEffects: (args: {
     client: WorkflowClient;
-    tags: string[];
+    tag: string;
     workflowResource: WorkflowResource;
     instanceId: string;
     claimed?: boolean;
@@ -12160,14 +12405,14 @@ export declare const workflow: {
    * record. (The per-task `spawnedInstances` field on the active stage
    * only exists while that stage is current; history survives.) Strips
    * the GDR URI on each `instanceRef` to a bare `_id`, fetches the
-   * instances, drops any that aren't visible to this engine's tags, and
+   * instances, drops any that aren't visible to this engine's tag, and
    * returns them sorted by `startedAt` ascending.
    *
    * Pass `task` to restrict to a single spawning task on the parent.
    */
   children: (args: {
     client: WorkflowClient;
-    tags: string[];
+    tag: string;
     workflowResource: WorkflowResource;
     instanceId: string;
     task?: string;
@@ -12259,6 +12504,7 @@ export declare interface WorkflowClient {
     },
   >(
     doc: T,
+    options?: WorkflowCommitOptions,
   ) => Promise<T>;
   /**
    * Build a multi-document transaction. All operations succeed or fail
@@ -12311,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
 >;
@@ -12453,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
@@ -13737,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?:
@@ -14120,11 +14421,11 @@ export declare interface WorkflowFetchOptions {
 export declare interface WorkflowInstance extends SanityDocument {
   _type: typeof WORKFLOW_INSTANCE_TYPE;
   /**
-   * Engine-scope tags stamped on the instance at create time. Engines
-   * with disjoint tag sets cannot read this instance; engines sharing
-   * any tag with this array can.
+   * Engine-scope environment partition stamped on the instance at create
+   * time. Reads are scoped to a single tag, so an engine only sees
+   * instances whose `tag` equals its own.
    */
-  tags: string[];
+  tag: string;
   /**
    * The Sanity resource this instance lives in. Stored on the doc so
    * any internal operation can mint GDRs for ancestors / spawned
@@ -14215,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>;
 }
 
 /**
@@ -14316,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 {};