@sanity/workflow-engine 0.18.0 → 0.20.0

package/dist/index.d.ts

@@ -140,6 +140,19 @@ export declare interface ActionEvaluation {
   triggered?: true;
   /** Present iff `allowed === false`. The first failing gate wins. */
   disabledReason?: DisabledReason;
+  /**
+   * What firing this action would do to the flow RIGHT NOW — the fire
+   * replayed in memory on the engine's own machinery (ops, the triggered
+   * fixpoint, transition selection) against this projection's state, and
+   * conditional on the commit landing (rejectability is `allowed` /
+   * `disabledReason`'s story). Omitted when the consequence depends on
+   * inputs the projection doesn't hold — caller params, a spawn's
+   * dataset-driven fan-out, a terminal instance, a stage visit whose
+   * entries have diverged from the pinned definition — and on cascade-fired
+   * actions, which are never a caller's to fire. Advisory like every
+   * derived verdict: a placement/phrasing hint, never a gate.
+   */
+  firing?: FiringConsequence;
   /** Derived state of the action's `filter` gate — why it holds or fails,
    *  atom by atom. Present iff the action declares a filter. */
   insight?: ConditionInsight;
@@ -190,7 +203,7 @@ declare const ActionParamSchema: v.SchemaWithPipe<
             "doc.refs",
             "json",
           ],
-          `Invalid option: expected one of ${string}`
+          string
         >;
         readonly name: v.SchemaWithPipe<
           readonly [
@@ -734,10 +747,7 @@ declare type AuthoringFieldRef = v.InferOutput<typeof AuthoringFieldRefSchema>;
 declare const AuthoringFieldRefSchema: v.StrictObjectSchema<
   {
     readonly scope: v.OptionalSchema<
-      v.PicklistSchema<
-        readonly ["workflow", "stage", "activity"],
-        `Invalid option: expected one of ${string}`
-      >,
+      v.PicklistSchema<readonly ["workflow", "stage", "activity"], string>,
       undefined
     >;
     readonly field: v.SchemaWithPipe<
@@ -903,7 +913,7 @@ declare const AuthoringGuardSchema: v.StrictObjectSchema<
             v.ArraySchema<
               v.PicklistSchema<
                 readonly ["create", "update", "delete", "publish", "unpublish"],
-                `Invalid option: expected one of ${string}`
+                string
               >,
               undefined
             >,
@@ -1078,7 +1088,7 @@ declare const AuthoringManualTargetSchema: v.VariantSchema<
                 readonly scope: v.OptionalSchema<
                   v.PicklistSchema<
                     readonly ["workflow", "stage", "activity"],
-                    `Invalid option: expected one of ${string}`
+                    string
                   >,
                   undefined
                 >;
@@ -1114,7 +1124,7 @@ declare const AuthoringOpSchema: v.VariantSchema<
             readonly scope: v.OptionalSchema<
               v.PicklistSchema<
                 readonly ["workflow", "stage", "activity"],
-                `Invalid option: expected one of ${string}`
+                string
               >,
               undefined
             >;
@@ -1139,7 +1149,7 @@ declare const AuthoringOpSchema: v.VariantSchema<
             readonly scope: v.OptionalSchema<
               v.PicklistSchema<
                 readonly ["workflow", "stage", "activity"],
-                `Invalid option: expected one of ${string}`
+                string
               >,
               undefined
             >;
@@ -1163,7 +1173,7 @@ declare const AuthoringOpSchema: v.VariantSchema<
             readonly scope: v.OptionalSchema<
               v.PicklistSchema<
                 readonly ["workflow", "stage", "activity"],
-                `Invalid option: expected one of ${string}`
+                string
               >,
               undefined
             >;
@@ -1188,7 +1198,7 @@ declare const AuthoringOpSchema: v.VariantSchema<
             readonly scope: v.OptionalSchema<
               v.PicklistSchema<
                 readonly ["workflow", "stage", "activity"],
-                `Invalid option: expected one of ${string}`
+                string
               >,
               undefined
             >;
@@ -1219,7 +1229,7 @@ declare const AuthoringOpSchema: v.VariantSchema<
             readonly scope: v.OptionalSchema<
               v.PicklistSchema<
                 readonly ["workflow", "stage", "activity"],
-                `Invalid option: expected one of ${string}`
+                string
               >,
               undefined
             >;
@@ -1255,7 +1265,7 @@ declare const AuthoringOpSchema: v.VariantSchema<
         >;
         readonly status: v.PicklistSchema<
           readonly ["active", "done", "skipped", "failed"],
-          `Invalid option: expected one of ${string}`
+          string
         >;
       },
       undefined
@@ -1268,7 +1278,7 @@ declare const AuthoringOpSchema: v.VariantSchema<
             readonly scope: v.OptionalSchema<
               v.PicklistSchema<
                 readonly ["workflow", "stage", "activity"],
-                `Invalid option: expected one of ${string}`
+                string
               >,
               undefined
             >;
@@ -1672,6 +1682,42 @@ declare type Clocked<T> = T & {
   clock?: Clock;
 };
 
+declare interface CommitEffectOpsArgs extends DedupableOperationArgs {
+  /** The `_key` of the pending effect being reported on. */
+  effectKey: string;
+  /**
+   * Required here, unlike the other dedupable verbs: the engine cannot
+   * assume a supplied field op is idempotent, so every mid-dispatch report
+   * must be retry-safe. (The runtime check remains for untyped callers.)
+   */
+  idempotencyKey: string;
+  /**
+   * The exact-claim identity handed to the reporting dispatch. The commit
+   * re-reads the instance and rejects (writing nothing) unless the entry's
+   * live claim carries this token unexpired — so an expired, released, or
+   * superseded handler cannot update state. A successful commit renews the
+   * claim's lease.
+   */
+  claimToken: string;
+  /**
+   * Mid-dispatch field state, `field.*` ops only — validated and applied
+   * exactly like completion ops (same applier, same target resolution
+   * against the current open stage, workflow-/stage-scope only, never
+   * `status.set`). Must be non-empty. Completion ops remain the final
+   * atomic result committed when the handler returns; these are separately
+   * committed and observable before it.
+   */
+  ops: FieldOp[];
+  /** Lease duration the successful commit renews the claim to — the
+   *  drain's `effectLeaseMs`. Default `DEFAULT_EFFECT_LEASE_MS` (5 min). */
+  leaseMs?: number;
+}
+
+export declare interface CommitOpsRequest {
+  ops: FieldOp[];
+  idempotencyKey: string;
+}
+
 export { ComparisonOp };
 
 /**
@@ -1749,6 +1795,20 @@ export declare function computeDiffEntries<
   target: DeployTarget;
 }): Promise<DiffEntry[]>;
 
+/** {@link ConcurrentCompleteEffectError}'s mid-dispatch sibling: a
+ *  `commitEffectOps` commit lost every optimistic-locking attempt. Nothing
+ *  was written; the report may be retried under the same idempotency key. */
+export declare class ConcurrentCommitEffectOpsError extends WorkflowError<"concurrent-commit-effect-ops"> {
+  readonly instanceId: string;
+  readonly effectKey: string;
+  readonly attempts: number;
+  constructor(args: {
+    instanceId: string;
+    effectKey: string;
+    attempts: number;
+  });
+}
+
 /**
  * Completion twin of {@link ConcurrentFireActionError}: a `completeEffect`
  * commit lost the optimistic-locking race on every attempt. Same contract —
@@ -1934,10 +1994,9 @@ export declare type ConditionVarBinding = "always" | "caller" | "spawn";
 
 /**
  * The one-doc read a reactive adapter subscribes with to observe a content doc
- * under a perspective stack — the same GROQ as the engine's own hydration read
- * ({@link hydrateSnapshot}), so the adapter and the engine resolve identical
- * content: draft/version content projected onto the published id, a doc that
- * exists only as a draft (or only inside a release) still visible.
+ * under a perspective stack. It uses the same perspective semantics as
+ * {@link hydrateSnapshot}: draft/version content is projected onto the published
+ * id, and a doc that exists only as a draft or release version remains visible.
  */
 export declare function contentDocQuery(documentId: string): CompiledQuery;
 
@@ -2221,6 +2280,24 @@ export declare const DATA_MODEL_CHANGES: readonly [
     applicability: "detectable";
     summary: "String, text, and number values may carry persisted inclusive bounds.";
   }>,
+  Readonly<{
+    id: "progress-field-kind";
+    introducedInModel: 3;
+    minReaderModel: 0;
+    documentTypes: readonly ["definition", "instance"];
+    compatibility: "additive";
+    applicability: "detectable";
+    summary: "A progress field kind carries application-defined 0–100 completion.";
+  }>,
+  Readonly<{
+    id: "effect-claim-tokens";
+    introducedInModel: 3;
+    minReaderModel: 0;
+    documentTypes: readonly ["instance"];
+    compatibility: "additive";
+    applicability: "detectable";
+    summary: "Pending-effect claims carry an exact-claim token gating mid-dispatch state reports.";
+  }>,
 ];
 
 /**
@@ -2245,7 +2322,7 @@ export declare const DATA_MODEL_MIN_READER = 2;
  * job. Declare every bump in `DATAMODEL.md`; the model-surface snapshot test
  * keeps undeclared drift red.
  */
-export declare const DATA_MODEL_VERSION = 2;
+export declare const DATA_MODEL_VERSION = 3;
 
 export declare interface DataModelChange {
   readonly id: string;
@@ -2278,9 +2355,10 @@ export declare type DeclaredExecutionContext = Pick<
 
 /**
  * The {@link OperationArgs} of the verbs that own a discrete commit —
- * `fireAction`, `editField`, `completeEffect`, `setStage`, `abortInstance`.
- * `tick` deliberately takes the plain base: it owns no commit of its own and
- * re-derives everything, so retrying it blind is already safe.
+ * `fireAction`, `editField`, `completeEffect`, `commitEffectOps`, `setStage`,
+ * `abortInstance`. `tick` deliberately takes the plain base: it owns no
+ * commit of its own and re-derives everything, so retrying it blind is
+ * already safe.
  */
 export declare interface DedupableOperationArgs extends OperationArgs {
   /**
@@ -3285,6 +3363,16 @@ export declare type EditMode = "set" | "append" | "unset";
 
 export declare type Effect = v.InferOutput<typeof EffectSchema>;
 
+/** Total commits one dispatch may make — the runaway-handler bound: without
+ *  it, a looping reporter renews its own lease and appends history forever.
+ *  2× the ceiling of 1%-granularity progress reporting. */
+export declare const EFFECT_COMMIT_DISPATCH_CAP = 200;
+
+/** Pending mid-dispatch commits one dispatch may hold before `commitOps` /
+ *  `setProgress` throws synchronously. An awaiting handler never reaches it
+ *  (its queue depth stays ≤ 1). */
+export declare const EFFECT_COMMIT_QUEUE_DEPTH = 32;
+
 /**
  * Every terminal state an effect run can record. `done` and `failed` are
  * reported through completion ({@link EffectCompletionStatus}); `cancelled`
@@ -3294,6 +3382,22 @@ export declare type Effect = v.InferOutput<typeof EffectSchema>;
  */
 declare const EFFECT_RUN_STATUSES: readonly ["done", "failed", "cancelled"];
 
+/**
+ * A `ctx.commitOps` / `ctx.setProgress` call hit one of the dispatch's
+ * bounds. Thrown synchronously at the call site — see the module doc for why
+ * a rejection would be invisible to exactly the caller the bound exists for.
+ */
+export declare class EffectCommitQueueOverflowError extends WorkflowError<"effect-commit-queue-overflow"> {
+  readonly effectKey: string;
+  readonly bound: "queue-depth" | "dispatch-cap";
+  readonly limit: number;
+  constructor(args: {
+    effectKey: string;
+    bound: "queue-depth" | "dispatch-cap";
+    limit: number;
+  });
+}
+
 /** The outcomes a completer may report through `completeEffect` — a run
  *  either succeeded or failed. `cancelled` is not reportable: only an abort
  *  stamps it, on entries that never dispatched. */
@@ -3349,11 +3453,13 @@ export declare type EffectHandler<
  */
 declare type EffectHandlerContext<Client extends WorkflowClient> = {
   /**
-   * The exact concrete client supplied to `createEngine`, bound to the
-   * workflow resource rather than an
-   * engine wrapper. Its class identity, namespaces, configuration, and
-   * credentials are preserved. Handler-owned requests are not automatically
-   * tagged by the engine.
+   * A concrete sibling of the client supplied to `createEngine`, bound to the
+   * workflow resource with the same namespaces and credentials. Untagged
+   * handler requests on its workflow-client surface carry the `workflow.effect`
+   * request tag by default. A concrete client's explicit tags compose beneath
+   * that prefix. On the structural fallback for minimal clients, pass-through
+   * namespaces are not stamped and core builders expose the engine's minimal
+   * workflow-client surface.
    */
   client: Client;
   /**
@@ -3369,8 +3475,8 @@ declare type EffectHandlerContext<Client extends WorkflowClient> = {
    * {@link GlobalDocumentReference}. Returns the `resourceClients` client
    * for that resource when one is mapped, {@link client} for the workflow
    * resource itself, and a sibling derived from {@link client}'s
-   * credentials otherwise. Mapped clients are returned unchanged; an
-   * unmapped foreign resource necessarily returns a configured sibling.
+   * credentials otherwise. Returned clients preserve their concrete APIs and
+   * apply the same default effect request tag.
    * Throws if `ref` isn't a GDR — a bare id can't
    * be routed, so failing loud beats silently patching the wrong dataset.
    */
@@ -3378,6 +3484,34 @@ declare type EffectHandlerContext<Client extends WorkflowClient> = {
   instanceId: string;
   effectKey: string;
   log: (message: string, extra?: Record<string, unknown>) => void;
+  /**
+   * Commit mid-dispatch field state as a real engine transaction —
+   * validated like completion ops (`field.*` only, never `status.set`),
+   * gated on THIS dispatch's exact claim (a stale/superseded claim
+   * rejects before writing), history + idempotency recorded, guards
+   * refreshed, cascade run, and the claim's lease renewed in the same
+   * commit. Calls enqueue synchronously into a bounded per-dispatch FIFO
+   * and execute strictly in call order, one at a time — forgetting to
+   * `await` cannot create same-handler write races, and overflow (or the
+   * per-dispatch commit cap) throws synchronously at the call site.
+   * Await each call anyway: that is where errors surface promptly and
+   * engine commit latency paces the reporter. `idempotencyKey` is
+   * required — the engine does not assume a supplied op is idempotent.
+   * An accepted-but-unawaited commit that fails still fails the effect
+   * at settlement; the final completion always waits for this queue to
+   * drain. Never coalesced.
+   */
+  commitOps: (req: CommitOpsRequest) => Promise<void>;
+  /**
+   * Report absolute progress — sugar over {@link commitOps} that
+   * `field.set`s a number (a `progress` field's 0–100 contract is
+   * enforced by the engine at commit). A bare string targets a
+   * workflow-scope field; pass `{scope: 'stage', field}` for stage
+   * scope. Unlike `commitOps`, PENDING sets to the same field coalesce
+   * (latest value wins, one commit), so a tight reporting loop is safe
+   * by construction; idempotency keys are engine-derived.
+   */
+  setProgress: (target: ProgressTarget, value: number) => Promise<void>;
 };
 
 export declare interface EffectHistoryEntry {
@@ -3579,6 +3713,10 @@ export declare interface Engine {
    *  reassign / reschedule / claim-by-hand / append-to-log, then cascade. */
   editField: (args: EditFieldArgs) => Promise<OperationResult>;
   completeEffect: (args: CompleteEffectArgs) => Promise<OperationResult>;
+  /** Commit mid-dispatch field state from a running effect handler — the
+   *  verb behind `ctx.commitOps`. Gated on the dispatch's exact claim token;
+   *  a successful commit renews the claim's lease. */
+  commitEffectOps: (args: CommitEffectOpsArgs) => Promise<OperationResult>;
   tick: (args: OperationArgs) => Promise<OperationResult>;
   /** Project the instance from an actor's perspective — per-action verdicts
    *  with structured disabled reasons. Pure read. */
@@ -3705,10 +3843,10 @@ export declare interface Engine {
  * {@link WorkflowClient.withConfig}, and `resourceClients`-resolved clients
  * are rebound the same way. A caller's configured `apiVersion` therefore
  * never reaches engine-owned traffic (the caller's own client instance is
- * untouched). Effect handlers are host traffic and deliberately receive the
- * caller's configuration unchanged. The other exception is a client that lacks `withConfig` and so
- * cannot be rebound — it must be built to serve this version; see
- * {@link WorkflowClient.withConfig}.
+ * untouched). Effect handlers keep the caller's `apiVersion`; their derived
+ * clients change only the request-tag prefix. The other exception is a client
+ * that lacks `withConfig` and so cannot be rebound — it must be built to serve
+ * this version; see {@link WorkflowClient.withConfig}.
  */
 export declare const ENGINE_API_VERSION = "2026-04-29";
 
@@ -4117,6 +4255,10 @@ export declare const FIELD_KIND_DISPLAY: {
     title: string;
     description: string;
   };
+  progress: {
+    title: string;
+    description: string;
+  };
   boolean: {
     title: string;
     description: string;
@@ -4174,6 +4316,7 @@ declare const FIELD_VALUE_KINDS: readonly [
   "string",
   "text",
   "number",
+  "progress",
   "boolean",
   "date",
   "datetime",
@@ -4314,6 +4457,10 @@ export declare interface FieldValueMap {
   /** Multiline string — same value as {@link FieldValueMap.string}, distinct kind for rendering. */
   text: string | null;
   number: number | null;
+  /** Application-defined 0–100 completion — same stored value as
+   *  {@link FieldValueMap.number}, distinct kind so surfaces can elevate it;
+   *  always finite and within 0–100 inclusive (fractions allowed). */
+  progress: number | null;
   boolean: boolean | null;
   /** Date-only (`YYYY-MM-DD`), no time component. */
   date: string | null;
@@ -4411,6 +4558,20 @@ export declare interface FireActionArgs extends DedupableOperationArgs {
   idempotent?: boolean;
 }
 
+/**
+ * The flow consequence of one caller fire, computed by replaying it in
+ * memory through the same machinery a real commit runs — never by a
+ * parallel model of it. State-dependent: it answers "now", not "always".
+ */
+export declare interface FiringConsequence {
+  /** The replayed commit's cascade exits the current stage in its first
+   *  hop. `false` is a definite answer for the current state — including
+   *  a selection halted by an unevaluable trigger, which holds the stage. */
+  exitsStage: boolean;
+  /** The transition the selection picked, present iff `exitsStage`. */
+  transition?: string;
+}
+
 export { formatRead };
 
 /**
@@ -4663,7 +4824,7 @@ export declare type GuardAction = v.InferOutput<typeof GuardActionSchema>;
 
 declare const GuardActionSchema: v.PicklistSchema<
   readonly ["create", "update", "delete", "publish", "unpublish"],
-  `Invalid option: expected one of ${string}`
+  string
 >;
 
 export declare type GuardMatch = Guard["match"];
@@ -4828,7 +4989,7 @@ declare const GuardSchema: v.StrictObjectSchema<
             v.ArraySchema<
               v.PicklistSchema<
                 readonly ["create", "update", "delete", "publish", "unpublish"],
-                `Invalid option: expected one of ${string}`
+                string
               >,
               undefined
             >,
@@ -5364,13 +5525,14 @@ export declare type InsightSite =
 export declare function instanceDocId(tag: string): string;
 
 /**
- * The per-instance guard filter — the single definition of "this instance's
- * guards in one datasource". The engine's verdict load
- * ({@link verdictGuardsForInstance}) fetches it once against the engine
- * datasource; the reactive adapters feed the same query/params to their
- * stores as a live subscription; {@link guardsForInstance} unions it across
- * datasources for housekeeping. Ordinary stage retraction deletes guards, so
- * results represent active persisted guard documents.
+ * The per-instance guard filter — "this instance's guards in one datasource".
+ * The engine's verdict load ({@link verdictGuardsForInstance}) fetches it once
+ * against the engine datasource, and {@link guardsForInstance} unions it
+ * across datasources for housekeeping; the reactive adapters subscribe the
+ * set-shaped {@link instancesGuardQuery} this delegates to (one shared
+ * live query per resource, sliced per `sourceInstanceId`), so every path
+ * reads through one filter definition. Ordinary stage retraction deletes
+ * guards, so results represent active persisted guard documents.
  */
 export declare function instanceGuardQuery(instanceId: string): CompiledQuery;
 
@@ -5423,6 +5585,12 @@ export declare interface InstanceSession {
    *  docs are processed), never from the commit itself — the commit's
    *  outcome is never masked by a store echo's failure. */
   update(docs: LoadedDoc[]): void;
+  /** Replace one held document without rebuilding the rest of the overlay.
+   *  Consumers with per-document streams use this after the initial
+   *  {@link InstanceSession.update} snapshot. Self-doc recency, commit-time
+   *  buffering, and deferred buffered-validation errors follow the same
+   *  contract as {@link InstanceSession.update}. */
+  updateDocument(doc: LoadedDoc): void;
   /** Replace the held live guards (the consumer's guard stream,
    *  last-write-wins). Guards are a separate stream from the watch-set:
    *  {@link InstanceSession.evaluate} pre-flights the instance write against
@@ -5484,6 +5652,18 @@ export declare interface InstancesForDocumentArgs {
   document: GdrUri;
 }
 
+/**
+ * The guard filter for a SET of instances in one datasource — the single
+ * definition every per-instance read delegates to ({@link instanceGuardQuery}).
+ * Reactive adapters subscribe it as ONE shared live query per resource for
+ * every co-mounted session, fanning results back out per `sourceInstanceId`,
+ * so a document's guard subscription count doesn't grow with its instance
+ * count. Deterministically ordered, matching {@link guardsForResource}.
+ */
+export declare function instancesGuardQuery(
+  instanceIds: readonly string[],
+): CompiledQuery;
+
 /**
  * The instance-list GROQ for a {@link InstancesQueryFilter}, ordered by
  * `startedAt` ascending (descending + sliced under
@@ -5577,6 +5757,10 @@ export declare function isClaimExpired(
   now: string,
 ): boolean;
 
+export declare function isClientProjectUser(
+  value: unknown,
+): value is ClientProjectUser;
+
 export { isComparisonOp };
 
 /**
@@ -6335,6 +6519,16 @@ export declare interface PendingEffectClaim {
    * live claim), and a field would drift from that trail across releases.
    */
   leaseExpiresAt?: string;
+  /**
+   * The exact-claim identity a mid-dispatch state report must present.
+   * `effectKey` cannot serve: a lease takeover keeps the same key, so a
+   * superseded handler holding only the key could still write. The token is
+   * minted fresh on every claim and takeover; `commitEffectOps` rejects a
+   * report whose token no longer matches before writing anything. Absent
+   * only on claims persisted before tokens existed — those never match, so
+   * their dispatches simply cannot report mid-flight.
+   */
+  claimToken?: string;
 }
 
 /**
@@ -6400,14 +6594,23 @@ export declare function processShellUserProperties<
   runtimeVersion: string;
 };
 
+/** `setProgress`'s field addressing: a bare name targets the workflow scope;
+ *  pass `{scope: 'stage', field}` for a stage-scope progress field. */
+export declare type ProgressTarget =
+  | string
+  | {
+      scope: "workflow" | "stage";
+      field: string;
+    };
+
 /**
  * Project a store-resolved doc onto its watch ref's identity, the way the
  * lake's perspective reads do: the published-form id becomes `_id` (the form
  * the session keys its overlay and snapshot by), and a draft/version
  * representation's stored id rides along as `_originalId` — session-side
  * conditions (including the `_originalId in path("versions.**")` shape) then
- * read exactly what the engine's own hydration ({@link contentDocQuery})
- * returns. Strict by construction: only the ids in
+ * read the same projected identity as the engine's perspective-aware hydration.
+ * Strict by construction: only the ids in
  * {@link watchRefRepresentations} are accepted — an id that merely *ends* in
  * the watched id (another doc's dotted id under a version prefix), a release
  * the perspective doesn't read, or a draft the perspective makes invisible is
@@ -6457,7 +6660,7 @@ export declare class ReaderModelAcknowledgementError extends WorkflowError<"read
   readonly code = "WORKFLOW_READER_MODEL_ACKNOWLEDGEMENT_MISMATCH";
   readonly expectedMinReaderModel: unknown;
   readonly engineMinReaderModel = 2;
-  readonly engineModelVersion = 2;
+  readonly engineModelVersion = 3;
   readonly documentationUrl =
     "https://github.com/sanity-io/workflows/blob/main/docs/reader-model-rollout.md";
   constructor(expectedMinReaderModel: unknown, context?: string);
@@ -6795,8 +6998,8 @@ export declare function resourceAliasesToMap(
  * refs to the resources it stops serving.
  *
  * Engine-owned verb scopes rebind resolved clients onto
- * `ENGINE_API_VERSION`. Effect handlers receive resolver clients unchanged
- * because handler traffic belongs to the host.
+ * `ENGINE_API_VERSION`. Effect handlers derive request-tagged siblings from
+ * resolver clients so their concrete APIs remain available and attributed.
  */
 export declare type ResourceClientResolver = (
   parsed: ParsedGdr,
@@ -7079,6 +7282,32 @@ declare interface StageGuardArgs {
 
 export declare type StageName = string;
 
+/** Why a mid-dispatch report's claim no longer authorises it — see
+ *  {@link StaleEffectClaimError}. */
+export declare type StaleClaimReason =
+  | "unclaimed"
+  | "claim-superseded"
+  | "lease-expired";
+
+/**
+ * Thrown when a mid-dispatch state report (`commitEffectOps`) presents a
+ * claim token that no longer authorises writing: the entry's claim was
+ * released, taken over by another dispatch (`claim-superseded`), or its
+ * lease lapsed. Nothing was written — the gate runs before any mutation.
+ * The handler should stop reporting; its completion still follows the
+ * normal first-writer-wins completion semantics.
+ */
+export declare class StaleEffectClaimError extends WorkflowError<"stale-effect-claim"> {
+  readonly instanceId: string;
+  readonly effectKey: string;
+  readonly reason: StaleClaimReason;
+  constructor(args: {
+    instanceId: string;
+    effectKey: string;
+    reason: StaleClaimReason;
+  });
+}
+
 /**
  * The vars a definition's `start.allowed` reads — the start-time permission
  * dialect: everything the filter context binds ({@link START_FILTER_VARS})
@@ -7428,7 +7657,7 @@ declare const StoredFieldOpSchema: v.VariantSchema<
           {
             readonly scope: v.PicklistSchema<
               readonly ["workflow", "stage", "activity"],
-              `Invalid option: expected one of ${string}`
+              string
             >;
             readonly field: v.SchemaWithPipe<
               readonly [
@@ -7450,7 +7679,7 @@ declare const StoredFieldOpSchema: v.VariantSchema<
           {
             readonly scope: v.PicklistSchema<
               readonly ["workflow", "stage", "activity"],
-              `Invalid option: expected one of ${string}`
+              string
             >;
             readonly field: v.SchemaWithPipe<
               readonly [
@@ -7471,7 +7700,7 @@ declare const StoredFieldOpSchema: v.VariantSchema<
           {
             readonly scope: v.PicklistSchema<
               readonly ["workflow", "stage", "activity"],
-              `Invalid option: expected one of ${string}`
+              string
             >;
             readonly field: v.SchemaWithPipe<
               readonly [
@@ -7493,7 +7722,7 @@ declare const StoredFieldOpSchema: v.VariantSchema<
           {
             readonly scope: v.PicklistSchema<
               readonly ["workflow", "stage", "activity"],
-              `Invalid option: expected one of ${string}`
+              string
             >;
             readonly field: v.SchemaWithPipe<
               readonly [
@@ -7521,7 +7750,7 @@ declare const StoredFieldOpSchema: v.VariantSchema<
           {
             readonly scope: v.PicklistSchema<
               readonly ["workflow", "stage", "activity"],
-              `Invalid option: expected one of ${string}`
+              string
             >;
             readonly field: v.SchemaWithPipe<
               readonly [
@@ -7551,7 +7780,7 @@ declare const StoredFieldRefSchema: v.StrictObjectSchema<
   {
     readonly scope: v.PicklistSchema<
       readonly ["workflow", "stage", "activity"],
-      `Invalid option: expected one of ${string}`
+      string
     >;
     readonly field: v.SchemaWithPipe<
       readonly [
@@ -7586,7 +7815,7 @@ declare const StoredManualTargetSchema: v.VariantSchema<
           {
             readonly scope: v.PicklistSchema<
               readonly ["workflow", "stage", "activity"],
-              `Invalid option: expected one of ${string}`
+              string
             >;
             readonly field: v.SchemaWithPipe<
               readonly [
@@ -7614,7 +7843,7 @@ declare const StoredOpSchema: v.VariantSchema<
           {
             readonly scope: v.PicklistSchema<
               readonly ["workflow", "stage", "activity"],
-              `Invalid option: expected one of ${string}`
+              string
             >;
             readonly field: v.SchemaWithPipe<
               readonly [
@@ -7636,7 +7865,7 @@ declare const StoredOpSchema: v.VariantSchema<
           {
             readonly scope: v.PicklistSchema<
               readonly ["workflow", "stage", "activity"],
-              `Invalid option: expected one of ${string}`
+              string
             >;
             readonly field: v.SchemaWithPipe<
               readonly [
@@ -7657,7 +7886,7 @@ declare const StoredOpSchema: v.VariantSchema<
           {
             readonly scope: v.PicklistSchema<
               readonly ["workflow", "stage", "activity"],
-              `Invalid option: expected one of ${string}`
+              string
             >;
             readonly field: v.SchemaWithPipe<
               readonly [
@@ -7679,7 +7908,7 @@ declare const StoredOpSchema: v.VariantSchema<
           {
             readonly scope: v.PicklistSchema<
               readonly ["workflow", "stage", "activity"],
-              `Invalid option: expected one of ${string}`
+              string
             >;
             readonly field: v.SchemaWithPipe<
               readonly [
@@ -7707,7 +7936,7 @@ declare const StoredOpSchema: v.VariantSchema<
           {
             readonly scope: v.PicklistSchema<
               readonly ["workflow", "stage", "activity"],
-              `Invalid option: expected one of ${string}`
+              string
             >;
             readonly field: v.SchemaWithPipe<
               readonly [
@@ -7738,7 +7967,7 @@ declare const StoredOpSchema: v.VariantSchema<
         >;
         readonly status: v.PicklistSchema<
           readonly ["active", "done", "skipped", "failed"],
-          `Invalid option: expected one of ${string}`
+          string
         >;
       },
       undefined
@@ -8012,10 +8241,7 @@ declare const SubworkflowsSchema: v.StrictObjectSchema<
      * `$subworkflows`) decide.
      */
     readonly onExit: v.OptionalSchema<
-      v.PicklistSchema<
-        readonly ["detach", "abort"],
-        `Invalid option: expected one of ${string}`
-      >,
+      v.PicklistSchema<readonly ["detach", "abort"], string>,
       undefined
     >;
   },
@@ -8333,9 +8559,10 @@ declare type ValueExprInternal =
  * 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, 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.
+ * it is not itself a security boundary. Reads through the same filter
+ * definition the reactive adapters subscribe with
+ * ({@link instanceGuardQuery}, the one-id form of the set-shaped
+ * {@link instancesGuardQuery}), so the stateless and reactive paths agree.
  */
 export declare function verdictGuardsForInstance(
   client: WorkflowClient,
@@ -8527,6 +8754,23 @@ export declare const workflow: {
   completeEffect: (
     rawArgs: Clocked<Telemetered<CompleteEffectArgs & EngineScopeArgs>>,
   ) => Promise<OperationResult>;
+  /**
+   * Commit mid-dispatch field state from a running effect handler — the
+   * engine verb behind `ctx.commitOps`. Gates on the dispatch's exact claim
+   * (token match + unexpired lease; a stale report throws
+   * `StaleEffectClaimError` and writes nothing), validates and applies the
+   * `field.*` ops through the shared op applier, records history and the
+   * mandatory idempotency key, renews the claim's lease in the same
+   * compare-and-swap commit, refreshes the stage's guards, then cascades —
+   * a report that satisfies a transition moves the instance, by design.
+   *
+   * Completion (`completeEffect`) remains the authoritative final result
+   * and stays claim-blind; this verb only protects the mid-dispatch write
+   * channel from superseded handlers.
+   */
+  commitEffectOps: (
+    rawArgs: Clocked<Telemetered<CommitEffectOpsArgs & EngineScopeArgs>>,
+  ) => Promise<OperationResult>;
   /**
    * Run the cascade until stable — triggered actions fire, transitions move.
    *
@@ -8882,7 +9126,7 @@ export declare interface WorkflowClient {
    * Optional — present on the real `@sanity/client` and the in-memory test
    * fake. Returns a sibling client with the given config overrides,
    * inheriting everything else from the source (token, apiHost). The engine
-   * derives two things from it:
+   * derives three things from it:
    *
    * - **Cross-resource routing** (`resource` + the dataset pair): a sibling
    *   for a foreign GDR when `resourceClients` doesn't map it. A client
@@ -8896,6 +9140,10 @@ export declare interface WorkflowClient {
    *   rebound and is used as-is — it must be built to serve
    *   {@link ENGINE_API_VERSION} already; older dated versions fail
    *   silently incomplete, not loud.
+   * - **Effect request attribution** (`requestTagPrefix`): handlers receive a
+   *   derived client whose untagged traffic carries the effect tag while the
+   *   caller's own client remains untouched. A client without `withConfig`
+   *   uses the structural request wrapper instead.
    *
    * Dataset resources carry the `{projectId, dataset}` pair alongside
    * `resource`: the real client routes by `resource` (it takes precedence in
@@ -8904,7 +9152,7 @@ export declare interface WorkflowClient {
    * only — a canvas/media-library derivation on the fake aliases the current
    * store until the fake learns `resource` upstream.
    */
-  withConfig?: (config: WorkflowClientConfig) => WorkflowClient;
+  withConfig?: (config: WorkflowClientConfig) => this;
   /**
    * Optional — present on the real `@sanity/client`, absent on the
    * in-memory test client. The engine probes for it when auto-resolving
@@ -8930,14 +9178,15 @@ export declare interface WorkflowClient {
 /**
  * The config bag {@link WorkflowClient.withConfig} accepts — all optional: a
  * resource rebind (`resource`, plus the dataset pair for dataset targets), an
- * `apiVersion` rebind, or both. Everything omitted is inherited from the
- * source client.
+ * `apiVersion` rebind, a request-tag prefix, or any combination. Everything
+ * omitted is inherited from the source client.
  */
 export declare interface WorkflowClientConfig {
   resource?: WorkflowResource;
   projectId?: string;
   dataset?: string;
   apiVersion?: string;
+  requestTagPrefix?: string;
 }
 
 export declare interface WorkflowCommitOptions {
@@ -8979,7 +9228,11 @@ declare const WorkflowConfigSchema: v.ObjectSchema<
               readonly name: v.SchemaWithPipe<
                 readonly [
                   v.StringSchema<undefined>,
-                  v.NonEmptyAction<string, "must not be empty">,
+                  v.NonEmptyAction<string, undefined>,
+                  v.CheckAction<
+                    string,
+                    `invalid ${string} \u2014 ASCII lowercase + digits + dashes, no leading dash, no dots`
+                  >,
                 ]
               >;
               readonly expectedMinReaderModel: v.OptionalSchema<
@@ -8992,7 +9245,7 @@ declare const WorkflowConfigSchema: v.ObjectSchema<
                   v.NonEmptyAction<string, undefined>,
                   v.CheckAction<
                     string,
-                    "invalid tag — lowercase letters, digits and dashes only, no leading dash, no dots"
+                    `invalid ${string} \u2014 ASCII lowercase + digits + dashes, no leading dash, no dots`
                   >,
                 ]
               >;
@@ -9193,7 +9446,30 @@ declare const WorkflowConfigSchema: v.ObjectSchema<
                               id: string;
                             };
                       }[],
-                      "duplicate resource handle name — each binding name must be unique within a deployment"
+                      (
+                        issue: v.CheckIssue<
+                          {
+                            name: string;
+                            resource:
+                              | {
+                                  type: "dataset";
+                                  id: string;
+                                }
+                              | {
+                                  type: "canvas";
+                                  id: string;
+                                }
+                              | {
+                                  type: "media-library";
+                                  id: string;
+                                }
+                              | {
+                                  type: "dashboard";
+                                  id: string;
+                                };
+                          }[]
+                        >,
+                      ) => string
                     >,
                   ]
                 >,
@@ -9363,7 +9639,187 @@ declare const WorkflowConfigSchema: v.ObjectSchema<
               roleAliases?: RoleAliases | undefined;
             }[];
           }[],
-          "duplicate deployment tag — each deployment must use a unique tag"
+          (
+            issue: v.CheckIssue<
+              {
+                name: string;
+                expectedMinReaderModel?: 2 | undefined;
+                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;
+                  groups?: Group[] | undefined;
+                  lifecycle?: WorkflowLifecycle | undefined;
+                  start?: StartBlock | undefined;
+                  initialStage: string;
+                  fields?: FieldEntry[] | undefined;
+                  stages: Stage[];
+                  predicates?: Record<string, string> | undefined;
+                  roleAliases?: RoleAliases | undefined;
+                }[];
+              }[]
+            >,
+          ) => string
+        >,
+        v.CheckAction<
+          {
+            name: string;
+            expectedMinReaderModel?: 2 | undefined;
+            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;
+              groups?: Group[] | undefined;
+              lifecycle?: WorkflowLifecycle | undefined;
+              start?: StartBlock | undefined;
+              initialStage: string;
+              fields?: FieldEntry[] | undefined;
+              stages: Stage[];
+              predicates?: Record<string, string> | undefined;
+              roleAliases?: RoleAliases | undefined;
+            }[];
+          }[],
+          (
+            issue: v.CheckIssue<
+              {
+                name: string;
+                expectedMinReaderModel?: 2 | undefined;
+                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;
+                  groups?: Group[] | undefined;
+                  lifecycle?: WorkflowLifecycle | undefined;
+                  start?: StartBlock | undefined;
+                  initialStage: string;
+                  fields?: FieldEntry[] | undefined;
+                  stages: Stage[];
+                  predicates?: Record<string, string> | undefined;
+                  roleAliases?: RoleAliases | undefined;
+                }[];
+              }[]
+            >,
+          ) => string
         >,
       ]
     >;
@@ -9506,6 +9962,17 @@ export declare interface WorkflowEffectsDrainedData extends InstanceScopedEventD
   drainedEffects: EffectName[];
 }
 
+export declare const WorkflowEffectStateReported: WorkflowTelemetryEvent<WorkflowEffectStateReportedData>;
+
+export declare interface WorkflowEffectStateReportedData extends InstanceScopedEventData {
+  /** The reporting effect's author-chosen name — one of the payload policy's
+   *  two deliberate customer-string exceptions (module doc). */
+  effect: EffectName;
+  /** Auto-transitions fired during the post-report cascade — a report that
+   *  satisfies a transition moves the instance. */
+  cascaded: number;
+}
+
 /**
  * Base class of the engine's structured errors. `kind` is the stable
  * discriminant — render on it; `name` mirrors the concrete class for logs.
@@ -9538,6 +10005,9 @@ export declare type WorkflowErrorKind =
   | "concurrent-fire-action"
   | "concurrent-edit-field"
   | "concurrent-complete-effect"
+  | "concurrent-commit-effect-ops"
+  | "stale-effect-claim"
+  | "effect-commit-queue-overflow"
   | "cascade-limit"
   | "field-value-shape"
   | "ref-resource-undeclared"