@sanity/workflow-engine 0.13.0 → 0.14.0

package/dist/index.d.ts

@@ -13,17 +13,33 @@ export declare function abortReason(
 
 export declare type Action = ActionFields<Op>;
 
-export declare class ActionDisabledError extends Error {
-  readonly reason: DisabledReason;
+/**
+ * Thrown by `fireAction` when the requested action's verdict is
+ * `allowed: false` for any reason other than a guard denial (that one is
+ * {@link MutationGuardDeniedError} across all verbs). Carries the structured
+ * verdict so UIs render the same reason they would have shown on the
+ * disabled control, instead of parsing a string.
+ */
+export declare class ActionDisabledError extends WorkflowError<"action-disabled"> {
+  readonly reason: ActionDisabledReason;
   readonly activity: ActivityName;
   readonly action: ActionName;
   constructor(args: {
     activity: ActivityName;
     action: ActionName;
-    reason: DisabledReason;
+    reason: ActionDisabledReason;
   });
 }
 
+/** The verdicts {@link ActionDisabledError} can carry — every {@link DisabledReason}
+ *  except `mutation-guard-denied`, which escalates to {@link MutationGuardDeniedError}. */
+export declare type ActionDisabledReason = Exclude<
+  DisabledReason,
+  {
+    kind: "mutation-guard-denied";
+  }
+>;
+
 export declare interface ActionEvaluation {
   action: Action;
   allowed: boolean;
@@ -89,7 +105,7 @@ declare const ActionParamSchema: v.StrictObjectSchema<
  * declared `params[]` — missing required fields or wrong primitive
  * type. The action does not commit; the engine has not mutated state.
  */
-export declare class ActionParamsInvalidError extends Error {
+export declare class ActionParamsInvalidError extends WorkflowError<"action-params-invalid"> {
   readonly action: string;
   readonly activity: ActivityName;
   readonly issues: {
@@ -215,7 +231,7 @@ export declare interface ActivityEvaluation {
   /**
    * The activity's effective {@link ActivityKind} — the explicit {@link Activity.kind}, or
    * the shape-derived default when omitted. Advisory: a label so a consumer can
-   * render each activity as what it is (decision / wait / effect / off-system).
+   * render each activity as what it is (`user` / `service` / `script` / `manual` / `receive`).
    */
   kind: ActivityKind;
   /** Whether this activity is the current actor's responsibility right now. */
@@ -259,8 +275,16 @@ export declare type ActivityName = string;
 
 export declare type ActivityStatus = (typeof ACTIVITY_STATUSES)[number];
 
+/**
+ * Who is acting, as asserted by the caller — advisory provenance, not an
+ * authenticated principal. The engine resolves it from the client's token by
+ * default (`/users/me`), but every acting verb accepts an `access.actor`
+ * override and nothing verifies the asserted id against the token performing
+ * the writes. Only the lake's own token identity is authenticated; hard
+ * enforcement lives there.
+ */
 export declare interface Actor {
-  kind: "user" | "ai" | "system";
+  kind: ActorKind;
   id: string;
   /**
    * Free-form role names — typically a copy of Sanity's `user.roles[].name`
@@ -279,6 +303,10 @@ export declare interface Actor {
   onBehalfOf?: string;
 }
 
+export declare const ACTOR_KINDS: readonly ["person", "agent", "system"];
+
+export declare type ActorKind = (typeof ACTOR_KINDS)[number];
+
 /**
  * One member of an `assignees`-kind entry's value — and the value of the
  * singular `assignee` kind. The WHO-FOR spec the inbox reverse-query and the
@@ -335,7 +363,7 @@ export declare type AuthoringEditable = v.InferOutput<
 /**
  * Authoring editability adds the `role[]` convenience: a non-empty role list
  * desugars to the same `count($actor.roles[@ in [...]]) > 0` membership
- * predicate `action.roles` produces. `true` opens the slot to anyone in its
+ * predicate `action.roles` produces. `true` opens the field to anyone in its
  * window; a bare string is a raw predicate.
  */
 declare const AuthoringEditableSchema: v.UnionSchema<
@@ -387,6 +415,292 @@ declare const AuthoringFieldRefSchema: v.StrictObjectSchema<
   undefined
 >;
 
+export declare type AuthoringGuard = v.InferOutput<typeof AuthoringGuardSchema>;
+
+declare const AuthoringGuardSchema: v.StrictObjectSchema<
+  {
+    name: v.SchemaWithPipe<
+      readonly [
+        v.StringSchema<undefined>,
+        v.MinLengthAction<string, 1, "must be a non-empty string">,
+      ]
+    >;
+    title: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    description: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    match: v.StrictObjectSchema<
+      {
+        /** Subject `_type`(s); empty matches any type. */
+        types: v.OptionalSchema<
+          v.ArraySchema<
+            v.SchemaWithPipe<
+              readonly [
+                v.StringSchema<undefined>,
+                v.MinLengthAction<string, 1, "must be a non-empty string">,
+              ]
+            >,
+            undefined
+          >,
+          undefined
+        >;
+        /** Target docs as field reads (or the instance itself), resolved at deploy to bare ids + the resource. */
+        idRefs: v.OptionalSchema<
+          v.ArraySchema<
+            v.VariantSchema<
+              "type",
+              [
+                v.StrictObjectSchema<
+                  {
+                    readonly type: v.LiteralSchema<"self", undefined>;
+                  },
+                  undefined
+                >,
+                v.StrictObjectSchema<
+                  {
+                    readonly type: v.LiteralSchema<"now", undefined>;
+                  },
+                  undefined
+                >,
+                v.StrictObjectSchema<
+                  {
+                    readonly type: v.LiteralSchema<"fieldRead", undefined>;
+                    readonly field: v.SchemaWithPipe<
+                      readonly [
+                        v.StringSchema<undefined>,
+                        v.RegexAction<string, string>,
+                      ]
+                    >;
+                    readonly path: v.OptionalSchema<
+                      v.SchemaWithPipe<
+                        readonly [
+                          v.SchemaWithPipe<
+                            readonly [
+                              v.StringSchema<undefined>,
+                              v.MinLengthAction<
+                                string,
+                                1,
+                                "must be a non-empty string"
+                              >,
+                            ]
+                          >,
+                          v.CheckAction<
+                            string,
+                            "a guard read path cannot contain a line break"
+                          >,
+                        ]
+                      >,
+                      undefined
+                    >;
+                  },
+                  undefined
+                >,
+                v.StrictObjectSchema<
+                  {
+                    readonly type: v.LiteralSchema<"effectsRead", undefined>;
+                    readonly effect: v.SchemaWithPipe<
+                      readonly [
+                        v.SchemaWithPipe<
+                          readonly [
+                            v.StringSchema<undefined>,
+                            v.MinLengthAction<
+                              string,
+                              1,
+                              "must be a non-empty string"
+                            >,
+                          ]
+                        >,
+                        v.CheckAction<
+                          string,
+                          "an effect name cannot contain `'`"
+                        >,
+                      ]
+                    >;
+                    readonly path: v.OptionalSchema<
+                      v.SchemaWithPipe<
+                        readonly [
+                          v.SchemaWithPipe<
+                            readonly [
+                              v.StringSchema<undefined>,
+                              v.MinLengthAction<
+                                string,
+                                1,
+                                "must be a non-empty string"
+                              >,
+                            ]
+                          >,
+                          v.CheckAction<
+                            string,
+                            "a guard read path cannot contain a line break"
+                          >,
+                        ]
+                      >,
+                      undefined
+                    >;
+                  },
+                  undefined
+                >,
+              ],
+              undefined
+            >,
+            undefined
+          >,
+          undefined
+        >;
+        /** Glob id patterns (bare, resource-local). */
+        idPatterns: v.OptionalSchema<
+          v.ArraySchema<
+            v.SchemaWithPipe<
+              readonly [
+                v.StringSchema<undefined>,
+                v.MinLengthAction<string, 1, "must be a non-empty string">,
+              ]
+            >,
+            undefined
+          >,
+          undefined
+        >;
+        actions: v.SchemaWithPipe<
+          readonly [
+            v.ArraySchema<
+              v.PicklistSchema<
+                readonly ["create", "update", "delete", "publish", "unpublish"],
+                `Invalid option: expected one of ${string}`
+              >,
+              undefined
+            >,
+            v.MinLengthAction<
+              ("create" | "update" | "delete" | "publish" | "unpublish")[],
+              1,
+              "a guard must match at least one action"
+            >,
+          ]
+        >;
+      },
+      undefined
+    >;
+    /**
+     * Lake GROQ predicate — a distinct eval context reading
+     * `document.before`/`document.after`, `mutation`, `guard`, and
+     * `identity()`. Bare ids/fields only. Omitted or empty means
+     * UNCONDITIONAL DENY.
+     */
+    predicate: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    /**
+     * Projected workflow fields the predicate reads as `guard.metadata.*` —
+     * the only bridge from the lake eval context (which cannot see `$fields`)
+     * to workflow fields. Each value is a deploy-time read — a typed
+     * {@link GuardRead} when authoring, the printed string spelling once
+     * stored — resolved into a bare value at deploy and re-synced by the
+     * post-field-op guard refresh.
+     */
+    metadata: v.OptionalSchema<
+      v.RecordSchema<
+        v.SchemaWithPipe<
+          readonly [
+            v.StringSchema<undefined>,
+            v.MinLengthAction<string, 1, "must be a non-empty string">,
+          ]
+        >,
+        v.VariantSchema<
+          "type",
+          [
+            v.StrictObjectSchema<
+              {
+                readonly type: v.LiteralSchema<"self", undefined>;
+              },
+              undefined
+            >,
+            v.StrictObjectSchema<
+              {
+                readonly type: v.LiteralSchema<"now", undefined>;
+              },
+              undefined
+            >,
+            v.StrictObjectSchema<
+              {
+                readonly type: v.LiteralSchema<"fieldRead", undefined>;
+                readonly field: v.SchemaWithPipe<
+                  readonly [
+                    v.StringSchema<undefined>,
+                    v.RegexAction<string, string>,
+                  ]
+                >;
+                readonly path: v.OptionalSchema<
+                  v.SchemaWithPipe<
+                    readonly [
+                      v.SchemaWithPipe<
+                        readonly [
+                          v.StringSchema<undefined>,
+                          v.MinLengthAction<
+                            string,
+                            1,
+                            "must be a non-empty string"
+                          >,
+                        ]
+                      >,
+                      v.CheckAction<
+                        string,
+                        "a guard read path cannot contain a line break"
+                      >,
+                    ]
+                  >,
+                  undefined
+                >;
+              },
+              undefined
+            >,
+            v.StrictObjectSchema<
+              {
+                readonly type: v.LiteralSchema<"effectsRead", undefined>;
+                readonly effect: v.SchemaWithPipe<
+                  readonly [
+                    v.SchemaWithPipe<
+                      readonly [
+                        v.StringSchema<undefined>,
+                        v.MinLengthAction<
+                          string,
+                          1,
+                          "must be a non-empty string"
+                        >,
+                      ]
+                    >,
+                    v.CheckAction<string, "an effect name cannot contain `'`">,
+                  ]
+                >;
+                readonly path: v.OptionalSchema<
+                  v.SchemaWithPipe<
+                    readonly [
+                      v.SchemaWithPipe<
+                        readonly [
+                          v.StringSchema<undefined>,
+                          v.MinLengthAction<
+                            string,
+                            1,
+                            "must be a non-empty string"
+                          >,
+                        ]
+                      >,
+                      v.CheckAction<
+                        string,
+                        "a guard read path cannot contain a line break"
+                      >,
+                    ]
+                  >,
+                  undefined
+                >;
+              },
+              undefined
+            >,
+          ],
+          undefined
+        >,
+        undefined
+      >,
+      undefined
+    >;
+  },
+  undefined
+>;
+
 export declare type AuthoringManualTarget = v.InferOutput<
   typeof AuthoringManualTargetSchema
 >;
@@ -546,7 +860,12 @@ declare const AuthoringOpSchema: v.VariantSchema<
           },
           undefined
         >;
-        readonly where: v.GenericSchema<OpPredicateInternal>;
+        readonly where: v.SchemaWithPipe<
+          readonly [
+            v.StringSchema<undefined>,
+            v.MinLengthAction<string, 1, "must be a non-empty string">,
+          ]
+        >;
         readonly value: v.GenericSchema<ValueExprInternal>;
       },
       undefined
@@ -572,7 +891,12 @@ declare const AuthoringOpSchema: v.VariantSchema<
           },
           undefined
         >;
-        readonly where: v.GenericSchema<OpPredicateInternal>;
+        readonly where: v.SchemaWithPipe<
+          readonly [
+            v.StringSchema<undefined>,
+            v.MinLengthAction<string, 1, "must be a non-empty string">,
+          ]
+        >;
       },
       undefined
     >,
@@ -660,7 +984,10 @@ declare const AuthoringOpSchema: v.VariantSchema<
  *   - `status` → a `status.set` op on the firing activity, appended **after**
  *     the authored ops (deliberately never implied: a forgotten explicit
  *     `status` is a visible stall, an implied default silently completes
- *     claim-like actions).
+ *     claim-like actions). Status is the health axis: a decision action
+ *     (decline, send back) resolves `done` and writes the decision into a
+ *     field the transition filter reads — `failed` is for work that
+ *     genuinely could not complete.
  */
 declare type AuthoringRawAction = ActionFields<AuthoringOp> & {
   roles?: string[] | undefined;
@@ -673,6 +1000,7 @@ export declare type AuthoringStage = StageFields<
   AuthoringFieldEntry,
   AuthoringActivity,
   AuthoringTransition,
+  AuthoringGuard,
   AuthoringEditable
 >;
 
@@ -788,7 +1116,12 @@ declare const AuthoringTransitionOpSchema: v.VariantSchema<
           },
           undefined
         >;
-        readonly where: v.GenericSchema<OpPredicateInternal>;
+        readonly where: v.SchemaWithPipe<
+          readonly [
+            v.StringSchema<undefined>,
+            v.MinLengthAction<string, 1, "must be a non-empty string">,
+          ]
+        >;
         readonly value: v.GenericSchema<ValueExprInternal>;
       },
       undefined
@@ -814,7 +1147,12 @@ declare const AuthoringTransitionOpSchema: v.VariantSchema<
           },
           undefined
         >;
-        readonly where: v.GenericSchema<OpPredicateInternal>;
+        readonly where: v.SchemaWithPipe<
+          readonly [
+            v.StringSchema<undefined>,
+            v.MinLengthAction<string, 1, "must be a non-empty string">,
+          ]
+        >;
       },
       undefined
     >,
@@ -903,14 +1241,6 @@ export declare interface AvailableActionsResult {
   actions: AvailableAction[];
 }
 
-declare type Bound<
-  Args extends {
-    client: WorkflowClient;
-    tag: string;
-    workflowResource: WorkflowResource;
-  },
-> = Omit<Args, "client" | "tag" | "workflowResource">;
-
 /**
  * Build a snapshot from a set of loaded docs. Pure transform.
  *
@@ -940,12 +1270,17 @@ export declare function buildSnapshot(args: {
  * The cascade aborts at the limit rather than the engine hanging; the
  * instance is left at whatever stage the last completed pass reached.
  */
-export declare class CascadeLimitError extends Error {
+export declare class CascadeLimitError extends WorkflowError<"cascade-limit"> {
   readonly instanceId: string;
   readonly limit: number;
   constructor(args: { instanceId: string; limit: number });
 }
 
+export declare interface ChildrenArgs extends InstanceRefArgs {
+  /** Restrict to children spawned by this activity on the parent. */
+  activity?: string;
+}
+
 /**
  * The action half of the mirrored claim pair. `field` references an
  * author-declared actor-valued entry (the pair's other half), resolved
@@ -969,7 +1304,7 @@ declare type ClaimAction = {
 /**
  * Authoring fields accept the raw entries plus the `claim` sugar type — the
  * field half of the mirrored claim pair. Expansion: an `actor` working-
- * memory slot (no `initialValue`; the claim action's op fills it), strictly
+ * memory field (no `initialValue`; the claim action's op fills it), strictly
  * within this entry.
  */
 declare type ClaimField = {
@@ -1016,6 +1351,16 @@ declare type Clocked<T> = T & {
   clock?: Clock;
 };
 
+/**
+ * A compiled lake read — what the engine's query builders return and what a
+ * reactive adapter's live-query store subscribes with, so the stateless and
+ * reactive paths run the same GROQ.
+ */
+export declare interface CompiledQuery {
+  query: string;
+  params: Record<string, string>;
+}
+
 /** Assemble a persisted guard doc from resolved pieces. */
 export declare function compileGuard(args: CompileGuardArgs): MutationGuardDoc;
 
@@ -1070,7 +1415,7 @@ export declare function computeDiffEntries({
  * lost the optimistic-locking race on every attempt. Same contract — re-read
  * and retry, or investigate a write storm; nothing committed on the final try.
  */
-export declare class ConcurrentEditFieldError extends Error {
+export declare class ConcurrentEditFieldError extends WorkflowError<"concurrent-edit-field"> {
   readonly instanceId: string;
   readonly target: {
     scope: FieldScope;
@@ -1097,7 +1442,7 @@ export declare class ConcurrentEditFieldError extends Error {
  * whether to retry later or report a write storm; nothing was committed
  * on the final attempt.
  */
-export declare class ConcurrentFireActionError extends Error {
+export declare class ConcurrentFireActionError extends WorkflowError<"concurrent-fire-action"> {
   readonly instanceId: string;
   readonly activity: ActivityName;
   readonly action: string;
@@ -1110,8 +1455,69 @@ export declare class ConcurrentFireActionError extends Error {
   });
 }
 
+/**
+ * A raw GROQ string evaluated over the rendered scope: the engine-bound
+ * variables inventoried in {@link CONDITION_VARS} (each annotated with the
+ * context that binds it) plus the author's nullary `predicates` as `$<name>`
+ * booleans. Evaluation runs against the instance's in-memory snapshot —
+ * never a `_type` scan over the lake (rejected at deploy).
+ *
+ * There is no `{ref, args}` wrapper: parameterized reuse is a define-time
+ * TypeScript function producing a condition string (see the {@link groq} tag).
+ */
 export declare type Condition = string;
 
+/**
+ * Every variable the engine binds for conditions, in one place. The
+ * deploy-time shadow check ({@link RESERVED_CONDITION_VARS}) and the docs on
+ * {@link Condition} derive from this list — extend it here when the engine
+ * grows a binding, never in a comment elsewhere.
+ */
+export declare const CONDITION_VARS: readonly ConditionVar[];
+
+export declare interface ConditionVar {
+  /** The GROQ param name, read as `$<name>`. */
+  name: string;
+  binding: ConditionVarBinding;
+  description: string;
+}
+
+/**
+ * The condition-variable inventory — the single source of truth for every
+ * `$var` the engine binds when it evaluates a {@link Condition}.
+ *
+ * Three evaluation contexts read a definition's GROQ:
+ *
+ * 1. **Rendered condition scope** — every condition site in a definition
+ *    (transition filters, `completeWhen`/`failWhen`, action filters, effect
+ *    bindings, `subworkflows` reads, where-op `where`s, editability
+ *    predicates, author predicates). {@link CONDITION_VARS} is its inventory;
+ *    each entry's `binding` says when the var actually holds a value. The
+ *    where-op context is the one closed subset — its bound set is statically
+ *    fixed and deploy-enforced (see the op-where scope's param-name list in
+ *    the op applier).
+ * 2. **Filter evaluation without a caller** — the engine's cascade evaluates
+ *    transition filters and `completeWhen`/`failWhen` with no caller, so only
+ *    the `'always'`-bound subset carries values there ({@link FILTER_SCOPE_VARS}).
+ *    Caller-bound vars evaluate to `undefined` and fail closed.
+ * 3. **Guard predicates** — NOT conditions. A lake mutation guard's
+ *    `predicate` is groq-js **delta-mode** GROQ over a document mutation:
+ *    `before()`/`after()`/`identity()` are dialect natives, and the wire
+ *    format binds the identifiers in {@link GUARD_PREDICATE_VARS}. None of
+ *    the condition vars exist there.
+ */
+/**
+ * When a condition var holds a value:
+ *
+ * - `'always'` — bound in every condition evaluation, derived from the
+ *   instance and its snapshot.
+ * - `'caller'` — rides the acting caller; without one the var is `undefined`
+ *   (conditions referencing it fail closed). Author predicates may not read
+ *   these — they pre-evaluate once per instance, caller-free.
+ * - `'spawn'` — bound only at `subworkflows` sites.
+ */
+export declare type ConditionVarBinding = "always" | "caller" | "spawn";
+
 /**
  * The Content Release a watched doc resolves under, or `undefined` for a raw
  * read — how a reactive adapter turns the watch-set's perspective into the
@@ -1135,39 +1541,52 @@ export declare function contentReleaseName(args: {
   perspective: WorkflowPerspective | undefined;
 }): string | undefined;
 
+/**
+ * A caller broke a public-API contract — a call the engine rejects
+ * before touching the lake: an invalid `tag`, a `workflow.query` GROQ that
+ * never binds `$tag`, a bare id where a GDR URI is required, an action,
+ * activity, or field the definition never declared. Fix the call site;
+ * retrying cannot succeed.
+ */
+export declare class ContractViolationError extends WorkflowError<"contract-violation"> {
+  constructor(message: string);
+}
+
 /**
  * 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 / tag / workflowResource)
- * which are pinned at construction. The `tag` is required — see
- * {@link validateTag} for the accepted shape.
+ * object exposes the `workflow.*` verbs minus the {@link EngineScopeArgs}
+ * scope (client / tag / workflowResource / resourceClients), which is
+ * pinned at construction. The `tag` is required — see {@link validateTag}
+ * for the accepted shape.
+ *
+ * Parity with the namespace is exact, with these deliberate exceptions:
+ *
+ * - Engine-only: {@link Engine.session} and
+ *   {@link Engine.subscriptionDocumentsForInstance} (need the pinned
+ *   binding), {@link Engine.drainEffects} and
+ *   {@link Engine.verifyDeployedDefinitions} (need the construction-time
+ *   `effectHandlers` / `missingHandler` / `loggerFactory`).
+ * - Namespace-only: `workflow.permissions` — pure grant helpers that need
+ *   no engine scope.
  *
- * Effect handlers + missingHandler are stored for future drain wiring
- * (Step 10). They have no effect on `fireAction` / `tick` /
- * `completeEffect` today — those still expect the runtime to dispatch
- * effects and report back via `completeEffect`.
+ * Effect handlers + missingHandler feed {@link Engine.drainEffects}
+ * (dispatch of unclaimed pending effects) and
+ * {@link Engine.verifyDeployedDefinitions} (the startup audit of
+ * deployed effect names). They don't change `fireAction` / `tick` /
+ * `completeEffect` — the runtime still decides when to drain and
+ * reports outcomes via `completeEffect`.
  */
 export declare function createEngine(args: CreateEngineArgs): Engine;
 
-export declare interface CreateEngineArgs {
-  client: WorkflowClient;
-  workflowResource: WorkflowResource;
-  /**
-   * 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
-   * the resolver; if the resolver returns a client, that one is used.
-   * Otherwise the engine's default `client` is used (best for
-   * single-resource setups — most demos).
-   */
-  resourceClients?: ResourceClientResolver;
+/**
+ * The {@link EngineScopeArgs} scope pinned at construction, plus the
+ * engine-only extras (`effectHandlers` / `missingHandler` / `loggerFactory`
+ * feed `drainEffects` + `verifyDeployedDefinitions`). The `tag` partition is
+ * required and never defaulted — the engine enforces nothing, so the
+ * partition is the only thing keeping reads and writes off the wrong
+ * environment.
+ */
+export declare interface CreateEngineArgs extends EngineScopeArgs {
   effectHandlers?: Record<string, EffectHandler>;
   missingHandler?: MissingHandlerPolicy;
   loggerFactory?: LoggerFactory;
@@ -1213,14 +1632,52 @@ export declare const DEFAULT_CONTENT_PERSPECTIVE = "drafts";
  */
 export declare const defaultLoggerFactory: LoggerFactory;
 
-export declare interface DeleteDefinitionArgs {
+declare interface DefinitionGuardsQueryArgs {
   client: WorkflowClient;
-  /** Engine-scope environment partition — required. See {@link validateTag} + `tags.ts`. */
-  tag: string;
-  /** The Sanity resource the engine's own data lives in. */
+  clientForGdr: (parsed: ParsedGdr) => WorkflowClient;
   workflowResource: WorkflowResource;
-  /** Cross-resource routing — see `StartInstanceArgs.resourceClients`. */
-  resourceClients?: ResourceClientResolver;
+  definition: string;
+  /** Every deployed version of {@link DefinitionGuardsQueryArgs.definition}. */
+  definitions: WorkflowDefinition[];
+}
+
+/** What blocks a `deleteDefinition`, so a consumer can render the remediation:
+ *  abort-in-place via `cascade`, or delete/redeploy the referrer first. */
+export declare type DefinitionInUseBlocker =
+  | {
+      reason: "non-terminal-instances";
+      instanceIds: string[];
+    }
+  | {
+      reason: "spawn-referrers";
+      referrers: {
+        definition: string;
+        version: number;
+      }[];
+    };
+
+/**
+ * `deleteDefinition` refused because the definition is still in use — either
+ * non-terminal instances are pinned to it (pass `cascade` to abort them in
+ * place first) or a surviving deployed definition still spawn-references a
+ * targeted version (delete or redeploy the referrer first). `blockedBy` says
+ * which, with the blocking ids, so a consumer can render the remediation.
+ */
+export declare class DefinitionInUseError extends WorkflowError<"definition-in-use"> {
+  readonly definition: string;
+  readonly blockedBy: DefinitionInUseBlocker;
+  constructor(args: { definition: string; blockedBy: DefinitionInUseBlocker });
+}
+
+/** No deployed workflow definition matches the requested name (and version,
+ *  when given) under this engine's tag. */
+export declare class DefinitionNotFoundError extends WorkflowError<"definition-not-found"> {
+  readonly definition: string;
+  readonly version?: number;
+  constructor(args: { definition: string; version?: number });
+}
+
+export declare interface DeleteDefinitionArgs {
   /** The definition's `name` — delete addresses the workflow, not a doc id. */
   definition: string;
   /** Delete only this deployed version. Default: every deployed version. */
@@ -1256,6 +1713,26 @@ export declare interface DeleteDefinitionResult {
   deletedGuardCount: number;
 }
 
+/**
+ * Human label per denying guard — the authored `name` when present, else the
+ * raw guard id. The one display convention for rendering a denial to a
+ * person; the payload keeps the raw ids for operators locating the guard doc.
+ */
+export declare function deniedGuardLabels(
+  denied: readonly DeniedGuardRef[],
+): string[];
+
+/**
+ * One denying guard, as carried by both the read-side verdict
+ * (`mutation-guard-denied` in {@link DisabledReason}) and the thrown
+ * {@link MutationGuardDeniedError} — one shape for the same denial, so a
+ * consumer renders it once.
+ */
+export declare interface DeniedGuardRef {
+  guardId: string;
+  name?: string;
+}
+
 /**
  * Run every guard whose `match` applies and collect those that DENY. Empty
  * result ⇒ allowed (optimistically).
@@ -1271,22 +1748,13 @@ export declare function denyingGuards(args: {
 
 export declare interface DeployDefinitionResult {
   /** The definition's `name`. */
-  definition: string;
+  name: string;
   /** The deploy-assigned version this deploy created or matched. */
   version: number;
   status: "created" | "unchanged";
 }
 
 export declare interface DeployDefinitionsArgs {
-  client: WorkflowClient;
-  /** 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,
-   * ancestor refs). Mirrors `@sanity/client`'s `ClientConfigResource`.
-   */
-  workflowResource: WorkflowResource;
   /**
    * Resource-alias bindings for this deploy (alias name → physical resource).
    * Every `@<alias>:` reference in a definition is expanded to its bound
@@ -1321,7 +1789,7 @@ export declare type DeployedDefinition = WorkflowDefinition & {
 /**
  * Deploy every guard for a stage being entered (idempotent upsert), but only
  * while the instance is still committed to that stage. A deploy that lost the
- * race to a newer transition would otherwise re-enforce a stage the instance
+ * race to a newer transition would otherwise re-lock a stage the instance
  * already left — a stale lock the newer transition's retract can't see. A
  * vanished instance (`undefined`) likewise no-ops: `undefined !== stageName`.
  *
@@ -1462,13 +1930,23 @@ export declare function diffEntry({
   target: DeployTarget;
 }): DiffEntry;
 
+/**
+ * Why an action is disabled for this actor right now — the read-side verdict.
+ *
+ * Verdict↔exception mapping (what `fireAction` throws when the verdict says
+ * no): the `mutation-guard-denied` arm escalates to
+ * {@link MutationGuardDeniedError} — the one guard-denial error, shared by
+ * every verb; every other arm is thrown as {@link ActionDisabledError}
+ * carrying the verdict as `reason`. The edit seam mirrors this: see
+ * {@link EditDisabledReason} and {@link EditFieldDeniedError}.
+ */
 export declare type DisabledReason =
   | {
       /**
        * The action's condition evaluated falsy for this actor — the ONE
-       * engine-side gate (advisory: hard enforcement is the lake ACL +
-       * guards). Sugar like `roles` desugared into this condition, so a
-       * role miss surfaces here too.
+       * engine-side gate (advisory, like every engine check). Sugar like
+       * `roles` desugared into this condition, so a role miss surfaces
+       * here too.
        */
       kind: "filter-failed";
       filter: string;
@@ -1484,13 +1962,13 @@ export declare type DisabledReason =
     }
   | {
       /**
-       * A live lake mutation guard denies the instance write every action
-       * commit performs. Advisory pre-flight of the lake's own enforcement;
-       * carries the denying guard ids.
+       * A deployed mutation guard denies the instance write every action
+       * commit performs. Advisory pre-flight — the engine's optimistic
+       * evaluation; `denied` is the same {@link DeniedGuardRef} shape the
+       * thrown {@link MutationGuardDeniedError} carries.
        */
       kind: "mutation-guard-denied";
-      guardIds: string[];
-      detail?: string;
+      denied: DeniedGuardRef[];
     }
   | {
       kind: "instance-completed";
@@ -1509,19 +1987,6 @@ export declare type DisabledReason =
       unmetRequirements: string[];
     };
 
-export declare interface DispatchResult {
-  /** The instance after the operation + all cascading auto-transitions. */
-  instance: WorkflowInstance;
-  /** Number of auto-transitions that fired during the cascade. */
-  cascaded: number;
-  /** Whether the originally-requested intent fired. */
-  fired: boolean;
-  /** Engine primitives (`workflow.op.field.*` / `status.set`) that ran
-   *  during the action commit. Surfaced for caller-side assertions and
-   *  audit. */
-  ranOps?: OpAppliedSummary[];
-}
-
 /**
  * Single combined map for callers that don't care which family the
  * key belongs to (e.g. an audit row showing any `_type`).
@@ -1567,6 +2032,13 @@ declare const DOCUMENT_VALUE_PERMISSIONS: readonly ["create", "read", "update"];
 export declare type DocumentValuePermission =
   (typeof DOCUMENT_VALUE_PERMISSIONS)[number];
 
+export declare interface DrainEffectsArgs extends InstanceRefArgs {
+  /** Override the drainer's identity (e.g. impersonate a real user whose
+   *  grants the dispatch should respect). Defaults to a
+   *  `{ kind: "system", id: "engine.drainEffects" }` actor. */
+  access?: WorkflowAccessOverride;
+}
+
 export declare interface DrainEffectsResult {
   drained: PendingEffect[];
   failed: PendingEffect[];
@@ -1607,9 +2079,9 @@ export declare const DRIVER_KINDS: readonly [
 export declare type DriverKind = (typeof DRIVER_KINDS)[number];
 
 /**
- * Classify the actor that drove an action for the audit-trail glyph: a human is
- * a `person`, an LLM is an `agent`, and a `system` actor is the `engine` itself
- * ({@link isEngineActor}) or otherwise an external `service`.
+ * Classify the actor that drove an action for the audit-trail glyph. `person`
+ * and `agent` pass through from {@link Actor.kind}; a `system` actor is the
+ * `engine` itself ({@link isEngineActor}) or otherwise an external `service`.
  *
  * Advisory and only as trustworthy as the {@link Actor} it reads — actor
  * identity is itself advisory in this engine (the lake/token is authoritative),
@@ -1620,36 +2092,36 @@ export declare function driverKind(actor: Actor): DriverKind;
 export declare type Editable = v.InferOutput<typeof StoredEditableSchema>;
 
 /**
- * One declared-editable slot in the current scope, projected for an actor: its
+ * One declared-editable field in the current scope, projected for an actor: its
  * resolved value, whether this actor may edit it now (advisory), and the
  * provenance of the current value read off `opApplied` history. The reactive
  * surface a consumer renders as an inline field (the field widget itself is
- * out of scope here — see the slot-component work).
+ * out of scope here — see the field-component work).
  */
-export declare interface EditableSlotEvaluation {
+export declare interface EditableFieldEvaluation {
   scope: FieldScope;
   /** Present iff `scope === "activity"`. */
   activity?: ActivityName;
   name: string;
   type: FieldKind;
   title?: string;
-  /** Current resolved value; `undefined` until the slot is first resolved. */
+  /** Current resolved value; `undefined` until the field is first resolved. */
   value: unknown;
-  /** Whether THIS actor may edit the slot right now (window + predicate + guard). */
+  /** Whether THIS actor may edit the field right now (window + predicate + guard). */
   editable: boolean;
   /** Present iff `editable === false`. */
   disabledReason?: EditDisabledReason;
-  /** Actor who last wrote the slot (latest `opApplied`); absent if never written. */
+  /** Actor who last wrote the field (latest `opApplied`); absent if never written. */
   setBy?: Actor;
-  /** When the slot was last written (ISO); absent if never written. */
+  /** When the field was last written (ISO); absent if never written. */
   setAt?: string;
 }
 
 /**
- * Why an editable slot can't be edited by this actor right now — the edit-seam
- * twin of {@link DisabledReason}. First failing gate wins: the slot must be
- * declared editable, its scope window open, no lake guard denying the instance
- * write, and the who-may-edit predicate satisfied. Reuses the shared
+ * Why an editable field can't be edited by this actor right now — the edit-seam
+ * twin of {@link DisabledReason}. First failing gate wins: the field must be
+ * declared editable, its scope window open, no deployed guard denying the
+ * instance write, and the who-may-edit predicate satisfied. Reuses the shared
  * `mutation-guard-denied` shape — an edit is the same instance-doc `update` an
  * action commit performs, so the same guard pre-flight applies.
  */
@@ -1662,49 +2134,45 @@ export declare type EditDisabledReason =
       completedAt: string;
     }
   | {
-      /** The slot's scope window is closed: an activity-scope slot whose activity isn't
+      /** The field's scope window is closed: an activity-scope field whose activity isn't
        *  active, or otherwise out of its editable window. */
       kind: "edit-window-closed";
       detail: string;
     }
   | {
-      /** The slot's effective `editable` predicate evaluated falsy for this
+      /** The field's effective `editable` predicate evaluated falsy for this
        *  actor (a role/predicate miss; the stage tighten-override is folded in). */
       kind: "editor-not-permitted";
       predicate: string;
     }
-  | Extract<
-      DisabledReason,
-      {
-        kind: "mutation-guard-denied";
-      }
-    >;
+  | MutationGuardDenial;
 
 export declare interface EditFieldArgs extends OperationArgs {
   /**
-   * Which declared-editable slot to write. Omit `scope` to resolve lexically
+   * Which declared-editable field to write. Omit `scope` to resolve lexically
    * (a `activity` implies activity scope; otherwise the nearest declaring scope, stage
-   * before workflow). `activity` is required to address an activity-scope slot.
+   * before workflow). `activity` is required to address an activity-scope field.
    */
   target: EditFieldTarget;
   /**
    * How to write: `set` replaces the value (reassign / reschedule), `append`
-   * adds a row to an array slot (a running log / todo list), `unset` clears it.
+   * adds a row to an array field (a running log / todo list), `unset` clears it.
    * Default `set`.
    */
   mode?: EditMode;
   /**
    * The new value (for `set`) or row (for `append`), as plain JSON matching the
-   * slot's kind. Validated against the slot kind in the op path; omit for
+   * field's kind. Validated against the field kind in the op path; omit for
    * `unset`.
    */
   value?: unknown;
 }
 
 /** Edit-seam twin of {@link ActionDisabledError}: thrown by `editField` when
- *  the slot can't be edited by the caller. Carries the structured reason. */
-export declare class EditFieldDeniedError extends Error {
-  readonly reason: EditDisabledReason;
+ *  the field can't be edited by the caller — except a guard denial, which is
+ *  {@link MutationGuardDeniedError} across all verbs. Carries the structured reason. */
+export declare class EditFieldDeniedError extends WorkflowError<"edit-field-denied"> {
+  readonly reason: EditFieldDeniedReason;
   readonly target: {
     scope: FieldScope;
     field: string;
@@ -1716,31 +2184,39 @@ export declare class EditFieldDeniedError extends Error {
       field: string;
       activity?: string;
     };
-    reason: EditDisabledReason;
+    reason: EditFieldDeniedReason;
   });
 }
 
+/** The verdicts {@link EditFieldDeniedError} can carry — every {@link EditDisabledReason}
+ *  except `mutation-guard-denied`, which escalates to {@link MutationGuardDeniedError}. */
+export declare type EditFieldDeniedReason = Exclude<
+  EditDisabledReason,
+  {
+    kind: "mutation-guard-denied";
+  }
+>;
+
 export declare interface EditFieldTarget {
-  /** Omit to resolve lexically (activity slot if `activity` set, else stage then workflow). */
+  /** Omit to resolve lexically (activity field if `activity` set, else stage then workflow). */
   scope?: FieldScope;
   field: string;
-  /** Required to address an activity-scope slot. */
+  /** Required to address an activity-scope field. */
   activity?: string;
 }
 
 /**
- * The generic edit seam (EDEX-1319). `editField` writes a declared-editable
- * slot directly — reassign, reschedule, claim-by-hand, append to a log —
+ * The generic edit seam. `editField` writes a declared-editable
+ * field directly — reassign, reschedule, claim-by-hand, append to a log —
  * without a bespoke action per field. It is NOT a raw patch: the edit applies
  * as a `field.*` op through the shared op path (so it stamps `opApplied`
- * provenance + history), gates on the slot's declared editability the same way
+ * provenance + history), gates on the field's declared editability the same way
  * an action gates on its filter, then refreshes the stage's guards and lets the
  * caller cascade. Editing a value a transition reads can and should move the
  * instance — that rippling is intended.
  *
- * Gating is ONE mechanism (advisory, like every engine check): the slot's
- * effective `editable` predicate over the rendered scope. The lake ACL + guards
- * are the only hard locks.
+ * Gating is ONE mechanism (advisory, like every engine check): the field's
+ * effective `editable` predicate over the rendered scope.
  */
 export declare type EditMode = "set" | "append" | "unset";
 
@@ -1799,6 +2275,15 @@ export declare interface EffectHistoryEntry {
   params: Record<string, unknown>;
   origin: EffectOrigin;
   actor?: Actor;
+  /**
+   * `_key` of the stage entry the run was queued under, carried from the
+   * pending entry — the identity that makes the `$effectStatus` read
+   * re-entry-safe (a timestamp tie could not be: same-commit loop-backs and
+   * frozen test clocks stamp identical times). Absent only on rows persisted
+   * before the engine stamped it; those never count as the current entry's
+   * run (fail closed).
+   */
+  stageEntryKey?: string;
   ranAt: string;
   durationMs?: number;
   status: "done" | "failed";
@@ -1817,6 +2302,18 @@ export declare interface EffectHistoryEntry {
 
 export declare type EffectName = string;
 
+/**
+ * The effect key does not match any pending effect on the instance. Besides a
+ * typo'd key, an at-least-once runtime hits this on a double delivery — the
+ * first completion drained the effect — so a consumer can branch on this kind
+ * to treat the second attempt as already-done rather than as a failure.
+ */
+export declare class EffectNotFoundError extends WorkflowError<"effect-not-found"> {
+  readonly instanceId: string;
+  readonly effectKey: string;
+  constructor(args: { instanceId: string; effectKey: string });
+}
+
 /**
  * Thrown when the ops an effect handler returns from its completion don't
  * parse against the stored op schema — a malformed `field.*` / `status.set`
@@ -1825,7 +2322,7 @@ export declare type EffectName = string;
  * a handler is external code, so its returned ops are validated at the
  * completion boundary rather than trusted to be well-formed.
  */
-export declare class EffectOpsInvalidError extends Error {
+export declare class EffectOpsInvalidError extends WorkflowError<"effect-ops-invalid"> {
   readonly effect: string;
   readonly issues: string[];
   constructor(args: { effect: string; issues: string[] });
@@ -1952,7 +2449,7 @@ export declare type EffectsContextEntry =
  * `$effects['<effect name>'].<output>`.
  */
 export declare function effectsContextMap(
-  instance: WorkflowInstance,
+  instance: Pick<WorkflowInstance, "effectsContext">,
 ): Record<string, unknown>;
 
 export declare interface Engine {
@@ -1966,36 +2463,34 @@ export declare interface Engine {
   readonly missingHandler: MissingHandlerPolicy;
   readonly logger: LoggerFactory;
   deployDefinitions: (
-    args: Bound<DeployDefinitionsArgs>,
+    args: DeployDefinitionsArgs,
   ) => Promise<DeployDefinitionsResult>;
-  startInstance: (args: Bound<StartInstanceArgs>) => Promise<WorkflowInstance>;
-  fireAction: (args: Bound<FireActionArgs>) => Promise<DispatchResult>;
-  /** Edit a declared-editable field slot directly (the generic edit seam):
+  startInstance: (args: StartInstanceArgs) => Promise<OperationResult>;
+  fireAction: (args: FireActionArgs) => Promise<OperationResult>;
+  /** Edit a declared-editable field directly (the generic edit seam):
    *  reassign / reschedule / claim-by-hand / append-to-log, then cascade. */
-  editField: (args: Bound<EditFieldArgs>) => Promise<DispatchResult>;
-  completeEffect: (args: Bound<CompleteEffectArgs>) => Promise<DispatchResult>;
-  tick: (args: Bound<OperationArgs>) => Promise<DispatchResult>;
-  evaluateInstance: (
-    args: Bound<EvaluateArgs>,
-  ) => ReturnType<typeof evaluateInstance>;
+  editField: (args: EditFieldArgs) => Promise<OperationResult>;
+  completeEffect: (args: CompleteEffectArgs) => Promise<OperationResult>;
+  tick: (args: OperationArgs) => Promise<OperationResult>;
+  /** Project the instance from an actor's perspective — per-action verdicts
+   *  with structured disabled reasons. Pure read. */
+  evaluate: (args: EvaluateArgs) => Promise<WorkflowEvaluation>;
   /** Diagnose why an instance is or isn't progressing — a classified
    *  {@link DiagnoseResult} plus the evaluation it was derived from. */
-  diagnose: (args: Bound<EvaluateArgs>) => Promise<DiagnoseResult>;
+  diagnose: (args: EvaluateArgs) => Promise<DiagnoseResult>;
   /** The actions firable on the instance's current stage, each flagged
    *  allowed/disabled, plus the evaluation they came from. */
-  availableActions: (
-    args: Bound<EvaluateArgs>,
-  ) => Promise<AvailableActionsResult>;
+  availableActions: (args: EvaluateArgs) => Promise<AvailableActionsResult>;
   /** Admin override — bypass filters/transitions and force the stage. */
-  setStage: (args: Bound<SetStageArgs>) => Promise<DispatchResult>;
+  setStage: (args: SetStageArgs) => Promise<OperationResult>;
   /** Admin override — hard-stop an in-flight instance where it stands. */
-  abortInstance: (args: Bound<AbortInstanceArgs>) => Promise<DispatchResult>;
+  abortInstance: (args: AbortInstanceArgs) => Promise<OperationResult>;
   /** Admin override — remove a deployed definition (instances are only ever aborted, never deleted). */
   deleteDefinition: (
-    args: Bound<DeleteDefinitionArgs>,
+    args: DeleteDefinitionArgs,
   ) => Promise<DeleteDefinitionResult>;
   /** Fetch a workflow instance by id. */
-  getInstance: (args: { instanceId: string }) => Promise<WorkflowInstance>;
+  getInstance: (args: InstanceRefArgs) => Promise<WorkflowInstance>;
   /** The reactive {@link WatchSet} for an instance — every document whose
    *  change should re-evaluate it (the instance, its ancestors, and the docs
    *  named by `doc.ref`/`doc.refs`/`release.ref` field entries on the workflow scope
@@ -2003,27 +2498,19 @@ export declare interface Engine {
    *  instance's read perspective. Fetches the instance, then derives. A
    *  reactive adapter that already holds the live instance calls the pure
    *  `subscriptionDocumentsForInstance` directly instead, to avoid the re-fetch. */
-  subscriptionDocumentsForInstance: (args: {
-    instanceId: string;
-  }) => Promise<WatchSet>;
+  subscriptionDocumentsForInstance: (
+    args: InstanceRefArgs,
+  ) => Promise<WatchSet>;
   /** Opt into reactivity: bind the engine to an instance doc and get a stateful
    *  {@link InstanceSession}. Push the docs it lists in `subscriptionDocuments`
    *  via `update`, then `evaluate`/`tick`/`fireAction` against the held state —
    *  pushed content is never refetched. The session never observes or ticks on
    *  its own; the consumer drives it. */
-  instance: (
-    instanceDoc: WorkflowInstance,
-    opts?: {
-      access?: WorkflowAccessOverride | undefined;
-      grantsFromPath?: string | undefined;
-    },
-  ) => InstanceSession;
+  session: (args: SessionArgs) => InstanceSession;
   /** Every lake mutation guard this instance registered, unioned across the
    *  instance's own resource and the resource of each `doc.ref`/`doc.refs`
    *  GDR it holds in state. For coherency refresh and housekeeping. */
-  guardsForInstance: (args: {
-    instanceId: string;
-  }) => Promise<MutationGuardDoc[]>;
+  guardsForInstance: (args: InstanceRefArgs) => Promise<MutationGuardDoc[]>;
   /** Every lake mutation guard a workflow deployed (any version), across the
    *  datasources its guards statically name — the workflow resource plus any
    *  literal-GDR field entries, unioned over all deployed versions.
@@ -2031,58 +2518,40 @@ export declare interface Engine {
    *  (input/runtime-sourced entries) are not reachable here — use
    *  {@link Engine.guardsForInstance}. For housekeeping. Takes the
    *  definition's `name`. */
-  guardsForDefinition: (args: {
-    definition: string;
-  }) => Promise<MutationGuardDoc[]>;
+  guardsForDefinition: (
+    args: GuardsForDefinitionArgs,
+  ) => Promise<MutationGuardDoc[]>;
   /** Spawned children of a parent instance, optionally filtered by the
    *  spawning activity. Sorted by `startedAt` asc. */
-  children: (args: {
-    instanceId: string;
-    activity?: string;
-  }) => Promise<WorkflowInstance[]>;
+  children: (args: ChildrenArgs) => Promise<WorkflowInstance[]>;
   /** The reverse of {@link Engine.subscriptionDocumentsForInstance}: every
    *  in-flight instance whose watch-set includes `document` (a resource-qualified
    *  GDR URI). For a non-reactive, content-change-driven runtime deciding which
    *  instances a changed doc should `tick`. Matches the same ref set the forward
    *  watch-set uses (self, ancestors, current-stage `doc.ref`/`doc.refs`/`release.ref`)
    *  via the shared `collectWatchRefs`. Sorted by `startedAt` asc. */
-  instancesForDocument: (args: {
-    document: GdrUri;
-  }) => Promise<WorkflowInstance[]>;
+  instancesForDocument: (
+    args: InstancesForDocumentArgs,
+  ) => Promise<WorkflowInstance[]>;
   /** 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>;
-  }) => Promise<T>;
+  query: <T = unknown>(args: QueryArgs) => Promise<T>;
   /** Snapshot-aware GROQ — runs against the same in-memory view the
-   *  engine's filters see for the supplied instance. The rendered scope
-   *  (`$self`, `$fields`, `$parent`, `$ancestors`, `$stage`, `$now`,
-   *  `$effects`, `$activities`, `$allActivitiesDone`, `$anyActivityFailed`) is bound,
-   *  ids in GDR URI form to match the snapshot's keying. */
-  queryInScope: <T = unknown>(args: {
-    instanceId: string;
-    groq: string;
-    params?: Record<string, unknown>;
-  }) => Promise<T>;
+   *  engine's filters see for the supplied instance. The rendered scope's
+   *  instance-derived vars ({@link FILTER_SCOPE_VARS}) are bound, ids in
+   *  GDR URI form to match the snapshot's keying. */
+  queryInScope: <T = unknown>(args: QueryInScopeArgs) => Promise<T>;
   /** List every pending effect on an instance. */
-  listPendingEffects: (args: {
-    instanceId: string;
-  }) => Promise<PendingEffect[]>;
+  listPendingEffects: (args: InstanceRefArgs) => Promise<PendingEffect[]>;
   /** Filter pending effects by claimed status and/or effect names. */
-  findPendingEffects: (args: {
-    instanceId: string;
-    claimed?: boolean;
-    names?: string[];
-  }) => Promise<PendingEffect[]>;
+  findPendingEffects: (
+    args: FindPendingEffectsArgs,
+  ) => Promise<PendingEffect[]>;
   /** Dispatch unclaimed effects through registered handlers. The
    *  drainer's identity defaults to a `{ kind: "system", id: "engine.drainEffects" }`
    *  actor; pass `access` to override (e.g. impersonate a real user
    *  whose grants you want the dispatch to respect). */
-  drainEffects: (args: {
-    instanceId: string;
-    access?: WorkflowAccessOverride;
-  }) => Promise<DrainEffectsResult>;
+  drainEffects: (args: DrainEffectsArgs) => Promise<DrainEffectsResult>;
   /**
    * Inspect every deployed definition in the engine's tag and apply
    * the configured missingHandler policy at `phase: "deploy"` for any
@@ -2096,18 +2565,43 @@ export declare interface Engine {
   verifyDeployedDefinitions: () => Promise<VerifyDeployedDefinitionsResult>;
 }
 
+/**
+ * The API surface the engine's reads and writes assume. Every client bound to
+ * the engine pins this one version so they cannot drift apart.
+ */
+export declare const ENGINE_API_VERSION = "2026-04-29";
+
 export declare interface EngineLogger {
   info: (message: string, extra?: Record<string, unknown>) => void;
   warn: (message: string, extra?: Record<string, unknown>) => void;
   error: (message: string, extra?: Record<string, unknown>) => void;
 }
 
-export declare interface EvaluateArgs {
+/**
+ * The engine-scope bindings pinned once by `createEngine` and carried
+ * explicitly on every raw `workflow.*` call. `Engine` methods never take
+ * these — they were supplied at construction.
+ */
+export declare interface EngineScopeArgs {
   client: WorkflowClient;
-  /** Engine-scope environment partition — required. */
+  /** Engine-scope environment partition — required. See {@link validateTag} + `tags.ts`. */
   tag: string;
-  /** Engine workflow resource — required. */
+  /**
+   * The Sanity resource the engine's own data lives in. Used to mint
+   * GDR URIs for every doc the engine writes (definitions, instances,
+   * ancestor refs). Mirrors `@sanity/client`'s `ClientConfigResource`.
+   */
   workflowResource: WorkflowResource;
+  /**
+   * Optional routing for cross-resource reads (subject + ancestor docs that
+   * live in a different Sanity resource than the workflow). Called with a
+   * parsed GDR; return a client for that resource, or undefined to fall back
+   * to `client`. Engine-scope configuration — see `CreateEngineArgs`.
+   */
+  resourceClients?: ResourceClientResolver;
+}
+
+export declare interface EvaluateArgs {
   instanceId: string;
   /**
    * Optional access-state override. By default the engine resolves
@@ -2131,16 +2625,6 @@ export declare interface EvaluateArgs {
    * call would mean a network round-trip on every fireAction.
    */
   grantsFromPath?: string;
-  /**
-   * Optional resource-aware client routing — see
-   * `StartInstanceArgs.resourceClients`. When the workflow's subject
-   * (or any ancestor) lives in a different resource than the engine's
-   * client, this resolver decides which client to read it through.
-   * The evaluation hydrates a GDR-keyed snapshot from those reads and
-   * runs `_id`-scoped conditions locally in groq-js — same model as the
-   * cascade path.
-   */
-  resourceClients?: (parsed: ParsedGdr) => WorkflowClient | undefined;
 }
 
 /**
@@ -2148,8 +2632,8 @@ export declare interface EvaluateArgs {
  * instance, its definition, the resolved actor/grants, and a snapshot,
  * compute "what can this actor do right now, and why not the rest." No
  * I/O — feed it a fresh snapshot (e.g. rebuilt from a live store on
- * change) for reactive re-evaluation. Best-effort by design: the lake's
- * mutation guards + ACL are the real enforcement.
+ * change) for reactive re-evaluation. Best-effort by design: verdicts are
+ * advisory, not enforcement.
  */
 export declare function evaluateFromSnapshot(
   args: EvaluateFromSnapshotArgs,
@@ -2179,19 +2663,16 @@ export declare interface EvaluateFromSnapshotArgs {
    */
   now?: string;
   /**
-   * Live lake mutation guards held for this instance (a reactive adapter's
+   * Live mutation guards held for this instance (a reactive adapter's
    * guard stream). Every action commit is an `update` write to the instance
    * doc, so a guard that matches the instance and denies that write disables
-   * every action with `mutation-guard-denied`. Omit to skip the gate — the
-   * lake still enforces at commit time.
+   * every action with `mutation-guard-denied`. Omit to skip the gate in this
+   * projection — the engine's verb paths load live guards and re-check at
+   * commit time ({@link evaluateInstance} fetches them itself).
    */
   guards?: readonly MutationGuardDoc[];
 }
 
-declare function evaluateInstance(
-  args: Clocked<EvaluateArgs>,
-): Promise<WorkflowEvaluation>;
-
 /**
  * Evaluate a guard predicate against a mutation. Returns `true` only when the
  * predicate is strictly `true` (ALLOW). Empty predicate denies. Fail-closed:
@@ -2227,13 +2708,11 @@ declare function fetchGrants(args: {
   signal?: AbortSignal;
 }): Promise<Grant[]>;
 
-declare const FIELD_SCOPES: readonly ["workflow", "stage", "activity"];
-
 /**
  * Field-entry `_type` discriminators. The entry's kind defines what
  * shape `value` takes (single GDR vs array, scalar vs notes log).
  */
-export declare const FIELD_SLOT_DISPLAY: {
+export declare const FIELD_KIND_DISPLAY: {
   "doc.ref": {
     title: string;
     description: string;
@@ -2296,6 +2775,8 @@ export declare const FIELD_SLOT_DISPLAY: {
   };
 };
 
+declare const FIELD_SCOPES: readonly ["workflow", "stage", "activity"];
+
 /**
  * The kinds a VALUE can take — scalars aligned to Sanity's names, the
  * reference kinds, the actor/assignee identities, and the two compositional
@@ -2320,11 +2801,21 @@ declare const FIELD_VALUE_KINDS: readonly [
   "array",
 ];
 
+/** Type-mirror of {@link fieldBase}, parameterised over the `editable` grammar. */
+declare type FieldBase<TEditable> = {
+  name: string;
+  title?: string | undefined;
+  description?: string | undefined;
+  required?: boolean | undefined;
+  initialValue?: FieldSource | undefined;
+  editable?: TEditable | undefined;
+};
+
 export declare type FieldEntry = FieldEntryFields<Editable>;
 
 /** Type-mirror of {@link fieldEntryFields}: a raw field entry of the given
  *  editability grammar. */
-declare type FieldEntryFields<TEditable> = SlotFields<TEditable> & {
+declare type FieldEntryFields<TEditable> = FieldBase<TEditable> & {
   type: FieldValueKind;
   fields?: FieldShape[] | undefined;
   of?: FieldShape[] | undefined;
@@ -2392,6 +2883,31 @@ export declare interface FieldValueMap {
   array: Record<string, unknown>[];
 }
 
+export declare class FieldValueShapeError extends WorkflowError<"field-value-shape"> {
+  readonly entryType: string;
+  readonly entryName: string;
+  readonly issues: string[];
+  constructor(args: {
+    entryType: string;
+    entryName: string;
+    issues: string[];
+    mode: "value" | "item";
+  });
+}
+
+/**
+ * The subset that holds a value when the engine evaluates filters without a
+ * caller (the cascade path: transition filters, `completeWhen`/`failWhen`).
+ */
+export declare const FILTER_SCOPE_VARS: readonly string[];
+
+export declare interface FindPendingEffectsArgs extends InstanceRefArgs {
+  /** Filter on claim presence. */
+  claimed?: boolean;
+  /** Restrict to specific effect names. */
+  names?: string[];
+}
+
 export declare interface FireActionArgs extends OperationArgs {
   activity: string;
   action: string;
@@ -2407,7 +2923,7 @@ export declare interface FireActionArgs extends OperationArgs {
    * the current stage's `activityStatus` — typically because the workflow
    * has already advanced past it. Useful for drive scripts and
    * at-least-once delivery semantics: the second call returns the
-   * unchanged instance with `fired: false` rather than blowing up.
+   * unchanged instance with `changed: false` rather than blowing up.
    */
   idempotent?: boolean;
 }
@@ -2518,8 +3034,15 @@ export declare type Guard = v.InferOutput<typeof GuardSchema>;
 /**
  * The lake document type for a mutation guard. Single source of truth — both
  * the runtime value (id construction, `compileGuard`, queries) and the
- * {@link MutationGuardDoc} `_type` literal derive from here, so the `temp.`
- * POC prefix drops in exactly one place at cutover.
+ * {@link MutationGuardDoc} `_type` literal derive from here.
+ *
+ * The enforcement story hangs off this type: the lake does not evaluate
+ * this doc type — it is the engine's placeholder for the lake's
+ * forthcoming guard primitive (the lake reserves `system.*`). Until that
+ * primitive ships, deployed guards deny OPTIMISTICALLY engine-side only, on
+ * every project plan, and the lake ACL is the only hard gate. At cutover the
+ * `temp.` prefix drops here, in exactly one place, and deployed guards become
+ * lake-enforced (a breaking type change for already-persisted guard docs).
  */
 export declare const GUARD_DOC_TYPE = "temp.system.guard";
 
@@ -2528,6 +3051,18 @@ export declare const GUARD_LIFTED_PREDICATE = "true";
 
 export declare const GUARD_OWNER = "robot:workflow-engine";
 
+/**
+ * The identifiers a lake mutation guard's `predicate` reads — the wire
+ * dialect, not the condition scope (so no {@link ConditionVarBinding}: these
+ * bind only when a guard evaluates a mutation). `before()`/`after()`/
+ * `identity()` are groq-js delta-mode natives on top of these. Bound in one
+ * place: `guardPredicateParams` in the guard evaluator.
+ */
+export declare const GUARD_PREDICATE_VARS: readonly {
+  name: string;
+  description: string;
+}[];
+
 export declare type GuardAction = v.InferOutput<typeof GuardActionSchema>;
 
 declare const GuardActionSchema: v.PicklistSchema<
@@ -2535,7 +3070,7 @@ declare const GuardActionSchema: v.PicklistSchema<
   `Invalid option: expected one of ${string}`
 >;
 
-export declare type GuardMatch = v.InferOutput<typeof GuardMatchSchema>;
+export declare type GuardMatch = Guard["match"];
 
 /**
  * Does this guard's `match` apply to a mutation on the given document?
@@ -2554,84 +3089,102 @@ export declare function guardMatches({
   action: MutationGuardAction;
 }): boolean;
 
-declare const GuardMatchSchema: v.StrictObjectSchema<
-  {
-    /** Subject `_type`(s); empty matches any type. */
-    readonly types: v.OptionalSchema<
-      v.ArraySchema<
-        v.SchemaWithPipe<
-          readonly [
-            v.StringSchema<undefined>,
-            v.MinLengthAction<string, 1, "must be a non-empty string">,
-          ]
-        >,
-        undefined
-      >,
+export declare type GuardRead = v.InferOutput<typeof GuardReadSchema>;
+
+declare const GuardReadSchema: v.VariantSchema<
+  "type",
+  [
+    v.StrictObjectSchema<
+      {
+        readonly type: v.LiteralSchema<"self", undefined>;
+      },
       undefined
-    >;
-    /** Target docs as `$fields` reads (or `"$self"`), resolved at deploy to bare ids + the resource. */
-    readonly idRefs: v.OptionalSchema<
-      v.ArraySchema<
-        v.SchemaWithPipe<
-          readonly [
-            v.StringSchema<undefined>,
-            v.MinLengthAction<string, 1, "must be a non-empty string">,
-          ]
-        >,
-        undefined
-      >,
+    >,
+    v.StrictObjectSchema<
+      {
+        readonly type: v.LiteralSchema<"now", undefined>;
+      },
+      undefined
+    >,
+    v.StrictObjectSchema<
+      {
+        readonly type: v.LiteralSchema<"fieldRead", undefined>;
+        readonly field: v.SchemaWithPipe<
+          readonly [v.StringSchema<undefined>, v.RegexAction<string, string>]
+        >;
+        readonly path: v.OptionalSchema<
+          v.SchemaWithPipe<
+            readonly [
+              v.SchemaWithPipe<
+                readonly [
+                  v.StringSchema<undefined>,
+                  v.MinLengthAction<string, 1, "must be a non-empty string">,
+                ]
+              >,
+              v.CheckAction<
+                string,
+                "a guard read path cannot contain a line break"
+              >,
+            ]
+          >,
+          undefined
+        >;
+      },
       undefined
-    >;
-    /** Glob id patterns (bare, resource-local). */
-    readonly idPatterns: v.OptionalSchema<
-      v.ArraySchema<
-        v.SchemaWithPipe<
+    >,
+    v.StrictObjectSchema<
+      {
+        readonly type: v.LiteralSchema<"effectsRead", undefined>;
+        readonly effect: 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">,
+              ]
+            >,
+            v.CheckAction<string, "an effect name cannot contain `'`">,
           ]
-        >,
-        undefined
-      >,
-      undefined
-    >;
-    readonly actions: v.SchemaWithPipe<
-      readonly [
-        v.ArraySchema<
-          v.PicklistSchema<
-            readonly ["create", "update", "delete", "publish", "unpublish"],
-            `Invalid option: expected one of ${string}`
+        >;
+        readonly path: v.OptionalSchema<
+          v.SchemaWithPipe<
+            readonly [
+              v.SchemaWithPipe<
+                readonly [
+                  v.StringSchema<undefined>,
+                  v.MinLengthAction<string, 1, "must be a non-empty string">,
+                ]
+              >,
+              v.CheckAction<
+                string,
+                "a guard read path cannot contain a line break"
+              >,
+            ]
           >,
           undefined
-        >,
-        v.MinLengthAction<
-          ("create" | "update" | "delete" | "publish" | "unpublish")[],
-          1,
-          "a guard must match at least one action"
-        >,
-      ]
-    >;
-  },
+        >;
+      },
+      undefined
+    >,
+  ],
   undefined
 >;
 
+/** Stored guards carry the printed string reads (the deploy resolver's input). */
 declare const GuardSchema: v.StrictObjectSchema<
   {
-    readonly name: v.SchemaWithPipe<
+    name: v.SchemaWithPipe<
       readonly [
         v.StringSchema<undefined>,
         v.MinLengthAction<string, 1, "must be a non-empty string">,
       ]
     >;
-    readonly title: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
-    readonly description: v.OptionalSchema<
-      v.StringSchema<undefined>,
-      undefined
-    >;
-    readonly match: v.StrictObjectSchema<
+    title: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    description: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    match: v.StrictObjectSchema<
       {
         /** Subject `_type`(s); empty matches any type. */
-        readonly types: v.OptionalSchema<
+        types: v.OptionalSchema<
           v.ArraySchema<
             v.SchemaWithPipe<
               readonly [
@@ -2643,8 +3196,8 @@ declare const GuardSchema: v.StrictObjectSchema<
           >,
           undefined
         >;
-        /** Target docs as `$fields` reads (or `"$self"`), resolved at deploy to bare ids + the resource. */
-        readonly idRefs: v.OptionalSchema<
+        /** Target docs as field reads (or the instance itself), resolved at deploy to bare ids + the resource. */
+        idRefs: v.OptionalSchema<
           v.ArraySchema<
             v.SchemaWithPipe<
               readonly [
@@ -2657,7 +3210,7 @@ declare const GuardSchema: v.StrictObjectSchema<
           undefined
         >;
         /** Glob id patterns (bare, resource-local). */
-        readonly idPatterns: v.OptionalSchema<
+        idPatterns: v.OptionalSchema<
           v.ArraySchema<
             v.SchemaWithPipe<
               readonly [
@@ -2669,7 +3222,7 @@ declare const GuardSchema: v.StrictObjectSchema<
           >,
           undefined
         >;
-        readonly actions: v.SchemaWithPipe<
+        actions: v.SchemaWithPipe<
           readonly [
             v.ArraySchema<
               v.PicklistSchema<
@@ -2694,16 +3247,16 @@ declare const GuardSchema: v.StrictObjectSchema<
      * `identity()`. Bare ids/fields only. Omitted or empty means
      * UNCONDITIONAL DENY.
      */
-    readonly predicate: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    predicate: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
     /**
      * Projected workflow fields the predicate reads as `guard.metadata.*` —
      * the only bridge from the lake eval context (which cannot see `$fields`)
-     * to workflow fields. Values are NOT GROQ: each is a deploy-time read in
-     * the guard mini-language — `"$self"`, `"$now"`, or
-     * `"$fields.<name>[.path]"` — resolved into a bare value at deploy and
-     * re-synced by the post-field-op guard refresh.
+     * to workflow fields. Each value is a deploy-time read — a typed
+     * {@link GuardRead} when authoring, the printed string spelling once
+     * stored — resolved into a bare value at deploy and re-synced by the
+     * post-field-op guard refresh.
      */
-    readonly metadata: v.OptionalSchema<
+    metadata: v.OptionalSchema<
       v.RecordSchema<
         v.SchemaWithPipe<
           readonly [
@@ -2730,7 +3283,7 @@ declare const GuardSchema: v.StrictObjectSchema<
  * its guards statically name — no live instance required. Guard docs are
  * stamped with the version-less definition, so this spans the datasources
  * declared across ALL deployed versions
- * ({@link GuardsForDefinitionArgs.definitions}), not just the latest.
+ * ({@link DefinitionGuardsQueryArgs.definitions}), not just the latest.
  *
  * A datasource is statically reachable when a guard idRef resolves to a
  * hardcoded GDR literal — directly, or via a `fieldRead` of a field entry whose
@@ -2741,16 +3294,12 @@ declare const GuardSchema: v.StrictObjectSchema<
  * {@link guardsForInstance}. Dedups resources by key, results by `_id`.
  */
 export declare function guardsForDefinition(
-  args: GuardsForDefinitionArgs,
+  args: DefinitionGuardsQueryArgs,
 ): Promise<MutationGuardDoc[]>;
 
-declare interface GuardsForDefinitionArgs {
-  client: WorkflowClient;
-  clientForGdr: (parsed: ParsedGdr) => WorkflowClient;
-  workflowResource: WorkflowResource;
+export declare interface GuardsForDefinitionArgs {
+  /** The definition's `name`. */
   definition: string;
-  /** Every deployed version of {@link GuardsForDefinitionArgs.definition}. */
-  definitions: WorkflowDefinition[];
 }
 
 /**
@@ -2761,15 +3310,9 @@ declare interface GuardsForDefinitionArgs {
  * boundary.
  */
 export declare function guardsForInstance(
-  args: GuardsForInstanceArgs,
+  args: InstanceGuardsQueryArgs,
 ): Promise<MutationGuardDoc[]>;
 
-declare interface GuardsForInstanceArgs {
-  client: WorkflowClient;
-  clientForGdr: (parsed: ParsedGdr) => WorkflowClient;
-  instance: WorkflowInstance;
-}
-
 /** Every guard in one resource, regardless of which workflow registered it. */
 export declare function guardsForResource(
   client: WorkflowClient,
@@ -2963,8 +3506,8 @@ export declare type HistoryEntry =
       stage: StageName;
       /** The boundary that ran the op. For an action/transition/activation,
        *  exactly one of activity/action/transition is set; for a direct edit
-       *  (the edit seam), `edit` is set and `activity` carries the slot's activity when
-       *  the edited slot is activity-scope; for an effect's completion ops,
+       *  (the edit seam), `edit` is set and `activity` carries the field's activity when
+       *  the edited field is activity-scope; for an effect's completion ops,
        *  `effect` names the effect. */
       activity?: ActivityName;
       action?: ActionName;
@@ -3038,18 +3581,38 @@ export declare type InitialFieldValue = {
  * datasources for housekeeping. Matches lifted guards too (predicate
  * `"true"`) — the consumer decides how to render a lifted guard.
  */
-export declare function instanceGuardQuery(instanceId: string): {
-  query: string;
-  params: Record<string, string>;
-};
+export declare function instanceGuardQuery(instanceId: string): CompiledQuery;
+
+declare interface InstanceGuardsQueryArgs {
+  client: WorkflowClient;
+  clientForGdr: (parsed: ParsedGdr) => WorkflowClient;
+  instance: WorkflowInstance;
+}
+
+/**
+ * The instance id does not resolve to a workflow instance this engine can
+ * see — the document is missing, or it belongs to another engine's tag
+ * partition. Both arms share this class and kind (an invisible instance is
+ * not-found to this caller); the message says which arm it was.
+ */
+export declare class InstanceNotFoundError extends WorkflowError<"instance-not-found"> {
+  readonly instanceId: string;
+  constructor(args: { instanceId: string; detail?: string });
+}
+
+/** Args for the verbs that address an instance without further input. */
+export declare interface InstanceRefArgs {
+  instanceId: string;
+}
 
 export declare interface InstanceSession {
   /** The watch-set to feed via {@link InstanceSession.update}, derived from the
    *  held instance. Recompute after the instance changes (a new stage changes it). */
   readonly subscriptionDocuments: WatchSet;
   /** Replace the held content with the current values the consumer observed
-   *  (last-write-wins, scoped). A doc whose id is the instance itself updates
-   *  the held instance. Buffered if a commit is in flight. */
+   *  (last-write-wins, scoped). A self-doc updates the held instance only when
+   *  its `_updatedAt` is strictly newer — an older or timestamp-equal echo is
+   *  ignored. Buffered if a commit is in flight. */
   update(docs: LoadedDoc[]): void;
   /** Replace the held live guards (the consumer's guard stream,
    *  last-write-wins). Guards are a separate stream from the watch-set:
@@ -3064,20 +3627,55 @@ export declare interface InstanceSession {
   evaluate(): Promise<WorkflowEvaluation>;
   /** Advance the instance against the held content: cascade auto-transitions,
    *  deploy guards, queue effects, commit with `ifRevisionId`. */
-  tick(): Promise<DispatchResult>;
+  tick(): Promise<OperationResult>;
   /** Fire an action against an activity, gated on the held content, then cascade. */
   fireAction(args: {
     activity: string;
     action: string;
     params?: Record<string, unknown>;
-  }): Promise<DispatchResult>;
-  /** Edit a declared-editable slot against the held content (the generic edit
+  }): Promise<OperationResult>;
+  /** Edit a declared-editable field against the held content (the generic edit
    *  seam), gated on the held projection, then cascade. */
   editField(args: {
     target: EditFieldTarget;
     mode?: EditMode;
     value?: unknown;
-  }): Promise<DispatchResult>;
+  }): Promise<OperationResult>;
+}
+
+export declare interface InstancesForDocumentArgs {
+  /** A resource-qualified GDR URI; a bare id is rejected. */
+  document: GdrUri;
+}
+
+/**
+ * The instance-list GROQ for a {@link InstancesQueryFilter}, ordered by
+ * `startedAt` ascending. Adapters subscribe to it; {@link workflow.query}
+ * -style one-shot reads fetch it — both see the same rows.
+ */
+export declare function instancesQuery(args: {
+  tag: string;
+  filter?: InstancesQueryFilter;
+}): CompiledQuery;
+
+/**
+ * Narrows an instance-list read. All conditions AND together; an empty
+ * filter means "every in-flight instance in the engine's resource".
+ */
+export declare interface InstancesQueryFilter {
+  /**
+   * Only instances that may reference this document (resource-qualified GDR
+   * URI). This is a lake-side PREFILTER — a deliberate superset that also
+   * matches exited-stage refs; narrow the fetched rows to the exact reactive
+   * watch-set with {@link instanceWatchesDocument}.
+   */
+  document?: GdrUri;
+  /** Version-less definition `name` the instances were started from. */
+  definition?: string;
+  /** Current stage name. */
+  stage?: string;
+  /** Include completed/aborted instances (default: in-flight only). */
+  includeCompleted?: boolean;
 }
 
 /**
@@ -3100,16 +3698,26 @@ export declare function instanceWatchesDocument(
 /** Type filter for GDR shape. */
 export declare function isGdr(value: unknown): value is GlobalDocumentReference;
 
+/**
+ * Whether a guard has been lifted (retracted to the unconditional-allow
+ * predicate). A lift patches the predicate and keeps the doc, so lifted
+ * guards still appear in guard queries and streams — this is the
+ * discriminator a consumer filters or renders by.
+ */
+export declare function isGuardLifted(
+  guard: Pick<MutationGuardDoc, "predicate">,
+): boolean;
+
 /**
  * Whether a human may start this definition standalone (the default). A
- * `role: 'child'` definition is spawn-only — instantiated by a parent via
+ * `lifecycle: 'child'` definition is spawn-only — instantiated by a parent via
  * `activity.subworkflows`, so consumers exclude it from top-level start pickers.
  * Advisory: the engine does not enforce it (see the `required`-field backstop
- * for load-bearing input slots). Accepts any definition-shaped value (authored,
+ * for load-bearing input fields). Accepts any definition-shaped value (authored,
  * stored, deployed, or a projected list row).
  */
 export declare function isStartableDefinition(definition: {
-  role?: WorkflowRole | undefined;
+  lifecycle?: WorkflowLifecycle | undefined;
 }): boolean;
 
 /**
@@ -3182,6 +3790,17 @@ export declare interface MissingHandlerDrainInfo {
   instanceId: string;
 }
 
+/**
+ * The `missingHandler: 'fail'` policy tripped: an effect names a handler the
+ * runtime never registered. `info` carries the phase-specific location
+ * (deploy verification vs a drain attempt) so the runtime that opted into
+ * failing can report exactly which handler is missing where.
+ */
+export declare class MissingHandlerError extends WorkflowError<"missing-effect-handler"> {
+  readonly info: MissingHandlerInfo;
+  constructor(args: { info: MissingHandlerInfo });
+}
+
 export declare type MissingHandlerInfo =
   | MissingHandlerDeployInfo
   | MissingHandlerDrainInfo;
@@ -3218,7 +3837,11 @@ export declare interface MutationContext {
       } & Record<string, unknown>)
     | null;
   action: MutationGuardAction;
-  /** Authenticated caller id, resolved as `identity()` in the predicate. */
+  /**
+   * Caller-asserted actor id, resolved as `identity()` in the predicate.
+   * Advisory — the engine takes the caller's word for who is acting; only
+   * the lake's own token identity is authenticated.
+   */
   identity?: string;
 }
 
@@ -3234,7 +3857,14 @@ export declare interface MutationGuardBody {
   /** Engine-layer: the single datasource this guard belongs to. */
   resourceType: string;
   resourceId: string;
-  /** Registering identity — the engine robot. Only owner/admin may modify. */
+  /**
+   * Provenance stamp — who registered the guard (the engine writes its own
+   * marker here). Unenforced: nothing reads `owner`, and there is no
+   * owner/admin modification rule — guard deploy/refresh/retract ride the
+   * caller's token like every other engine write. A lake-enforced guard can
+   * therefore lock the engine's own housekeeping out (self-lockout) until a
+   * dedicated engine execution identity exists.
+   */
   owner: string;
   /**
    * Provenance — the workflow that registered this guard. The lake's own guard
@@ -3254,30 +3884,36 @@ export declare interface MutationGuardBody {
   metadata: Record<string, unknown>;
 }
 
+/** The `mutation-guard-denied` verdict arm, shared verbatim by
+ *  {@link DisabledReason} and {@link EditDisabledReason}. */
+export declare type MutationGuardDenial = Extract<
+  DisabledReason,
+  {
+    kind: "mutation-guard-denied";
+  }
+>;
+
 /**
- * Thrown when one or more guards deny a mutation. POC: raised by the engine /
- * bench enforcement layer; carries every denial. Fail-closed: a predicate that
- * errors or is non-true denies.
+ * Thrown when one or more guards deny a mutation — raised by the engine's
+ * optimistic pre-flight and the bench's write seam; carries every denial.
+ * Fail-closed: a predicate that errors or is non-true denies.
+ *
+ * The ONE guard-denial error: every verb whose write a guard denies —
+ * `fireAction`, `editField`, `tick`, a session tick, a bench write — throws
+ * this class, never a verb-specific wrapper.
  */
-export declare class MutationGuardDeniedError extends Error {
-  readonly denied: Array<{
-    guardId: string;
-    name?: string;
-  }>;
+export declare class MutationGuardDeniedError extends WorkflowError<"mutation-guard-denied"> {
+  readonly denied: DeniedGuardRef[];
   readonly documentId: string;
   readonly action: MutationGuardAction;
   constructor(args: {
     documentId: string;
     action: MutationGuardAction;
-    denied: Array<{
-      guardId: string;
-      name?: string;
-    }>;
+    denied: DeniedGuardRef[];
   });
   /**
-   * Build the error straight from the denying guard docs — the one mapping
-   * from {@link MutationGuardDoc} to the structured `denied` payload, shared
-   * by every enforcement site (engine pre-flight, bench write seam).
+   * Build the error straight from the denying guard docs, shared by every
+   * enforcement site (engine pre-flight, bench write seam).
    */
   static fromGuards(args: {
     documentId: string;
@@ -3307,7 +3943,7 @@ export declare interface MutationGuardMatch {
  * { body, actor, at }` (the `actor`/`at` sub-fields match the `audit` op's
  * stamp names, so it pairs with it). Never a stored kind.
  */
-declare type NotesField = SlotFields<AuthoringEditable> & {
+declare type NotesField = FieldBase<AuthoringEditable> & {
   type: "notes";
 };
 
@@ -3353,13 +3989,6 @@ export declare interface OpAppliedSummary {
 }
 
 export declare interface OperationArgs {
-  client: WorkflowClient;
-  /** 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`. */
-  resourceClients?: ResourceClientResolver;
   instanceId: string;
   /**
    * Optional access-state override. See `StartInstanceArgs.access`
@@ -3373,22 +4002,30 @@ export declare interface OperationArgs {
   idempotencyKey?: string;
 }
 
-export declare type OpPredicate = OpPredicateInternal;
-
-declare type OpPredicateInternal =
-  | {
-      type: "field";
-      field: string;
-      equals: ValueExpr;
-    }
-  | {
-      type: "all";
-      of: OpPredicateInternal[];
-    }
-  | {
-      type: "any";
-      of: OpPredicateInternal[];
-    };
+/**
+ * What a state-changing verb reports back. Every mutating verb —
+ * `startInstance`, `fireAction`, `editField`, `completeEffect`, `tick`,
+ * `setStage`, `abortInstance` — returns this one shape, on the namespace,
+ * the `Engine`, and the reactive session alike.
+ */
+export declare interface OperationResult {
+  /** The instance after the operation + all cascading auto-transitions. */
+  instance: WorkflowInstance;
+  /** Number of auto-transitions that fired during the cascade. */
+  cascaded: number;
+  /**
+   * Whether this call changed the instance's workflow state. `false` means
+   * the call succeeded but was a no-op: an idempotent re-fire of an already
+   * resolved activity, a `tick` that wrote nothing, a `setStage` already at
+   * the target, an abort of an already-terminal instance. Failures throw —
+   * `changed: false` never signals an error.
+   */
+  changed: boolean;
+  /** Engine primitives (`workflow.op.field.*` / `status.set`) that ran
+   *  during the action commit. Surfaced for caller-side assertions and
+   *  audit. */
+  ranOps?: OpAppliedSummary[];
+}
 
 export declare interface ParsedGdr {
   scheme: GdrScheme;
@@ -3416,7 +4053,7 @@ export declare function parseGdr(uri: string): ParsedGdr;
  * 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 {
+export declare class PartialGuardDeployError extends WorkflowError<"partial-guard-deploy"> {
   readonly stageName: string;
   readonly deployed: number;
   constructor(args: { stageName: string; deployed: number; cause: unknown });
@@ -3443,6 +4080,14 @@ export declare interface PendingEffect {
    */
   actor?: Actor;
   queuedAt: string;
+  /**
+   * `_key` of the stage entry this effect was queued under — for a
+   * transition's effects, the entry being entered. Carried onto the
+   * completion's history row, where it is what ties a run to its stage
+   * entry for the `$effectStatus` read. Absent only on entries persisted
+   * before the engine stamped it.
+   */
+  stageEntryKey?: string;
   /**
    * Presence = a drainer is dispatching this entry. Absence = the entry
    * is unclaimed and eligible for drain. Entries in terminal states
@@ -3467,6 +4112,13 @@ export declare interface PendingEffectClaim {
   claimedBy: Actor;
 }
 
+export declare interface QueryArgs {
+  groq: string;
+  params?: Record<string, unknown>;
+}
+
+export declare interface QueryInScopeArgs extends InstanceRefArgs, QueryArgs {}
+
 /**
  * Whether a watched ref reads RAW — never perspective-scoped. The
  * instance, its ancestors (both instance docs), and `release.ref`
@@ -3554,11 +4206,11 @@ export declare type RemediationVerb =
 /**
  * Thrown when a workflow is started (or a child spawned) without a value for
  * a field entry marked `required`. Mirrors {@link ActionParamsInvalidError}:
- * the engine has NOT created the instance — a missing load-bearing slot
+ * the engine has NOT created the instance — a missing load-bearing field
  * (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 RequiredFieldNotProvidedError extends Error {
+export declare class RequiredFieldNotProvidedError extends WorkflowError<"required-field-not-provided"> {
   readonly definition?: string;
   readonly missing: {
     name: string;
@@ -3573,6 +4225,14 @@ export declare class RequiredFieldNotProvidedError extends Error {
   });
 }
 
+/**
+ * Names an author's predicate may not use — engine-owned and author names
+ * share one namespace, so a predicate redefining a binding would silently
+ * shadow engine behaviour. Rejected at deploy; derived from
+ * {@link CONDITION_VARS}.
+ */
+export declare const RESERVED_CONDITION_VARS: readonly string[];
+
 /**
  * Resolve the engine's `WorkflowAccess` for a client. Override wins
  * outright; otherwise both halves are fetched in parallel and
@@ -3654,6 +4314,15 @@ export declare type ResolvedFieldEntry = {
  */
 export declare type ResourceAliases = Record<string, WorkflowResource>;
 
+/**
+ * Collapse a deployment's `resourceAliases` bindings into the engine's
+ * {@link ResourceAliases} map (handle name → physical resource) — the shape
+ * {@link deployDefinitions} consumes.
+ */
+export declare function resourceAliasesToMap(
+  resourceAliases: WorkflowDeployment["resourceAliases"],
+): ResourceAliases;
+
 /**
  * Resolver for cross-resource reads. The engine has ONE `client` bound
  * to its own resource (where definition / instance
@@ -3665,7 +4334,7 @@ export declare type ResourceAliases = Record<string, WorkflowResource>;
  * The resolver receives the parsed pieces, not the raw URI, so it can
  * pattern-match on scheme + resource id without re-parsing.
  */
-declare type ResourceClientResolver = (
+export declare type ResourceClientResolver = (
   parsed: ParsedGdr,
 ) => WorkflowClient | undefined;
 
@@ -3691,7 +4360,7 @@ declare interface ResourceRefArgs {
  * on it: an aborted instance keeps its `currentStage` (no stage move), so the
  * `abortedAt` stamp is what licenses lifting the stage it still occupies. The
  * gate is `abortedAt`, not `completedAt` — normal completion parks the
- * instance on a structurally terminal stage whose guards must stay enforced.
+ * instance on a structurally terminal stage whose guards must stay live.
  * Skip if it is still live on the stage (a concurrent loop-back re-entered
  * the stage and must keep its lock) or gone (leave the lock as the orphan
  * seam rather than silently unlocking a vanished instance — the same
@@ -3756,6 +4425,15 @@ declare const RoleAliasesSchema: v.RecordSchema<
   undefined
 >;
 
+export declare interface SessionArgs {
+  /** The instance document to bind — typically the consumer's live-store value. */
+  instance: WorkflowInstance;
+  /** Optional access-state override — see `StartInstanceArgs.access`. */
+  access?: WorkflowAccessOverride | undefined;
+  /** URL path for grant resolution — see `StartInstanceArgs.grantsFromPath`. */
+  grantsFromPath?: string | undefined;
+}
+
 export declare interface SetStageArgs extends OperationArgs {
   /** Stage id to force the instance into. */
   targetStage: string;
@@ -3774,20 +4452,11 @@ export declare interface SetStageArgs extends OperationArgs {
  */
 export declare const silentLogger: EngineLogger;
 
-/** Type-mirror of {@link slotFields}, parameterised over the `editable` grammar. */
-declare type SlotFields<TEditable> = {
-  name: string;
-  title?: string | undefined;
-  description?: string | undefined;
-  required?: boolean | undefined;
-  initialValue?: FieldSource | undefined;
-  editable?: TEditable | undefined;
-};
-
 export declare type Stage = StageFields<
   FieldEntry,
   Activity,
   Transition,
+  Guard,
   Editable
 >;
 
@@ -3808,14 +4477,14 @@ export declare interface StageEvaluation {
   transitions: TransitionEvaluation[];
 }
 
-/** Type-mirror of {@link stageFields}, parameterised over field/activity/transition/editable. */
-declare type StageFields<TField, TActivity, TTransition, TEditable> = {
+/** Type-mirror of {@link stageFields}, parameterised over field/activity/transition/guard/editable. */
+declare type StageFields<TField, TActivity, TTransition, TGuard, TEditable> = {
   name: string;
   title?: string | undefined;
   description?: string | undefined;
   activities?: TActivity[] | undefined;
   transitions?: TTransition[] | undefined;
-  guards?: Guard[] | undefined;
+  guards?: TGuard[] | undefined;
   fields?: TField[] | undefined;
   editable?: Record<string, TEditable> | undefined;
 };
@@ -3833,18 +4502,6 @@ declare interface StageGuardArgs {
 export declare type StageName = string;
 
 export declare interface StartInstanceArgs {
-  client: WorkflowClient;
-  /** Engine-scope environment partition — required. */
-  tag: string;
-  /** The Sanity resource the engine's own data lives in. */
-  workflowResource: WorkflowResource;
-  /**
-   * Optional routing for cross-resource reads (subject + ancestor
-   * docs that live in a different Sanity resource than the workflow).
-   * Called with a parsed GDR; return a client for that resource, or
-   * undefined to fall back to `client`. See `CreateEngineArgs`.
-   */
-  resourceClients?: ResourceClientResolver;
   /** The definition's `name` — which deployed workflow to instantiate. */
   definition: string;
   /** Optional explicit version. Defaults to the highest deployed version. */
@@ -3892,10 +4549,11 @@ export declare interface StartInstanceArgs {
   access?: WorkflowAccessOverride;
   /**
    * URL path on the supplied client where the engine fetches the
-   * actor's ACL grants when `access.grants` isn't supplied. Required
-   * for the permission gate in production; omitting it means the
-   * gate is skipped (graceful degradation; the real Sanity write
-   * boundary still enforces).
+   * actor's ACL grants when `access.grants` isn't supplied. Grants
+   * feed the advisory `$can.*` params action conditions can read;
+   * omitting this leaves the rendered `$can` undefined (conditions
+   * referencing it fail closed, nothing else is gated engine-side —
+   * the real Sanity write boundary still enforces).
    *
    * Canvas-style: `/canvases/<resourceId>/acl`.
    * Project/dataset: `/projects/<id>/datasets/<ds>/acl`.
@@ -3916,13 +4574,13 @@ export declare interface StartInstanceArgs {
 }
 
 /**
- * Declared editability of a field slot — the generic edit seam's gate. Default
- * (absent) is NOT editable: a slot is op-only engine working memory unless the
+ * Declared editability of a field — the generic edit seam's gate. Default
+ * (absent) is NOT editable: a field is op-only engine working memory unless the
  * modeler opens it. The stored form is `true` (editable by anyone within the
- * slot's scope window) or a GROQ predicate over the rendered scope (`$actor`,
+ * field's scope window) or an EDIT CONDITION — rendered-scope GROQ (`$actor`,
  * `$can`, `$fields`, `$assigned`), checked like an action filter to decide
  * who-may-edit. ADVISORY like every engine gate — it disables the inline field
- * and explains; real immutability needs a lake {@link Guard}.
+ * and explains; a {@link Guard} declares the intended write-lock.
  */
 declare const StoredEditableSchema: v.UnionSchema<
   [
@@ -4032,7 +4690,12 @@ declare const StoredFieldOpSchema: v.VariantSchema<
           },
           undefined
         >;
-        readonly where: v.GenericSchema<OpPredicateInternal>;
+        readonly where: v.SchemaWithPipe<
+          readonly [
+            v.StringSchema<undefined>,
+            v.MinLengthAction<string, 1, "must be a non-empty string">,
+          ]
+        >;
         readonly value: v.GenericSchema<ValueExprInternal>;
       },
       undefined
@@ -4055,7 +4718,12 @@ declare const StoredFieldOpSchema: v.VariantSchema<
           },
           undefined
         >;
-        readonly where: v.GenericSchema<OpPredicateInternal>;
+        readonly where: v.SchemaWithPipe<
+          readonly [
+            v.StringSchema<undefined>,
+            v.MinLengthAction<string, 1, "must be a non-empty string">,
+          ]
+        >;
       },
       undefined
     >,
@@ -4208,7 +4876,12 @@ declare const StoredOpSchema: v.VariantSchema<
           },
           undefined
         >;
-        readonly where: v.GenericSchema<OpPredicateInternal>;
+        readonly where: v.SchemaWithPipe<
+          readonly [
+            v.StringSchema<undefined>,
+            v.MinLengthAction<string, 1, "must be a non-empty string">,
+          ]
+        >;
         readonly value: v.GenericSchema<ValueExprInternal>;
       },
       undefined
@@ -4231,7 +4904,12 @@ declare const StoredOpSchema: v.VariantSchema<
           },
           undefined
         >;
-        readonly where: v.GenericSchema<OpPredicateInternal>;
+        readonly where: v.SchemaWithPipe<
+          readonly [
+            v.StringSchema<undefined>,
+            v.MinLengthAction<string, 1, "must be a non-empty string">,
+          ]
+        >;
       },
       undefined
     >,
@@ -4441,7 +5119,7 @@ export declare type TerminalActivityStatus =
  * { label, status, assignee?, dueDate? }`; a plain checklist is this used with
  * `{label, status}` only (open ↔ done). Never a stored kind.
  */
-declare type TodoListField = SlotFields<AuthoringEditable> & {
+declare type TodoListField = FieldBase<AuthoringEditable> & {
   type: "todoList";
 };
 
@@ -4541,12 +5219,12 @@ declare type ValueExprInternal =
 
 /**
  * The guards allowed to influence this instance's verdicts, read from the
- * engine's own datasource only. A guard enforces solely within the datasource
+ * engine's own datasource only. A guard applies solely within the datasource
  * it physically lives in, and `resourceType`/`resourceId` are plain document
  * fields any writer in that datasource can set — so a verdict load must be
  * physically scoped: a guard doc in a watched content dataset that
  * self-declares the engine's resource id must never reach a verdict. This
- * keeps the advisory layer consistent (verdicts are UX, the lake enforces);
+ * keeps the advisory layer consistent (verdicts are UX, not enforcement);
  * it is not itself a security boundary. Runs the same query the reactive
  * adapters subscribe with ({@link instanceGuardQuery}), so the stateless and
  * reactive paths agree.
@@ -4605,7 +5283,9 @@ export declare interface WatchSet {
 }
 
 /**
- * The four-method workflow API.
+ * The workflow verbs, bound as one object — write path, admin
+ * overrides, pure reads, and permission helpers. The module doc above
+ * describes the model.
  */
 export declare const workflow: {
   /**
@@ -4627,7 +5307,7 @@ export declare const workflow: {
    * Cycles in the dependency graph error before any write happens.
    */
   deployDefinitions: (
-    args: DeployDefinitionsArgs,
+    args: DeployDefinitionsArgs & EngineScopeArgs,
   ) => Promise<DeployDefinitionsResult>;
   /**
    * Remove a deployed workflow definition (all versions, or one via
@@ -4637,7 +5317,7 @@ export declare const workflow: {
    * full contract (spawn-referrer check, guard-doc housekeeping).
    */
   deleteDefinition: (
-    args: Clocked<DeleteDefinitionArgs>,
+    args: Clocked<DeleteDefinitionArgs & EngineScopeArgs>,
   ) => Promise<DeleteDefinitionResult>;
   /**
    * Spawn a new workflow instance from a deployed definition.
@@ -4645,11 +5325,12 @@ export declare const workflow: {
    * Pins the snapshot at start-time, seeds `effectsContext`, enters
    * the initial stage (which builds activityStatus, queues onEnter
    * effects, auto-activates activities). Then cascades auto-transitions
-   * until stable. Returns the resulting instance.
+   * until stable. Starting always changes state (`changed: true`) —
+   * `cascaded` reports how far the new instance auto-advanced.
    */
   startInstance: (
-    args: Clocked<StartInstanceArgs>,
-  ) => Promise<WorkflowInstance>;
+    args: Clocked<StartInstanceArgs & EngineScopeArgs>,
+  ) => Promise<OperationResult>;
   /**
    * Fire an action against an activity. If the activity is pending, it is
    * auto-invoked first (pending → active) so callers don't have to know
@@ -4660,23 +5341,27 @@ export declare const workflow: {
    * Runtimes fire it in response to webhooks, effect completions, and
    * timer firings. External signals never bypass this.
    */
-  fireAction: (args: Clocked<FireActionArgs>) => Promise<DispatchResult>;
+  fireAction: (
+    args: Clocked<FireActionArgs & EngineScopeArgs>,
+  ) => Promise<OperationResult>;
   /**
-   * Edit a declared-editable field slot directly — reassign, reschedule,
+   * Edit a declared-editable field directly — reassign, reschedule,
    * claim-by-hand, append to a running log — through the generic edit seam,
-   * instead of a bespoke action per field. Soft-gates on the slot's declared
+   * instead of a bespoke action per field. Soft-gates on the field's declared
    * editability (the same projection a UI renders), applies the edit as a
    * `field.*` op (so provenance + history are stamped by the op path),
    * refreshes the stage's guards, then cascades — an edit to a value a
    * transition reads can and should move the instance. Advisory like every
-   * engine gate; the lake ACL + guards are the only hard locks.
+   * engine gate.
    *
    * Each call is a discrete COMMIT (a history entry, a guard refresh, a
    * cascade, an `ifRevisionId` write), not a draft patch — so an inline-field
    * UI must bind it to a deliberate boundary (blur / Enter / Save / debounce),
    * never an `onChange` per keystroke.
    */
-  editField: (args: Clocked<EditFieldArgs>) => Promise<DispatchResult>;
+  editField: (
+    args: Clocked<EditFieldArgs & EngineScopeArgs>,
+  ) => Promise<OperationResult>;
   /**
    * Report a queued effect's outcome. Drains it from `pendingEffects`,
    * appends an `effectHistory` entry, and (if `outputs` are supplied
@@ -4684,11 +5369,13 @@ export declare const workflow: {
    * `effectsContext` by key — so downstream effect bindings can
    * reference them. Any `ops` the handler returned (`field.*`) are
    * validated and applied to the instance in the same commit, through the
-   * same op applier an action's field ops use. Cascades after.
+   * same op applier an action's field ops use. Cascades after. A completion
+   * always changes state (the effect drains + history is appended), so
+   * `changed` is always `true` — a bad `effectKey`/status throws instead.
    */
   completeEffect: (
-    args: Clocked<CompleteEffectArgs>,
-  ) => Promise<DispatchResult>;
+    args: Clocked<CompleteEffectArgs & EngineScopeArgs>,
+  ) => Promise<OperationResult>;
   /**
    * Re-evaluate auto-transitions and resolve due waits until stable.
    *
@@ -4696,48 +5383,50 @@ export declare const workflow: {
    * but isn't itself an activity action: a subject doc was patched, a sibling
    * workflow completed, the clock crossed a `completeWhen` deadline, etc.
    * The runtime doesn't need to know what changed — it just nudges
-   * affected instances and the engine re-evaluates.
+   * affected instances and the engine re-evaluates. `changed` reports
+   * whether the nudge wrote anything: a fired transition, but also a
+   * persisted activity-gate flip (`completeWhen`/`failWhen`) that didn't
+   * unlock a transition yet — so it's derived from the instance's `_rev`,
+   * not from `cascaded` alone.
    */
-  tick: (args: Clocked<OperationArgs>) => Promise<DispatchResult>;
+  tick: (
+    args: Clocked<OperationArgs & EngineScopeArgs>,
+  ) => Promise<OperationResult>;
   /**
    * Admin override — force the instance into `targetStage` regardless
    * of filters or declared transitions. ACL gating should be enforced
-   * upstream; this verb performs the mechanical move.
+   * upstream; this verb performs the mechanical move. `changed: false`
+   * means the move was a no-op (already at the target / terminal).
    */
-  setStage: (args: Clocked<SetStageArgs>) => Promise<DispatchResult>;
+  setStage: (
+    args: Clocked<SetStageArgs & EngineScopeArgs>,
+  ) => Promise<OperationResult>;
   /**
    * Admin override — hard-stop an in-flight instance where it stands.
    * No stage move, no transition effects, pending effects cancelled;
    * see {@link abortAndPropagate} for the abort + ancestor-propagation
-   * contract (propagated, not cascaded — the instance is terminal).
+   * contract (propagated, not cascaded — the instance is terminal, so
+   * `cascaded` is always `0`; ancestor movement is reported on the
+   * ancestors, not here). `changed: false` means the instance was
+   * already terminal.
    */
-  abortInstance: (args: Clocked<AbortInstanceArgs>) => Promise<DispatchResult>;
+  abortInstance: (
+    args: Clocked<AbortInstanceArgs & EngineScopeArgs>,
+  ) => Promise<OperationResult>;
   /**
    * 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;
-    tag: string;
-    workflowResource: WorkflowResource;
-    instanceId: string;
-  }) => Promise<WorkflowInstance>;
-  guardsForInstance: (args: {
-    client: WorkflowClient;
-    tag: string;
-    workflowResource: WorkflowResource;
-    instanceId: string;
-    resourceClients?: ResourceClientResolver;
-  }) => Promise<MutationGuardDoc[]>;
-  guardsForDefinition: (args: {
-    client: WorkflowClient;
-    tag: string;
-    workflowResource: WorkflowResource;
-    /** The definition's `name`. */
-    definition: string;
-    resourceClients?: ResourceClientResolver;
-  }) => Promise<MutationGuardDoc[]>;
+  getInstance: (
+    args: InstanceRefArgs & EngineScopeArgs,
+  ) => Promise<WorkflowInstance>;
+  guardsForInstance: (
+    args: InstanceRefArgs & EngineScopeArgs,
+  ) => Promise<MutationGuardDoc[]>;
+  guardsForDefinition: (
+    args: GuardsForDefinitionArgs & EngineScopeArgs,
+  ) => Promise<MutationGuardDoc[]>;
   /**
    * Run a caller-supplied GROQ query with the engine's tag bound as
    * `$tag`. This does NOT rewrite the query — arbitrary GROQ
@@ -4747,13 +5436,7 @@ export declare const workflow: {
    * rejected before it reaches the lake. Caller is responsible for type
    * narrowing the result.
    */
-  query: <T = unknown>(args: {
-    client: WorkflowClient;
-    tag: string;
-    workflowResource: WorkflowResource;
-    groq: string;
-    params?: Record<string, unknown>;
-  }) => Promise<T>;
+  query: <T = unknown>(args: QueryArgs & EngineScopeArgs) => Promise<T>;
   /**
    * Snapshot-aware GROQ — runs against the same in-memory view that
    * filters see for a given instance.
@@ -4761,49 +5444,31 @@ export declare const workflow: {
    * Hydrates the instance's snapshot (instance + ancestors + every doc
    * declared by a `doc.ref` / `doc.refs` entry in scope), then
    * evaluates the supplied GROQ in groq-js against that dataset. The
-   * rendered scope is auto-bound: `$self`, `$fields`, `$parent`,
-   * `$ancestors`, `$stage`, `$now`, `$effects`, `$activities`,
-   * `$allActivitiesDone`, `$anyActivityFailed` — ids in GDR URI form to match
-   * the snapshot's keying.
+   * rendered scope's instance-derived vars ({@link FILTER_SCOPE_VARS}) are
+   * auto-bound — ids in GDR URI form to match the snapshot's keying.
    *
    * Use when an external consumer (a UI, a debug pane, a test) wants
    * to ask "what does the engine see for this workflow right now?"
    * without re-implementing hydration. Pure read — never writes.
    */
   queryInScope: <T = unknown>(
-    args: Clocked<{
-      client: WorkflowClient;
-      tag: string;
-      workflowResource: WorkflowResource;
-      resourceClients?: ResourceClientResolver;
-      instanceId: string;
-      groq: string;
-      params?: Record<string, unknown>;
-    }>,
+    args: Clocked<QueryInScopeArgs & EngineScopeArgs>,
   ) => Promise<T>;
   /**
    * List every pending effect on the instance. Returns the same entries
    * the runtime would see — claimed and unclaimed alike.
    */
-  listPendingEffects: (args: {
-    client: WorkflowClient;
-    tag: string;
-    workflowResource: WorkflowResource;
-    instanceId: string;
-  }) => Promise<PendingEffect[]>;
+  listPendingEffects: (
+    args: InstanceRefArgs & EngineScopeArgs,
+  ) => Promise<PendingEffect[]>;
   /**
    * Filter pending effects on the instance by criteria. `claimed`
    * filters on claim presence; `names` restricts to specific effect
    * names. Both filters compose (AND).
    */
-  findPendingEffects: (args: {
-    client: WorkflowClient;
-    tag: string;
-    workflowResource: WorkflowResource;
-    instanceId: string;
-    claimed?: boolean;
-    names?: string[];
-  }) => Promise<PendingEffect[]>;
+  findPendingEffects: (
+    args: FindPendingEffectsArgs & EngineScopeArgs,
+  ) => Promise<PendingEffect[]>;
   /**
    * Project the instance from a given actor's perspective. Returns a
    * `WorkflowEvaluation` with per-action verdicts (`allowed` + a
@@ -4812,7 +5477,9 @@ export declare const workflow: {
    * Used by UIs to render disabled-with-reason buttons and by
    * `fireAction` to gate writes via the same logic.
    */
-  evaluate: (args: Clocked<EvaluateArgs>) => Promise<WorkflowEvaluation>;
+  evaluate: (
+    args: Clocked<EvaluateArgs & EngineScopeArgs>,
+  ) => Promise<WorkflowEvaluation>;
   /**
    * Diagnose why an instance is or isn't progressing. Projects the
    * instance (the same read as `evaluate`) and classifies it — terminal,
@@ -4822,7 +5489,9 @@ export declare const workflow: {
    * consumer can render the supporting evidence without a second projection.
    * Pure read.
    */
-  diagnose: (args: Clocked<EvaluateArgs>) => Promise<DiagnoseResult>;
+  diagnose: (
+    args: Clocked<EvaluateArgs & EngineScopeArgs>,
+  ) => Promise<DiagnoseResult>;
   /**
    * List the actions an actor could fire on an instance's current stage,
    * each flagged `allowed` (with a structured `disabledReason` when not).
@@ -4831,7 +5500,7 @@ export declare const workflow: {
    * consumer can read the instance/stage context. Pure read.
    */
   availableActions: (
-    args: Clocked<EvaluateArgs>,
+    args: Clocked<EvaluateArgs & EngineScopeArgs>,
   ) => Promise<AvailableActionsResult>;
   /**
    * Materialised spawned children of a parent instance.
@@ -4845,13 +5514,9 @@ export declare const workflow: {
    *
    * Pass `activity` to restrict to a single spawning activity on the parent.
    */
-  children: (args: {
-    client: WorkflowClient;
-    tag: string;
-    workflowResource: WorkflowResource;
-    instanceId: string;
-    activity?: string;
-  }) => Promise<WorkflowInstance[]>;
+  children: (
+    args: ChildrenArgs & EngineScopeArgs,
+  ) => Promise<WorkflowInstance[]>;
   /**
    * Every in-flight instance whose reactive watch-set includes `document` —
    * the reverse of {@link subscriptionDocumentsForInstance}.
@@ -4881,16 +5546,14 @@ export declare const workflow: {
    * (it can't be resource-routed and would silently mismatch). Sorted by
    * `startedAt` ascending.
    */
-  instancesForDocument: (args: {
-    client: WorkflowClient;
-    tag: string;
-    workflowResource: WorkflowResource;
-    document: GdrUri;
-  }) => Promise<WorkflowInstance[]>;
+  instancesForDocument: (
+    args: InstancesForDocumentArgs & EngineScopeArgs,
+  ) => Promise<WorkflowInstance[]>;
   /**
    * Permission helpers — Sanity ACL grants evaluated against documents
    * via GROQ. Used by `workflow.evaluate` to soft-gate actions when the
-   * caller supplies grants.
+   * caller supplies grants. Deliberately namespace-only (not mirrored on
+   * `Engine`): pure helpers that need none of the engine's pinned scope.
    */
   permissions: {
     matchesFilter: typeof matchesFilter;
@@ -4914,13 +5577,18 @@ 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"];
+declare const WORKFLOW_LIFECYCLES: readonly ["standalone", "child"];
 
 /**
  * The engine's view of "who am I, what can I do?". `actor` is who
- * the engine stamps onto history / `completedBy` / `ValueExpr.actor`.
- * `grants` (when present) gates `permission-denied`; when absent the
- * gate is skipped and the real Sanity write boundary takes over.
+ * the engine stamps onto history / `completedBy` / `ValueExpr.actor` —
+ * caller-asserted advisory provenance (see {@link Actor}), never an
+ * authenticated principal. `grants` (when present) feed the advisory
+ * `$can.*` params action conditions can read; there is no engine-side
+ * permission verdict. When grants are absent the rendered `$can` is
+ * undefined — conditions referencing it fail closed, everything else
+ * is ungated engine-side — and the real Sanity write boundary takes
+ * over.
  *
  * This is the RESOLVED shape — `actor` is guaranteed. For the
  * partial-override shape callers pass on verb args, see
@@ -4932,13 +5600,13 @@ export declare interface WorkflowAccess {
 }
 
 /**
- * Partial override accepted by every public verb's `access?:`
+ * Partial override accepted by every acting verb's `access?:`
  * argument. Any field present wins; missing halves token-resolve.
  *
  *   `{ actor, grants }` — bench's all-access default; both halves
  *     injected, no token round-trip.
  *   `{ actor }` — "act as another user"; grants come from
- *     `grantsFromPath` (or the gate is skipped).
+ *     `grantsFromPath` (or the rendered `$can` stays undefined).
  *   `{ grants }` — "preview with restricted permissions"; actor
  *     comes from `/users/me`.
  *   omitted entirely — both halves token-resolved.
@@ -5044,6 +5712,396 @@ export declare interface WorkflowCommitOptions {
   visibility?: WorkflowVisibility;
 }
 
+export declare type WorkflowConfig = v.InferOutput<typeof WorkflowConfigSchema>;
+
+declare const WorkflowConfigSchema: v.ObjectSchema<
+  {
+    readonly deployments: v.SchemaWithPipe<
+      readonly [
+        v.ArraySchema<
+          v.ObjectSchema<
+            {
+              readonly name: v.SchemaWithPipe<
+                readonly [
+                  v.StringSchema<undefined>,
+                  v.NonEmptyAction<string, "must not be empty">,
+                ]
+              >;
+              readonly tag: v.SchemaWithPipe<
+                readonly [
+                  v.StringSchema<undefined>,
+                  v.NonEmptyAction<string, undefined>,
+                  v.CheckAction<
+                    string,
+                    "invalid tag — lowercase letters, digits and dashes only, no leading dash, no dots"
+                  >,
+                ]
+              >;
+              readonly workflowResource: v.VariantSchema<
+                "type",
+                [
+                  v.ObjectSchema<
+                    {
+                      readonly type: v.LiteralSchema<"dataset", undefined>;
+                      readonly id: v.SchemaWithPipe<
+                        readonly [
+                          v.SchemaWithPipe<
+                            readonly [
+                              v.StringSchema<undefined>,
+                              v.NonEmptyAction<string, "must not be empty">,
+                            ]
+                          >,
+                          v.CheckAction<
+                            string,
+                            'invalid dataset resource id — expected "<projectId>.<dataset>"'
+                          >,
+                        ]
+                      >;
+                    },
+                    undefined
+                  >,
+                  v.ObjectSchema<
+                    {
+                      readonly type: v.LiteralSchema<"canvas", undefined>;
+                      readonly id: v.SchemaWithPipe<
+                        readonly [
+                          v.StringSchema<undefined>,
+                          v.NonEmptyAction<string, "must not be empty">,
+                        ]
+                      >;
+                    },
+                    undefined
+                  >,
+                  v.ObjectSchema<
+                    {
+                      readonly type: v.LiteralSchema<
+                        "media-library",
+                        undefined
+                      >;
+                      readonly id: v.SchemaWithPipe<
+                        readonly [
+                          v.StringSchema<undefined>,
+                          v.NonEmptyAction<string, "must not be empty">,
+                        ]
+                      >;
+                    },
+                    undefined
+                  >,
+                  v.ObjectSchema<
+                    {
+                      readonly type: v.LiteralSchema<"dashboard", undefined>;
+                      readonly id: v.SchemaWithPipe<
+                        readonly [
+                          v.StringSchema<undefined>,
+                          v.NonEmptyAction<string, "must not be empty">,
+                        ]
+                      >;
+                    },
+                    undefined
+                  >,
+                ],
+                undefined
+              >;
+              readonly resourceAliases: v.OptionalSchema<
+                v.SchemaWithPipe<
+                  readonly [
+                    v.ArraySchema<
+                      v.ObjectSchema<
+                        {
+                          readonly name: v.SchemaWithPipe<
+                            readonly [
+                              v.SchemaWithPipe<
+                                readonly [
+                                  v.StringSchema<undefined>,
+                                  v.NonEmptyAction<string, "must not be empty">,
+                                ]
+                              >,
+                              v.CheckAction<
+                                string,
+                                "invalid resource handle name — lowercase letters, digits and dashes only, no leading dash"
+                              >,
+                            ]
+                          >;
+                          readonly resource: v.VariantSchema<
+                            "type",
+                            [
+                              v.ObjectSchema<
+                                {
+                                  readonly type: v.LiteralSchema<
+                                    "dataset",
+                                    undefined
+                                  >;
+                                  readonly id: v.SchemaWithPipe<
+                                    readonly [
+                                      v.SchemaWithPipe<
+                                        readonly [
+                                          v.StringSchema<undefined>,
+                                          v.NonEmptyAction<
+                                            string,
+                                            "must not be empty"
+                                          >,
+                                        ]
+                                      >,
+                                      v.CheckAction<
+                                        string,
+                                        'invalid dataset resource id — expected "<projectId>.<dataset>"'
+                                      >,
+                                    ]
+                                  >;
+                                },
+                                undefined
+                              >,
+                              v.ObjectSchema<
+                                {
+                                  readonly type: v.LiteralSchema<
+                                    "canvas",
+                                    undefined
+                                  >;
+                                  readonly id: v.SchemaWithPipe<
+                                    readonly [
+                                      v.StringSchema<undefined>,
+                                      v.NonEmptyAction<
+                                        string,
+                                        "must not be empty"
+                                      >,
+                                    ]
+                                  >;
+                                },
+                                undefined
+                              >,
+                              v.ObjectSchema<
+                                {
+                                  readonly type: v.LiteralSchema<
+                                    "media-library",
+                                    undefined
+                                  >;
+                                  readonly id: v.SchemaWithPipe<
+                                    readonly [
+                                      v.StringSchema<undefined>,
+                                      v.NonEmptyAction<
+                                        string,
+                                        "must not be empty"
+                                      >,
+                                    ]
+                                  >;
+                                },
+                                undefined
+                              >,
+                              v.ObjectSchema<
+                                {
+                                  readonly type: v.LiteralSchema<
+                                    "dashboard",
+                                    undefined
+                                  >;
+                                  readonly id: v.SchemaWithPipe<
+                                    readonly [
+                                      v.StringSchema<undefined>,
+                                      v.NonEmptyAction<
+                                        string,
+                                        "must not be empty"
+                                      >,
+                                    ]
+                                  >;
+                                },
+                                undefined
+                              >,
+                            ],
+                            undefined
+                          >;
+                        },
+                        undefined
+                      >,
+                      undefined
+                    >,
+                    v.CheckAction<
+                      {
+                        name: string;
+                        resource:
+                          | {
+                              type: "dataset";
+                              id: string;
+                            }
+                          | {
+                              type: "canvas";
+                              id: string;
+                            }
+                          | {
+                              type: "media-library";
+                              id: string;
+                            }
+                          | {
+                              type: "dashboard";
+                              id: string;
+                            };
+                      }[],
+                      "duplicate resource handle name — each binding name must be unique within a deployment"
+                    >,
+                  ]
+                >,
+                undefined
+              >;
+              readonly definitions: v.SchemaWithPipe<
+                readonly [
+                  v.ArraySchema<
+                    v.CustomSchema<
+                      {
+                        name: string;
+                        title: string;
+                        description?: string | undefined;
+                        lifecycle?: WorkflowLifecycle | undefined;
+                        initialStage: string;
+                        fields?: FieldEntry[] | undefined;
+                        stages: Stage[];
+                        predicates?: Record<string, string> | undefined;
+                        roleAliases?: RoleAliases | undefined;
+                      },
+                      v.ErrorMessage<v.CustomIssue> | undefined
+                    >,
+                    undefined
+                  >,
+                  v.MinLengthAction<
+                    {
+                      name: string;
+                      title: string;
+                      description?: string | undefined;
+                      lifecycle?: WorkflowLifecycle | undefined;
+                      initialStage: string;
+                      fields?: FieldEntry[] | undefined;
+                      stages: Stage[];
+                      predicates?: Record<string, string> | undefined;
+                      roleAliases?: RoleAliases | undefined;
+                    }[],
+                    1,
+                    "a deployment needs at least one definition"
+                  >,
+                ]
+              >;
+            },
+            undefined
+          >,
+          undefined
+        >,
+        v.MinLengthAction<
+          {
+            name: string;
+            tag: string;
+            workflowResource:
+              | {
+                  type: "dataset";
+                  id: string;
+                }
+              | {
+                  type: "canvas";
+                  id: string;
+                }
+              | {
+                  type: "media-library";
+                  id: string;
+                }
+              | {
+                  type: "dashboard";
+                  id: string;
+                };
+            resourceAliases?:
+              | {
+                  name: string;
+                  resource:
+                    | {
+                        type: "dataset";
+                        id: string;
+                      }
+                    | {
+                        type: "canvas";
+                        id: string;
+                      }
+                    | {
+                        type: "media-library";
+                        id: string;
+                      }
+                    | {
+                        type: "dashboard";
+                        id: string;
+                      };
+                }[]
+              | undefined;
+            definitions: {
+              name: string;
+              title: string;
+              description?: string | undefined;
+              lifecycle?: WorkflowLifecycle | undefined;
+              initialStage: string;
+              fields?: FieldEntry[] | undefined;
+              stages: Stage[];
+              predicates?: Record<string, string> | undefined;
+              roleAliases?: RoleAliases | undefined;
+            }[];
+          }[],
+          1,
+          "a config needs at least one deployment"
+        >,
+        v.CheckAction<
+          {
+            name: string;
+            tag: string;
+            workflowResource:
+              | {
+                  type: "dataset";
+                  id: string;
+                }
+              | {
+                  type: "canvas";
+                  id: string;
+                }
+              | {
+                  type: "media-library";
+                  id: string;
+                }
+              | {
+                  type: "dashboard";
+                  id: string;
+                };
+            resourceAliases?:
+              | {
+                  name: string;
+                  resource:
+                    | {
+                        type: "dataset";
+                        id: string;
+                      }
+                    | {
+                        type: "canvas";
+                        id: string;
+                      }
+                    | {
+                        type: "media-library";
+                        id: string;
+                      }
+                    | {
+                        type: "dashboard";
+                        id: string;
+                      };
+                }[]
+              | undefined;
+            definitions: {
+              name: string;
+              title: string;
+              description?: string | undefined;
+              lifecycle?: WorkflowLifecycle | undefined;
+              initialStage: string;
+              fields?: FieldEntry[] | undefined;
+              stages: Stage[];
+              predicates?: Record<string, string> | undefined;
+              roleAliases?: RoleAliases | undefined;
+            }[];
+          }[],
+          "duplicate deployment tag — each deployment must use a unique tag"
+        >,
+      ]
+    >;
+  },
+  undefined
+>;
+
 export declare type WorkflowDefinition = v.InferOutput<
   typeof WorkflowDefinitionSchema
 >;
@@ -5065,6 +6123,59 @@ declare const WorkflowDefinitionSchema: v.GenericSchema<
   WorkflowFields<FieldEntry, Stage>
 >;
 
+export declare type WorkflowDeployment = WorkflowConfig["deployments"][number];
+
+/**
+ * Base class of the engine's structured errors. `kind` is the stable
+ * discriminant — render on it; `name` mirrors the concrete class for logs.
+ * Each subclass pins its literal via the `K` parameter, so passing a
+ * mismatched kind to `super` is a compile error. Advisory like every engine
+ * check: catching one of these explains a refusal, it does not enforce
+ * anything.
+ */
+export declare abstract class WorkflowError<
+  K extends WorkflowErrorKind = WorkflowErrorKind,
+> extends Error {
+  readonly kind: K;
+  constructor(kind: K, message: string, options?: ErrorOptions);
+}
+
+/**
+ * The engine's error model — one base class, one discriminant.
+ *
+ * Every structured error the engine throws at a caller extends
+ * {@link WorkflowError} and carries a {@link WorkflowErrorKind}, so a consumer
+ * can write ONE catch-and-render path: `instanceof WorkflowError`, then switch
+ * on `kind` (or `instanceof` a concrete class to read its typed payload). The
+ * model covers the runtime verbs' refusals, denials, races and lookups.
+ * Three things deliberately stay plain `Error`: deploy/authoring validation
+ * (a structured issue-report design of its own), transient transport
+ * failures (retryable, carrying `cause` — not engine verdicts), and internal
+ * invariant violations (the remediation is a bug report, not a catch branch).
+ *
+ * How thrown errors relate to the read-side verdicts is documented on
+ * {@link DisabledReason}.
+ */
+export declare type WorkflowErrorKind =
+  | "action-disabled"
+  | "edit-field-denied"
+  | "mutation-guard-denied"
+  | "action-params-invalid"
+  | "effect-ops-invalid"
+  | "required-field-not-provided"
+  | "workflow-state-diverged"
+  | "partial-guard-deploy"
+  | "concurrent-fire-action"
+  | "concurrent-edit-field"
+  | "cascade-limit"
+  | "field-value-shape"
+  | "instance-not-found"
+  | "definition-not-found"
+  | "definition-in-use"
+  | "effect-not-found"
+  | "missing-effect-handler"
+  | "contract-violation";
+
 export declare interface WorkflowEvaluation {
   instance: WorkflowInstance;
   definition: WorkflowDefinition;
@@ -5075,12 +6186,12 @@ export declare interface WorkflowEvaluation {
   /** True if at least one action on any active activity is allowed. */
   canInteract: boolean;
   /**
-   * Declared-editable slots in the current scope (workflow + current stage +
+   * Declared-editable fields in the current scope (workflow + current stage +
    * its activities), each with this actor's edit verdict and the current value's
    * provenance. The reactive edit-seam surface; empty when the workflow
-   * declares no editable slots.
+   * declares no editable fields.
    */
-  editableSlots: EditableSlotEvaluation[];
+  editableFields: EditableFieldEvaluation[];
 }
 
 export declare interface WorkflowFetchOptions {
@@ -5097,7 +6208,7 @@ declare type WorkflowFields<TField, TStage> = {
   name: string;
   title: string;
   description?: string | undefined;
-  role?: WorkflowRole | undefined;
+  lifecycle?: WorkflowLifecycle | undefined;
   initialStage: string;
   fields?: TField[] | undefined;
   stages: TStage[];
@@ -5192,6 +6303,11 @@ export declare interface WorkflowInstance extends SanityDocument {
   abortedAt?: string;
 }
 
+/** How instances of a definition come to exist: started standalone (the
+ *  default) or spawned by a parent. `'child'` is spawn-only — see
+ *  {@link isStartableDefinition}. */
+export declare type WorkflowLifecycle = (typeof WORKFLOW_LIFECYCLES)[number];
+
 /**
  * The subset of `@sanity/client` the engine actually needs. The
  * `@sanity-labs/client-fake-for-test` TestClient is
@@ -5257,9 +6373,6 @@ 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 cleanly undo the result — any of: the rollback write itself
@@ -5270,7 +6383,7 @@ export declare type WorkflowRole = (typeof WORKFLOW_ROLES)[number];
  * need manual reconciliation; the engine screams rather than leaving the
  * inconsistency silent.
  */
-export declare class WorkflowStateDivergedError extends Error {
+export declare class WorkflowStateDivergedError extends WorkflowError<"workflow-state-diverged"> {
   readonly instanceId: string;
   /** The guard-deploy failure that triggered the (attempted) rollback. */
   readonly guardError: unknown;