@sanity/workflow-engine 0.32.0 → 0.34.0

package/dist/index.d.ts

@@ -102,7 +102,7 @@ export declare function aclPathForResource(
  *
  * @interface
  */
-export declare type Action = ActionFields<Op, string[]> & {
+export declare type Action = ActionFields<Op, string[], Effect> & {
   roles?: string[] | undefined;
 };
 
@@ -196,7 +196,7 @@ export declare interface ActionEvaluation {
 }
 
 /** @inline */
-declare type ActionFields<TOp, TGroup> = {
+declare type ActionFields<TOp, TGroup, TEffect> = {
   name: string;
   semantics?: ActionSemantic[] | undefined;
   title?: string | undefined;
@@ -206,7 +206,7 @@ declare type ActionFields<TOp, TGroup> = {
   filter?: string | undefined;
   params?: ActionParam[] | undefined;
   ops?: TOp[] | undefined;
-  effects?: Effect[] | undefined;
+  effects?: TEffect[] | undefined;
   spawn?: Subworkflows | undefined;
 };
 
@@ -551,15 +551,14 @@ export declare interface ActivityEvaluation {
    */
   scopedOut: boolean;
   /**
-   * The activity's unmet {@link Activity.requirements}, with authored display copy — present iff at least
-   * one is unmet. The activity's own readiness summary: a consumer can explain why
-   * the whole activity is gated without inspecting each action (every action also
-   * carries the matching `requirements-unmet` `disabledReason`).
+   * Unmet authored activity requirements and required-reference readability checks.
+   * Present when at least one is unmet. Required-reference descriptors use
+   * `field:<name>` and the field's declared title when available.
    */
   unmetRequirements?: RequirementDescriptor[];
-  /** Derived state per declared requirement, keyed by requirement name.
-   *  Present iff the activity declares requirements; `unmetRequirements`
-   *  contains descriptors for exactly the requirements whose insight isn't satisfied. */
+  /** Derived state per authored requirement, keyed by its declared name.
+   * Present when the activity declares requirements. Unmet authored requirements
+   * appear in `unmetRequirements`; required-reference checks have no insight entry. */
   requirementInsights?: Record<string, ConditionInsight>;
   /** Derived state of the activity's `filter` existence gate. Present iff
    *  declared. Advisory read: the engine's stage entry owns the gate itself. */
@@ -642,7 +641,13 @@ export declare interface Actor {
  */
 export declare const ACTOR_KINDS: readonly ["person", "agent", "system"];
 
-/** Runtime role check; like alias expansion, it expands only the required side. */
+/**
+ * Checks whether an actor role fulfills `required`, directly or through one
+ * level of aliases. Pass `roleAliases` from a definition returned by
+ * {@link define.defineWorkflow | defineWorkflow}; its universal aliases are
+ * normalized. A raw authored `"*"` entry is not expanded here.
+ * This role check is advisory.
+ */
 export declare function actorFulfillsRole({
   actorRoles,
   required,
@@ -682,6 +687,14 @@ export declare type ActorResolution<User> =
       readonly actor: Actor;
     };
 
+/** Missing-reference evidence accompanying another primary fault, for workspace renderers only.
+ * @internal
+ */
+export declare function _additionalMissingDocuments(
+  diagnosis: Diagnosis,
+  documents: MissingDocument[] | undefined,
+): MissingDocument[];
+
 export { analyzeCondition };
 
 /** Lake `identity()` sentinel for unauthenticated callers. */
@@ -736,11 +749,13 @@ export declare function assertReaderModelAcknowledgement(
 ): asserts expectedMinReaderModel is number;
 
 /**
- * One member of an assignment entry's value, matched by the inbox reverse-query
- * and rendered `$assigned` gate. A `role` member names a capability
- * (fulfilled by whoever deploys that role), not a concrete principal — which
- * is what distinguishes it from {@link Actor}. `id` here is a SYSTEM
- * identifier (a principal), not authored identity.
+ * One member of an `assignee` or `assignees` field. For a user member, pass a
+ * human's account-global `sanityUserId`, not a project-scoped user ID. Robot
+ * IDs are rejected.
+ *
+ * A role member identifies a project role, not an individual {@link Actor}.
+ * Direct user members take ownership ahead of role members. Role aliases apply
+ * to `$assigned` authorization, but inbox routing uses literal project roles.
  */
 export declare type Assignee =
   | {
@@ -859,6 +874,23 @@ export declare type AuthoringActivity = ActivityFields<
  */
 export declare type AuthoringEditable = true | string[] | string;
 
+/**
+ * An {@link Effect} whose `retry` block may omit its `kind`, plus the
+ * authoring-only `runtime` block that says where the generated runtime hosts
+ * this handler. `retry` is stored; `runtime` is stripped before the deploy
+ * writes the definition.
+ *
+ * @interface
+ */
+export declare type AuthoringEffect = EffectFields<AuthoringEffectRetry> & {
+  runtime?: EffectRuntimeBlock | undefined;
+};
+
+/** An {@link EffectRetry} whose omitted `kind` defaults to `engine`. */
+export declare type AuthoringEffectRetry = EffectRetryFields & {
+  kind?: EffectRetryKind | undefined;
+};
+
 /**
  * A raw field entry or one of the authoring-only field sugars. `todoList`
  * expands to an array of objects with `label`, `status`, optional `assignee`,
@@ -866,6 +898,7 @@ export declare type AuthoringEditable = true | string[] | string;
  * `notes` expands to an array of audit-shaped objects with `body`, `actor`,
  * and `at` fields. Sugar type names are compiled away and never become stored
  * field kinds.
+ * See {@link FieldEntry} for scope, required-input, and field-type constraints.
  */
 export declare type AuthoringFieldEntry =
   | AuthoringRawFieldEntry
@@ -899,8 +932,22 @@ declare const AuthoringFieldRefSchema: v.StrictObjectSchema<
 >;
 
 /**
- * {@link Guard}'s contract as authored: `match.idRefs` and `metadata` carry
- * typed {@link GuardRead} values that deploy resolves to bare ones.
+ * A stage's content mutation guard. Its name must be unique across the whole
+ * definition and use lowercase letters, digits, and dashes, starting with a
+ * letter or digit. `match.actions` must contain at least one action.
+ *
+ * `match.types` intersects the ID criteria. Within the ID criteria, matching
+ * either `idRefs` or `idPatterns` is sufficient. Omitted or empty optional
+ * criteria do not constrain the match. `idRefs` uses typed {@link GuardRead}s.
+ * Patterns use resource-local document-ID characters and `*` wildcards.
+ * A release-version pattern is rejected if translating it for a lifecycle
+ * action would broaden it to every document.
+ *
+ * `predicate` is delta-mode GROQ over `document`, `guard`, and `mutation`;
+ * see {@link GUARD_PREDICATE_VARS}. Only a strict `true` allows a matching
+ * mutation. An omitted or empty predicate denies it. `metadata` resolves
+ * {@link GuardRead}s into values available as `guard.metadata` in the predicate.
+ * Engine evaluations are advisory; the Content Lake is the enforcement point.
  *
  * @interface
  */
@@ -1019,7 +1066,11 @@ export declare type AuthoringOp =
     };
 
 /** @inline */
-declare type AuthoringRawAction = ActionFields<AuthoringOp, GroupMembership> & {
+declare type AuthoringRawAction = ActionFields<
+  AuthoringOp,
+  GroupMembership,
+  AuthoringEffect
+> & {
   roles?: string[] | undefined;
   status?: TerminalActivityStatus | undefined;
 };
@@ -1030,7 +1081,15 @@ declare type AuthoringRawFieldEntry = FieldEntryFields<
   GroupMembership
 >;
 
-/** @interface */
+/** @inline */
+declare type AuthoringRuntimeKey = "runtime";
+
+/**
+ * A {@link Stage} accepting authoring fields, activities, transitions, guards,
+ * and role-list editability. The same terminal-stage constraints apply.
+ *
+ * @interface
+ */
 export declare type AuthoringStage = StageFields<
   AuthoringFieldEntry,
   AuthoringActivity,
@@ -1039,21 +1098,23 @@ export declare type AuthoringStage = StageFields<
   AuthoringEditable
 >;
 
+/** A {@link StartBlock} whose omitted `kind` defaults to `interactive`. */
 export declare type AuthoringStartBlock = StartFields & {
   kind?: StartKind | undefined;
 };
 
 /**
- * Authoring transitions may omit `when`; desugar fills the safe,
- * overwhelmingly-common trigger `"$allActivitiesDone"`. "Fire unconditionally"
- * stays spellable as an explicit `when: "true"`.
+ * A {@link Transition} whose `when` may be omitted, defaulting to
+ * `$allActivitiesDone`. Use `when: 'true'` for an unconditional route.
  */
 export declare type AuthoringTransition = TransitionFields & {
   when?: string | undefined;
 };
 
 /**
- * The authoring surface: stored primitives plus the define-time sugar.
+ * The authoring surface: stored primitives plus the define-time sugar. `runtime`
+ * says where the generated unattended runtime hosts this workflow, overriding
+ * its deployment's kind; an effect node overrides it in turn.
  *
  * @interface
  */
@@ -1061,7 +1122,9 @@ export declare type AuthoringWorkflow = WorkflowFields<
   AuthoringFieldEntry,
   AuthoringStage,
   AuthoringStartBlock
->;
+> & {
+  runtime?: RuntimeBlock | undefined;
+};
 
 /** The narratable answer at one rollup level: the verdict plus what it waits
  *  on. `waitsOn` may be non-empty on a `yes` verdict (an effect settle is a
@@ -1224,6 +1287,15 @@ export declare interface ChoiceOption {
   value: ChoiceValue;
 }
 
+/**
+ * A closed list of allowed non-null scalar values. The list must be nonempty,
+ * with unique values and nonempty titles. Each value must satisfy the
+ * receiving type and its validation bounds.
+ *
+ * Fields accept choices on `string`, `text`, `number`, `url`, `date`,
+ * `dueDate`, `datetime`, and `dueDatetime`. Action parameters accept choices
+ * on `string`, `number`, `url`, and `dateTime`.
+ */
 export declare interface ChoiceOptions {
   list: ChoiceOption[];
 }
@@ -1279,6 +1351,14 @@ export declare function clientGuardDereference(
   client: Pick<WorkflowClient, "getDocument">,
 ): GuardDereference;
 
+/** @internal Shared member rows for workspace adapters; not a supported consumer API. */
+export declare interface _ClientProjectMember {
+  readonly id: string;
+  readonly isRobot?: boolean;
+  readonly roles?: unknown;
+  readonly [key: string]: unknown;
+}
+
 /** Native project-user response returned by Sanity's project API. */
 export declare interface ClientProjectUser {
   readonly id: string;
@@ -1836,6 +1916,13 @@ export declare interface CreateEngineArgs<
    * option.
    */
   clock?: Clock;
+  /**
+   * How the engine waits out a `retry` policy's backoff between attempts.
+   * Pinned once beside {@link CreateEngineArgs.clock}; omit (the default) to
+   * spend real time. A deterministic harness passes one that moves its clock
+   * forward instead, so a paced policy runs without waiting.
+   */
+  sleep?: Sleeper;
   /**
    * Product-telemetry seam, pinned once for this engine and threaded into
    * every verb it drives. The core engine ships no metrics pipeline — it
@@ -1863,6 +1950,8 @@ export declare function createTelemetryIntake(args: {
   client: TelemetryIntakeClient;
   projectId: string;
   denied?: boolean;
+  /** Context merged into every event at send time. These values win on key collisions. */
+  context?: Record<string, unknown>;
 }): TelemetryIntake;
 
 /** A define-time validated `custom.<camelCaseMeaning>` value. */
@@ -2014,10 +2103,28 @@ export declare const DATA_MODEL_CHANGES: readonly [
     applicability: "detectable";
     summary: "Singular assignee fields use member lists with at most one user and any number of roles.";
   }>,
+  Readonly<{
+    id: "required-content-references";
+    introducedInModel: 10;
+    minReaderModel: 10;
+    documentTypes: readonly ["definition", "instance"];
+    compatibility: "reader-floor";
+    applicability: "detectable";
+    summary: "Required content references must remain readable after initialization before actions or transitions advance.";
+  }>,
+  Readonly<{
+    id: "effect-retry-policy";
+    introducedInModel: 10;
+    minReaderModel: 10;
+    documentTypes: readonly ["definition", "instance"];
+    compatibility: "reader-floor";
+    applicability: "detectable";
+    summary: "An effect node declares a bounded retry policy the engine enforces on every runtime.";
+  }>,
 ];
 
 /** The maximum reader floor this writer can emit for a detectable feature. */
-export declare const DATA_MODEL_MAX_READER = 9;
+export declare const DATA_MODEL_MAX_READER = 10;
 
 /**
  * The unconditional model-4 reader floor for every engine-owned document.
@@ -2034,12 +2141,14 @@ export declare const DATA_MODEL_MIN_READER = 4;
  * instances are re-stamped on every full persist, so mixed-version fleets
  * honestly record whichever engine last shaped a doc.
  *
- * Bump on every declared shape change (additive included). Bumping does NOT
- * by itself lock out older engines — that is the document's derived
- * `minReaderModel` floor. Declare every bump in `DATAMODEL.md`; the model-surface snapshot test
- * fails on undeclared drift.
+ * A number is assigned per release, not per change: a declared shape change
+ * merged before this model has shipped joins it, and one merged after it has
+ * shipped moves the number on. Bumping does NOT by itself lock out older
+ * engines — that is the document's derived `minReaderModel` floor. Declare
+ * every change in `DATAMODEL.md`; the model-surface snapshot test fails on
+ * undeclared drift.
  */
-export declare const DATA_MODEL_VERSION = 9;
+export declare const DATA_MODEL_VERSION = 10;
 
 export declare interface DataModelChange {
   readonly id: string;
@@ -2137,6 +2246,16 @@ export declare const DEFAULT_TRANSITION_WHEN = "$allActivitiesDone";
  */
 export declare const defaultLoggerFactory: LoggerFactory;
 
+/**
+ * What `defineWorkflow` returns: the stored definition, plus `runtime` when the
+ * workflow or one of its effects declared a hosting kind. Generation and the
+ * blueprint tooling read `runtime`; the deploy drops it, so it never reaches the
+ * Content Lake and never affects a definition's content fingerprint.
+ */
+export declare type DefinedWorkflow = WorkflowDefinition & {
+  runtime?: DefinitionRuntime | undefined;
+};
+
 export declare interface DefinitionConditionSite {
   /** The stage the condition applies in; absent only for author predicates. */
   stage?: string;
@@ -2221,6 +2340,17 @@ export declare function definitionRoleNames(
   definition: WorkflowDefinition,
 ): readonly string[];
 
+/**
+ * The hosting declarations {@link DefinedWorkflow} carries for the generator,
+ * collected out of the authored tree. `kind` is present only when the workflow
+ * declared one, so an absent `kind` inherits the deployment's. `effects` holds
+ * one entry per effect that declared a block, keyed by effect name.
+ */
+export declare interface DefinitionRuntime {
+  kind?: RuntimeKind | undefined;
+  effects?: Record<string, EffectRuntimeBlock> | undefined;
+}
+
 export declare interface DefinitionsForDocumentArgs {
   /**
    * The LOADED candidate document — unlike {@link InstancesForDocumentArgs},
@@ -2608,6 +2738,8 @@ export declare type DiagnosedTransition = Pick<
  * builds it from a real {@link WorkflowEvaluation}.
  */
 export declare interface DiagnoseInput extends DocumentStuckInput {
+  /** Missing references read by unmet requirements or transition conditions; omit when not checked. */
+  missingDocuments?: MissingDocument[];
   instance: Pick<
     WorkflowInstance,
     | "currentStage"
@@ -2624,14 +2756,15 @@ export declare interface DiagnoseInput extends DocumentStuckInput {
 }
 
 /** Narrow a full {@link WorkflowEvaluation} to the {@link DiagnoseInput} the
- *  classifier reads. */
+ *  classifier reads. Throws when populated missing-reference evidence lacks
+ *  its blocking subset. */
 export declare function diagnoseInputFromEvaluation(
   evaluation: WorkflowEvaluation,
 ): DiagnoseInput;
 
 /**
- * Classify an instance. Terminal states win first; then the genuine stuck
- * causes (nothing advances on its own or via a normal action); then `waiting`
+ * Classify an instance. Terminal states win first; then effect or activity
+ * faults; then missing references read by unmet conditions; then transition faults; then `waiting`
  * (an action is available — healthy); then `blocked` (an active activity held by
  * an unmet requirement — healthy, not yet actionable); else `progressing` (a
  * transition is already satisfied and will cascade).
@@ -2785,12 +2918,10 @@ export declare type DisabledReason =
     }
   | {
       /**
-       * The activity's declared {@link Activity.requirements} aren't all satisfied —
-       * the readiness axis. The activity is visible and the actor authorized, but
-       * its own preconditions don't hold yet. `unmetRequirements` carries the
-       * authored descriptors so a consumer can disable the affirmative control and say
-       * which precondition is outstanding. Distinct from `filter-failed`
-       * (visibility/authorization) and `mutation-guard-denied` (content-write).
+       * An authored activity requirement is unmet, or a selected target of a
+       * required reference field cannot be read. Use `unmetRequirements` to
+       * explain what blocks the action. Required-reference descriptors use
+       * `field:<name>`; they have no entry in `requirementInsights`.
        */
       kind: "requirements-unmet";
       unmetRequirements: RequirementDescriptor[];
@@ -2875,6 +3006,21 @@ export declare interface DocumentActionDenialsArgs {
   dereference?: GuardDereference;
 }
 
+/**
+ * Completed evidence for a document absent from the snapshot. `deleted` confirms
+ * absence across versions; `outside-perspective` identifies an existing representation.
+ * `unreadable` covers denied access and unsuccessful availability checks.
+ */
+export declare type DocumentAvailability =
+  | "deleted"
+  | "unreadable"
+  | "outside-perspective";
+
+/** Supplies completed availability evidence for references absent from an evaluation snapshot. */
+export declare type DocumentAvailabilityReader = (
+  documents: readonly MissingDocument[],
+) => Promise<ReadonlyMap<string, DocumentAvailability>>;
+
 /** @inline */
 declare type DocumentEnvelopeKey =
   | `_${string}`
@@ -2898,8 +3044,8 @@ export declare function documentPrefilter(
 
 /**
  * Classify an instance from its document alone — no evaluation, no reads, no
- * actor. The transition-level causes need GROQ `when` results, so only
- * {@link diagnoseInstance} reaches those.
+ * actor. Document absence and transition-level causes require an evaluation,
+ * so only {@link diagnoseInstance} reaches those.
  *
  * Sound but incomplete, and a consumer must present it that way: `undefined`
  * means "no cause this classifier can see", never "healthy". Flag an instance on
@@ -2942,10 +3088,13 @@ export declare interface DrainEffectsResult {
   failed: PendingEffect[];
   skipped: PendingEffect[];
   /**
-   * Entries this drainer dispatched whose completion lost to another party
-   * (a lease-expiry takeover finishing first, or a manual recovery). The
-   * handler's side effect ran here too — the at-least-once overlap the
-   * {@link EffectHandler} contract tells handlers to tolerate.
+   * Entries this drainer dispatched without settling. Either another party
+   * settled the entry first (a lease-expiry takeover, a manual recovery, or a
+   * completion landing while a `retry` run waited out a backoff), or a `retry`
+   * run stopped because the claim could no longer be held, which leaves the
+   * entry pending for a later drain. The handler's side effect ran here too:
+   * the at-least-once overlap the {@link EffectHandler} contract tells
+   * handlers to tolerate.
    */
   lost: PendingEffect[];
 }
@@ -3137,20 +3286,24 @@ export declare interface EditFieldTarget {
 export declare type EditMode = "set" | "append" | "unset";
 
 /**
- * A registered effect: `name` is its only identity (unique per definition,
- * read downstream as `$effects.<name>`) — the host app registers a handler
- * against it 1:1, and the stored definition never references code.
- * `bindings` are GROQ reads over the rendered scope, resolved to concrete
- * JSON at queue time; `input` is static config passed through verbatim.
- * `outputs` (typed {@link FieldShape}s) is a STRICT allowlist: at completion
- * an undeclared output key, or a value that doesn't fit its shape, fails the
- * completion and nothing is stored. Omitting `outputs` is an EMPTY allowlist,
- * so ANY returned output is rejected and fails the completion — the bound is
- * universal, not opt-in.
+ * External work queued for the handler registered under `name`. Names are
+ * unique within a definition; completed outputs are read as `$effects['<name>']`.
+ *
+ * `bindings` resolves GROQ expressions against the action's rendered scope
+ * when the effect is queued. The handler receives one parameter bag combining
+ * those values with static `input`. An `input` key overrides a same-named
+ * binding, including when its value is null.
+ *
+ * `outputs` declares the allowed result keys and their {@link FieldShape}s.
+ * An undeclared key or invalid value rejects the completion without storing
+ * it. Omitting `outputs` allows no output keys.
+ *
+ * `retry` ({@link EffectRetry}) bounds how many times a failing handler is
+ * attempted. Omitting it completes the effect as failed on the first failure.
  *
  * @interface
  */
-export declare type Effect = v.InferOutput<typeof EffectSchema>;
+export declare type Effect = EffectFields<EffectRetry>;
 
 /** Total commits one dispatch may make — the runaway-handler bound: without
  *  it, a looping reporter renews its own lease and appends history forever.
@@ -3188,6 +3341,17 @@ export declare type EffectCompletionStatus = Exclude<
   "cancelled"
 >;
 
+/** @inline */
+declare type EffectFields<TRetry> = {
+  name: string;
+  title?: string | undefined;
+  description?: string | undefined;
+  bindings?: Record<string, string> | undefined;
+  input?: Record<string, unknown> | undefined;
+  outputs?: FieldShape[] | undefined;
+  retry?: TRetry | undefined;
+};
+
 /**
  * External effect handler — invoked at drain time with resolved `params` and
  * a context. Returning `outputs` records them on the run's `effectHistory`
@@ -3195,15 +3359,29 @@ export declare type EffectCompletionStatus = Exclude<
  * applies the state half of the effect in the completion commit (`field.*`
  * only, never `status.set`) — every returned op must explicitly set
  * `target.scope`, since completion ops have no authoring location to infer
- * one from. Throwing marks the effect failed, with no `ops`.
+ * one from. Throwing fails the attempt, with no `ops`. Without a
+ * {@link EffectRetry} policy on the node, or once one has spent its attempts
+ * or closed its window, that failure settles the effect as failed. A policy
+ * with attempts left inside its window dispatches again instead, unless the
+ * drain finds between two attempts that it no longer holds the claim: then it
+ * stops without settling and reports the entry as `lost`. That check happens
+ * between attempts only. The completion itself stays first-writer-wins, so a
+ * dispatch that runs to its end still reports its outcome and settles the
+ * entry if it gets there first.
  *
  * Delivery is at-least-once: a handler MAY run more than once for the same
- * effect (a dispatch dying after its side effect but before commit, or a
- * lease expiring mid-dispatch and being taken over). Completion is
- * first-writer-wins — the losing run's completion is reported as `lost`.
- * Write handlers to tolerate this: check `effectHistory[]` for a row keyed
- * by `ctx.effectKey` before irreversible work, and derive external
- * identifiers from `ctx.effectKey` so the receiving system can dedupe.
+ * effect. Three causes. A dispatch can die after its side effect but before
+ * commit. A lease can expire mid-dispatch and be taken over. And every
+ * admitted attempt of a `retry` policy invokes the handler again. Completion
+ * is first-writer-wins, and the losing run's completion is reported as `lost`.
+ *
+ * Write handlers to tolerate repetition. Derive external identifiers from
+ * `ctx.effectKey` so the receiving system can dedupe: the key is stable across
+ * every repeat, including all attempts of one policy run. Checking
+ * `effectHistory[]` for a row keyed by `ctx.effectKey` before irreversible
+ * work catches a repeat of an already-completed run, but never a retry
+ * attempt, because a policy writes one history row when the whole run ends and
+ * nothing records the attempt that just failed.
  *
  * The `bivarianceHack` indirection keeps this readable from the non-generic
  * `Engine` surface; only the typed drain invokes handlers.
@@ -3338,6 +3516,66 @@ export declare function effectOutputsMap(
   instance: Pick<WorkflowInstance, "effectHistory">,
 ): Record<string, unknown>;
 
+/**
+ * A bounded retry policy for one effect. Both bounds govern one drain's run of
+ * the policy, not the effect's lifetime: a drainer that dies mid-run leaves the
+ * entry for the next drain, which starts a fresh run with the full budget, so
+ * an effect can see more handler calls in total than `attempts`.
+ *
+ * `attempts` is the total number of attempts in a run, the first included, so
+ * `1` means "never retry".
+ *
+ * `expiryMs` and the backoff a policy accumulates are each capped at 366 days
+ * (`31_622_400_000` ms), inclusive. Deploy refuses a policy declaring more,
+ * and one whose accumulated backoff reaches its own `expiryMs` before its
+ * `attempts` are spent. Those checks weigh the declared waits alone. At
+ * runtime every elapsed millisecond counts against `expiryMs`, handler time
+ * included, so a slow handler can leave attempts unused. `backoff` paces
+ * them; omitting it retries with no wait. Every duration is a whole number of
+ * milliseconds above zero, and `attempts` a whole count above zero; deploy
+ * rejects anything else.
+ *
+ * `expiryMs` decides whether a further attempt may start, measured from the
+ * moment this run dispatched its first attempt. The window closes
+ * on reaching it, so an attempt is admitted only while less than `expiryMs`
+ * has elapsed. It is not a handler timeout. An attempt already running is
+ * never interrupted, so a run can finish after the window, and a success then
+ * still counts. Omitting it leaves `attempts` as the only bound.
+ *
+ * A policy that runs out of attempts, or that `expiryMs` stops, completes the
+ * effect as failed, and `$effectStatus['<name>'] == 'failed'` routes the
+ * instance. A successful attempt completes it as done, whichever attempt
+ * succeeded. An effect with no `retry` completes as failed on its handler's
+ * first failure.
+ */
+export declare type EffectRetry = EffectRetryFields & {
+  kind: EffectRetryKind;
+};
+
+/**
+ * How long the engine waits between two attempts. `delayMs` is that wait in
+ * milliseconds: `'fixed'` waits it every time, `'exponential'` doubles it per
+ * attempt already made (`delayMs`, then `2 × delayMs`, then `4 × delayMs`).
+ */
+export declare type EffectRetryBackoff = {
+  kind: "fixed" | "exponential";
+  delayMs: number;
+};
+
+/** @inline */
+declare type EffectRetryFields = {
+  attempts: number;
+  backoff?: EffectRetryBackoff | undefined;
+  expiryMs?: number | undefined;
+};
+
+/**
+ * Who runs a retry policy. `'engine'` is the only member: the engine loops
+ * inside the `drainEffects` call that picked the effect up, holding the claim
+ * across the waits.
+ */
+export declare type EffectRetryKind = "engine";
+
 /**
  * Every terminal state an effect run can record. `done` and `failed` are
  * reported through completion ({@link EffectCompletionStatus}); `cancelled`
@@ -3347,43 +3585,25 @@ export declare function effectOutputsMap(
  */
 export declare type EffectRunStatus = "done" | "failed" | "cancelled";
 
-declare const EffectSchema: v.StrictObjectSchema<
-  {
-    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 bindings: v.OptionalSchema<
-      v.RecordSchema<
-        v.StringSchema<undefined>,
-        v.SchemaWithPipe<
-          readonly [
-            v.StringSchema<undefined>,
-            v.MinLengthAction<string, 1, "must be a non-empty string">,
-          ]
-        >,
-        undefined
-      >,
-      undefined
-    >;
-    readonly input: v.OptionalSchema<
-      v.RecordSchema<v.StringSchema<undefined>, v.UnknownSchema, undefined>,
-      undefined
-    >;
-    readonly outputs: v.OptionalSchema<
-      v.ArraySchema<v.GenericSchema<FieldShape>, undefined>,
-      undefined
-    >;
-  },
-  undefined
->;
+/**
+ * The `runtime` block on an effect node, overriding its workflow's kind.
+ * `timeout` is seconds and `memory` megabytes of the function that runs this
+ * handler, and an effect declaring either gets its own drain function instead of
+ * sharing the deployment's. Both are the function budget, so both are accepted
+ * only under `'function'`.
+ */
+export declare type EffectRuntimeBlock =
+  | {
+      kind: "function";
+      timeout?: number | undefined;
+      memory?: number | undefined;
+    }
+  | {
+      kind: "durableFunction";
+    }
+  | {
+      kind: "selfHosted";
+    };
 
 /** The `effectHistory` outcome {@link EffectNotFoundError} reports when the
  *  missing key belongs to a settled run. `detail` is the row's recorded
@@ -3394,6 +3614,21 @@ export declare interface EffectSettledInfo {
   detail?: string;
 }
 
+/** One declared effect plus a structural location string identifying where it
+ *  sits in the definition (for diagnostics). */
+export declare interface EffectSite {
+  effect: Effect;
+  location: string;
+}
+
+/**
+ * Every effect a definition declares, with its location — the single source of
+ * "where effects live": action `effects[]` (actions are the only payload
+ * carriers). Effect names are unique per definition, so consumers can key by
+ * `site.effect.name` cleanly.
+ */
+export declare function effectSites(def: WorkflowDefinition): EffectSite[];
+
 export declare interface Engine {
   /** Engine-scoped bindings — exposed for the few advanced consumers
    *  (e.g. test bench, drain workers) that need them; the verbs already
@@ -3410,6 +3645,9 @@ export declare interface Engine {
   resolveActor: (
     args: ResolveClientActorArgs,
   ) => Promise<ActorResolution<ClientProjectUser>>;
+  /** Validates and stores immutable definition versions. Content matching the
+   *  latest deployed version's fingerprint keeps that version; otherwise,
+   *  deployment creates the next version. Batch dependencies deploy children first. */
   deployDefinitions: <T extends WorkflowDefinitionInput<T>>(
     args: DeployDefinitionsArgs<T>,
   ) => Promise<DeployDefinitionsResult>;
@@ -3418,15 +3656,25 @@ export declare interface Engine {
    *  starts without complaint. `instanceId` is the idempotency key: reusing
    *  it for the same start resumes; a different start throws. */
   startInstance: (args: StartInstanceArgs) => Promise<OperationResult>;
+  /** Commits a caller-fired action and runs the resulting cascade. Actions
+   *  declaring `when` cannot be fired through this method. Dispatch queued
+   *  effects separately with {@link Engine.drainEffects}. */
   fireAction: (args: FireActionArgs) => Promise<OperationResult>;
   /** Edit a declared-editable field directly (the generic edit seam):
    *  reassign / reschedule / claim-by-hand / append-to-log, then cascade. */
   editField: (args: EditFieldArgs) => Promise<OperationResult>;
+  /** Records an effect result, applies its completion field operations, and
+   *  runs the resulting cascade. Use {@link Engine.drainEffects} to invoke
+   *  registered handlers. */
   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>;
+  /** Reevaluates an instance and commits enabled triggers and transitions
+   *  until progression settles. A successful call reports `changed: false`
+   *  when the instance remains unchanged. It does not run effect handlers;
+   *  dispatch queued work with {@link Engine.drainEffects}. */
   tick: (args: OperationArgs) => Promise<OperationResult>;
   /** Project the instance from an actor's perspective — per-action verdicts
    *  with structured disabled reasons. Pure read. */
@@ -3441,8 +3689,9 @@ export declare interface Engine {
   setStage: (args: SetStageArgs) => Promise<OperationResult>;
   /** Admin override — hard-stop an in-flight instance where it stands. */
   abortInstance: (args: AbortInstanceArgs) => Promise<OperationResult>;
-  /** Admin override — reset a failed/terminal activity in the current stage
-   *  back to `active` (re-run) or `skipped` (bypass), then cascade. */
+  /** Changes a terminal activity in the current stage to `active` or `skipped`,
+   *  then continues the cascade. Already-fired triggers do not fire again
+   *  during the same stage visit. */
   resetActivity: (args: ResetActivityArgs) => Promise<OperationResult>;
   /** Admin override — remove a deployed definition (instances are only ever aborted, never deleted). */
   deleteDefinition: (
@@ -3683,11 +3932,13 @@ export declare interface EvaluateArgs {
 }
 
 /**
- * The pure projection at the heart of runtime evaluation: given an
- * instance, its definition, the resolved actor/grants, and a snapshot,
- * compute "what can this actor do right now, and why not the rest." The
+ * Evaluates an
+ * instance, its definition, resolved actor/grants, and a snapshot to
+ * report available actions and their blocking conditions. The
  * supplied snapshot is never refetched; guards using `->` may call the
- * supplied {@link EvaluateFromSnapshotArgs.guardDereference} resolver.
+ * supplied {@link EvaluateFromSnapshotArgs.guardDereference} resolver. An optional
+ * {@link EvaluateFromSnapshotArgs.documentAvailability} reader supplies completed
+ * evidence for missing references without replacing held content.
  * Feed it a fresh snapshot (e.g. rebuilt from a live store on change) for
  * reactive re-evaluation. Best-effort by design: verdicts are advisory,
  * not enforcement.
@@ -3722,10 +3973,13 @@ export declare interface EvaluateFromSnapshotArgs {
   /**
    * The in-memory snapshot to evaluate against. The caller assembles it
    * from whatever source — a fetch-backed evaluation or a
-   * live store. The `_id` of every doc must be in GDR-URI form, as
-   * {@link buildSnapshot} produces.
+   * live store. Every doc's `_id` must be in GDR-URI form, and `knownIds`
+   * must contain exactly those IDs for missing-reference diagnostics.
+   * Use {@link buildSnapshot} to construct both consistently.
    */
   snapshot: HydratedSnapshot;
+  /** Resolve availability outside the snapshot's perspective. Without a reader, absence is reported without claiming deletion. */
+  documentAvailability?: DocumentAvailabilityReader;
   /**
    * The `$now` reading every condition in this projection shares. Omit to
    * use {@link wallClock}; a reactive consumer (or the bench) passes its
@@ -3950,11 +4204,7 @@ export declare function extractDocumentId(gdrUriString: string): string;
 /** `resourcePath` is caller-supplied so this works for both project ACLs and a dedicated workflow-collaboration resource. */
 declare function fetchGrants(args: {
   client: {
-    request: <T>(opts: {
-      url: string;
-      signal?: AbortSignal;
-      tag?: string;
-    }) => Promise<T>;
+    request: NonNullable<WorkflowClient["request"]>;
   };
   resourcePath: string;
   signal?: AbortSignal;
@@ -4096,7 +4346,26 @@ export declare interface FieldDescription {
 }
 
 /**
- * One declared field entry as authored and stored: name, value kind, and its scope's sourcing and editability.
+ * A field declaration whose location determines its scope and lifetime.
+ * Workflow fields initialize at start; stage and activity fields initialize
+ * on each stage visit. {@link FieldSource} controls initialization;
+ * {@link Editable} controls direct edits independently.
+ *
+ * `required: true` is valid only on workflow-scope fields with an `input`
+ * source. It requires a non-null value at start or spawn. On `subject`,
+ * `doc.ref`, and `doc.refs`, selected targets must also remain readable in the
+ * workflow perspective after initialization. Missing targets block normal
+ * actions, triggered actions, and transitions. Abort and permitted field edits remain available.
+ * `subject` is also
+ * workflow-scope-only, with at most one subject per definition. Each scope
+ * may declare at most one `dueDate` or `dueDatetime` field, always top-level.
+ *
+ * `types` is a nonempty list of accepted document types on `subject`,
+ * `doc.ref`, or `doc.refs`; omit it to accept any document type. `roles`
+ * constrains assignment eligibility only on `assignee` and `assignees`.
+ * {@link FieldShape}, {@link ChoiceOptions}, and {@link ScalarValidation}
+ * define the nested-shape and scalar constraints. Authoring conveniences are
+ * accepted by {@link AuthoringFieldEntry}.
  *
  * @interface
  */
@@ -4139,7 +4408,22 @@ export declare interface FieldInsight {
 
 export declare type FieldKind = keyof FieldValueMap;
 
-/** A field mutation targeting the supplied field-reference shape. */
+/**
+ * A field mutation targeting a declared field. Resolved values must satisfy
+ * that field's shape, choices, validation, and assignment constraints.
+ *
+ * `field.setIfMissing` supports nullable fields only. If a value exists, it
+ * leaves the value unchanged and records no `opApplied` history event.
+ * `field.inc` and `field.dec` require an initialized `number` field; their
+ * delta defaults to `1`. Both the delta and resulting value must be finite,
+ * and the result must satisfy the field's validation bounds.
+ *
+ * `field.append` adds one valid list member. `field.updateWhere` accepts only
+ * `array` fields and merges an object into matching rows. The merge cannot
+ * write `_key` or `_type`, and each resulting row must satisfy its declared
+ * shape. `field.removeWhere` supports list fields. See {@link Op} for row
+ * selection and history behavior.
+ */
 export declare type FieldMutationOp<
   TTarget extends {
     field: string;
@@ -4187,8 +4471,9 @@ export declare type FieldMutationOp<
     };
 
 /**
- * A stored field mutation. `field.inc` and `field.dec` use the same names as
- * `@sanity/client` patches and default an omitted `value` to a delta of `1`.
+ * A {@link FieldMutationOp} whose target scope is explicit. Actions can write
+ * fields in their activity, stage, or workflow. Effect completions accept only
+ * workflow- or stage-scoped field operations, never activity status changes.
  */
 export declare type FieldOp = FieldMutationOp<StoredFieldRef>;
 
@@ -4220,12 +4505,16 @@ declare type FieldReadExpr = {
 export declare type FieldScope = "workflow" | "stage" | "activity";
 
 /**
- * A sub-field shape used inside an `object`'s `fields` or an `array`'s `of` —
- * lighter than {@link FieldEntry}: no `initialValue`/`editable`/`required`,
- * since a sub-field's value comes from the parent. An `object` kind requires
- * non-empty `fields` and no `of`; an `array` kind requires non-empty `of` and
- * no `fields`; every other kind requires neither — enforced at parse, not
- * visible in this type.
+ * A nested field shape inside an object's `fields`, an array's `of`, or an
+ * effect's `outputs`. It has no initialization, direct editability, or required
+ * setting; those belong to {@link FieldEntry}.
+ *
+ * An `object` requires nonempty `fields` and no `of`. An `array` requires
+ * nonempty `of` and no `fields`. Other types accept neither. Sibling names
+ * must be unique. Use ordinary `date` and `datetime` here; `dueDate` and
+ * `dueDatetime` are not valid nested fields or effect outputs.
+ * {@link ChoiceOptions} and {@link ScalarValidation} constrain supported
+ * scalar types. `roles` is valid only on `assignee` and `assignees` shapes.
  */
 export declare interface FieldShape {
   type: FieldValueKind;
@@ -4241,11 +4530,28 @@ export declare interface FieldShape {
 }
 
 /**
- * How a field seeds its `initialValue`, once at materialisation (advisory
- * after — the field stays freely editable). Absent means working memory: the
- * field starts empty and an op fills it later, spelled by omission rather
- * than an arm. Distinct from {@link ValueExpr}, an op's write payload; they
- * overlap only on the literal and field-read arms.
+ * Supplies a field's `initialValue` once, when the field is initialized.
+ * Omitting the source starts the field empty; an operation can fill it later.
+ * The source does not grant permission to edit. Direct editing requires an
+ * {@link Editable | editable} declaration.
+ *
+ * Distinct from {@link ValueExpr}, which supplies an operation's write value.
+ * Only the literal and field-read forms are shared.
+ *
+ * `input` reads workflow inputs supplied at start or spawn. Stage and activity
+ * input seeds receive no caller value; activity input seeds produce a deploy
+ * warning. `literal` supplies a fixed value. `query` runs against the Content
+ * Lake with earlier fields in the same scope available as `$fields`.
+ * Reference normalization can omit unrecognized values without recording
+ * `fieldQueryDiscarded`. A result that fails validation after normalization
+ * uses the field's empty value (`null` or `[]`) and records that event.
+ * A failed query throws.
+ *
+ * A `fieldRead` seed reads earlier fields in its own scope when `scope` is
+ * omitted. A stage or activity seed can read workflow fields with
+ * `scope: 'workflow'`. An activity seed cannot read stage fields. At workflow
+ * scope, omit `scope` to read an earlier workflow field. `path` selects a
+ * nested value; these reads do not load referenced documents.
  */
 export declare type FieldSource = FieldSourceInternal;
 
@@ -4261,6 +4567,11 @@ declare type FieldSourceInternal =
   | LiteralExpr
   | FieldReadExpr;
 
+/** Shared diagnostic field-address label for workspace consumers; unsupported outside this workspace.
+ * @internal
+ */
+export declare function _fieldTargetLabel(target: EditFieldTarget): string;
+
 /**
  * Every leaf replaced by its type name (`null` distinct from `object`); keys sorted by
  * UTF-16 code unit, not locale collation, so the shape canonicalises identically on every
@@ -4418,16 +4729,19 @@ export declare interface FiringConsequence {
 export { formatRead };
 
 /**
- * Build a GDR URI from a workflow resource config + a document id
- * within that resource. This is how the engine mints `_id`s for
- * definitions / instances / ancestor refs into its own resource.
+ * Creates a {@link GdrUri} for a document in the supplied resource. Dataset
+ * document IDs must be stable; `drafts.` and `versions.<release>.` prefixes
+ * throw. Select draft or release content through {@link WorkflowInstance.perspective}.
  */
 export declare function gdrFromResource(
   res: WorkflowResource,
   documentId: string,
 ): GdrUri;
 
-/** Build a GDR (id + type) pointing at a document within a workflow resource. */
+/**
+ * Creates a typed document reference in the supplied resource. Dataset
+ * references require a stable document ID, as described by {@link gdrFromResource}.
+ */
 export declare function gdrRef<TType extends string = string>({
   res,
   documentId,
@@ -4463,18 +4777,21 @@ export declare type GdrScheme =
   | "dashboard";
 
 /**
- * Typed GDR URI string. The compiler rejects bare doc ids (`"doc-1"`)
- * — only `<scheme>:<...id-parts>` values typecheck. Construct one via
- * `gdrUri()` / `gdrFromResource()` / `refDataset()` etc., or by hand
- * with the scheme prefix baked in (`` `dataset:proj:ds:${docId}` `` ).
+ * Resource-qualified document URI with a {@link GdrScheme} prefix. Construct
+ * it with {@link gdrUri}, {@link gdrFromResource}, or {@link refDataset}.
+ * Use {@link parseGdr} to validate a string's complete addressing format.
  *
- * Combined with schema validation at the API boundary, this is the
- * type + runtime guarantee that no bare-string id reaches the
- * snapshot, field entry, or filter layer.
+ * Dataset URIs require the stable document ID, such as `article-1`, without
+ * a `drafts.` or `versions.<release>.` prefix. Select draft and release
+ * content through {@link WorkflowInstance.perspective}.
  */
 export declare type GdrUri = `${GdrScheme}:${string}`;
 
-/** Compose a GDR URI from parts. Inverse of `parseGdr`. */
+/**
+ * Creates a {@link GdrUri} from addressing parts. For datasets, `documentId`
+ * must be the stable ID; `drafts.` and `versions.<release>.` prefixes throw.
+ * Select draft or release content through {@link WorkflowInstance.perspective}.
+ */
 export declare function gdrUri(
   parts:
     | {
@@ -4559,8 +4876,13 @@ declare function grantsPermissionOn(args: {
   userId?: string;
 }): Promise<boolean>;
 
-/** A named readiness condition. Activities accept only `'groq'`; workflow
- *  `start.requirements` also accepts `'singleSubject'` — see {@link StartRequirement}. */
+/**
+ * A named GROQ readiness condition. Its name must be unique in the containing
+ * requirements array. Activity requirements use instance and caller variables;
+ * workflow requirements use the input and projected dataset in {@link StartBlock}.
+ * Every requirement must pass before the corresponding caller action or fresh
+ * standalone start can commit.
+ */
 export declare type GroqRequirement = RequirementBase & {
   type: "groq";
   query: string;
@@ -4700,7 +5022,10 @@ export declare type GuardDereference = (ref: {
   _ref: string;
 }) => PromiseLike<Record<string, unknown> | null>;
 
-/** The stored document, pattern, type, and authored-action facets a guard matches. */
+/**
+ * A stored guard's match criteria. See {@link AuthoringGuard} for matching
+ * rules; stored `idRefs` contains strings instead of typed {@link GuardRead}s.
+ */
 export declare type GuardMatch = Guard["match"];
 
 /**
@@ -4721,15 +5046,13 @@ export declare function guardMatches({
 }): boolean;
 
 /**
- * A deploy-time value read on a guard's `match.idRefs` / `metadata`, typed
- * like {@link ValueExpr} (`self`/`now`/`fieldRead`, plus the guard-only
- * `effectsRead` for a completed effect's output). Workflow-scope only — a
- * guard outlives any activity, so `fieldRead` here carries no `scope`.
- * Desugar prints the STORED string spelling the deploy resolver and guard
- * refresh parse (`"$self"`, `"$now"`, `"$fields.<name>[.path]"`,
- * `"$effects['<name>'][.path]"`); those spellings are single-line strings
- * matched by anchored regexes, so a line break in a path would print an
- * unparseable read.
+ * A value read for a guard's `match.idRefs` or `metadata`, resolved when the
+ * guard is created or refreshed. `fieldRead` reads workflow fields only;
+ * stage and activity fields are unavailable. `effectsRead` reads a completed
+ * effect's output. `self` supplies the instance's GDR URI and `now` its ISO
+ * clock value.
+ * Paths cannot contain line breaks, and effect names cannot contain `'`.
+ * Stored {@link Guard} declarations carry string forms of these reads.
  */
 export declare type GuardRead =
   | {
@@ -4873,15 +5196,13 @@ export declare function guardsForResource(
 export { guillemets };
 
 /**
- * Content fingerprint of an authored definition: the canonical JSON of its
- * content, hashed. Stamped on the deployed document ({@link DeployedDefinition})
- * and pinned on every instance, so a redeploy of identical content is a no-op
- * and a definition that drifted from what an instance pinned is detectable.
- *
- * Advisory, like every engine check (the lake is the only enforcement point):
- * FNV-1a is a fast, deterministic, dependency-free, isomorphic digest — enough
- * to detect honest change and drift, not a tamper-proof seal. Kept synchronous
- * so the pure planning path needs no `await`.
+ * Computes a deterministic, non-cryptographic fingerprint of authored
+ * definition content. The result is 16 lowercase hexadecimal characters.
+ * Object-key order does not affect it; array order and field values do.
+ * Pass authored content without stored-document envelope fields: this
+ * function strips none of them. The authoring-only `runtime` block is the one
+ * key it ignores, so two definitions that differ only in a hosting kind
+ * fingerprint identically.
  */
 export declare function hashDefinitionContent(def: WorkflowDefinition): string;
 
@@ -5143,7 +5464,7 @@ export { humanize };
 export declare interface HydratedSnapshot {
   /** Hydrated docs, keyed by GDR URI as `_id`. */
   docs: SanityDocument[];
-  /** Existence-check helper; the core eval pipeline itself doesn't read it. */
+  /** The GDR URIs of every document in `docs`, used to diagnose missing references. */
   knownIds: Set<string>;
 }
 
@@ -5391,7 +5712,8 @@ export declare interface InstanceSession {
    *  call resolves the caller's identity/grants from the client's token over
    *  the network (cached per client) — plus each foreign subject resource's
    *  grants through its own client, for the subject-write forecast. The held
-   *  snapshot is not refetched; a guard predicate using `->` reads its target
+   *  snapshot is not refetched. Missing references receive completed availability
+   *  metadata checks; a guard predicate using `->` reads its target
    *  through the bound engine client. */
   evaluate(): Promise<WorkflowEvaluation>;
   /** Advance the instance against the held content: cascade auto-transitions,
@@ -5886,6 +6208,29 @@ export { MAX_COUNTERFACTUAL_INDEX };
  */
 export declare function minReaderModelOf(doc: object): number;
 
+/**
+ * A selected document absent from the evaluated snapshot. Absence alone does
+ * not prove deletion. When present, `availability` carries the completed check.
+ * This evidence is derived for the evaluation and is never persisted.
+ */
+export declare interface MissingDocument {
+  target: EditFieldTarget;
+  reference: GlobalDocumentReference;
+  /** The declared field title, when available. */
+  title?: string;
+  /** Completed availability evidence. Failed or unsupported checks yield `unreadable`.
+   * Omitted when the caller supplied only a content snapshot. */
+  availability?: DocumentAvailability;
+}
+
+/**
+ * Shared formatter for Workflows integrations; not a supported consumer API.
+ * @internal
+ */
+export declare function _missingDocumentsSummary(
+  documents: readonly MissingDocument[],
+): string;
+
 export declare interface MissingHandlerDeployInfo {
   phase: "deploy";
   name: string;
@@ -6131,8 +6476,15 @@ declare type NotesField = FieldBase<AuthoringEditable, GroupMembership> & {
   type: "notes";
 };
 
-/** A `field.updateWhere` / `field.removeWhere` op's `where` selects rows to
- *  mutate with rendered-scope GROQ (`$row`, `$params` bound) — row selection, not a gate; an unevaluable row never matches. */
+/**
+ * An action operation: a {@link FieldOp} or a status change on an activity in
+ * the current stage.
+ *
+ * For `field.updateWhere` and `field.removeWhere`, `where` evaluates each row
+ * as `$row`. Caller-fired actions also supply `$params`. Referenced document
+ * content is not loaded for row selection, and an unevaluable row never
+ * matches. An operation matching no rows still records `opApplied` history.
+ */
 export declare type Op =
   | FieldOp
   | {
@@ -6231,11 +6583,15 @@ export declare interface OperationResult {
    *  audit. */
   ranOps?: OpAppliedSummary[];
   /**
-   * The nearest future instant (ISO 8601) at which the clock alone changes what
-   * the instance evaluates to; schedule the next `tick` for it. Derived per
-   * call, never persisted. Absent on a terminal instance, when no site yields a
-   * boundary from the instance's values, and for a gate reading `$now` beside a
-   * caller variable, which {@link WorkflowEvaluation.nextEvaluationAt} carries.
+   * The earliest future ISO 8601 instant the engine can derive for a time-based
+   * change to the instance's evaluation. Schedule the next {@link Engine.tick | tick} for it.
+   * Excludes gates reading `$now` beside a caller variable;
+   * {@link WorkflowEvaluation.nextEvaluationAt} carries those boundaries.
+   * Derived per call, never persisted.
+   *
+   * Absent on a terminal instance or when the engine cannot derive a boundary.
+   * Conditions using date arithmetic may yield no boundary. Time can still
+   * affect a nonterminal instance when this value is absent.
    */
   nextEvaluationAt?: string;
 }
@@ -6253,10 +6609,11 @@ export declare function parentRef(
 /**
  * Parse one incoming definition at the deploy/diff boundary (`caller` prefixes
  * the error). Accepts authored content or a fetched definition document — the
- * document envelope is stripped (the inverse of the deploy serialisation, so a
- * fetched document round-trips to `unchanged` instead of fingerprinting its
- * envelope as content), then the remainder strict-parses against the stored
- * schema: any unknown key anywhere in the tree fails loud.
+ * document envelope and the authoring-only `runtime` block are stripped (the
+ * inverse of the deploy serialisation, so a fetched document round-trips to
+ * `unchanged` instead of fingerprinting its envelope as content, and a hosting
+ * kind never changes a definition's version), then the remainder strict-parses
+ * against the stored schema: any unknown key anywhere in the tree fails loud.
  */
 export declare function parseDefinitionInput(
   def: Record<string, unknown>,
@@ -6291,8 +6648,10 @@ export declare interface ParsedGdr {
 }
 
 /**
- * Parse a GDR URI into its scheme + addressing parts. Throws on
- * unknown scheme or malformed shape.
+ * Parses a GDR URI into its scheme and addressing parts. Throws for an
+ * unknown scheme, malformed addressing, or a dataset document ID prefixed
+ * with `drafts.` or `versions.<release>.`. Use the stable document ID and
+ * select draft or release content through {@link WorkflowInstance.perspective}.
  */
 export declare function parseGdr(uri: string): ParsedGdr;
 
@@ -6575,8 +6934,8 @@ export declare class ReaderModelAcknowledgementError extends WorkflowError<"read
   readonly expectedMinReaderModel: unknown;
   readonly requiredMinReaderModel: number;
   readonly engineMinReaderModel = 4;
-  readonly engineMaxReaderModel = 9;
-  readonly engineModelVersion = 9;
+  readonly engineMaxReaderModel = 10;
+  readonly engineModelVersion = 10;
   readonly documentationUrl = "https://www.sanity.io/docs/workflows/prerelease";
   constructor(
     expectedMinReaderModel: unknown,
@@ -6632,7 +6991,11 @@ export declare function refDashboard<TType extends string = string>({
   type,
 }: ResourceRefArgs<TType>): GlobalDocumentReference<TType>;
 
-/** Make a GDR pointer to a project-dataset doc. */
+/**
+ * Creates a typed reference to a dataset document. Pass the stable document
+ * ID; `drafts.` and `versions.<release>.` prefixes throw. Select draft or
+ * release content through {@link WorkflowInstance.perspective}.
+ */
 export declare function refDataset<TType extends string = string>({
   projectId,
   dataset,
@@ -6752,6 +7115,12 @@ export declare type RemediationVerb =
   | "set-stage"
   | "abort";
 
+/** @internal Validated project-member reads shared by workspace adapters; not a supported consumer API. */
+export declare function _requestProjectMembers(
+  request: (options: { url: string }) => Promise<unknown>,
+  projectId: string,
+): Promise<_ClientProjectMember[]>;
+
 /** The reader model a deployment must acknowledge for its submitted definitions. */
 export declare function requiredDefinitionReaderModel(
   definitions: readonly unknown[],
@@ -6798,7 +7167,10 @@ declare type RequirementBase = {
   description?: string | undefined;
 };
 
-/** Authored identity and display copy for one readiness requirement. */
+/**
+ * Identity and display copy for an unmet requirement. Authored requirements use
+ * their declared names; required-reference readability checks use `field:<name>`.
+ */
 export declare interface RequirementDescriptor {
   name: string;
   title?: string | undefined;
@@ -6817,11 +7189,10 @@ export declare interface ResetActivityArgs extends DedupableOperationArgs {
   /** Name of the activity to reset, within the instance's current stage. */
   activity: string;
   /**
-   * What to reset it into. `active` (the default) re-runs the activity — back
-   * in progress, for a caller to drive to completion again; `skipped` bypasses
-   * it — terminal but resolved, so a `$allActivitiesDone`-gated exit transition
-   * can fire. `done` is intentionally not offered: a reset is recovery, not a
-   * silent success.
+   * The target status. `active` (the default) reopens the activity for
+   * caller-fired actions. `skipped` counts the activity as resolved for
+   * `$allActivitiesDone`. Returning to `active` does not repeat a `when`
+   * action that already fired during this stage visit.
    */
   to?: ResetActivityTarget;
 }
@@ -6952,9 +7323,22 @@ export declare function resolveFieldEntry(
 ): ResolvedFieldEntry | undefined;
 
 /**
- * Resolve advisory `$attributes` for the caller-bound projection — project →
- * org → global-host attributes page. Cached per (client, orgId). Expected
- * absences (401–404) leave the bag unbound; unexpected failures throw.
+ * Resolves telemetry build or execution mode from `NODE_ENV`.
+ * `production` stays `production`; `development` and `test` map to `development`.
+ * Other values use the required fallback: CLI and MCP pass `production`, SDK
+ * passes `development`. This does not identify the target deployment or dataset.
+ * Unsupported outside the Workflows packages.
+ * @internal
+ */
+export declare function _resolveTelemetryEnvironment(
+  nodeEnv: string | undefined,
+  fallback: "development" | "production",
+): "development" | "production";
+
+/**
+ * Resolve the caller's advisory `$attributes`. Results are cached per client
+ * and organization. Expected absences (401–404) leave attributes undefined;
+ * unexpected failures throw.
  * Call only from soft-gate paths (evaluate / fireAction filter re-check /
  * editField), never from ticks or drainers.
  */
@@ -7053,14 +7437,44 @@ export declare function retractStageGuards(args: StageGuardArgs): Promise<void>;
  */
 export declare type RoleAliases = Record<string, string[]>;
 
+/**
+ * The `runtime` block on a deployment and on `defineWorkflow`. A workflow that
+ * declares none inherits its deployment's kind, and a deployment that declares
+ * none hosts on `'function'`. Authoring-only: the deploy strips it and stores
+ * nothing.
+ *
+ * It is a hint to the generator and to callers, never a rule the engine
+ * enforces. The engine never sees it: any engine built anywhere with a handler
+ * for an effect drains that effect when it calls `drainEffects`, whatever kind
+ * the node declares, so a `'selfHosted'` effect is drained by whoever registers
+ * its handler, the Studio included.
+ */
+export declare interface RuntimeBlock {
+  kind: RuntimeKind;
+}
+
+/**
+ * Where the generated unattended runtime hosts a workflow or an effect.
+ * `'function'` is a plain Sanity Function, `'durableFunction'` a durable one,
+ * and `'selfHosted'` a process you run yourself.
+ */
+export declare type RuntimeKind = "function" | "durableFunction" | "selfHosted";
+
 /** Whether two workflow resources address the same place. */
 export declare function sameResource(
   a: WorkflowResource,
   b: WorkflowResource,
 ): boolean;
 
-/** Inclusive scalar bounds. String/text bounds measure character length;
- * number bounds measure the numeric value. */
+/**
+ * Inclusive bounds for `string`, `text`, `number`, or `progress` values.
+ * String/text bounds count characters and must be non-negative integers.
+ * Number bounds are finite numeric values. Progress bounds may only narrow
+ * its inclusive 0–100 range.
+ *
+ * Supply at least one bound. When both are present, `min` must not exceed
+ * `max`. Null values remain allowed unless an input is required separately.
+ */
 export declare interface ScalarValidation {
   min?: number | undefined;
   max?: number | undefined;
@@ -7136,6 +7550,13 @@ export declare type SignalSemantic = (typeof SIGNAL_SEMANTICS)[number];
  */
 export declare const silentLogger: EngineLogger;
 
+/**
+ * A start requirement that rejects a fresh start when an unfinished run of
+ * this definition holds the same subject, across deployed versions.
+ * The workflow must declare an input-sourced `subject` field. Names are unique
+ * within the requirements array. Like other engine checks, this is advisory;
+ * it is not Content Lake enforcement.
+ */
 export declare type SingleSubjectRequirement = RequirementBase & {
   type: "singleSubject";
 };
@@ -7171,6 +7592,18 @@ export declare interface SiteConsequence {
   after: ConditionOutcome;
 }
 
+/**
+ * Suspends for `ms` before resolving. The engine's only deliberate wait is a
+ * `retry` policy's backoff between attempts inside one `drainEffects` call, so
+ * a deterministic harness substitutes one that moves its {@link Clock} instead
+ * of spending real time. Injected once beside the clock, never per call.
+ *
+ * A substitute must not resolve before `ms` has passed on whatever clock the
+ * engine reads: a policy's pacing and its `expiryMs` window are both judged
+ * against that clock.
+ */
+export declare type Sleeper = (ms: number) => Promise<void>;
+
 /** Pure resource-local dereferencing for held snapshot evaluation. */
 export declare function snapshotGuardDereference(args: {
   snapshot: HydratedSnapshot;
@@ -7199,16 +7632,16 @@ export declare class SpawnContractsInvalidError extends WorkflowError<"spawn-con
 }
 
 /**
- * A pure container — name, fields, guards, activities, transitions, no
- * behaviour of its own. Activities own enter, transitions own exit and
- * arrival; a stage with no transitions IS terminal (structural, nothing to
- * declare or mis-declare). `guards` are lake mutation guards active while
- * the stage holds, each compiling to a persisted guard document deployed on
- * stage entry and retracted on exit. `editable` is a tighten-only override
- * for the time the stage holds, keyed by an in-scope field name: the field's
- * own `editable` is the ceiling, ANDed with the stage value at runtime, so an
- * override can only NARROW — never open a field the baseline left closed. An
- * unlisted field inherits its baseline.
+ * The fields, activities, guards, and outgoing routes for one stage visit.
+ * A stage with no transitions is terminal: entering it completes the instance,
+ * and it cannot declare activities. Put completion work in the source stage
+ * or give the working stage an outgoing transition.
+ *
+ * Guards are registered on entry and retracted on exit. `editable` overrides
+ * are keyed by in-scope field name and apply while the stage is current.
+ * Each combines with the field's own edit condition using AND, so an override
+ * can restrict editing but cannot open a field whose baseline is closed.
+ * An unlisted field inherits its baseline.
  *
  * @interface
  */
@@ -7348,17 +7781,24 @@ export declare const START_REQUIREMENT_VARS: readonly {
 }[];
 
 /**
- * How standalone runs of this workflow begin. `filter` is a READ-SIDE
- * visibility predicate — "should a start surface offer this workflow for
- * this document?" — evaluated by `definitionsForDocument`/applicability in
- * the browse-time-pure start-filter context (`$tag`/`$definition`/`$now`
- * bound; `$fields` cannot exist before inputs do, so a `$fields` read here
- * is deploy-rejected). It is NOT a `startInstance` gate; the verb never
- * reads it. `requirements` are named readiness checks evaluated in author
- * order in the start-time context (GROQ nodes add `$fields`; `singleSubject`
- * is the one-in-flight-run-per-subject rule) — every node must pass before
- * `startInstance` commits. Both are advisory like every engine-side check;
- * the Content Lake remains the only enforcement point.
+ * Discovery and readiness rules for standalone starts.
+ * `filter` evaluates against a candidate document with `$tag`, `$definition`,
+ * and `$now`. It controls discovery and never gates `startInstance`.
+ * It cannot read `$fields` or caller variables.
+ *
+ * `requirements` evaluates named checks in declaration order before a fresh
+ * standalone start. All must pass. Resuming an existing start and spawning
+ * children do not rerun these checks. A GROQ requirement binds `$tag`,
+ * `$definition`, `$now`, and `$fields`, with no candidate document root.
+ * `$fields` contains supplied input values, including GDR reference envelopes;
+ * it excludes computed defaults and hydrated document content.
+ *
+ * At both sites, `*` scans projected instances in the engine's tag. Each row
+ * contains only `definition` (name), `subject` (GDR URI or null), and
+ * `completedAt` (ISO timestamp or null). Completed and aborted runs are
+ * included. Raw fields such as `_type`, `tag`, and `fields` are unavailable.
+ * Use {@link SingleSubjectRequirement} for one unfinished run per subject.
+ * These checks are advisory; the Content Lake remains the enforcement point.
  */
 export declare type StartBlock = StartFields & {
   kind: StartKind;
@@ -7464,15 +7904,19 @@ export declare interface StartInstanceArgs {
   initialFields?: InitialFieldValue[];
   ancestors?: GlobalDocumentReference[];
   /**
-   * The instance's start seed — stable named values set once at start (or
-   * handed down by a parent's `spawn.context`) and never mutated after.
+   * Stable named values supplied when starting this instance. They cannot
+   * be changed after start.
    * Effect bindings and conditions read them as `$context.<name>`; the
    * `$effects` bag is separate (completed effects' outputs only).
    *
-   * Each value may be any JSON — a scalar, a {@link GlobalDocumentReference},
+   * Values supplied directly to start may be any JSON: a scalar,
+   * a {@link GlobalDocumentReference},
    * or an arbitrary object/array. Scalars and GDRs store as their typed
    * `context` entries; anything else stores as one `context.json`
    * entry, so all forms read back the same under `$context.<name>`.
+   * A parent's `spawn.context` has a narrower contract: only strings, numbers,
+   * booleans, and full GDRs are accepted; nullish results are omitted, and
+   * other objects or arrays reject the spawn.
    */
   context?: StartContext;
   /**
@@ -7498,15 +7942,22 @@ export declare interface StartInstanceArgs {
    */
   grantsFromPath?: string;
   /**
-   * Optional read-side perspective for this instance. Threaded into
-   * field-entry query resolution and spawn `forEach.groq` discovery so
-   * a workflow can scope its reads to a Content Release stack. Child
-   * instances inherit the parent's perspective on spawn.
+   * Perspective for content reads, including field queries and subworkflow
+   * discovery. An explicit value applies to workflow-field initialization
+   * and subsequent reads.
+   *
+   * When omitted, workflow-field queries at start use `drafts`. After those
+   * fields resolve, the instance uses `[releaseName]` from its first populated
+   * workflow `release.ref` field, or `drafts` when none is populated.
+   * Under `drafts`, drafts take precedence over published content.
    *
-   * Pass `[releaseName]` for a workflow whose subject is a release;
-   * pass `[releaseName, "drafts"]` to also include drafts; omit for
-   * the engine's default (no perspective override = `"raw"` on the
-   * test client).
+   * A child's workflow fields initialize under its parent's perspective.
+   * Afterward, the child's first populated workflow `release.ref` field
+   * selects its release perspective; otherwise it inherits the parent's.
+   *
+   * Pass `[releaseName]` to read under a Content Release, or
+   * `[releaseName, 'drafts']` to include drafts. Engine-owned instance and
+   * definition documents, and `system.release` documents, always read under `raw`.
    */
   perspective?: WorkflowPerspective;
 }
@@ -7672,12 +8123,11 @@ export declare function stripSystemFields(
 ): Record<string, unknown>;
 
 /**
- * Why an in-flight instance is genuinely blocked — nothing advances it on its
- * own OR via a normal action. Ordered most- to least-actionable in
- * {@link diagnoseInstance}: a failed effect is the root cause even when it left
- * its activity looking merely "active", so it wins over the activity- and
- * transition-level symptoms it produces. Note an active activity awaiting a human
- * action is NOT here — that's the healthy {@link Diagnosis} `waiting` state.
+ * A fault or missing dependency in an in-flight instance. Missing documents
+ * follow effect/activity faults and precede transition faults. The diagnosis
+ * is advisory: it does not prohibit actions that can still run.
+ * An active activity awaiting a human action is the healthy
+ * {@link Diagnosis} `waiting` state.
  *
  * `transition-unevaluable` is the recoverable arm: every activity resolved,
  * but an exit transition's `when` came back GROQ `null` (a referenced operand
@@ -7686,6 +8136,10 @@ export declare function stripSystemFields(
  * definite `false`. It carries the undecidable transitions.
  */
 export declare type StuckCause =
+  | {
+      kind: "document-missing";
+      documents: MissingDocument[];
+    }
   | {
       kind: "failed-effect";
       effect: EffectHistoryEntry;
@@ -7840,17 +8294,27 @@ export declare interface SubworkflowEntry {
 }
 
 /**
- * Fan-out declared as an action's `spawn`, read back as `$subworkflows`.
- * `forEach` is GROQ producing one row per subworkflow (bound as `$row`); each
- * row needs an identity the engine can adopt on re-entry (`_key` ?? `_id` ??
- * GDR `id`, or the value itself for a scalar row) or the spawn fails.
- * `definition` resolves by stable `name`, ordered `version desc` unless
- * pinned. `with` seeds each child's initial fields; `context` delivers extra
- * parent-scope values into the child's `$context`. `onExit` governs only
- * still-live children when the cohort's scope stops applying: `'detach'`
- * (default) lets them run to completion, `'abort'` kills them recursively —
- * always an authored choice, never automatic. Whether the PARENT may move at
- * all is a separate gate over `$subworkflows`.
+ * Child workflows created by an action's `spawn`, exposed as `$subworkflows`.
+ * `definition` selects the highest deployed version unless a version is pinned.
+ *
+ * `forEach` evaluates with workflow fields only and no caller variables, even
+ * for a caller-fired action. Rows need unique identities: a nonempty `_key`,
+ * then `_id`, then a GDR's `id`, or a scalar's string representation.
+ * Missing or duplicate identities reject the spawn. Re-entry adopts matching
+ * live children from the same activity, action, and definition instead of
+ * duplicating them.
+ *
+ * `with` maps child input-field names to expressions evaluated with `$row`.
+ * `context` evaluates once without `$row` and supplies the child's `$context`.
+ * Both use the parent activity's field scope and the acting identity when
+ * available. Neither binds `$can`, `$attributes`, or `$params`.
+ * Context results must be strings, numbers, booleans, or full GDRs; null and
+ * undefined omit the entry. Other objects and arrays reject the spawn.
+ *
+ * `onExit` governs live children when their cohort leaves scope: `detach`
+ * (the default) leaves them running; `abort` stops them recursively. Aborting
+ * the parent always stops its children. Parent transitions must separately
+ * declare whether they wait for the cohort to settle.
  *
  * @interface
  */
@@ -8022,7 +8486,7 @@ export declare interface TelemetryIntake {
  *  closes the socket (a `Promise.race` alone cannot). */
 export declare interface TelemetryIntakeClient {
   request: <T>(opts: {
-    uri: string;
+    url: string;
     method?: string;
     body?: unknown;
     tag?: string;
@@ -8085,14 +8549,14 @@ export declare interface TodoListItem {
 }
 
 /**
- * A pure edge — `{name, when, to}` plus presentation, no ops or effects
- * (structure never does; only actions do). Every transition is evaluated on
- * every commit and cascade; the first truthy `when` in declaration order
- * fires. No action coupling: a routing difference is written into fields by
- * an action and read by the trigger — arrival work is a `when: 'true'`
- * action in the destination stage, and exit work is an action in the source
- * stage whose `when` repeats this transition's condition (the hop rule
- * guarantees it commits before the move).
+ * A one-way route to another stage, without operations or effects. Selection
+ * checks `when` conditions in declaration order. The first satisfied condition
+ * fires; an earlier unevaluable condition, such as GROQ null, stops selection
+ * without considering later routes. A false condition permits the next route.
+ *
+ * Actions write routing decisions into fields; transitions read that state.
+ * Source-stage triggered actions run before transition selection. Arrival work
+ * belongs to a triggered action in a nonterminal destination stage.
  */
 export declare type Transition = TransitionFields & {
   when: string;
@@ -8217,10 +8681,18 @@ export declare interface ValidationIssue {
 }
 
 /**
- * An op's write payload, resolved to concrete JSON when the op applies. Each
- * context-bound arm has a rendered `$`-twin in conditions (`actor` ↔
- * `$actor`, `now` ↔ `$now`, `self` ↔ `$self`), so learning one side teaches
- * the other. Distinct from {@link FieldSource}, a field's seed recipe.
+ * An operation's write value, resolved when the operation applies.
+ * `param` reads a caller-supplied action argument; `actor` records the acting
+ * identity. `now` supplies the operation's ISO timestamp, `self` its instance's
+ * GDR URI, and `stage` the current stage name. `object` resolves its fields
+ * recursively.
+ *
+ * A `fieldRead` with no scope searches activity, stage, then workflow fields.
+ * An explicit scope searches only that scope. A pathless read from a subject
+ * or `doc.ref` into another subject or `doc.ref` preserves the stored reference.
+ * Other reads use the referenced snapshot document, or only its `_id` and
+ * `_type` when it is not loaded. No additional documents are fetched.
+ * Initialization uses {@link FieldSource}, whose field-read scope rules differ.
  */
 export declare type ValueExpr = ValueExprInternal;
 
@@ -8325,17 +8797,20 @@ export { withAssignment };
 
 export declare const workflow: {
   /**
-   * Deploy a set of definitions as one call. Definitions are immutable and
-   * content-addressed: the author writes no version, identical content no-ops
-   * (`unchanged`), and any change mints the next version (`created`) — deploy
-   * never patches a deployed version out from under the instances pinned to it.
-   * The engine orders the batch itself (children before the parents that spawn
-   * them). Refs may point inside the batch or at already-deployed definitions;
-   * a ref resolving to neither, or a cycle, errors before any write. Input is
-   * authored content or a fetched definition document — the document envelope
-   * (`_*` system fields, `tag`, `version`, `contentHash`) is stripped at the
-   * boundary and never fingerprinted, so a fetched document redeploys as
-   * `unchanged`; any other unknown key fails loud.
+   * Deploys immutable definition versions. The engine assigns each version:
+   * content matching the latest deployed fingerprint returns `unchanged`;
+   * otherwise deployment creates the next version and returns `created`.
+   * Redeploying older content creates a new version; existing versions and
+   * their pinned instances are unchanged.
+   *
+   * Children deploy before parents. References may resolve within the batch
+   * or to deployed definitions; unresolved references and cycles reject the
+   * batch before any write.
+   *
+   * Accepts authored content or a fetched definition document. The document
+   * envelope (`_*` system fields, `tag`, `version`, `contentHash`) is excluded
+   * from the fingerprint. Fetched content follows the same latest-version
+   * comparison; any other unknown input key is rejected.
    */
   deployDefinitions: <T extends WorkflowDefinitionInput<T>>(
     rawArgs: Telemetered<DeployDefinitionsArgs<T> & EngineScopeArgs>,
@@ -8708,17 +9183,20 @@ export declare interface WorkflowAutonomy extends AutonomyAnswer {
 }
 
 export declare interface WorkflowClient {
+  /** Build a resource-bound data URL, as on SanityClient. Used to confirm document availability. */
+  getDataUrl?: (operation: string, path?: string) => string;
   /**
-   * Read the effective client configuration. The engine reads two fields from
-   * it. `apiHost` is probed before deriving the global `/users/me` sibling,
-   * because `@sanity/client` shallow-merges `withConfig` overrides and
-   * otherwise preserves an explicit project host even when
-   * `useProjectHostname` is set to `false`. `projectId` addresses the project's
-   * user directory when a project-scoped principal has to be bridged to its
-   * account-global id — a client reporting none has no directory to ask, and
-   * such a session is refused rather than stamped locally.
+   * Read the effective client configuration. The engine uses `apiHost` for
+   * account-global identity routing and `projectId` for project directory and
+   * organization lookups. Without `projectId`, organization attributes cannot
+   * be loaded and project-scoped principals cannot use the directory bridge.
+   *
+   * For clients without {@link WorkflowClient.withConfig}, an omitted
+   * `apiVersion` means the implementation must already serve
+   * {@link ENGINE_API_VERSION}. A declared `apiVersion` other than that version
+   * skips organization attributes with a warning.
    */
-  config?: () => WorkflowClientConfig;
+  config?: () => WorkflowClientConfigState;
   fetch: <T = unknown>(
     query: string,
     params?: Record<string, unknown>,
@@ -8819,21 +9297,12 @@ export declare interface WorkflowClient {
    * discovery uses its dry-run fallback, while a definition containing
    * role-constrained assignment fields fails loudly because the engine cannot
    * read the project membership directory required to validate assignees.
+   *
+   * Raw request transport. The engine passes the request target through
+   * `url`; relative paths must resolve against the client's configured API
+   * host, matching supported `SanityClient.request` implementations.
    */
-  request?: <T>(opts: {
-    /** Raw URL (host + path). One of `url` / `uri` required. */
-    url?: string;
-    /**
-     * Project-scoped path resolved against the `@sanity/client`'s
-     * apiHost (e.g. `/users/me` → `https://api.sanity.io/v1/users/me`).
-     * Use this for global endpoints like `/users/me`. Mirrors
-     * `SanityClient.request({uri})` in `@sanity/client`.
-     */
-    uri?: string;
-    signal?: AbortSignal;
-    /** Optional `?tag=` query for observability — supported by `@sanity/client`. */
-    tag?: string;
-  }) => Promise<T>;
+  request?: <T>(opts: WorkflowRequestOptions) => Promise<T>;
 }
 
 /**
@@ -8859,6 +9328,17 @@ export declare interface WorkflowClientConfig {
   useProjectHostname?: boolean;
 }
 
+/** The engine reads only project and API metadata from this value. */
+export declare interface WorkflowClientConfigState extends Omit<
+  WorkflowClientConfig,
+  "resource"
+> {
+  resource?: {
+    type: string;
+    id: string;
+  };
+}
+
 export declare interface WorkflowCommitOptions {
   /**
    * When the mutation becomes visible to subsequent queries. The engine
@@ -9168,44 +9648,22 @@ declare const WorkflowConfigSchema: v.ObjectSchema<
                 readonly [
                   v.ArraySchema<
                     v.CustomSchema<
-                      {
-                        name: string;
-                        semantics?: Semantic[] | undefined;
-                        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;
-                      },
+                      DefinedWorkflow,
                       v.ErrorMessage<v.CustomIssue> | undefined
                     >,
                     undefined
                   >,
                   v.MinLengthAction<
-                    {
-                      name: string;
-                      semantics?: Semantic[] | undefined;
-                      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;
-                    }[],
+                    DefinedWorkflow[],
                     1,
                     "a deployment needs at least one definition"
                   >,
                 ]
               >;
+              readonly runtime: v.OptionalSchema<
+                v.GenericSchema<RuntimeBlock>,
+                undefined
+              >;
             },
             undefined
           >,
@@ -9255,20 +9713,8 @@ declare const WorkflowConfigSchema: v.ObjectSchema<
                       };
                 }[]
               | undefined;
-            definitions: {
-              name: string;
-              semantics?: Semantic[] | undefined;
-              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;
-            }[];
+            definitions: DefinedWorkflow[];
+            runtime?: RuntimeBlock | undefined;
           }[],
           1,
           "a config needs at least one deployment"
@@ -9317,20 +9763,8 @@ declare const WorkflowConfigSchema: v.ObjectSchema<
                       };
                 }[]
               | undefined;
-            definitions: {
-              name: string;
-              semantics?: Semantic[] | undefined;
-              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;
-            }[];
+            definitions: DefinedWorkflow[];
+            runtime?: RuntimeBlock | undefined;
           }[],
           (
             issue: v.CheckIssue<
@@ -9377,20 +9811,8 @@ declare const WorkflowConfigSchema: v.ObjectSchema<
                           };
                     }[]
                   | undefined;
-                definitions: {
-                  name: string;
-                  semantics?: Semantic[] | undefined;
-                  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;
-                }[];
+                definitions: DefinedWorkflow[];
+                runtime?: RuntimeBlock | undefined;
               }[]
             >,
           ) => string
@@ -9439,20 +9861,8 @@ declare const WorkflowConfigSchema: v.ObjectSchema<
                       };
                 }[]
               | undefined;
-            definitions: {
-              name: string;
-              semantics?: Semantic[] | undefined;
-              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;
-            }[];
+            definitions: DefinedWorkflow[];
+            runtime?: RuntimeBlock | undefined;
           }[],
           (
             issue: v.CheckIssue<
@@ -9499,20 +9909,8 @@ declare const WorkflowConfigSchema: v.ObjectSchema<
                           };
                     }[]
                   | undefined;
-                definitions: {
-                  name: string;
-                  semantics?: Semantic[] | undefined;
-                  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;
-                }[];
+                definitions: DefinedWorkflow[];
+                runtime?: RuntimeBlock | undefined;
               }[]
             >,
           ) => string
@@ -9600,35 +9998,22 @@ export declare interface WorkflowDefinitionDeployedData {
  * of a literal is a finite key union that `string` never extends) — i.e. how
  * fetch results are typed (`Record<string, unknown>`), which pass through to
  * the runtime boundary parse. Everything precisely typed gets the exact
- * {@link WorkflowDefinition} contract: beyond the document envelope
- * (the closed system-key union, so a typed {@link DeployedDefinition} passes
- * castless), unknown keys are `never` — a typo'd literal is a compile error,
- * never a silent collapse to the record arm.
+ * {@link WorkflowDefinition} contract with two accepted exceptions: the
+ * document envelope (the closed system-key union, so a typed
+ * {@link DeployedDefinition} passes castless) and the authoring-only root
+ * `runtime` block, so a {@link DefinedWorkflow} passes castless too. Every
+ * other unknown key is `never`, making a typo'd literal a compile error rather
+ * than a silent collapse to the record arm.
  */
 export declare type WorkflowDefinitionInput<T> = string extends keyof T
   ? Record<string, unknown>
   : WorkflowDefinition & {
       [K in Exclude<
         keyof T,
-        keyof WorkflowDefinition | DocumentEnvelopeKey
+        keyof WorkflowDefinition | DocumentEnvelopeKey | AuthoringRuntimeKey
       >]?: never;
     };
 
-/**
- * Structural schema for a STORED workflow definition — primitives only,
- * every reference scope resolved. Cross-field invariants (unique names,
- * transition targets, effect-name uniqueness, predicate shadowing) are
- * checked by `checkWorkflowInvariants` after desugar — see `defineWorkflow`.
- * Carries NO `version`: a definition's version and content fingerprint are
- * stamped onto the deployed document at deploy time, derived from the
- * content itself, so redeploying identical content is a no-op and any
- * change mints the next version.
- *
- * Exported (module-level, not package API) for the model-surface gate's
- * coverage test and for `parseStoredDefinition` — the boundary parse for a
- * definition that did not come out of `defineWorkflow` in-process; trusted
- * in-process desugar output is never re-parsed.
- */
 declare const WorkflowDefinitionSchema: v.GenericSchema<
   WorkflowFields<FieldEntry, Stage, StartBlock>
 >;
@@ -9640,10 +10025,22 @@ declare const WorkflowDefinitionSchema: v.GenericSchema<
 export declare type WorkflowDeployment = WorkflowConfig["deployments"][number];
 
 /**
- * What an author writes for one deployment: the highest reader model verified
- * across runtimes sharing its workflow resource. Runtime validation compares
- * it with the submitted definitions, so a dependency upgrade alone does not
- * require changing the literal.
+ * Author one deployment with a nonempty `definitions` array and a
+ * {@link WorkflowResource}. Dataset resource IDs use `<projectId>.<dataset>`.
+ *
+ * `name` and `tag` must contain only ASCII lowercase letters, digits, and dashes,
+ * starting with a letter or digit. Deployment names and `(workflowResource, tag)`
+ * pairs must be unique across the config. Optional `resourceAliases` use the same
+ * name grammar, with unique names within this deployment.
+ *
+ * `expectedMinReaderModel` is the highest reader model you have verified across
+ * runtimes sharing the workflow resource. Supply a reviewed numeric literal.
+ * Definition submission checks it against the required reader floor; upgrading
+ * a dependency alone does not require changing it.
+ *
+ * `runtime` is the default hosting kind for this deployment's workflows, which
+ * each workflow and effect may override. Omitted, its workflows host on
+ * `'function'`.
  */
 export declare type WorkflowDeploymentInput = Omit<
   WorkflowDeployment,
@@ -9745,6 +10142,16 @@ export declare type WorkflowErrorKind =
 export declare interface WorkflowEvaluation {
   instance: WorkflowInstance;
   definition: WorkflowDefinition;
+  /** Missing targets of populated subject, doc.ref, and doc.refs fields in active
+   * scopes. Clears on resolution; empty fields and exited-stage fields are excluded.
+   * Required reference declarations and runtime conditions determine whether absence blocks progress. */
+  missingDocuments?: MissingDocument[];
+  /**
+   * Missing required reference targets, or references read by unmet runtime requirements or transition conditions,
+   * including named predicates in their evaluated scope. Empty when missing references
+   * are optional for current progress. Omitted when no references are missing.
+   */
+  blockingMissingDocuments?: MissingDocument[];
   /** The workflow's advisory meaning, unchanged from its definition. */
   semantics?: Semantic[] | undefined;
   actor: Actor;
@@ -9776,11 +10183,14 @@ export declare interface WorkflowEvaluation {
    */
   autonomy: WorkflowAutonomy;
   /**
-   * The nearest future instant (ISO 8601) at which the clock alone changes this
-   * projection; re-evaluate then. Includes a gate reading `$now` beside
-   * `$actor`, `$assigned`, `$can`, or `$attributes`, evaluated in this actor's
-   * scopes. Derived per call, never persisted. Absent on a terminal instance
-   * and when no site yields a boundary from those scopes.
+   * The earliest future ISO 8601 instant the engine can derive for a time-based
+   * change to this evaluation. Re-evaluate then. Includes a gate reading `$now`
+   * beside `$actor`, `$assigned`, `$can`, or `$attributes`, evaluated in this
+   * actor's scopes. Derived per call, never persisted.
+   *
+   * Absent on a terminal instance or when the engine cannot derive a boundary.
+   * Conditions using date arithmetic may yield no boundary. Time can still
+   * affect a nonterminal instance when this value is absent.
    */
   nextEvaluationAt?: string;
 }
@@ -9871,15 +10281,14 @@ export declare interface WorkflowInstance extends SanityDocument {
   /** Frozen JSON snapshot of the definition at the moment the instance started. */
   definitionSnapshot: string;
   /**
-   * Workflow-level resolved field entries.
-   * Populated from the workflow definition's `fields[]` declarations plus
-   * the caller-supplied `initialFields` at `startInstance`. Persists for
-   * the lifetime of the instance.
+   * Resolved workflow fields, retained for the instance's lifetime. Their
+   * initial values come from the definition's `fields` declarations and
+   * {@link StartInstanceArgs.initialFields}.
    *
-   * To declare "the subject document of this workflow", add a
-   * `{ type: "doc.ref", name: "subject", initialValue: { type: "input" } }`
-   * entry to the workflow definition. Conditions then read it as
-   * `$fields.subject`. There is no other subject mechanism.
+   * To declare the workflow's subject document, use
+   * `{type: 'subject', name: 'subject', initialValue: {type: 'input'}}`.
+   * Conditions read that entry as `$fields.subject`. The `subject` field
+   * type identifies its role; naming a `doc.ref` field `subject` does not.
    */
   fields: ResolvedFieldEntry[];
   /**
@@ -9895,14 +10304,13 @@ export declare interface WorkflowInstance extends SanityDocument {
    */
   ancestors: GlobalDocumentReference[];
   /**
-   * Optional perspective applied to field-entry query reads and spawn
-   * `forEach.groq` discovery. When unset the engine treats reads as
-   * `"raw"` (no filtering). Set at `startInstance` time to scope a
-   * workflow's reads to a Content Release stack (e.g. `[releaseName]`
-   * or `[releaseName, "drafts"]`).
+   * Perspective for content reads, including field queries and subworkflow
+   * discovery. Defaults to {@link DEFAULT_CONTENT_PERSPECTIVE}, where drafts
+   * take precedence over published content. Set it through
+   * {@link StartInstanceArgs.perspective}; child instances inherit it.
    *
-   * Engine-internal reads of instance / definition documents are
-   * always raw, regardless of this field.
+   * Engine-owned instance and definition documents, and `system.release`
+   * documents, always read under `raw`.
    */
   perspective?: WorkflowPerspective;
   currentStage: StageName;
@@ -10076,6 +10484,14 @@ export declare type WorkflowPerspective =
   | "drafts"
   | string[];
 
+export declare interface WorkflowRequestOptions {
+  /** API-relative path resolved against the configured API host, or an absolute URL. */
+  url: string;
+  signal?: AbortSignal;
+  /** Optional `?tag=` query for observability — supported by `@sanity/client`. */
+  tag?: string;
+}
+
 /**
  * The resource a Sanity client is configured against — mirrors
  * `@sanity/client`'s `ClientConfigResource` discriminator. For