@sanity/workflow-engine 0.17.0 → 0.19.0

package/dist/index.d.cts

@@ -40,17 +40,15 @@ export declare function abortReason(
 ): string | undefined;
 
 /**
- * The structured half of applicability: does a required subject entry
- * ({@link isSubjectEntry} — `doc.ref` / `doc.refs`, workflow scope) accept
- * `documentType`? Name-blind and EXISTENTIAL: ANY required ref entry counts —
- * a multi-input definition (say, contract + counterparty) surfaces from
- * either document's picker, and the start dialog collects the remaining
- * required entries (their fail-hard validation backstops). An entry without
- * `types` accepts any type; a definition with NO required ref entry takes no
- * subject and never matches. Cheap and indexable — no GROQ evaluation — so a
- * consumer can pre-filter before loading document content. (`required` is
- * pinned to caller-filled `input` entries by a deploy invariant, so it alone
- * identifies the handoff.)
+ * The structured half of applicability: does the definition's subject entry
+ * ({@link isSubjectEntry} — the `subject` kind, workflow scope, at most one
+ * by deploy invariant) accept `documentType`? The kind is the discriminator,
+ * so a definition surfaces from its SUBJECT's document picker and nowhere
+ * else; the start dialog collects the remaining required entries (their
+ * fail-hard validation backstops). A subject without `types` accepts any
+ * type; a definition with NO subject entry takes no subject and never
+ * matches. Cheap and indexable — no GROQ evaluation — so a consumer can
+ * pre-filter before loading document content.
  */
 export declare function acceptsDocumentType(
   definition: Pick<ApplicabilitySource, "fields">,
@@ -83,6 +81,11 @@ export declare type Action = ActionFields<Op, string[]> & {
   roles?: string[] | undefined;
 };
 
+export declare const ACTION_SEMANTICS: readonly [
+  "decision.accept",
+  "decision.decline",
+];
+
 /**
  * The engine's per-reason detail fragment — the same wording
  * {@link ActionDisabledError} embeds in its message. Exported so a dev-facing
@@ -124,6 +127,8 @@ export declare type ActionDisabledReason = Exclude<
 
 export declare interface ActionEvaluation {
   action: Action;
+  /** The action's advisory workflow meaning, unchanged from its definition. */
+  semantics?: ActionSemantic[] | undefined;
   allowed: boolean;
   /**
    * The action is cascade-fired (`when`): the engine fires it on truth, it
@@ -135,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;
@@ -147,6 +165,7 @@ export declare interface ActionEvaluation {
  *  group-membership grammars. */
 declare type ActionFields<TOp, TGroup> = {
   name: string;
+  semantics?: ActionSemantic[] | undefined;
   title?: string | undefined;
   description?: string | undefined;
   group?: TGroup | undefined;
@@ -168,36 +187,131 @@ export declare type ActionParam = v.InferOutput<typeof ActionParamSchema>;
  * effects: missing required params → ActionParamsInvalidError, action
  * does not commit. Resolved values feed `ValueExpr.param` lookups.
  */
-declare const ActionParamSchema: v.StrictObjectSchema<
-  {
-    readonly type: v.PicklistSchema<
-      readonly [
-        "string",
-        "number",
-        "boolean",
-        "url",
-        "dateTime",
-        "actor",
-        "doc.ref",
-        "doc.refs",
-        "json",
-      ],
-      `Invalid option: expected one of ${string}`
-    >;
-    readonly 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>,
+declare const ActionParamSchema: v.SchemaWithPipe<
+  readonly [
+    v.StrictObjectSchema<
+      {
+        readonly type: v.PicklistSchema<
+          readonly [
+            "string",
+            "number",
+            "boolean",
+            "url",
+            "dateTime",
+            "actor",
+            "doc.ref",
+            "doc.refs",
+            "json",
+          ],
+          `Invalid option: expected one of ${string}`
+        >;
+        readonly 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 required: v.OptionalSchema<
+          v.BooleanSchema<undefined>,
+          undefined
+        >;
+        readonly options: v.OptionalSchema<
+          v.GenericSchema<ChoiceOptions>,
+          undefined
+        >;
+        readonly validation: v.OptionalSchema<
+          v.GenericSchema<ScalarValidation>,
+          undefined
+        >;
+      },
       undefined
-    >;
-    readonly required: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
-  },
-  undefined
+    >,
+    v.CheckAction<
+      {
+        type:
+          | "string"
+          | "number"
+          | "boolean"
+          | "doc.ref"
+          | "doc.refs"
+          | "url"
+          | "actor"
+          | "dateTime"
+          | "json";
+        name: string;
+        title?: string | undefined;
+        description?: string | undefined;
+        required?: boolean | undefined;
+        options?: ChoiceOptions | undefined;
+        validation?: ScalarValidation | undefined;
+      },
+      (
+        issue: v.CheckIssue<{
+          type:
+            | "string"
+            | "number"
+            | "boolean"
+            | "doc.ref"
+            | "doc.refs"
+            | "url"
+            | "actor"
+            | "dateTime"
+            | "json";
+          name: string;
+          title?: string | undefined;
+          description?: string | undefined;
+          required?: boolean | undefined;
+          options?: ChoiceOptions | undefined;
+          validation?: ScalarValidation | undefined;
+        }>,
+      ) => string
+    >,
+    v.CheckAction<
+      {
+        type:
+          | "string"
+          | "number"
+          | "boolean"
+          | "doc.ref"
+          | "doc.refs"
+          | "url"
+          | "actor"
+          | "dateTime"
+          | "json";
+        name: string;
+        title?: string | undefined;
+        description?: string | undefined;
+        required?: boolean | undefined;
+        options?: ChoiceOptions | undefined;
+        validation?: ScalarValidation | undefined;
+      },
+      (
+        issue: v.CheckIssue<{
+          type:
+            | "string"
+            | "number"
+            | "boolean"
+            | "doc.ref"
+            | "doc.refs"
+            | "url"
+            | "actor"
+            | "dateTime"
+            | "json";
+          name: string;
+          title?: string | undefined;
+          description?: string | undefined;
+          required?: boolean | undefined;
+          options?: ChoiceOptions | undefined;
+          validation?: ScalarValidation | undefined;
+        }>,
+      ) => string
+    >,
+  ]
 >;
 
 /**
@@ -242,6 +356,8 @@ export declare function actionRendering(action: {
     | undefined;
 }): "absent" | "automation" | "button";
 
+export declare type ActionSemantic = (typeof ACTION_SEMANTICS)[number];
+
 /** The fireable-action verdict for one action on an activity — its `allowed`
  *  state, structured `disabledReason`, and declared params, tagged with the
  *  owning activity. The per-action atom both projections share:
@@ -459,6 +575,26 @@ export declare const ACTOR_KINDS: readonly ["person", "agent", "system"];
 
 export declare type ActorKind = (typeof ACTOR_KINDS)[number];
 
+export declare type ActorResolution<User> =
+  | {
+      readonly status: "resolved";
+      readonly actor: PersonActor;
+      readonly user: User;
+    }
+  | {
+      readonly status: "missing";
+      readonly actor: PersonActor;
+    }
+  | {
+      readonly status: "inaccessible";
+      readonly actor: PersonActor;
+      readonly cause?: unknown;
+    }
+  | {
+      readonly status: "not-person";
+      readonly actor: Actor;
+    };
+
 export { analyzeCondition };
 
 /** The definition surface the start contexts read — structural, so authored,
@@ -508,6 +644,11 @@ export declare function assertReadableModel<
   },
 >(doc: T): T;
 
+export declare function assertReaderModelAcknowledgement(
+  expectedMinReaderModel: unknown,
+  context?: string,
+): asserts expectedMinReaderModel is typeof DATA_MODEL_MIN_READER;
+
 /**
  * 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
@@ -1355,10 +1496,10 @@ export declare interface AvailableActionsResult {
 /**
  * Type each caller-supplied name→value against the workflow's declared field
  * entries — the engine takes typed {@link InitialFieldValue}s, and a value's
- * type IS its declared entry's kind. Only `input`-sourced entries read
- * caller values (the engine silently ignores the rest), so anything else
- * fails here, naming the fields that ARE settable; value validation stays
- * in the engine.
+ * type IS its declared entry's kind. Only `input`-sourced entries read caller
+ * values, so anything else fails here, naming the fields that ARE settable.
+ * The engine repeats this structural validation at its contract boundary;
+ * value validation also stays there.
  */
 export declare function buildInitialFields({
   declared,
@@ -1422,6 +1563,17 @@ export declare interface ChildrenArgs extends InstanceRefArgs {
   activity?: string;
 }
 
+export declare interface ChoiceOption {
+  title: string;
+  value: ChoiceValue;
+}
+
+export declare interface ChoiceOptions {
+  list: ChoiceOption[];
+}
+
+export declare type ChoiceValue = string | number;
+
 /**
  * The action half of the mirrored claim pair. `field` references an
  * author-declared actor-valued entry (the pair's other half), resolved
@@ -1482,6 +1634,21 @@ export declare function clientConfigFromResource(res: WorkflowResource):
  *  resolves to a client, or the router throws. */
 declare type ClientForGdr = (parsed: ParsedGdr) => WorkflowClient;
 
+/** Native project-user response returned by Sanity's project API. */
+export declare interface ClientProjectUser {
+  readonly id: string;
+  readonly displayName?: string;
+  readonly email?: string;
+  readonly imageUrl?: string | null;
+  readonly [key: string]: unknown;
+}
+
+/** Project-user directory for CLI, MCP, and server runtimes using the engine client. */
+export declare function clientProjectUserDirectory(
+  client: WorkflowClient,
+  projectId: string,
+): ProjectUserDirectory<ClientProjectUser>;
+
 /**
  * The engine's single source of "now".
  *
@@ -1518,6 +1685,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 };
 
 /**
@@ -1595,6 +1798,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 —
@@ -1949,7 +2166,9 @@ export declare class ContractViolationError extends WorkflowError<"contract-viol
  * `completeEffect` — the runtime still decides when to drain and
  * reports outcomes via `completeEffect`.
  */
-export declare function createEngine(args: CreateEngineArgs): Engine;
+export declare function createEngine<Client extends WorkflowClient>(
+  args: CreateEngineArgs<Client>,
+): Engine;
 
 /**
  * The {@link EngineScopeArgs} scope pinned at construction, plus the
@@ -1959,8 +2178,11 @@ export declare function createEngine(args: CreateEngineArgs): Engine;
  * partition is the only thing keeping reads and writes off the wrong
  * environment.
  */
-export declare interface CreateEngineArgs extends EngineScopeArgs {
-  effectHandlers?: Record<string, EffectHandler>;
+export declare interface CreateEngineArgs<
+  Client extends WorkflowClient = WorkflowClient,
+> extends EngineScopeArgs {
+  client: Client;
+  effectHandlers?: Record<string, EffectHandler<Client>>;
   missingHandler?: MissingHandlerPolicy;
   loggerFactory?: LoggerFactory;
   /**
@@ -2012,19 +2234,88 @@ export declare function createTelemetryIntake(args: {
 }): TelemetryIntake;
 
 /**
- * The reader floor the current model imposes — the compatibility half of
- * {@link MODEL_STAMP}, stamped as `minReaderModel`: the oldest engine model
- * that can safely interpret a document written at {@link DATA_MODEL_VERSION}.
- * An additive change leaves it untouched (older engines read newer docs
- * fine — mixed fleets of Functions, Studios, and CLIs are the steady state);
- * ONLY a breaking shape change raises it, and doing so is a declared,
- * DATAMODEL.md-logged decision to fence out older readers.
+ * The append-only, machine-readable counterpart of the model log in
+ * `DATAMODEL.md`. It records compatibility decisions; the prose log retains
+ * the reasoning, absent-value semantics, and old-writer round-trip proof.
+ */
+export declare const DATA_MODEL_CHANGES: readonly [
+  Readonly<{
+    id: "governed-model-stamps";
+    introducedInModel: 1;
+    minReaderModel: 0;
+    documentTypes: readonly ["definition", "instance"];
+    compatibility: "additive";
+    applicability: "unconditional";
+    summary: "Definition and instance documents carry model provenance and reader-floor stamps.";
+  }>,
+  Readonly<{
+    id: "subject-field-kind";
+    introducedInModel: 2;
+    minReaderModel: 0;
+    documentTypes: readonly ["definition", "instance"];
+    compatibility: "additive";
+    applicability: "detectable";
+    summary: "A workflow-level subject field identifies the document a workflow is about.";
+  }>,
+  Readonly<{
+    id: "typed-scalar-choice-lists";
+    introducedInModel: 2;
+    minReaderModel: 2;
+    documentTypes: readonly ["definition", "instance"];
+    compatibility: "reader-floor";
+    applicability: "detectable";
+    summary: "Scalar fields may constrain writes to a persisted typed choice list.";
+  }>,
+  Readonly<{
+    id: "action-semantics";
+    introducedInModel: 2;
+    minReaderModel: 0;
+    documentTypes: readonly ["definition"];
+    compatibility: "additive";
+    applicability: "detectable";
+    summary: "Ordinary actions may carry a closed bag of advisory workflow semantics.";
+  }>,
+  Readonly<{
+    id: "inclusive-scalar-bounds";
+    introducedInModel: 2;
+    minReaderModel: 2;
+    documentTypes: readonly ["definition", "instance"];
+    compatibility: "reader-floor";
+    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.";
+  }>,
+];
+
+/**
+ * The maximum reader floor this writer can emit. Individual documents derive
+ * their `minReaderModel` from the compatibility-bearing features actually
+ * present; a document written at {@link DATA_MODEL_VERSION} may therefore
+ * carry a lower floor. Raising this maximum is a declared, DATAMODEL.md-logged
+ * decision that requires readers-first fleet sequencing.
  */
-export declare const DATA_MODEL_MIN_READER = 0;
+export declare const DATA_MODEL_MIN_READER = 2;
 
 /**
  * The engine's persisted data-model version — the provenance half of
- * {@link MODEL_STAMP}, stamped as `modelVersion` on every engine-owned
+ * the model stamp, written as `modelVersion` on every engine-owned
  * document at its construction and persist choke-points. Conforms-to
  * semantics: the stamp means "this document conforms to model N now" —
  * instances are re-stamped on every full persist, so mixed-version fleets
@@ -2035,7 +2326,19 @@ export declare const DATA_MODEL_MIN_READER = 0;
  * job. Declare every bump in `DATAMODEL.md`; the model-surface snapshot test
  * keeps undeclared drift red.
  */
-export declare const DATA_MODEL_VERSION = 1;
+export declare const DATA_MODEL_VERSION = 3;
+
+export declare interface DataModelChange {
+  readonly id: string;
+  readonly introducedInModel: number;
+  readonly minReaderModel: number;
+  readonly documentTypes: readonly DataModelDocumentType[];
+  readonly compatibility: "additive" | "reader-floor";
+  readonly applicability: "unconditional" | "detectable";
+  readonly summary: string;
+}
+
+export declare type DataModelDocumentType = "definition" | "instance";
 
 /**
  * Split a dataset resource id (`<projectId>.<dataset>`) into its parts — the
@@ -2056,9 +2359,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 {
   /**
@@ -2211,6 +2515,10 @@ export declare interface DefinitionsForDocumentArgs {
    * perspective the caller loaded the document with.
    */
   document: CandidateDocument;
+  /** Resource-qualified identity of `document`. Required when an applicable
+   *  definition's `start.filter` reads `$subjectHasInFlightInstance`; the
+   *  loaded value's bare `_id` cannot distinguish resources. */
+  subject?: GdrUri;
 }
 
 /** A definition-level site address: every runtime {@link InsightSite}, plus
@@ -2335,6 +2643,8 @@ export declare interface DeployDefinitionResult {
 export declare interface DeployDefinitionsArgs<
   T extends WorkflowDefinitionInput<T> = WorkflowDefinition,
 > {
+  /** Reviewed literal acknowledging the installed writer's maximum reader-floor capability. */
+  expectedMinReaderModel: typeof DATA_MODEL_MIN_READER;
   /**
    * Resource-alias bindings for this deploy (alias name → physical resource).
    * A deploy-time abstraction ONLY: every `@<alias>:` reference in a
@@ -2392,7 +2702,7 @@ export declare type DeployedDefinition = WorkflowDefinition & {
  *
  * An aborted instance also no-ops: it parks on its stage forever, so a stale
  * deploy landing after abort's retract would re-lock the subjects with no
- * remaining path to lift them. The gate is `abortedAt`, not `completedAt` —
+ * remaining path to delete them. The gate is `abortedAt`, not `completedAt` —
  * a normal move *into* a terminal stage stamps `completedAt` in the same
  * persist and must still deploy that stage's guards.
  */
@@ -2404,6 +2714,7 @@ export declare function deployStageGuards(args: StageGuardArgs): Promise<void>;
  *  definitions themselves — carrying `resourceAliases` here is what keeps a diff
  *  fingerprinting the same physical content `deployDefinitions` would. */
 export declare interface DeployTarget {
+  expectedMinReaderModel: typeof DATA_MODEL_MIN_READER;
   tag: string;
   workflowResource: WorkflowResource;
   resourceAliases?: ResourceAliases;
@@ -2746,7 +3057,7 @@ export declare type DisabledReason =
       /**
        * The actor's grants on an involved subject's resource don't allow the
        * content write the action's effects would perform there. Forecast
-       * per-resource: each subject named by a `doc.ref`/`doc.refs`/`release.ref`
+       * per-resource: each subject named by a `doc.ref`/`subject`/`doc.refs`/`release.ref`
        * field entry outside the workflow's own resource is checked against
        * THAT resource's ACL. Advisory like every engine verdict — the subject's
        * lake still enforces; and it degrades open: a resource whose grants
@@ -2941,6 +3252,7 @@ export declare interface EditableFieldEvaluation {
   name: string;
   type: FieldKind;
   title?: string;
+  validation?: ScalarValidation;
   /** Current resolved value; `undefined` until the field is first resolved. */
   value: unknown;
   /** Whether THIS actor may edit the field right now (window + predicate + guard). */
@@ -3055,6 +3367,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`
@@ -3064,6 +3386,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. */
@@ -3072,6 +3410,20 @@ export declare type EffectCompletionStatus = Exclude<
   "cancelled"
 >;
 
+export declare type EffectHandler<
+  Client extends WorkflowClient = WorkflowClient,
+> = {
+  /** Bivariant so a concretely typed handler registry remains readable from
+   * the non-generic Engine surface; only the typed drain invokes handlers. */
+  bivarianceHack(
+    params: Record<string, unknown>,
+    ctx: EffectHandlerContext<Client>,
+  ): Promise<{
+    outputs?: Record<string, unknown>;
+    ops?: FieldOp[];
+  } | void>;
+}["bivarianceHack"];
+
 /**
  * External effect handler — invoked at drain time with the resolved
  * `params` and a context. Returning `outputs` records them on the run's
@@ -3082,8 +3434,10 @@ export declare type EffectCompletionStatus = Exclude<
  * applier as an action's field ops (so a created doc's ref enters `$fields`, or
  * a screened outcome lands in a field the activity/stage gate reads). Effects
  * report results as field state, never by flipping an activity status, so `ops`
- * excludes `status.set`. Throwing marks the effect as failed (and returns no
- * `ops`).
+ * excludes `status.set`. Unlike definition-authored field ops, completion ops
+ * have no authoring location from which to infer a target scope: every returned
+ * op must explicitly set `target.scope` to `'workflow'` or `'stage'`. Throwing
+ * marks the effect as failed (and returns no `ops`).
  *
  * **Delivery is at-least-once — a handler MAY run more than once for the
  * same effect.** Two overlaps produce a double-run: the dispatching process
@@ -3101,38 +3455,66 @@ export declare type EffectCompletionStatus = Exclude<
  * already completed; derive external-system identifiers from `ctx.effectKey`
  * so the receiving system can dedupe the overlap the ledger can't see.
  */
-export declare type EffectHandler = (
-  params: Record<string, unknown>,
-  ctx: {
-    /** The engine's own client — bound to the workflow resource the
-     *  instance lives in. Use it for same-resource subjects; for a
-     *  cross-resource subject, route through {@link clientFor} instead. */
-    client: WorkflowClient;
-    /**
-     * Resolve the client bound to a subject doc's own resource. A handler
-     * patches the SUBJECT (which may live in a different Sanity resource
-     * than the instance — split-dataset GDR deploys); the drainer's
-     * `completeEffect` writes the INSTANCE through {@link client}. One
-     * client can't address both, so a handler that patches a foreign
-     * subject must route its write here.
-     *
-     * Pass the subject's GDR — the URI a binding like `$fields.subject._id`
-     * resolves to (the hydrated doc's `_id`), or a full
-     * {@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. Throws if `ref` isn't a GDR — a bare id can't
-     * be routed, so failing loud beats silently patching the wrong dataset.
-     */
-    clientFor: (ref: GdrUri | GlobalDocumentReference) => WorkflowClient;
-    instanceId: string;
-    effectKey: string;
-    log: (message: string, extra?: Record<string, unknown>) => void;
-  },
-) => Promise<{
-  outputs?: Record<string, unknown>;
-  ops?: FieldOp[];
-} | void>;
+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.
+   */
+  client: Client;
+  /**
+   * Resolve the client bound to a subject doc's own resource. A handler
+   * patches the SUBJECT (which may live in a different Sanity resource
+   * than the instance — split-dataset GDR deploys); the drainer's
+   * `completeEffect` writes the INSTANCE through {@link client}. One
+   * client can't address both, so a handler that patches a foreign
+   * subject must route its write here.
+   *
+   * Pass the subject's GDR — the URI a binding like `$fields.subject._id`
+   * resolves to (the hydrated doc's `_id`), or a full
+   * {@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.
+   * Throws if `ref` isn't a GDR — a bare id can't
+   * be routed, so failing loud beats silently patching the wrong dataset.
+   */
+  clientFor: (ref: GdrUri | GlobalDocumentReference) => 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 {
   _key: string;
@@ -3320,6 +3702,10 @@ export declare interface Engine {
   /** The resolved telemetry logger ({@link noopTelemetry} unless injected) —
    *  exposed so adapters built on the engine log through the same seam. */
   readonly telemetry: WorkflowTelemetryLogger;
+  /** Resolve durable actor provenance through this engine's project client. */
+  resolveActor: (
+    args: ResolveClientActorArgs,
+  ) => Promise<ActorResolution<ClientProjectUser>>;
   deployDefinitions: <T extends WorkflowDefinitionInput<T>>(
     args: DeployDefinitionsArgs<T>,
   ) => Promise<DeployDefinitionsResult>;
@@ -3329,6 +3715,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. */
@@ -3351,7 +3741,7 @@ export declare interface Engine {
   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
+   *  named by `doc.ref`/`subject`/`doc.refs`/`release.ref` field entries on the workflow scope
    *  + current stage) as exploded {@link SubscriptionDocument}s, plus the
    *  instance's read perspective. Fetches the instance, then derives. A
    *  reactive adapter that already holds the live instance calls the pure
@@ -3366,8 +3756,9 @@ export declare interface Engine {
    *  its own; the consumer drives it. */
   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. */
+   *  instance's own resource and the resource of each
+   *  `doc.ref`/`subject`/`doc.refs` GDR it holds in state. For coherency
+   *  refresh and housekeeping. */
   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
@@ -3386,14 +3777,14 @@ export declare interface Engine {
    *  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`)
+   *  watch-set uses (self, ancestors, current-stage `doc.ref`/`subject`/`doc.refs`/`release.ref`)
    *  via the shared `collectWatchRefs`. Sorted by `startedAt` asc. */
   instancesForDocument: (
     args: InstancesForDocumentArgs,
   ) => Promise<WorkflowInstance[]>;
   /** The startable half of {@link Engine.instancesForDocument}: the latest
    *  deployed version of every definition that applies to the LOADED candidate
-   *  document — startable, a required subject entry accepts its `_type`, and
+   *  document — startable, the `subject`-kind entry accepts its `_type`, and
    *  `start.filter` (browse-time-pure — `$fields` never binds) passes. All
    *  matches, name ascending; advisory — a start picker's filter, never
    *  enforcement. */
@@ -3401,9 +3792,10 @@ export declare interface Engine {
     args: DefinitionsForDocumentArgs,
   ) => Promise<DeployedDefinition[]>;
   /** Pre-flight `startInstance`'s gates for a definition + the
-   *  `initialFields` gathered so far: the `start.allowed` verdict with its
-   *  insight (disable the start affordance on a definitive false AND say
-   *  why) plus the still-missing required inputs. Bindability-aware — a
+   *  `initialFields` gathered so far: structurally invalid rows, the
+   *  `start.allowed` verdict with its insight, and still-missing required
+   *  inputs. `allowed` is the overall startability signal; `outcome` describes
+   *  only the condition. Bindability-aware — a
    *  predicate reading a not-yet-supplied entry reports `'unevaluable'`
    *  with the entries named in `unboundReads`, never a collapsed verdict.
    *  Pure read; the enforcement moment is `startInstance` itself. */
@@ -3452,8 +3844,9 @@ export declare interface Engine {
  * housekeeping exports — derives its working client onto this version via
  * {@link WorkflowClient.withConfig}, and `resourceClients`-resolved clients
  * are rebound the same way. A caller's configured `apiVersion` therefore
- * never reaches engine traffic (the caller's own client instance is
- * untouched). The one exception is a client that lacks `withConfig` and so
+ * 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}.
  */
@@ -3520,9 +3913,9 @@ export declare interface EngineScopeArgs {
 
 /**
  * Pull the {@link GlobalDocumentReference} values out of `doc.ref` /
- * `doc.refs` (content) field entries. Content only — release field entries come
- * from {@link entryReleaseRefs}, so guard discovery (which reads this via
- * `collectEntryDocUris`) stays scoped to content docs.
+ * `subject` / `doc.refs` (content) field entries. Content only — release
+ * field entries come from {@link entryReleaseRefs}, so guard discovery (which
+ * reads this via `collectEntryDocUris`) stays scoped to content docs.
  */
 export declare function entryDocRefs(
   entries: unknown,
@@ -3648,14 +4041,15 @@ export declare interface EvaluateStartArgs {
  * Evaluate one `start.filter` in the start-filter context: `document` (may
  * be absent — a root read is then GROQ null, fail-closed or vacuous-pass by
  * shape) as the GROQ root, the {@link StartScope} bindings plus
- * `$definition`, and — only when
- * `analyzeCondition` says the filter reads the dataset — the scope's fetched
- * slice as `*`. Cheap pure evaluation otherwise: no I/O rides a filter that
- * never scans. GROQ null ("can't decide") is `false` — every consumer of
+ * `$definition`, and — when `analyzeCondition` says the filter reads the
+ * dataset or the filter reads `$subjectHasInFlightInstance` — the scope's
+ * fetched slice as `*`. Cheap pure evaluation otherwise: no I/O rides a
+ * filter that needs neither. GROQ null ("can't decide") is `false` — every consumer of
  * this verdict fails closed; a parse/evaluation THROW is a malformed
- * predicate, not an unevaluable one — rethrown loud, naming the definition
- * (only writable by bypassing deploy validation), so every read surface that
- * evaluates the filter reports the same context. A failed slice FETCH
+ * predicate, not an unevaluable one — rethrown loud, naming the definition,
+ * so every read surface that evaluates the filter reports the same context.
+ * A caller that omits the prospective subject required by the synthetic
+ * variable also throws as a scope-contract error. A failed slice FETCH
  * propagates as itself: transport trouble, never definition blame.
  */
 export declare function evaluateStartFilter(args: {
@@ -3744,6 +4138,30 @@ export declare const EXECUTOR_CLASSIFICATIONS: readonly [
 export declare type ExecutorClassification =
   (typeof EXECUTOR_CLASSIFICATIONS)[number];
 
+/**
+ * Expand every `@<alias>:` reference in a definition to the physical GDR prefix
+ * its alias binds to, returning a definition that carries only physical
+ * references. Fails closed — naming the definition + alias — when a referenced
+ * alias isn't bound: the check that stops a portable definition from deploying
+ * against the wrong (or no) resource.
+ *
+ * Runs at deploy (inside {@link planDefinitionDeploy}), BEFORE the content
+ * fingerprint, so a deployed definition never carries a logical alias. The
+ * stored references are physical, and a rebind (same source, a different alias
+ * map) surfaces as changed content — a new version, never a silent shift in what
+ * the workflow reads. A no-op when the definition references no aliases.
+ *
+ * Rewrites string VALUES only (via the shared {@link mapJsonStrings} deep-walk),
+ * skipping the prose fields in {@link PROSE_KEYS}. A reference that stands alone
+ * (the whole value is `@<alias>:<id>`, e.g. a literal `doc.ref`) must expand to a
+ * well-formed GDR — a malformed one (`@content:a:b`, an empty id) is rejected
+ * here rather than failing when an instance later reads it.
+ */
+export declare function expandResourceAliases(
+  definition: WorkflowDefinition,
+  resourceAliases: ResourceAliases | undefined,
+): WorkflowDefinition;
+
 export { explainCondition };
 
 export { ExplainConditionArgs };
@@ -3769,7 +4187,7 @@ export { ExplainConditionArgs };
  */
 export declare function explainStartAllowed(args: {
   allowed: string;
-  definition: Pick<ApplicabilitySource, "name">;
+  definition: Pick<ApplicabilitySource, "name" | "fields">;
   /** The caller's input entries as a `$fields` map — the engine verbs build
    *  it with `startFieldsParam` (field resolution's projection), so the
    *  predicate can only see values the resolution would persist. */
@@ -3819,6 +4237,10 @@ export declare const FIELD_KIND_DISPLAY: {
     title: string;
     description: string;
   };
+  subject: {
+    title: string;
+    description: string;
+  };
   "release.ref": {
     title: string;
     description: string;
@@ -3835,6 +4257,10 @@ export declare const FIELD_KIND_DISPLAY: {
     title: string;
     description: string;
   };
+  progress: {
+    title: string;
+    description: string;
+  };
   boolean: {
     title: string;
     description: string;
@@ -3887,10 +4313,12 @@ declare const FIELD_SCOPES: readonly ["workflow", "stage", "activity"];
 declare const FIELD_VALUE_KINDS: readonly [
   "doc.ref",
   "doc.refs",
+  "subject",
   "release.ref",
   "string",
   "text",
   "number",
+  "progress",
   "boolean",
   "date",
   "datetime",
@@ -3930,6 +4358,8 @@ declare type FieldEntryFields<TEditable, TGroup> = FieldBase<
   TGroup
 > & {
   type: FieldValueKind;
+  options?: ChoiceOptions | undefined;
+  validation?: ScalarValidation | undefined;
   types?: string[] | undefined;
   fields?: FieldShape[] | undefined;
   of?: FieldShape[] | undefined;
@@ -3985,6 +4415,8 @@ export declare interface FieldShape {
   name: string;
   title?: string | undefined;
   description?: string | undefined;
+  options?: ChoiceOptions | undefined;
+  validation?: ScalarValidation | undefined;
   fields?: FieldShape[] | undefined;
   of?: FieldShape[] | undefined;
 }
@@ -4018,11 +4450,19 @@ declare type FieldValueKind = (typeof FIELD_VALUE_KINDS)[number];
 export declare interface FieldValueMap {
   "doc.ref": GlobalDocumentReference | null;
   "doc.refs": GlobalDocumentReference[];
+  /** THE document the workflow is about — same value as
+   *  {@link FieldValueMap."doc.ref"}, distinct kind so the runtime and UI
+   *  identify the subject deterministically (workflow scope, at most one). */
+  subject: GlobalDocumentReference | null;
   "release.ref": ReleaseRef | null;
   string: string | null;
   /** 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;
@@ -4120,6 +4560,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 };
 
 /**
@@ -4354,9 +4808,6 @@ export declare type Guard = v.InferOutput<typeof GuardSchema>;
  */
 export declare const GUARD_DOC_TYPE = "temp.system.guard";
 
-/** Retracted predicate — unconditionally allows, lifting the guard. */
-export declare const GUARD_LIFTED_PREDICATE = "true";
-
 export declare const GUARD_OWNER = "robot:workflow-engine";
 
 /**
@@ -4955,6 +5406,67 @@ export declare interface HydratedSnapshot {
  */
 export declare function inFlightFilter(): string;
 
+/** Why one caller-supplied initial-field row cannot be consumed. */
+export declare type InitialFieldIssue = {
+  index: number;
+  name: string;
+  type: FieldKind;
+} & (
+  | {
+      reason: "duplicate";
+      duplicateIndexes: number[];
+    }
+  | {
+      reason: "undeclared";
+    }
+  | {
+      reason: "wrong-kind";
+      expectedTypes: FieldKind[];
+    }
+  | {
+      reason: "not-input";
+      source:
+        | "working-memory"
+        | Exclude<NonNullable<FieldEntry["initialValue"]>["type"], "input">;
+    }
+  | ({
+      reason: "invalid-scope";
+      stage: string;
+      declaredType: FieldKind;
+    } & (
+      | {
+          scope: "stage";
+        }
+      | {
+          scope: "activity";
+          activity: string;
+        }
+    ))
+);
+
+/**
+ * Explain every structural reason caller-supplied initial-field rows cannot
+ * be consumed. Value-shape validation remains in the resolver because it
+ * needs the matched declaration's complete schema.
+ */
+export declare function initialFieldIssues(
+  args: ScopedInitialFieldDeclarations & {
+    initialFields: readonly InitialFieldValue[];
+  },
+): InitialFieldIssue[];
+
+/**
+ * Thrown before start writes when one or more caller-supplied `initialFields`
+ * rows cannot be consumed by workflow-scope, input-sourced declarations.
+ * `issues` is stable machine-readable remediation context; the message renders
+ * the same complete set for logs and command-line callers.
+ */
+export declare class InitialFieldsInvalidError extends WorkflowError<"initial-fields-invalid"> {
+  readonly definition?: string;
+  readonly issues: InitialFieldIssue[];
+  constructor(args: { definition?: string; issues: InitialFieldIssue[] });
+}
+
 /**
  * Initial value for an `input`-sourced entry — what a caller supplies at
  * `startInstance` (or `setStage`). Same discriminator shape as
@@ -5020,8 +5532,8 @@ export declare function instanceDocId(tag: string): string;
  * ({@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. Matches lifted guards too (predicate
- * `"true"`) — the consumer decides how to render a lifted guard.
+ * datasources for housekeeping. Ordinary stage retraction deletes guards, so
+ * results represent active persisted guard documents.
  */
 export declare function instanceGuardQuery(instanceId: string): CompiledQuery;
 
@@ -5265,13 +5777,14 @@ export declare function isFilterScopedOut(entry: {
 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.
+ * Whether an entry is caller-filled at start/spawn — the only source that
+ * reads `initialFields`. Every other source (query/literal/fieldRead, or
+ * working memory) resolves itself at materialisation, so a `$fields.<name>`
+ * read of it can never bind on any read surface that evaluates a
+ * `start.filter`. The deploy read-check keys on this.
  */
-export declare function isGuardLifted(
-  guard: Pick<MutationGuardDoc, "predicate">,
+export declare function isInputSourced(
+  entry: Pick<FieldEntry, "initialValue">,
 ): boolean;
 
 /**
@@ -5295,6 +5808,32 @@ export declare function isNotesEntry(
   }
 >;
 
+/** Whether a project-user API failure explicitly means the user is absent. */
+export declare function isProjectUserNotFoundError(error: unknown): boolean;
+
+/** Entry-level {@link isSingleDocRefKind}: narrows a resolved entry to the
+ *  single-GDR arms (`doc.ref` / `subject`) — the value is one GDR (or null)
+ *  and the entry may carry the accepted-target `types`. */
+export declare function isSingleDocRefEntry(
+  entry: ResolvedFieldEntry,
+): entry is Extract<
+  ResolvedFieldEntry,
+  {
+    _type: "doc.ref" | "subject";
+  }
+>;
+
+/**
+ * Kinds whose value is a single content-document GDR — `doc.ref` and its
+ * elevated alias `subject`. The one predicate behind every "this entry is one
+ * document reference" branch (deref reads, query/spawn ref coercion, input
+ * shape checks, watch-set collection), so the alias can't drift out of a
+ * site.
+ */
+export declare function isSingleDocRefKind(
+  kind: string,
+): kind is "doc.ref" | "subject";
+
 /**
  * Whether a human may start this definition standalone (the default). A
  * `lifecycle: 'child'` definition is spawn-only — instantiated by a parent via
@@ -5308,15 +5847,16 @@ export declare function isStartableDefinition(definition: {
 }): boolean;
 
 /**
- * The SUBJECT-ENTRY RULE: a required `doc.ref` / `doc.refs` input entry is
- * what makes a definition "about" a subject document. One predicate shared by
- * applicability's type matching (`acceptsDocumentType`), the autonomous-start
- * deploy invariant, and the root-read deploy check (a root-reading
- * `start.filter` needs a subject entry to bind a candidate root) — so
- * "counts as a subject" can't drift between them.
+ * The SUBJECT-ENTRY RULE: the `subject`-kind entry is what makes a definition
+ * "about" a subject document — the kind is the discriminator, never a
+ * heuristic over required refs. One predicate shared by applicability's type
+ * matching (`acceptsDocumentType`), the autonomous-start deploy invariant,
+ * and the root-read deploy check (a root-reading `start.filter` needs a
+ * subject entry to bind a candidate root) — so "counts as a subject" can't
+ * drift between them.
  */
 export declare function isSubjectEntry(
-  entry: Pick<FieldEntry, "required" | "type">,
+  entry: Pick<FieldEntry, "type">,
 ): boolean;
 
 /**
@@ -5445,6 +5985,15 @@ export declare interface LoadedDoc {
 
 export declare type LoggerFactory = (name: string) => EngineLogger;
 
+/** A by-name reference to another workflow definition (an
+ *  `action.spawn.definition`). No `version` (or `'latest'`) means "the
+ *  highest deployed version at spawn time"; a numeric version pins one
+ *  deployed version permanently. */
+export declare interface LogicalRef {
+  name: string;
+  version?: number | "latest";
+}
+
 export declare type ManualTarget = v.InferOutput<
   typeof StoredManualTargetSchema
 >;
@@ -5471,7 +6020,7 @@ export { MAX_COUNTERFACTUAL_INDEX };
 
 /**
  * The oldest engine model that can safely read a persisted engine document.
- * The engine always writes the {@link MODEL_STAMP} pair, so a `modelVersion`
+ * The engine always writes the stamp pair, so a `modelVersion`
  * with no `minReaderModel` is malformed foreign data — read conservatively:
  * the stamp itself is the floor. A doc with neither is model 0 (floor 0).
  */
@@ -5818,12 +6367,7 @@ export declare function parseDefinitionInput(
   caller: string,
 ): WorkflowDefinition;
 
-/**
- * The ONE way to read an instance's frozen {@link WorkflowInstance.definitionSnapshot}
- * back into a {@link WorkflowDefinition} — wraps the parse so a corrupt
- * snapshot fails with the instance id attached instead of a bare
- * `SyntaxError`.
- */
+/** Parse the frozen definition from a complete persisted instance. */
 export declare function parseDefinitionSnapshot(
   instance: WorkflowInstance,
 ): WorkflowDefinition;
@@ -5840,6 +6384,11 @@ export declare interface ParsedGdr {
   documentId: string;
 }
 
+declare type ParsedWorkflowConfig = v.InferOutput<typeof WorkflowConfigSchema>;
+
+declare type ParsedWorkflowDeployment =
+  ParsedWorkflowConfig["deployments"][number];
+
 /**
  * Parse a GDR URI into its scheme + addressing parts. Throws on
  * unknown scheme or malformed shape.
@@ -5949,6 +6498,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;
 }
 
 /**
@@ -5971,6 +6530,10 @@ export declare class PersistedDocShapeError extends WorkflowError<"persisted-doc
   });
 }
 
+export declare type PersonActor = Omit<Actor, "kind"> & {
+  readonly kind: "person";
+};
+
 /**
  * One row of the instance's idempotency ledger — a caller-supplied
  * `idempotencyKey` a state-changing verb already committed under. Recorded in
@@ -6010,6 +6573,15 @@ 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
@@ -6030,6 +6602,26 @@ export declare function projectToWatchRef(args: {
   perspective: WorkflowPerspective | undefined;
 }): SanityDocument;
 
+/** Host integration for current project-user data. */
+export declare interface ProjectUserDirectory<User> {
+  /** Return `inaccessible` for lookup failures; directory methods must not reject. */
+  readonly findById: (id: string) => Promise<ProjectUserLookup<User>>;
+  readonly findByEmail?: (email: string) => Promise<ProjectUserLookup<User>>;
+}
+
+export declare type ProjectUserLookup<User> =
+  | {
+      readonly status: "resolved";
+      readonly user: User;
+    }
+  | {
+      readonly status: "missing";
+    }
+  | {
+      readonly status: "inaccessible";
+      readonly cause?: unknown;
+    };
+
 export declare interface QueryArgs {
   groq: string;
   params?: Record<string, unknown>;
@@ -6039,6 +6631,20 @@ export declare interface QueryInScopeArgs extends InstanceRefArgs, QueryArgs {}
 
 export { quoted };
 
+export declare const READER_MODEL_ROLLOUT_URL =
+  "https://github.com/sanity-io/workflows/blob/main/docs/reader-model-rollout.md";
+
+/** A producer has not explicitly acknowledged this engine's writer capability. */
+export declare class ReaderModelAcknowledgementError extends WorkflowError<"reader-model-acknowledgement"> {
+  readonly code = "WORKFLOW_READER_MODEL_ACKNOWLEDGEMENT_MISMATCH";
+  readonly expectedMinReaderModel: unknown;
+  readonly engineMinReaderModel = 2;
+  readonly engineModelVersion = 3;
+  readonly documentationUrl =
+    "https://github.com/sanity-io/workflows/blob/main/docs/reader-model-rollout.md";
+  constructor(expectedMinReaderModel: unknown, context?: string);
+}
+
 /**
  * The one spelling of the instance read discipline — model gate
  * ({@link assertReadableModel}) first, shape parse
@@ -6097,6 +6703,15 @@ export declare function refDataset<TType extends string = string>({
   type: TType;
 }): GlobalDocumentReference<TType>;
 
+/**
+ * Kinds whose entries carry the accepted-target `types` facet — the
+ * content-document reference kinds. `release.ref` is excluded: it points at a
+ * release system doc whose type is fixed.
+ */
+export declare function refKindAcceptsTypes(
+  kind: string,
+): kind is "doc.ref" | "doc.refs" | "subject";
+
 /** Make a GDR pointer to a Media-Library-resource doc. */
 export declare function refMediaLibrary<TType extends string = string>({
   resourceId,
@@ -6117,15 +6732,24 @@ export declare class RefResourceUndeclaredError extends WorkflowError<"ref-resou
 }
 
 /**
- * The GDR `type`s in a `doc.ref` / `doc.refs` value that the entry's declared
- * accepted `types` reject — empty when the value conforms, the entry declares
- * no `types`, or the kind isn't a ref. A GDR's `type` names the target
- * document's schema type, so this is the declared-subject-type contract.
- * Skips anything that isn't GDR-shaped — the shape schemas scream about
- * those. Boundaries that need their own error framing (the spawn `with`
- * projection gates its remediation hint on the generic `"document"` type
- * being among the rejects) read this; everything else goes through
- * {@link refTypeIssues} / {@link checkFieldValue}.
+ * Every spawn reference a definition carries, as logical
+ * {@link LogicalRef} entries — the definition's outgoing edges in the
+ * spawn-dependency graph. The one walk deploy ordering, delete's
+ * referrer check, and external dependency tooling all share, so what
+ * counts as a reference can never drift between them.
+ */
+export declare function refsOf(def: WorkflowDefinition): LogicalRef[];
+
+/**
+ * The GDR `type`s in a reference-kind ({@link refKindAcceptsTypes}) value
+ * that the entry's declared accepted `types` reject — empty when the value
+ * conforms, the entry declares no `types`, or the kind isn't a ref. A GDR's
+ * `type` names the target document's schema type, so this is the
+ * declared-target-type contract. Skips anything that isn't GDR-shaped — the
+ * shape schemas scream about those. Boundaries that need their own error
+ * framing (the spawn `with` projection gates its remediation hint on the
+ * generic `"document"` type being among the rejects) read this; everything
+ * else goes through {@link refTypeIssues} / {@link checkFieldValue}.
  */
 export declare function rejectedRefTypes(args: {
   entryType: string;
@@ -6213,12 +6837,18 @@ export declare class RequiredFieldNotProvidedError extends WorkflowError<"requir
   });
 }
 
-/**
- * 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}.
- */
+/** The known persisted-model requirements applicable to one canonical stored tree. */
+export declare function requiredModelFeatures(
+  documentType: DataModelDocumentType,
+  document: unknown,
+): readonly DataModelChange[];
+
+/** The oldest engine model that can safely interpret one canonical stored tree. */
+export declare function requiredReaderModel(
+  documentType: DataModelDocumentType,
+  document: unknown,
+): number;
+
 export declare const RESERVED_CONDITION_VARS: readonly string[];
 
 /**
@@ -6242,6 +6872,23 @@ export declare interface ResolveAccessArgs {
   grantsFromPath?: string;
 }
 
+/** Resolves person provenance without treating agent or system ids as user ids. */
+export declare function resolveActor<User>(
+  directory: ProjectUserDirectory<User>,
+  actor: Actor,
+): Promise<ActorResolution<User>>;
+
+/** Resolve an actor through a plain engine client, without a UI adapter. */
+export declare function resolveClientActor(
+  client: WorkflowClient,
+  args: ResolveClientActorArgs,
+): Promise<ActorResolution<ClientProjectUser>>;
+
+export declare interface ResolveClientActorArgs {
+  readonly actor: Actor;
+  readonly projectId: string;
+}
+
 /**
  * A resolved field entry as the engine persists it on an instance.
  * Discriminated by `_type` (bare — unique within this union); the `value`
@@ -6249,9 +6896,9 @@ export declare interface ResolveAccessArgs {
  * `initialValue` is `{type:'query'}`, of any kind) additionally carries
  * `resolvedAt` — the lake-read time — so `resolvedAt` is provenance-driven,
  * not kind-specific. `object` / `array` entries carry their declared
- * sub-field shape (`fields` / `of`) — and `doc.ref` / `doc.refs` entries
- * their declared accepted `types` — so the instance is self-describing for
- * op-time validation and rendering.
+ * sub-field shape (`fields` / `of`) — and the reference kinds
+ * ({@link refKindAcceptsTypes}) their declared accepted `types` — so the
+ * instance is self-describing for op-time validation and rendering.
  */
 export declare type ResolvedFieldEntry = {
   [K in FieldKind]: {
@@ -6263,6 +6910,8 @@ export declare type ResolvedFieldEntry = {
     value: FieldValueMap[K];
     /** Lake-read time, present only on `query`-sourced entries. */
     resolvedAt?: string;
+    options?: ChoiceOptions;
+    validation?: ScalarValidation;
   } & (K extends "object"
     ? {
         fields: FieldShape[];
@@ -6273,7 +6922,7 @@ export declare type ResolvedFieldEntry = {
           of: FieldShape[];
         }
       : Record<never, never>) &
-    (K extends "doc.ref" | "doc.refs"
+    (K extends "doc.ref" | "doc.refs" | "subject"
       ? {
           types?: string[];
         }
@@ -6327,10 +6976,9 @@ export declare function resourceAliasesToMap(
  * boundaries probe this resolver per ref, so narrowing a resolver rejects
  * refs to the resources it stops serving.
  *
- * Resolved clients ride the engine's API version like every other engine
- * client: the verb scope rebinds them onto `ENGINE_API_VERSION` when they
- * carry {@link WorkflowClient.withConfig} (one without it is used as
- * returned and must be built to serve that version).
+ * Engine-owned verb scopes rebind resolved clients onto
+ * `ENGINE_API_VERSION`. Effect handlers receive resolver clients unchanged
+ * because handler traffic belongs to the host.
  */
 export declare type ResourceClientResolver = (
   parsed: ParsedGdr,
@@ -6369,10 +7017,10 @@ export declare interface ResourceSurface {
 }
 
 /**
- * Retract every guard for a stage being exited (lift predicate to allow), but
+ * Retract every guard for a stage being exited by deleting it, but
  * only once the instance has genuinely moved off that stage — or was aborted
  * 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
+ * `abortedAt` stamp is what licenses retracting 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 live.
  * Skip if it is still live on the stage (a concurrent loop-back re-entered
@@ -6445,6 +7093,19 @@ export declare function sameResource(
   b: WorkflowResource,
 ): boolean;
 
+/** Inclusive scalar bounds. String/text bounds measure character length;
+ * number bounds measure the numeric value. */
+export declare interface ScalarValidation {
+  min?: number | undefined;
+  max?: number | undefined;
+}
+
+export declare function scalarValidationIssues(args: {
+  entryType: string;
+  validation: ScalarValidation | undefined;
+  value: unknown;
+}): string[] | undefined;
+
 /**
  * The DECLARED field tree of a runtime schema — every entry key (optional
  * keys marked `key?`), every enum vocabulary, every variant arm — walked out
@@ -6458,6 +7119,20 @@ export declare function schemaTreeShape(schema: v.GenericSchema): unknown;
 
 export { ScopeAssignment };
 
+export declare interface ScopedInitialFieldDeclarations {
+  workflowFields: readonly FieldEntry[];
+  stages?: readonly {
+    name: string;
+    fields?: readonly FieldEntry[] | undefined;
+    activities?:
+      | readonly {
+          name: string;
+          fields?: readonly FieldEntry[] | undefined;
+        }[]
+      | undefined;
+  }[];
+}
+
 export { sentenceCase };
 
 export declare interface SessionArgs {
@@ -6492,6 +7167,27 @@ export declare interface SiteConsequence {
   after: ConditionOutcome;
 }
 
+/** One statically invalid parent-to-child spawn contract found at deploy. */
+export declare type SpawnContractIssue =
+  | {
+      reason: "unresolved-definition";
+      from: string;
+      ref: string;
+    }
+  | {
+      reason: "unconsumable-field";
+      from: string;
+      child: string;
+      field: string;
+      detail: string;
+    };
+
+/** Deploy refused one or more invalid static `spawn` contracts. */
+export declare class SpawnContractsInvalidError extends WorkflowError<"spawn-contracts-invalid"> {
+  readonly issues: SpawnContractIssue[];
+  constructor(args: { issues: SpawnContractIssue[]; message: string });
+}
+
 export declare type Stage = StageFields<
   FieldEntry,
   Activity,
@@ -6565,17 +7261,44 @@ 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})
  * plus `$fields`, which start time always has. No candidate root ever binds
  * here (the subject rides `$fields.<entry>.id`; a root read is
- * deploy-rejected), so a false/GROQ-null verdict is genuinely fail-closed —
- * there is no unbound-binding ambiguity to caveat. Bound in one place:
- * `startContextParams` in the applicability evaluator.
+ * deploy-rejected). Pre-flights can omit not-yet-collected input bindings and
+ * report those reads as provisional. Bound in one place: `startContextParams`
+ * in the applicability evaluator.
  */
 export declare const START_ALLOWED_VARS: readonly {
   name: string;
+  label: string;
   description: string;
 }[];
 
@@ -6584,17 +7307,15 @@ export declare const START_ALLOWED_VARS: readonly {
  * not the rendered condition scope (no {@link ConditionVarBinding}: these
  * bind only while the filter is evaluated on the READ side — the
  * `definitionsForDocument` derivation and the Studio start control).
- * `startInstance` never evaluates the filter. BROWSE-TIME-PURE: every var is
- * knowable before any inputs exist, so `$fields` is deliberately absent — a
- * `$fields` read in a filter is deploy-rejected with a pointer to
- * `start.allowed`, the context that binds it. An absent binding evaluates to
- * GROQ null; the VERDICT-level coercion (null result ⇒ not applicable) is
- * what fails closed — what a null read does inside the expression depends on
- * its shape. Bound in one place: `startContextParams` in the applicability
- * evaluator.
+ * `startInstance` never evaluates the filter. BROWSE-TIME-PURE: `$fields` is
+ * deliberately absent — a `$fields` read is deploy-rejected with a pointer
+ * to `start.allowed`. The synthetic subject variable requires a prospective
+ * subject; evaluation throws when the caller omits that required scope.
+ * Bound in one place: `startContextParams` in the applicability evaluator.
  */
 export declare const START_FILTER_VARS: readonly {
   name: string;
+  label: string;
   description: string;
 }[];
 
@@ -6623,8 +7344,10 @@ export declare type StartContext = Record<string, unknown>;
  * `RequiredFieldNotProvidedError` for it), never a `start.allowed` verdict.
  */
 export declare interface StartEvaluation {
-  /** The `start.allowed` verdict — `outcome === 'satisfied'`. Vacuously true
-   *  when the definition declares no `allowed`, exactly like the verb. */
+  /** Overall preflight startability: every supplied initial-field row is
+   *  valid and the `start.allowed` outcome is satisfied. `outcome` describes
+   *  only the condition; structurally invalid rows can therefore produce
+   *  `allowed: false` with `outcome: 'satisfied'`. */
   allowed: boolean;
   /**
    * Three-valued, BINDABILITY-AWARE verdict: `'unsatisfied'` is a definitive
@@ -6653,6 +7376,10 @@ export declare interface StartEvaluation {
     name: string;
     type: FieldEntry["type"];
   }[];
+  /** Supplied rows `startInstance` would reject before writing. Empty means
+   *  every row targets a workflow-scope, input-sourced declaration exactly
+   *  once. Render these as corrections, not an authorization verdict. */
+  invalidInitialFields: InitialFieldIssue[];
 }
 
 /** Type-mirror of {@link startFields}: how standalone runs of this workflow
@@ -6691,10 +7418,11 @@ export declare interface StartInstanceArgs {
    * `initialValue` resolution for query/working-memory entries).
    *
    * To start an instance "about" a specific document, declare a
-   * `{ type: "doc.ref", name: "subject", initialValue: { type: "input" } }`
+   * `{ type: "subject", name: "subject", initialValue: { type: "input" } }`
    * entry on the workflow and pass
-   * `{ type: "doc.ref", name: "subject", value: { id, type } }` here.
-   * Conditions then read it as `$fields.subject`.
+   * `{ type: "subject", name: "subject", value: { id, type } }` here.
+   * Conditions then read it as `$fields.subject`, and document pickers key
+   * on the `subject` kind.
    */
   initialFields?: InitialFieldValue[];
   ancestors?: GlobalDocumentReference[];
@@ -6834,6 +7562,7 @@ export declare function startRefusal(definition: {
  * The caller-side half of the start contexts — everything the evaluating
  * surface knows that the definition doesn't. Every member is optional
  * because the surfaces genuinely differ (a pure consumer may hold no clock):
+ * except for the subject identity required by `$subjectHasInFlightInstance`,
  * an absent binding evaluates each read of it to GROQ null, and where that
  * null lands decides the verdict — a predicate that can't decide without
  * the binding fails closed, while a count-of-matches clause over values
@@ -6848,9 +7577,13 @@ export declare interface StartScope {
   tag?: string | undefined;
   /** ISO clock reading — binds `$now`. */
   now?: string | undefined;
+  /** Resource-qualified identity of the prospective subject. Required when
+   *  `start.filter` reads `$subjectHasInFlightInstance`; unlike a loaded
+   *  document's bare `_id`, this stays collision-free across resources. */
+  subject?: GdrUri | undefined;
   /**
    * The WORKFLOW resource's dataset, for predicates that read it (`*[...]` or
-   * a deref) — invoked lazily, only when `analyzeCondition` says the
+   * a deref) or `$subjectHasInFlightInstance` — invoked lazily only when the
    * predicate needs it. A slice is fine as long as it covers what predicates
    * scan; the engine verbs supply EVERY instance of the tag, completed
    * included — `*` carries no hidden predicate, so authors qualify in-flight
@@ -7843,7 +8576,7 @@ export declare const wallClock: Clock;
 export declare interface WatchSet {
   /**
    * Docs to subscribe to — instance + ancestors + the docs named by
-   * `doc.ref`/`doc.refs`/`release.ref` field entries — deduped by
+   * `doc.ref`/`subject`/`doc.refs`/`release.ref` field entries — deduped by
    * `globalDocumentId`. Refs that aren't resource-qualified GDR URIs are
    * skipped (without a resource there's nothing to subscribe against).
    */
@@ -8002,6 +8735,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.
    *
@@ -8067,7 +8817,7 @@ export declare const workflow: {
    * filters see for a given instance.
    *
    * Hydrates the instance's snapshot (instance + ancestors + every doc
-   * declared by a `doc.ref` / `doc.refs` entry in scope), then
+   * declared by a `doc.ref` / `subject` / `doc.refs` entry in scope), then
    * evaluates the supplied GROQ in groq-js against that dataset. The
    * caller-free rendered scope cascade gates evaluate in is auto-bound —
    * the instance-derived vars ({@link FILTER_SCOPE_VARS}) with the open
@@ -8153,7 +8903,8 @@ export declare const workflow: {
    * Inngest/durable worker, any server) that holds no instances in memory: a
    * document changed; which instances should it `tick`? The watch-set covers
    * the instance itself, its ancestors, and the docs named by
-   * `doc.ref` / `doc.refs` / `release.ref` field entries on the workflow scope
+   * `doc.ref` / `subject` / `doc.refs` / `release.ref` field entries on the
+   * workflow scope
    * **and the current stage** — so a hand-rolled GROQ over `fields[]` gets it
    * subtly wrong (misses stage-scope refs, `release.ref`, ancestors).
    *
@@ -8182,7 +8933,7 @@ export declare const workflow: {
    * deployed definition that APPLIES to `document` — what a start picker for
    * it should offer. Loads the latest deployed version of each definition
    * visible to the engine's tag and filters it through the derivation
-   * ({@link applicableDefinitions}): startable ∧ a required subject entry
+   * ({@link applicableDefinitions}): startable ∧ the `subject`-kind entry
    * accepts the doc's `_type` ∧ `start.filter` passes — evaluated in the
    * browse-time-pure start-filter context with `$tag`/`$definition`/`$now`
    * bound and the tag's instance slice (completed included) backing dataset
@@ -8190,9 +8941,12 @@ export declare const workflow: {
    * question; pre-flight it with {@link workflow.evaluateStart}.
    *
    * Takes the LOADED candidate document, not a ref — applicability evaluates
-   * its content, under whatever perspective the caller read it with. Surfaces
-   * ALL matches (name ascending), no engine ranking — presenting a picker or
-   * auto-picking is consumer policy. Advisory like every engine-side check.
+   * its content, under whatever perspective the caller read it with. A
+   * resource-qualified `subject` accompanies it when a filter reads
+   * `$subjectHasInFlightInstance`; a bare document id cannot identify a
+   * cross-resource subject. Surfaces ALL matches (name ascending), no engine
+   * ranking — presenting a picker or auto-picking is consumer policy.
+   * Advisory like every engine-side check.
    */
   definitionsForDocument: (
     rawArgs: Clocked<DefinitionsForDocumentArgs & EngineScopeArgs>,
@@ -8433,7 +9187,12 @@ export declare interface WorkflowCommitOptions {
   tag?: string;
 }
 
-export declare type WorkflowConfig = v.InferOutput<typeof WorkflowConfigSchema>;
+export declare type WorkflowConfig = Omit<
+  ParsedWorkflowConfig,
+  "deployments"
+> & {
+  deployments: WorkflowDeployment[];
+};
 
 declare const WorkflowConfigSchema: v.ObjectSchema<
   {
@@ -8445,16 +9204,24 @@ 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<
+                v.CustomSchema<2, undefined>,
+                undefined
+              >;
               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"
+                    `invalid ${string} \u2014 ASCII lowercase + digits + dashes, no leading dash, no dots`
                   >,
                 ]
               >;
@@ -8655,7 +9422,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
                     >,
                   ]
                 >,
@@ -8709,6 +9499,7 @@ declare const WorkflowConfigSchema: v.ObjectSchema<
         v.MinLengthAction<
           {
             name: string;
+            expectedMinReaderModel?: 2 | undefined;
             tag: string;
             workflowResource:
               | {
@@ -8769,6 +9560,127 @@ declare const WorkflowConfigSchema: v.ObjectSchema<
         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
+        >,
+        v.CheckAction<
+          {
+            name: string;
+            expectedMinReaderModel?: 2 | undefined;
             tag: string;
             workflowResource:
               | {
@@ -8823,7 +9735,67 @@ 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
         >,
       ]
     >;
@@ -8930,7 +9902,12 @@ declare const WorkflowDefinitionSchema: v.GenericSchema<
   WorkflowFields<FieldEntry, Stage, StartBlock>
 >;
 
-export declare type WorkflowDeployment = WorkflowConfig["deployments"][number];
+export declare type WorkflowDeployment = Omit<
+  ParsedWorkflowDeployment,
+  "expectedMinReaderModel"
+> & {
+  expectedMinReaderModel: typeof DATA_MODEL_MIN_READER;
+};
 
 export declare const WorkflowEffectCompleted: WorkflowTelemetryEvent<WorkflowEffectCompletedData>;
 
@@ -8961,6 +9938,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.
@@ -8985,6 +9973,7 @@ export declare type WorkflowErrorKind =
   | "effect-ops-invalid"
   | "effect-outputs-invalid"
   | "required-field-not-provided"
+  | "initial-fields-invalid"
   | "workflow-state-diverged"
   | "partial-guard-deploy"
   | "start-not-primed"
@@ -8992,14 +9981,19 @@ 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"
   | "model-version-ahead"
+  | "reader-model-acknowledgement"
   | "persisted-doc-shape"
   | "instance-not-found"
   | "definition-not-found"
   | "definition-in-use"
+  | "spawn-contracts-invalid"
   | "effect-not-found"
   | "missing-effect-handler"
   | "contract-violation";
@@ -9095,9 +10089,9 @@ export declare interface WorkflowInstance extends SanityDocument {
   modelVersion?: number;
   /**
    * Reader floor — the oldest engine data model that can safely interpret
-   * this document (see {@link DATA_MODEL_MIN_READER}). Written alongside
-   * {@link WorkflowInstance.modelVersion}; additive model changes leave it,
-   * only breaking ones raise it.
+   * this document. Derived from features actually present, bounded by
+   * {@link DATA_MODEL_MIN_READER}, and written alongside
+   * {@link WorkflowInstance.modelVersion}. Full persists never lower it.
    */
   minReaderModel?: number;
   /**
@@ -9405,11 +10399,11 @@ export declare interface WorkflowTransaction {
   /**
    * Queue a document delete. Deliberately a transaction-only capability —
    * the top-level client surface stays delete-free so no engine code path
-   * can casually remove documents; engine-side the sole consumer is
-   * `deleteDefinition` housekeeping (definition docs + orphaned guard docs),
-   * and outside the engine the CLI's `nuke` reset deletes raw engine-owned
-   * docs through it. Both the real `@sanity/client` Transaction and the test
-   * fake's TransactionHandle carry this shape.
+   * can casually remove documents. Engine-side consumers are guard retraction
+   * and `deleteDefinition` housekeeping; outside the engine the CLI's `nuke`
+   * reset deletes raw engine-owned docs through it. Both the real
+   * `@sanity/client` Transaction and the test fake's TransactionHandle carry
+   * this shape.
    */
   delete: (id: string) => WorkflowTransaction;
   /**