@sanity/workflow-engine 0.32.0 → 0.33.0

package/dist/define.d.ts

@@ -17,12 +17,12 @@ import * as v from "valibot";
  *
  * @interface
  */
-declare type Action = ActionFields<Op, string[]> & {
+declare type Action = ActionFields<Op, string[], Effect> & {
   roles?: string[] | undefined;
 };
 
 /** @inline */
-declare type ActionFields<TOp, TGroup> = {
+declare type ActionFields<TOp, TGroup, TEffect> = {
   name: string;
   semantics?: ActionSemantic[] | undefined;
   title?: string | undefined;
@@ -32,7 +32,7 @@ declare type ActionFields<TOp, TGroup> = {
   filter?: string | undefined;
   params?: ActionParam[] | undefined;
   ops?: TOp[] | undefined;
-  effects?: Effect[] | undefined;
+  effects?: TEffect[] | undefined;
   spawn?: Subworkflows | undefined;
 };
 
@@ -250,6 +250,23 @@ declare type AuthoringActivity = ActivityFields<
  */
 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
+ */
+declare type AuthoringEffect = EffectFields<AuthoringEffectRetry> & {
+  runtime?: EffectRuntimeBlock | undefined;
+};
+
+/** An {@link EffectRetry} whose omitted `kind` defaults to `engine`. */
+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`,
@@ -257,6 +274,7 @@ 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.
  */
 declare type AuthoringFieldEntry =
   | AuthoringRawFieldEntry
@@ -288,8 +306,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
  */
@@ -408,7 +440,11 @@ declare type AuthoringOp =
     };
 
 /** @inline */
-declare type AuthoringRawAction = ActionFields<AuthoringOp, GroupMembership> & {
+declare type AuthoringRawAction = ActionFields<
+  AuthoringOp,
+  GroupMembership,
+  AuthoringEffect
+> & {
   roles?: string[] | undefined;
   status?: TerminalActivityStatus | undefined;
 };
@@ -419,7 +455,12 @@ declare type AuthoringRawFieldEntry = FieldEntryFields<
   GroupMembership
 >;
 
-/** @interface */
+/**
+ * A {@link Stage} accepting authoring fields, activities, transitions, guards,
+ * and role-list editability. The same terminal-stage constraints apply.
+ *
+ * @interface
+ */
 declare type AuthoringStage = StageFields<
   AuthoringFieldEntry,
   AuthoringActivity,
@@ -428,21 +469,23 @@ declare type AuthoringStage = StageFields<
   AuthoringEditable
 >;
 
+/** A {@link StartBlock} whose omitted `kind` defaults to `interactive`. */
 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.
  */
 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
  */
@@ -450,13 +493,24 @@ declare type AuthoringWorkflow = WorkflowFields<
   AuthoringFieldEntry,
   AuthoringStage,
   AuthoringStartBlock
->;
+> & {
+  runtime?: RuntimeBlock | undefined;
+};
 
 declare interface ChoiceOption {
   title: string;
   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`.
+ */
 declare interface ChoiceOptions {
   list: ChoiceOption[];
 }
@@ -534,11 +588,21 @@ export declare function defineActivity(
   activity: AuthoringActivity,
 ): AuthoringActivity;
 
+/**
+ * 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.
+ */
+declare type DefinedWorkflow = WorkflowDefinition & {
+  runtime?: DefinitionRuntime | undefined;
+};
+
 /**
  * Validate and return an effect declaration — the registry model: `name` is
  * the effect's only identity; the host app registers a handler against it.
  */
-export declare function defineEffect(effect: Effect): Effect;
+export declare function defineEffect(effect: AuthoringEffect): AuthoringEffect;
 
 export declare function defineEffectDescriptor(
   descriptor: EffectDescriptor,
@@ -567,8 +631,9 @@ export declare function defineTransition(
 ): AuthoringTransition;
 
 /**
- * Validate, desugar, and return a workflow definition in its stored shape.
- * Throws with a formatted, path-prefixed error message if validation fails.
+ * Validate, desugar, and return a workflow definition in its stored shape, plus
+ * the `runtime` hosting the workflow or its effects declared. Throws with a
+ * formatted, path-prefixed error message if validation fails.
  *
  * Example error:
  *
@@ -580,7 +645,7 @@ export declare function defineTransition(
  */
 export declare function defineWorkflow(
   definition: AuthoringWorkflow,
-): WorkflowDefinition;
+): DefinedWorkflow;
 
 /**
  * Validate a deploy config — the binding of each definition's logical resource
@@ -602,6 +667,17 @@ export declare function defineWorkflowConfig(
   config: WorkflowConfigInput,
 ): WorkflowConfig;
 
+/**
+ * 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.
+ */
+declare interface DefinitionRuntime {
+  kind?: RuntimeKind | undefined;
+  effects?: Record<string, EffectRuntimeBlock> | undefined;
+}
+
 /**
  * Declared editability of a field — the generic edit seam's gate. Default
  * (absent) is NOT editable: a field is op-only engine working memory unless the
@@ -614,20 +690,24 @@ export declare function defineWorkflowConfig(
 declare type Editable = true | string;
 
 /**
- * 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
  */
-declare type Effect = v.InferOutput<typeof EffectSchema>;
+declare type Effect = EffectFields<EffectRetry>;
 
 /**
  * Effect handler descriptor, registered by the runtime against an effect
@@ -648,43 +728,96 @@ export declare interface EffectDescriptorParam {
   description?: string;
 }
 
-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
->;
+/** @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;
+};
+
+/**
+ * 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.
+ */
+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`).
+ */
+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.
+ */
+declare type EffectRetryKind = "engine";
+
+/**
+ * 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'`.
+ */
+declare type EffectRuntimeBlock =
+  | {
+      kind: "function";
+      timeout?: number | undefined;
+      memory?: number | undefined;
+    }
+  | {
+      kind: "durableFunction";
+    }
+  | {
+      kind: "selfHosted";
+    };
 
 /**
  * The kinds a VALUE can take — scalars aligned to Sanity's names, the
@@ -732,7 +865,26 @@ declare type FieldBase<TEditable, TGroup> = {
 };
 
 /**
- * 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
  */
@@ -753,7 +905,22 @@ declare type FieldEntryFields<TEditable, TGroup> = FieldBase<
   of?: FieldShape[] | undefined;
 };
 
-/** 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.
+ */
 declare type FieldMutationOp<
   TTarget extends {
     field: string;
@@ -801,8 +968,9 @@ 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.
  */
 declare type FieldOp = FieldMutationOp<StoredFieldRef>;
 
@@ -815,12 +983,16 @@ declare type FieldReadExpr = {
 };
 
 /**
- * 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.
  */
 declare interface FieldShape {
   type: FieldValueKind;
@@ -836,11 +1008,28 @@ 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.
  */
 declare type FieldSource = FieldSourceInternal;
 
@@ -885,8 +1074,13 @@ export declare function groq(
   ...values: unknown[]
 ): string;
 
-/** 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.
+ */
 declare type GroqRequirement = RequirementBase & {
   type: "groq";
   query: string;
@@ -954,15 +1148,13 @@ export declare const GUARD_PREDICATE_VARS: readonly {
 }[];
 
 /**
- * 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.
  */
 declare type GuardRead =
   | {
@@ -1090,8 +1282,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.
+ */
 declare type Op =
   | FieldOp
   | {
@@ -1124,8 +1323,38 @@ export declare const RESERVED_CONDITION_VARS: readonly string[];
  */
 declare type RoleAliases = Record<string, string[]>;
 
-/** Inclusive scalar bounds. String/text bounds measure character length;
- * number bounds measure the numeric value. */
+/**
+ * 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.
+ */
+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.
+ */
+declare type RuntimeKind = "function" | "durableFunction" | "selfHosted";
+
+/**
+ * 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.
+ */
 declare interface ScalarValidation {
   min?: number | undefined;
   max?: number | undefined;
@@ -1141,21 +1370,28 @@ declare const SIGNAL_SEMANTICS: readonly [
 
 declare type SignalSemantic = (typeof SIGNAL_SEMANTICS)[number];
 
+/**
+ * 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.
+ */
 declare type SingleSubjectRequirement = RequirementBase & {
   type: "singleSubject";
 };
 
 /**
- * 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
  */
@@ -1182,17 +1418,24 @@ declare type StageFields<TField, TActivity, TTransition, TGuard, TEditable> = {
 };
 
 /**
- * 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.
  */
 declare type StartBlock = StartFields & {
   kind: StartKind;
@@ -1242,17 +1485,27 @@ declare const StoredFieldRefSchema: v.StrictObjectSchema<
 >;
 
 /**
- * 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
  */
@@ -1353,14 +1606,14 @@ declare type TodoListField = FieldBase<AuthoringEditable, GroupMembership> & {
 };
 
 /**
- * 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.
  */
 declare type Transition = TransitionFields & {
   when: string;
@@ -1375,10 +1628,18 @@ declare type TransitionFields = {
 };
 
 /**
- * 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.
  */
 declare type ValueExpr = ValueExprInternal;
 
@@ -1691,44 +1952,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
           >,
@@ -1778,20 +2017,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"
@@ -1840,20 +2067,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<
@@ -1900,20 +2115,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
@@ -1962,20 +2165,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<
@@ -2022,20 +2213,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
@@ -2074,21 +2253,6 @@ declare type WorkflowDefinition = v.InferOutput<
   typeof WorkflowDefinitionSchema
 >;
 
-/**
- * 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>
 >;
@@ -2100,10 +2264,22 @@ declare const WorkflowDefinitionSchema: v.GenericSchema<
 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'`.
  */
 declare type WorkflowDeploymentInput = Omit<
   WorkflowDeployment,