@sanity/workflow-engine 0.29.0 → 0.31.0

package/dist/index.d.cts

@@ -57,6 +57,12 @@ export declare function acceptsDocumentType(
   documentType: string,
 ): boolean;
 
+/** A parsed deployment after its reader-model acknowledgement has been
+ *  validated against the definitions a command will submit. */
+export declare type AcknowledgedWorkflowDeployment = WorkflowDeployment & {
+  expectedMinReaderModel: number;
+};
+
 /**
  * The URL path a resource's ACL is served at — where the engine fetches an
  * actor's grants for that resource (and the canonical encoding of the shape
@@ -79,6 +85,21 @@ export declare function aclPathForResource(
   res: WorkflowResource,
 ): string | undefined;
 
+/**
+ * A stored action. `semantics` is engine-owned advisory meaning, independent
+ * of execution and presentation — an array so the vocabulary can grow without
+ * reshaping this field. `when`'s presence makes the action CASCADE-FIRED: the
+ * engine fires it the moment the condition turns true, at most once per stage
+ * visit, and it is never invocable via `fireAction`; absent, the action must
+ * be invoked via `fireAction` by any caller holding a token (fire-on-entry is
+ * `when: 'true'`). `filter` is existence with GROQ semantics — a non-matching
+ * action might as well not exist (invisible to UI and LLMs, never merely
+ * disabled); on a `when` action it composes: `filter` scopes whether the
+ * automation exists, `when` is its firing trigger. `roles` is kept VERBATIM
+ * only when cascade-fired (the pin on which identities may execute the
+ * trigger); a fireAction-fired action's `roles` folds into `filter` at
+ * desugar instead.
+ */
 export declare type Action = ActionFields<Op, string[]> & {
   roles?: string[] | undefined;
 };
@@ -184,14 +205,14 @@ declare type ActionFields<TOp, TGroup> = {
 
 export declare type ActionName = string;
 
-export declare type ActionParam = v.InferOutput<typeof ActionParamSchema>;
-
 /**
- * Caller-supplied params declared on an action. The engine validates
- * incoming `params` against this list before running ops or queuing
- * effects: missing required params → ActionParamsInvalidError, action
- * does not commit. Resolved values feed `ValueExpr.param` lookups.
+ * Caller-supplied params declared on an action, validated before running ops
+ * or queuing effects: a missing required param throws
+ * `ActionParamsInvalidError` and the action does not commit. Resolved values
+ * feed `ValueExpr.param` lookups.
  */
+export declare type ActionParam = v.InferOutput<typeof ActionParamSchema>;
+
 declare const ActionParamSchema: v.SchemaWithPipe<
   readonly [
     v.StrictObjectSchema<
@@ -363,17 +384,26 @@ export declare function actionRendering(action: {
 
 export declare type ActionSemantic = DecisionSemantic | Semantic;
 
-/** The fireable-action verdict for one action on an activity — its `allowed`
- *  state, structured `disabledReason`, and declared params, tagged with the
- *  owning activity. The per-action atom both projections share:
- *  {@link availableActions} flattens it across a stage's activities; a consumer
- *  that keeps per-activity nesting (e.g. the MCP) maps it over an activity's actions
- *  directly, so the verdict shape has a single source. */
+/** The per-action verdict shape shared by every projection: {@link availableActions} flattens it, a per-activity consumer (e.g. the MCP) maps it directly — both must stay on this one builder. */
 export declare function actionVerdict(
   activity: ActivityEvaluation,
   action: ActionEvaluation,
 ): AvailableAction;
 
+/**
+ * A unit of work carrying no payload of its own — every op, effect, and
+ * spawn lives on an action; an activity contributes scoped `fields`
+ * (resolved at stage entry), existence (`filter`), advisory readiness
+ * (`requirements`), and the off-system marker (`target`, a BPMN Manual Task
+ * deep-link, render-only and never gating). All in-scope activities are
+ * ACTIVE from stage entry until an action's terminal `status` resolves them —
+ * there is no activation moment. `filter` is existence with GROQ semantics,
+ * evaluated once against the stage's entry state: a definite `false`
+ * excludes the activity from UI, LLMs, and `$allActivitiesDone`.
+ * `requirements` are readiness gates orthogonal to `filter` — an unmet one
+ * keeps the activity visible but disables its actions with a
+ * `requirements-unmet` verdict; distinct from ACL and guards.
+ */
 export declare type Activity = ActivityFields<
   FieldEntry,
   Action,
@@ -410,6 +440,12 @@ export declare const ACTIVITY_KIND_DISPLAY: {
   };
 };
 
+/**
+ * BPMN-aligned classification of an activity by its EXECUTOR. Purely
+ * advisory and always DERIVED from the activity's shape (`target` marks
+ * off-system manual work, action shapes decide the rest) — it changes no
+ * gating or runtime.
+ */
 export declare const ACTIVITY_KINDS: readonly [
   "user",
   "service",
@@ -419,14 +455,10 @@ export declare const ACTIVITY_KINDS: readonly [
 ];
 
 /**
- * Leaf vocabularies that both the authoring schema and the engine address by
- * name. Some exported types also include grammar-validated open values that
- * cannot be enumerated by a const array.
- *
- * This module imports nothing. It is the schema-free foundation that
- * `../define/schema.ts` reads its value constants from, which is what keeps
- * the type model and the valibot schema free of an import cycle: the value edge
- * `schema.ts → enums.ts` terminates here.
+ * An activity is `active` from stage entry (or `skipped` when its `filter`
+ * excluded it) until a terminal status resolves it — there is no pre-active
+ * state. The authored action `status:` sugar (and the `status.set` op it
+ * desugars to) is constrained to {@link TerminalActivityStatus}.
  */
 declare const ACTIVITY_STATUSES: readonly [
   "active",
@@ -594,8 +626,24 @@ export declare interface Actor {
   onBehalfOf?: string;
 }
 
+/**
+ * WHO is acting: a human, an LLM, or automated machinery. The `system` kind
+ * covers both the engine's own housekeeping and external services;
+ * {@link DriverKind} splits that for the audit-trail glyph.
+ */
 export declare const ACTOR_KINDS: readonly ["person", "agent", "system"];
 
+/** Runtime counterpart of {@link expandRequiredRoles}; both expand only the required side. */
+export declare function actorFulfillsRole({
+  actorRoles,
+  required,
+  aliases,
+}: {
+  actorRoles: readonly string[] | undefined;
+  required: string;
+  aliases: RoleAliases | undefined;
+}): boolean;
+
 export declare type ActorKind = (typeof ACTOR_KINDS)[number];
 
 export declare type ActorResolution<User> =
@@ -653,16 +701,9 @@ export declare function applicableDefinitions<
 }): Promise<T[]>;
 
 /**
- * The data-model gate every engine read of an engine-owned document passes
- * through — point reads, list queries, projections, and snapshot hydration's
- * raw reads (the structural exceptions — existence-only probes and lake-side
- * GROQ filters — are declared in DATAMODEL.md). Throws
- * {@link ModelVersionAheadError} only when the document's
- * {@link minReaderModelOf reader floor} is ahead of
- * {@link DATA_MODEL_VERSION}; a doc stamped by a NEWER model whose changes
- * were additive keeps its old floor and reads fine — mixed-version fleets
- * interoperate across additive evolution. A missing stamp is model 0 and
- * always readable.
+ * Throws {@link ModelVersionAheadError} only when the document's reader floor exceeds
+ * {@link DATA_MODEL_VERSION}. A doc from a NEWER engine whose changes were purely additive
+ * keeps its old (lower) floor and still reads fine — only reader-floor-raising changes block a read.
  */
 export declare function assertReadableModel<
   T extends {
@@ -672,8 +713,11 @@ export declare function assertReadableModel<
 
 export declare function assertReaderModelAcknowledgement(
   expectedMinReaderModel: unknown,
-  context?: string,
-): asserts expectedMinReaderModel is typeof DATA_MODEL_MIN_READER;
+  options: {
+    requiredMinReaderModel: number;
+    context?: string;
+  },
+): asserts expectedMinReaderModel is number;
 
 /**
  * One member of an `assignees`-kind entry's value — and the value of the
@@ -721,6 +765,18 @@ export declare const AUTHORING_DISPLAY: {
   };
 };
 
+/**
+ * The stored action fields plus two authoring sugars, or the
+ * {@link ClaimAction} pair-half. `roles`: on a fireAction-fired action (no
+ * `when`) it desugars into a `count($actor.roles[@ in [...]]) > 0` condition
+ * ANDed with `filter`; on a CASCADE-FIRED action it stores VERBATIM instead —
+ * the pin on which identities may execute the trigger, since folding it into
+ * `filter` would make the action's existence depend on whose token cascades.
+ * `roleAliases` widens the membership either way. `status` compiles to a
+ * `status.set` op on the firing activity, appended AFTER the authored ops —
+ * deliberately never implied, so a forgotten `status` is a visible stall
+ * rather than a silently completed action.
+ */
 export declare type AuthoringAction = AuthoringRawAction | ClaimAction;
 
 export declare type AuthoringActivity = ActivityFields<
@@ -730,16 +786,16 @@ export declare type AuthoringActivity = ActivityFields<
   GroupMembership
 >;
 
-export declare type AuthoringEditable = v.InferOutput<
-  typeof AuthoringEditableSchema
->;
-
 /**
  * Authoring editability adds the `role[]` convenience: a non-empty role list
  * desugars to the same `count($actor.roles[@ in [...]]) > 0` membership
  * predicate `action.roles` produces. `true` opens the field to anyone in its
  * window; a bare string is a raw predicate.
  */
+export declare type AuthoringEditable = v.InferOutput<
+  typeof AuthoringEditableSchema
+>;
+
 declare const AuthoringEditableSchema: v.UnionSchema<
   [
     v.LiteralSchema<true, undefined>,
@@ -768,6 +824,8 @@ export declare type AuthoringFieldEntry =
   | TodoListField
   | NotesField;
 
+/** A field reference with `scope` optional; desugar resolves it lexically
+ *  (activity → stage → workflow) into {@link StoredFieldRef}. */
 declare type AuthoringFieldRef = v.InferOutput<typeof AuthoringFieldRefSchema>;
 
 declare const AuthoringFieldRefSchema: v.StrictObjectSchema<
@@ -786,15 +844,12 @@ declare const AuthoringFieldRefSchema: v.StrictObjectSchema<
   undefined
 >;
 
+/** {@link Guard}'s contract as authored: `match.idRefs` and `metadata` carry
+ *  typed {@link GuardRead} values that deploy resolves to bare ones. */
 export declare type AuthoringGuard = v.InferOutput<typeof AuthoringGuardSchema>;
 
 declare const AuthoringGuardSchema: v.StrictObjectSchema<
   {
-    /**
-     * Lake-id-segment grammar (`^[a-z0-9][a-z0-9-]*$`, deploy-enforced): the
-     * guard's lake `_id` derives from `(instanceId, name)` at stage entry.
-     * Unique per definition.
-     */
     name: v.SchemaWithPipe<
       readonly [
         v.StringSchema<undefined>,
@@ -805,7 +860,6 @@ declare const AuthoringGuardSchema: v.StrictObjectSchema<
     description: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
     match: v.StrictObjectSchema<
       {
-        /** Subject `_type`(s); empty matches any type. */
         types: v.OptionalSchema<
           v.ArraySchema<
             v.SchemaWithPipe<
@@ -818,7 +872,6 @@ declare const AuthoringGuardSchema: v.StrictObjectSchema<
           >,
           undefined
         >;
-        /** Target docs as field reads (or the instance itself), resolved at deploy to bare ids + the resource. */
         idRefs: v.OptionalSchema<
           v.ArraySchema<
             v.VariantSchema<
@@ -921,7 +974,6 @@ declare const AuthoringGuardSchema: v.StrictObjectSchema<
           >,
           undefined
         >;
-        /** Glob id patterns (bare, resource-local). */
         idPatterns: v.OptionalSchema<
           v.ArraySchema<
             v.SchemaWithPipe<
@@ -953,22 +1005,7 @@ declare const AuthoringGuardSchema: v.StrictObjectSchema<
       },
       undefined
     >;
-    /**
-     * Lake GROQ predicate — a distinct eval context: delta-mode GROQ
-     * reading the `before()`/`after()` natives, `mutation`, `guard`, and
-     * `identity()`. Bare ids/fields only. Polarity: a result of strictly
-     * `true` ALLOWS the matched mutation; anything else (false, null, an
-     * evaluation error) DENIES. Omitted or empty means UNCONDITIONAL DENY.
-     */
     predicate: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
-    /**
-     * Projected workflow fields the predicate reads as `guard.metadata.*` —
-     * the only bridge from the lake eval context (which cannot see `$fields`)
-     * to workflow fields. Each value is a deploy-time read — a typed
-     * {@link GuardRead} when authoring, the printed string spelling once
-     * stored — resolved into a bare value at deploy and re-synced by the
-     * post-field-op guard refresh.
-     */
     metadata: v.OptionalSchema<
       v.RecordSchema<
         v.SchemaWithPipe<
@@ -1078,6 +1115,8 @@ declare const AuthoringGuardSchema: v.StrictObjectSchema<
   undefined
 >;
 
+/** Like {@link ManualTarget}, but the `field` variant also accepts a bare
+ *  field name; desugar normalises it into {@link AuthoringFieldRef}. */
 export declare type AuthoringManualTarget = v.InferOutput<
   typeof AuthoringManualTargetSchema
 >;
@@ -1137,6 +1176,9 @@ declare const AuthoringManualTargetSchema: v.VariantSchema<
   undefined
 >;
 
+/** Like {@link Op}, plus: `status.set`'s `activity` is optional (desugar fills
+ *  the firing activity), and the `audit` sugar — a stamped append merging
+ *  `actor`/`at` {@link ValueExpr} fields into its own value. */
 export declare type AuthoringOp = v.InferOutput<typeof AuthoringOpSchema>;
 
 declare const AuthoringOpSchema: v.VariantSchema<
@@ -1432,27 +1474,6 @@ declare const AuthoringOpSchema: v.VariantSchema<
   undefined
 >;
 
-/**
- * Authoring action — the stored fields plus two field sugars with one
- * defined expansion each:
- *
- *   - `roles` — on a fireAction-fired action (no `when`) it desugars to a
- *     `count($actor.roles[@ in [...]]) > 0` membership condition ANDed with
- *     the authored `filter` (for a caller, "not yours to fire" and "doesn't
- *     exist for you" are the same advisory answer). On a CASCADE-FIRED
- *     action it stores VERBATIM — the pin on which identities may execute
- *     the trigger; folding it into `filter` would make the action's
- *     existence depend on whose token happens to cascade. The definition's
- *     `roleAliases` ({@link RoleAliasesSchema}) widen the membership either
- *     way.
- *   - `status` → a `status.set` op on the firing activity, appended **after**
- *     the authored ops (deliberately never implied: a forgotten explicit
- *     `status` is a visible stall, an implied default silently completes
- *     claim-like actions). Status is the health axis: a decision action
- *     (decline, send back) resolves `done` and writes the decision into a
- *     field the transition trigger reads — `failed` is for work that
- *     genuinely could not complete.
- */
 declare type AuthoringRawAction = ActionFields<AuthoringOp, GroupMembership> & {
   roles?: string[] | undefined;
   status?: TerminalActivityStatus | undefined;
@@ -1580,31 +1601,21 @@ export declare interface AvailableAction {
   params: ActionParam[];
 }
 
-/** Flatten an evaluation's current-stage activities into the actions the actor
- *  could fire, each carrying whether it's allowed (and why not). A
- *  filter-scoped-out activity does not exist for this visit, so its actions
- *  never list — the same {@link ActivityEvaluation.scopedOut} split every
- *  other surface applies. */
+/** Excludes a `scopedOut` activity's actions, matching the same split every other surface applies to filter-scoped-out activities. */
 export declare function availableActions(
   activities: ActivityEvaluation[],
 ): AvailableAction[];
 
-/** The `workflow.availableActions` result — the projected actions plus the
- *  evaluation they came from, so a consumer can read the instance/stage
- *  context without a second projection. */
+/** Pairs the projected actions with the evaluation they came from, so a consumer reads instance/stage context without a second call. */
 export declare interface AvailableActionsResult {
   evaluation: WorkflowEvaluation;
   actions: AvailableAction[];
 }
 
-/**
- * Type each caller-supplied name→value against the workflow's declared field
- * entries — the engine takes typed {@link InitialFieldValue}s, and a value's
- * type IS its declared entry's kind. Only `input`-sourced entries read caller
- * values, so anything else fails here, naming the fields that ARE settable.
- * The engine repeats this structural validation at its contract boundary;
- * value validation also stays there.
- */
+/** Builds the start payload's field rows from caller values: accepts only
+ *  declared `input`-sourced entries and throws on an unknown or non-input
+ *  name. Structural validation only — the engine repeats value-kind
+ *  validation at its own start boundary, not here. */
 export declare function buildInitialFields({
   declared,
   values,
@@ -1614,18 +1625,8 @@ export declare function buildInitialFields({
 }): InitialFieldValue[];
 
 /**
- * Build a snapshot from a set of loaded docs. Pure transform.
- *
- * For each `LoadedDoc { doc, resource }`:
- *   - The doc's `_id` is rewritten to `gdrFromResource(resource, _id)`.
- *   - Every nested `_ref` value (recursively, through objects and arrays)
- *     is rewritten the same way: bare ref → URI in the parent's resource.
- *     Already-qualified `_ref` URIs (containing `:`) are left alone.
- *
- * Plain string fields, numbers, booleans — anything that isn't an
- * object with a `_ref` field — pass through untouched. The rewriter is
- * structural, not schema-aware: only the `_ref` field on an object is
- * treated as a Sanity reference. Everything else is user data.
+ * Rewrites each doc's `_id` and every nested `_ref` field to GDR URI form,
+ * recursing through objects/arrays; already-URI `_ref`s pass through unchanged.
  */
 export declare function buildSnapshot(args: {
   docs: LoadedDoc[];
@@ -1678,14 +1679,8 @@ export declare interface ChoiceOptions {
 
 export declare type ChoiceValue = string | number;
 
-/**
- * The action half of the mirrored claim pair. `field` references an
- * author-declared actor-valued entry (the pair's other half), resolved
- * lexically. Expansion, strictly within this action: a no-steal
- * `!defined($fields.<field>)` filter ANDed with `roles`/`filter`, plus a
- * `field.set` ← actor op. `ops` and `status` are reserved (the expansion
- * owns them) — strictObject rejects them as unknown keys.
- */
+/** The action half of the mirrored claim pair: `field` names the actor-valued entry this action claims, resolved lexically, and the expansion
+ *  adds a no-steal `!defined($fields.<field>)` filter ANDed with `roles`/`filter` plus a `field.set` ← actor op. `ops`/`status` are reserved (strictObject rejects them). */
 declare type ClaimAction = {
   type: "claim";
   name: string;
@@ -1699,12 +1694,8 @@ declare type ClaimAction = {
   effects?: Effect[] | undefined;
 };
 
-/**
- * Authoring fields accept the raw entries plus the `claim` sugar type — the
- * field half of the mirrored claim pair. Expansion: an `actor` working-
- * memory field (no `initialValue`; the claim action's op fills it), strictly
- * within this entry.
- */
+/** The field half of the mirrored claim pair, expanding strictly within this entry: an `actor`
+ *  working-memory field with no `initialValue` — the paired {@link ClaimAction}'s op fills it. */
 declare type ClaimField = {
   type: "claim";
   name: string;
@@ -1771,14 +1762,9 @@ export declare interface ClientProjectUser {
   readonly email?: string;
   readonly imageUrl?: string | null;
   /**
-   * Which identity provider the person signs in with (`google`, `github`, or a
-   * `saml-<name>` deployment) — display only.
-   *
-   * Both spellings are declared because the two project-user endpoints
-   * disagree: the project-hosted `/users/<id>` the adapters read answers
-   * `provider`, while the management `/projects/<id>/users/<id>` answers
-   * `loginProvider`. Read them through {@link userLoginProvider} rather than
-   * picking one.
+   * Display only. Both spellings exist because the two project-user
+   * endpoints disagree on which they answer — read through
+   * {@link userLoginProvider} rather than picking one.
    */
   readonly provider?: string;
   readonly loginProvider?: string;
@@ -1876,10 +1862,7 @@ export declare interface CompiledQuery {
   params: Record<string, string | string[]>;
 }
 
-/** Assemble a persisted guard doc from resolved pieces. Deliberately carries
- *  NO engine data-model stamp: the guard doc format is the lake's forthcoming
- *  contract, not ours to grow fields on — its versioning event is the
- *  {@link GUARD_DOC_TYPE} cutover itself (see DATAMODEL.md). */
+/** Deliberately carries NO engine data-model stamp: the guard doc format is the lake's forthcoming contract, not ours to grow fields on (see DATAMODEL.md). */
 export declare function compileGuard(args: CompileGuardArgs): MutationGuardDoc;
 
 declare interface CompileGuardArgs extends MutationGuardBody {
@@ -2033,10 +2016,23 @@ export declare class ConcurrentFireActionError extends WorkflowError<"concurrent
 export declare type Condition = string;
 
 /**
- * Every variable the engine binds for conditions, in one place. The
- * deploy-time shadow check ({@link RESERVED_CONDITION_VARS}) and the docs on
- * {@link Condition} derive from this list — extend it here when the engine
- * grows a binding, never in a comment elsewhere.
+ * Every variable the engine binds for the RENDERED condition scope (every
+ * condition site: transition `when`s, activity filters, action
+ * `when`s/filters, effect bindings, `spawn` reads, where-op `where`s,
+ * editability predicates, author predicates) — the deploy-time shadow check
+ * ({@link RESERVED_CONDITION_VARS}) and the docs on {@link Condition} derive
+ * from this list; extend it here when the engine grows a binding, never in
+ * a comment elsewhere.
+ *
+ * Three other GROQ contexts read a definition and do NOT share this
+ * inventory: cascade gates (transition/activity/cascade-action gates, which
+ * must resolve identically regardless of caller — only the `'always'`-bound
+ * subset carries values, {@link FILTER_SCOPE_VARS}); the start contexts
+ * (`start.filter` is browse-time-pure over a candidate document,
+ * {@link START_FILTER_VARS}; a start `groq` requirement binds `$fields`
+ * instead, {@link START_REQUIREMENT_VARS}); and lake guard predicates, which
+ * are not conditions at all — delta-mode GROQ over a mutation, binding
+ * {@link GUARD_PREDICATE_VARS} instead.
  */
 export declare const CONDITION_VARS: readonly ConditionVar[];
 
@@ -2048,13 +2044,10 @@ export { ConditionClause };
 
 export { ConditionDescription };
 
-/**
- * Every STATIC `$fields.<name>` (or `$fields['<name>']` — groq-js normalises
- * both to `AccessAttribute`) read in a condition, from the AST. Dynamic access
- * (`$fields[$var]`) carries no static name and is not collected. A malformed
- * condition reads nothing here ({@link conditionSyntaxIssues} owns the parse
- * error).
- */
+/** Static `$fields.<name>` / `$fields['<name>']` reads (both normalise to the
+ *  same AST node); `$fields[$var]` dynamic access has no static name and is skipped.
+ *  A malformed condition reads nothing here rather than throwing — the deploy-time
+ *  syntax check owns the parse error. */
 export declare function conditionFieldReadNames(
   groq: string,
 ): ReadonlySet<string>;
@@ -2090,43 +2083,6 @@ export declare interface ConditionVar {
   label: string;
 }
 
-/**
- * The condition-variable inventory — the single source of truth for every
- * `$var` the engine binds when it evaluates a {@link Condition}.
- *
- * Four evaluation contexts read a definition's GROQ:
- *
- * 1. **Rendered condition scope** — every condition site in a definition
- *    (transition `when`s, activity filters, action `when`s/filters, effect
- *    bindings, `spawn` reads, where-op `where`s, editability predicates,
- *    author predicates). {@link CONDITION_VARS} is its inventory; each
- *    entry's `binding` says when the var actually holds a value. The
- *    where-op context is the one closed subset — its bound set is statically
- *    fixed and deploy-enforced (see the op-where scope's param-name list in
- *    the op applier).
- * 2. **Cascade gates** — transition `when`s, activity filters, and a
- *    cascade-fired action's `when`/`filter` must resolve identically no
- *    matter whose token drives the cascade, so only the `'always'`-bound
- *    subset carries values there ({@link FILTER_SCOPE_VARS}). Caller-bound
- *    vars fail closed — `$assigned` binds its caller-free constant `false`,
- *    the rest evaluate to `undefined` — and deploy rejects them at these
- *    sites; a cascade-fired action's per-token gate is `roles`, never its
- *    conditions.
- * 3. **The start contexts** — a definition's `start.filter` and start GROQ
- *    requirements evaluate against a CANDIDATE (no instance exists yet):
- *    `*[...]` reads the engine-owned `{definition, subject, completedAt}`
- *    projection of the tag's instances and none of the rendered
- *    condition vars exist. The two split on what a surface can know:
- *    `filter` is browse-time-pure (candidate document as root,
- *    {@link START_FILTER_VARS} — no `$fields`, which cannot exist before
- *    inputs do), a `groq` requirement is the start-time readiness predicate
- *    ({@link START_REQUIREMENT_VARS} — `$fields` bound, never a root).
- * 4. **Guard predicates** — NOT conditions. A lake mutation guard's
- *    `predicate` is groq-js **delta-mode** GROQ over a document mutation:
- *    `before()`/`after()`/`identity()` are dialect natives, and the wire
- *    format binds the identifiers in {@link GUARD_PREDICATE_VARS}. None of
- *    the condition vars exist there.
- */
 /**
  * When a condition var holds a value:
  *
@@ -2264,11 +2220,7 @@ export declare type ContextEntry =
       value: string;
     };
 
-/**
- * Render the instance's `context` bag as the `$context` map — the
- * start-time seed plus a parent's spawn handoff. `json` entries decode to
- * their object form.
- */
+/** `$context`: the context bag as a map by name; `json` entries decode to their object form. */
 export declare function contextMap(
   instance: Pick<WorkflowInstance, "context">,
 ): Record<string, unknown>;
@@ -2379,11 +2331,7 @@ export declare function createTelemetryIntake(args: {
 /** A define-time validated `custom.<camelCaseMeaning>` value. */
 export declare type CustomSemantic = `custom.${string}`;
 
-/**
- * The append-only, machine-readable counterpart of the model log in
- * `DATAMODEL.md`. It records compatibility decisions; the prose log retains
- * the reasoning, absent-value semantics, and old-writer round-trip proof.
- */
+/** Append-only, machine-readable counterpart of the model log in DATAMODEL.md, which keeps the full reasoning. */
 export declare const DATA_MODEL_CHANGES: readonly [
   Readonly<{
     id: "governed-model-stamps";
@@ -2502,14 +2450,24 @@ export declare const DATA_MODEL_CHANGES: readonly [
     applicability: "unconditional";
     summary: string;
   }>,
+  Readonly<{
+    id: "role-constrained-assignment-fields";
+    introducedInModel: 8;
+    minReaderModel: 8;
+    documentTypes: readonly ["definition", "instance"];
+    compatibility: "reader-floor";
+    applicability: "detectable";
+    summary: "Assignee fields may restrict newly assigned users and collective roles by role.";
+  }>,
 ];
 
+/** The maximum reader floor this writer can emit for a detectable feature. */
+export declare const DATA_MODEL_MAX_READER = 8;
+
 /**
- * The maximum reader floor this writer can emit. Individual documents derive
- * their `minReaderModel` from the compatibility-bearing features actually
- * present; a document written at {@link DATA_MODEL_VERSION} may therefore
- * carry a lower floor. Raising this maximum is a declared, DATAMODEL.md-logged
- * decision that requires readers-first fleet sequencing.
+ * The unconditional model-4 reader floor for every engine-owned document.
+ * Detectable features may raise an individual document through
+ * {@link DATA_MODEL_MAX_READER}.
  */
 export declare const DATA_MODEL_MIN_READER = 4;
 
@@ -2522,11 +2480,11 @@ export declare const DATA_MODEL_MIN_READER = 4;
  * 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 {@link DATA_MODEL_MIN_READER}'s
- * job. Declare every bump in `DATAMODEL.md`; the model-surface snapshot test
- * keeps undeclared drift red.
+ * 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.
  */
-export declare const DATA_MODEL_VERSION = 7;
+export declare const DATA_MODEL_VERSION = 8;
 
 export declare interface DataModelChange {
   readonly id: string;
@@ -2689,23 +2647,9 @@ export declare class DefinitionInUseError extends WorkflowError<"definition-in-u
 }
 
 /**
- * Pure GROQ builders for deployed workflow definitions. Composes the doc-type
- * constant and the tag-scope predicate so the engine's internal lookups and the
- * CLI share one definition of "tag-scoped, latest-or-pinned
- * `workflow.definition`" instead of hand-writing the query at each call site.
- *
- * The tag enumerations are the deliberate exception: they span partitions, for a
- * caller holding a resource but no tag yet.
- */
-/**
- * GROQ resolving a single deployed {@link WORKFLOW_DEFINITION_TYPE} visible to
- * the caller's tag. With {@link explicit} the query pins `$version`; otherwise
- * it returns the highest deployed version.
- *
- * Params: `$definition`, `$tag`, plus `$version` when {@link explicit}.
- *
- * @param explicit - whether the caller wants a specific version (`$version`)
- *   rather than the latest.
+ * GROQ resolving a single deployed {@link WORKFLOW_DEFINITION_TYPE} for the
+ * caller's tag — pinned to `$version` when {@link explicit}, else the highest
+ * deployed version. Params: `$definition`, `$tag`, plus `$version` when explicit.
  */
 export declare function definitionLookupGroq(explicit: boolean): string;
 
@@ -2862,10 +2806,9 @@ export declare interface DeployDefinitionsArgs<
   T extends WorkflowDefinitionInput<T> = WorkflowDefinition,
 > {
   /**
-   * Reviewed numeric literal acknowledging the installed writer's maximum reader-floor capability.
-   * The deploy gate checks the exact installed value and links the readers-first rollout; do not
-   * import {@link DATA_MODEL_MIN_READER}, because that would auto-advance this acknowledgement on
-   * upgrade.
+   * Highest reader model verified across runtimes sharing the workflow resource. The deploy gate
+   * compares this reviewed numeric literal with the submitted definitions; do not import
+   * either exported reader constant, because a dependency upgrade must not change it automatically.
    */
   expectedMinReaderModel: number;
   /**
@@ -2911,8 +2854,8 @@ export declare type DeployedDefinition = WorkflowDefinition & {
   /** Engine data-model stamp (see {@link DATA_MODEL_VERSION}) — absent on
    *  documents deployed before the stamp existed (model 0). */
   modelVersion?: number;
-  /** Reader floor (see {@link DATA_MODEL_MIN_READER}) — the oldest engine
-   *  data model that can safely interpret this document. */
+  /** The oldest engine data model that can safely interpret this document,
+   *  derived from its persisted features and the retained model-4 baseline. */
   minReaderModel?: number;
 };
 
@@ -2938,45 +2881,32 @@ export declare function deployedTagsGroq(): string;
  */
 export declare function deployStageGuards(args: StageGuardArgs): Promise<void>;
 
-/** Where a definition deploys: the engine tag it partitions under, the
- *  workflow resource it belongs to, and the resource-alias bindings to expand
- *  references against. Structurally what `deployDefinitions` receives, minus the
- *  definitions themselves — carrying `resourceAliases` here is what keeps a diff
- *  fingerprinting the same physical content `deployDefinitions` would. */
+/** Structurally what `deployDefinitions` receives, minus the definitions; carrying `resourceAliases` here keeps a diff's fingerprint matching what deploy would produce. */
 export declare interface DeployTarget {
-  /** Reviewed numeric literal, checked against the exact installed floor before client access. */
+  /** Highest reader model verified across runtimes sharing this workflow resource. */
   expectedMinReaderModel: number;
   tag: string;
   workflowResource: WorkflowResource;
   resourceAliases?: ResourceAliases;
 }
 
-/**
- * Classify an activity from its shape, BPMN-aligned: `target` marks off-system
- * work (`manual`); otherwise any fireAction-fired action means a person (or
- * robot caller) acts on it (`user`); otherwise cascade-fired effects make it a
- * `service` step; otherwise cascade-fired status flips make it a `receive`
- * wait; anything left is an inline `script` step.
- */
+/** Classifies an activity from its shape: `target` marks off-system work
+ *  (`manual`), the one bit action shapes alone can't otherwise show. Then:
+ *  any caller-fireable action → `user`; effects or spawns → `service`;
+ *  cascade-only actions → `receive`; no actions at all → `script`. */
 export declare function deriveActivityKind(activity: Activity): ActivityKind;
 
 export declare interface DeriveAutonomyOptions {
   /** Child definitions for `spawn` recursion, by definition `name` — the
-   *  deploy batch or previously deployed set. An unresolvable child reports
+   *  deploy batch or the already-deployed set. An unresolvable child reports
    *  `conditional` with an unresolved wait. */
   children?: ReadonlyMap<string, WorkflowDefinition>;
 }
 
-/**
- * Who, if anyone, fires the activity's actions — derived ahead-of-time from
- * the activity's shape alone: `off-system` when `target` is present; else
- * `autonomous` (every action cascade-fired — no caller fires anything),
- * `interactive` (only fireAction-fired actions), or `hybrid` (mixed). An
- * actionless activity classifies `autonomous` vacuously (deploy's
- * terminal-reachability invariant rejects it anyway). Shape-only: whether
- * the activity actually RESOLVES without a caller is the causal question
- * `deriveWorkflowAutonomy` answers.
- */
+/** Who fires the activity's actions, from shape alone — a separate causal
+ *  check decides whether it actually resolves without a caller. A `target`
+ *  is `off-system`; all-cascade actions are `autonomous`, none are
+ *  `interactive`, a mix is `hybrid`. */
 export declare function deriveExecutorClassification(
   activity: Activity,
 ): ExecutorClassification;
@@ -3158,6 +3088,18 @@ export declare interface DiagnoseResult {
   remediations: SuggestedRemediation[];
 }
 
+/**
+ * How an in-flight instance reads right now. `waiting` and `blocked` are both
+ * HEALTHY, not stuck: `waiting` means an active activity has an available
+ * action and advances when someone acts — how long a workflow is "allowed" to
+ * wait is workflow- and team-specific, not this classifier's call — while
+ * `blocked` means an active activity's declared requirements aren't all met
+ * yet, and flips to `waiting` once they hold (typically a sibling activity
+ * completing, or content landing). `completed` and `aborted` carry
+ * `liveChildren` when spawned work is still running: a parent finishing while
+ * detached children run is legal — detach means detach — but a consumer
+ * should surface it loudly.
+ */
 export declare type Diagnosis =
   | {
       state: "progressing";
@@ -3205,16 +3147,11 @@ export declare interface DiffEntry {
 }
 
 /**
- * Compare one local definition against the latest deployed version of its
- * name (or its absence), classifying it via the engine's own content-addressed
- * planner ({@link planDefinitionDeploy}). Create-only: a content change is a
- * NEW version, never an in-place update — so there is no `update` verdict.
- * Pure — the caller owns the fetch. `def` passes the same boundary parse as
- * deploy ({@link parseDefinitionInput}): a fetched document's envelope is
- * stripped and unknown keys fail loud, so diff and deploy accept and reject
- * the same input shape. Deploy's further checks (GROQ + invariants via
- * `validateDefinition`, batch ordering) stay the caller's job, as they always
- * were.
+ * Classifies `def` against the latest deployed version of its name via
+ * {@link planDefinitionDeploy} — a content change is always a new version,
+ * never an in-place update. `def` passes the same boundary parse deploy uses
+ * ({@link parseDefinitionInput}), so diff and deploy accept and reject the
+ * same input shape.
  */
 export declare function diffEntry<T extends WorkflowDefinitionInput<T>>({
   def: rawDef,
@@ -3324,20 +3261,11 @@ export declare function displayDescription(
 ): string | undefined;
 
 /**
- * Display metadata for the discriminator literals the engine persists
- * (history entries, field-entry kinds, ops, effects-context entry
- * kinds, document and effect-queue types). Each entry exposes
- *
- *   - `title` — short label for chips, badges, headings
- *   - `description` — longer prose for tooltips / inspector panes
- *
- * UIs that render an instance audit log should NEVER show
- * `transitionFired` raw — they look it up here and
- * render `"Transition fired"` instead.
- *
- * Each family map is checked (`satisfies`) against the canonical union
- * for that family, so adding or removing a discriminator in the engine
- * fails tsc here until the display entry follows.
+ * Display strings for one persisted discriminator: `title` is a short label
+ * for chips, badges, and headings, `description` longer prose for tooltips and
+ * inspector panes. A UI rendering an instance audit log looks the raw
+ * discriminator up here instead of showing it — `transitionFired` reads as
+ * "Transition fired".
  */
 export declare interface DisplayMetadata {
   readonly title: string;
@@ -3350,6 +3278,7 @@ export declare interface DisplayMetadata {
  */
 export declare function displayTitle(typeKey: string | undefined): string;
 
+/** Document-value permissions. Grants ({@link Grant} in ./authorization.ts) compose most-permissive-wins. */
 declare const DOCUMENT_VALUE_PERMISSIONS: readonly ["create", "read", "update"];
 
 /**
@@ -3484,6 +3413,13 @@ export declare const DRIVER_KIND_DISPLAY: {
   };
 };
 
+/**
+ * What KIND of actor drove an action, recorded on the `actionFired` history
+ * entry for the audit-trail "who did this?" glyph. Distinct from
+ * {@link ActivityKind} (the intended execution lane) — any driver can fire
+ * any kind. New entries stamp `'person'`; `'agent'`/`'service'`/`'engine'`
+ * remain as read vocabulary for stored entries.
+ */
 export declare const DRIVER_KINDS: readonly [
   "person",
   "agent",
@@ -3493,21 +3429,19 @@ export declare const DRIVER_KINDS: readonly [
 
 export declare type DriverKind = (typeof DRIVER_KINDS)[number];
 
-/**
- * Classify the actor that drove an action for the audit-trail glyph. `person`
- * and `agent` pass through from {@link Actor.kind}; `system` maps to
- * `service`. Today every token identity resolves as a person (`/users/me`
- * carries no kind), so new entries stamp `person` and the `agent`/`service`/
- * `engine` values are read vocabulary for stored entries — a service's
- * environment lives on the entry's `executionContext`, and agent delegation
- * is a future designed feature, not an actor kind the engine can mint.
- *
- * Advisory and only as trustworthy as the {@link Actor} it reads — actor
- * identity is itself advisory in this engine (the lake/token is authoritative),
- * so this is a best-effort glyph, never an authorization signal.
- */
+/** Actor-kind glyph for the audit trail — advisory only, never an
+ *  authorization signal. */
 export declare function driverKind(actor: Actor): DriverKind;
 
+/**
+ * Declared editability of a field — the generic edit seam's gate. Default
+ * (absent) is NOT editable: a field is op-only engine working memory unless the
+ * modeler opens it. The stored form is `true` (editable by anyone within the
+ * field's scope window) or an EDIT CONDITION — rendered-scope GROQ (`$actor`,
+ * `$can`, `$attributes`, `$fields`, `$assigned`), checked like an action filter
+ * to decide who-may-edit. ADVISORY like every engine gate — it disables the
+ * inline field and explains; a {@link Guard} declares the intended write-lock.
+ */
 export declare type Editable = v.InferOutput<typeof StoredEditableSchema>;
 
 /**
@@ -3525,6 +3459,10 @@ export declare interface EditableFieldEvaluation {
   type: FieldKind;
   title?: string;
   validation?: ScalarValidation;
+  /** Eligible assignment roles for `assignee` / `assignees`; absent means unconstrained. */
+  roles?: string[];
+  /** The definition aliases used to interpret {@link EditableFieldEvaluation.roles}. */
+  roleAliases?: RoleAliases;
   /** Current resolved value; `undefined` until the field is first resolved. */
   value: unknown;
   /** Whether THIS actor may edit the field right now (window + predicate + guard). */
@@ -3637,6 +3575,18 @@ 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.
+ */
 export declare type Effect = v.InferOutput<typeof EffectSchema>;
 
 /** Total commits one dispatch may make — the runaway-handler bound: without
@@ -3660,8 +3610,10 @@ declare const EFFECT_RUN_STATUSES: readonly ["done", "failed", "cancelled"];
 
 /**
  * A `ctx.commitOps` / `ctx.setProgress` call hit one of the dispatch's
- * bounds. Thrown synchronously at the call site — see the module doc for why
- * a rejection would be invisible to exactly the caller the bound exists for.
+ * bounds. Thrown synchronously at the call site, not as a promise rejection:
+ * a tight loop that forgot to `await` dies on its own stack at the bound
+ * instead of spraying unhandled rejections invisible to the caller the bound
+ * exists for.
  */
 export declare class EffectCommitQueueOverflowError extends WorkflowError<"effect-commit-queue-overflow"> {
   readonly effectKey: string;
@@ -3682,11 +3634,29 @@ export declare type EffectCompletionStatus = Exclude<
   "cancelled"
 >;
 
+/**
+ * External effect handler — invoked at drain time with resolved `params` and
+ * a context. Returning `outputs` records them on the run's `effectHistory`
+ * row, read downstream as `$effects['<name>'].<output>`. Returning `ops`
+ * 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`.
+ *
+ * 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.
+ *
+ * The `bivarianceHack` indirection keeps this readable from the non-generic
+ * `Engine` surface; only the typed drain invokes handlers.
+ */
 export declare type EffectHandler<
   Client extends WorkflowClient = WorkflowClient,
 > = {
-  /** Bivariant so a concretely typed handler registry remains readable from
-   * the non-generic Engine surface; only the typed drain invokes handlers. */
   bivarianceHack(
     params: Record<string, unknown>,
     ctx: EffectHandlerContext<Client>,
@@ -3696,97 +3666,21 @@ export declare type EffectHandler<
   } | void>;
 }["bivarianceHack"];
 
-/**
- * External effect handler — invoked at drain time with the resolved
- * `params` and a context. Returning `outputs` records them on the run's
- * `effectHistory` row, where downstream bindings and conditions read them
- * as `$effects['<effect name>'].<output>`.
- * Returning `ops` applies the state half of the effect in the completion
- * commit — `field.*` computed from the real result, run through the same op
- * applier as an action's field ops (so a created doc's ref enters `$fields`, or
- * a screened outcome lands in a field the activity/stage gate reads). Effects
- * report results as field state, never by flipping an activity status, so `ops`
- * excludes `status.set`. Unlike definition-authored field ops, completion ops
- * have no authoring location from which to infer a target scope: every returned
- * op must explicitly set `target.scope` to `'workflow'` or `'stage'`. Throwing
- * marks the effect as failed (and returns no `ops`).
- *
- * **Delivery is at-least-once — a handler MAY run more than once for the
- * same effect.** Two overlaps produce a double-run: the dispatching process
- * dies after the handler's side effect but before `completeEffect` commits,
- * and a slow dispatch outliving its claim's lease (the engine's
- * `effectLeaseMs`, default 5 minutes) — an expired claim is taken over by
- * the next drain, or force-released by `sweepStaleClaims`, and redispatched
- * while the original handler may still be running. Completion is
- * first-writer-wins: the losing drainer's dispatch already ran, its
- * completion is reported as `lost`.
- *
- * Write handlers to tolerate that: before irreversible work, check
- * `effectHistory[]` for a row with this run's `ctx.effectKey` (the stable
- * `_key` an entry keeps from queue to history) and skip work a prior run
- * already completed; derive external-system identifiers from `ctx.effectKey`
- * so the receiving system can dedupe the overlap the ledger can't see.
- */
 declare type EffectHandlerContext<Client extends WorkflowClient> = {
-  /**
-   * A concrete sibling of the client supplied to `createEngine`, bound to the
-   * workflow resource with the same namespaces and credentials. Untagged
-   * handler requests on its workflow-client surface carry the `workflow.effect`
-   * request tag by default. A concrete client's explicit tags compose beneath
-   * that prefix. On the structural fallback for minimal clients, pass-through
-   * namespaces are not stamped and core builders expose the engine's minimal
-   * workflow-client surface.
-   */
+  /** A concrete sibling of the `createEngine` client, bound to the workflow resource with the
+   *  same credentials; untagged handler requests carry the `workflow.effect` tag by default. */
   client: Client;
-  /**
-   * Resolve the client bound to a subject doc's own resource. A handler
-   * patches the SUBJECT (which may live in a different Sanity resource
-   * than the instance — split-dataset GDR deploys); the drainer's
-   * `completeEffect` writes the INSTANCE through {@link client}. One
-   * client can't address both, so a handler that patches a foreign
-   * subject must route its write here.
-   *
-   * Pass the subject's GDR — the URI a binding like `$fields.subject._id`
-   * resolves to (the hydrated doc's `_id`), or a full
-   * {@link GlobalDocumentReference}. Returns the `resourceClients` client
-   * for that resource when one is mapped, {@link client} for the workflow
-   * resource itself, and a sibling derived from {@link client}'s
-   * credentials otherwise. Returned clients preserve their concrete APIs and
-   * apply the same default effect request tag.
-   * Throws if `ref` isn't a GDR — a bare id can't
-   * be routed, so failing loud beats silently patching the wrong dataset.
-   */
+  /** Resolve the client for a subject doc's own resource: a handler patching a foreign subject
+   *  routes its write here — {@link client} addresses the instance's. Throws on a bare id. */
   clientFor: (ref: GdrUri | GlobalDocumentReference) => WorkflowClient;
   instanceId: string;
   effectKey: string;
   log: (message: string, extra?: Record<string, unknown>) => void;
-  /**
-   * Commit mid-dispatch field state as a real engine transaction —
-   * validated like completion ops (`field.*` only, never `status.set`),
-   * gated on THIS dispatch's exact claim (a stale/superseded claim
-   * rejects before writing), history + idempotency recorded, guards
-   * refreshed, cascade run, and the claim's lease renewed in the same
-   * commit. Calls enqueue synchronously into a bounded per-dispatch FIFO
-   * and execute strictly in call order, one at a time — forgetting to
-   * `await` cannot create same-handler write races, and overflow (or the
-   * per-dispatch commit cap) throws synchronously at the call site.
-   * Await each call anyway: that is where errors surface promptly and
-   * engine commit latency paces the reporter. `idempotencyKey` is
-   * required — the engine does not assume a supplied op is idempotent.
-   * An accepted-but-unawaited commit that fails still fails the effect
-   * at settlement; the final completion always waits for this queue to
-   * drain. Never coalesced.
-   */
+  /** Mid-dispatch `field.*` commit gated on THIS dispatch's exact claim — a superseded claim
+   *  writes nothing. Runs in call order, never coalesced; `idempotencyKey` is required. */
   commitOps: (req: CommitOpsRequest) => Promise<void>;
-  /**
-   * Report absolute progress — sugar over {@link commitOps} that
-   * `field.set`s a number (a `progress` field's 0–100 contract is
-   * enforced by the engine at commit). A bare string targets a
-   * workflow-scope field; pass `{scope: 'stage', field}` for stage
-   * scope. Unlike `commitOps`, PENDING sets to the same field coalesce
-   * (latest value wins, one commit), so a tight reporting loop is safe
-   * by construction; idempotency keys are engine-derived.
-   */
+  /** Absolute progress, sugar over {@link commitOps}: `field.set`s a number (0–100, enforced at
+   *  commit). Unlike `commitOps`, pending sets to one field coalesce — latest value wins. */
   setProgress: (target: ProgressTarget, value: number) => Promise<void>;
 };
 
@@ -3885,12 +3779,7 @@ export declare class EffectOutputsInvalidError extends WorkflowError<"effect-out
   constructor(args: { effect: string; issues: string[] });
 }
 
-/**
- * Render completed effects' outputs as the `$effects` map — each effect's
- * LATEST completed run with outputs wins, by name, across the whole
- * history (outputs are workflow-scope handler results; the per-visit
- * signal is `$effectStatus`).
- */
+/** `$effects`: each effect name → its LATEST completed run's outputs across the whole history. */
 export declare function effectOutputsMap(
   instance: Pick<WorkflowInstance, "effectHistory">,
 ): Record<string, unknown>;
@@ -3910,7 +3799,6 @@ declare const EffectSchema: v.StrictObjectSchema<
       v.StringSchema<undefined>,
       undefined
     >;
-    /** GROQ reads over the rendered scope, resolved to concrete JSON at queue time. */
     readonly bindings: v.OptionalSchema<
       v.RecordSchema<
         v.StringSchema<undefined>,
@@ -3924,28 +3812,10 @@ declare const EffectSchema: v.StrictObjectSchema<
       >,
       undefined
     >;
-    /** Static config, passed through to the handler verbatim. */
     readonly input: v.OptionalSchema<
       v.RecordSchema<v.StringSchema<undefined>, v.UnknownSchema, undefined>,
       undefined
     >;
-    /**
-     * The outputs this effect is allowed to produce, as typed {@link FieldShape}s
-     * (each `name` is an output key, read downstream as `$effects['<name>'].<key>`;
-     * an `array` output is an array of objects shaped by `of`).
-     *
-     * A STRICT allowlist: at completion the handler's returned `outputs` are
-     * validated against these shapes and an undeclared key — or a value that
-     * doesn't fit its shape — fails the completion (nothing is stored). Omitting
-     * `outputs` is an EMPTY allowlist: the effect produces nothing, so any returned
-     * output is rejected — the bound is universal, not opt-in.
-     * Why strict: outputs land on the instance document's `effectHistory`, so
-     * the allowlist keeps it bounded — a handler can't accidentally spread a
-     * whole API response
-     * into the instance — and the declared shapes let tooling (e.g. the simulator's
-     * drain UI) suggest an effect's exact output keys. Declaring outputs also
-     * powers the advisory deploy-time producer/consumer lint.
-     */
     readonly outputs: v.OptionalSchema<
       v.ArraySchema<v.GenericSchema<FieldShape>, undefined>,
       undefined
@@ -3983,6 +3853,10 @@ export declare interface Engine {
   deployDefinitions: <T extends WorkflowDefinitionInput<T>>(
     args: DeployDefinitionsArgs<T>,
   ) => Promise<DeployDefinitionsResult>;
+  /** Starts an instance. `start.filter` is never a gate here — applicability
+   *  belongs to `definitionsForDocument`, and an inapplicable definition
+   *  starts without complaint. `instanceId` is the idempotency key: reusing
+   *  it for the same start resumes; a different start throws. */
   startInstance: (args: StartInstanceArgs) => Promise<OperationResult>;
   fireAction: (args: FireActionArgs) => Promise<OperationResult>;
   /** Edit a declared-editable field directly (the generic edit seam):
@@ -4199,17 +4073,9 @@ export declare function entryDocRefs(
   entries: unknown,
 ): GlobalDocumentReference[];
 
-/**
- * Pure error helpers — no client, no I/O. The one home for the engine's
- * "coerce an unknown caught value" + "rethrow with context" idioms, so the
- * message shape and cause-chaining can't drift across call sites.
- */
-/**
- * A human-readable message for an unknown caught value: `.message` for an
- * {@link Error}, otherwise `String(value)`. Strips control characters
- * (keeping newlines and tabs) so server-derived error text can't smuggle
- * terminal escape sequences into consumer output.
- */
+/** The value's message — `Error.message`, else `String(value)` — with
+ *  control characters stripped so server-derived error text can't smuggle
+ *  terminal escape sequences into consumer output. */
 export declare function errorMessage(err: unknown): string;
 
 export declare interface EvaluateArgs {
@@ -4352,16 +4218,16 @@ export declare function evaluateStartFilter(args: {
 
 /**
  * Well-known {@link ExecutionContext.kind} values. The field is a free
- * string — these are the shipped vocabulary, not a closed set.
+ * string — these are the shipped vocabulary, not a closed set. `interactive`
+ * is the generic human-session fallback when `studio`/`sdkApp` don't apply;
+ * `server` is a proxy acting with a user's token; `drainer` is an
+ * effect-drain runtime.
  */
 export declare const EXECUTION_KINDS: {
-  /** A human-facing session (generic — prefer `studio`/`sdkApp` when known). */
   readonly interactive: "interactive";
-  /** A server process acting with a user's token (e.g. a publish proxy). */
   readonly server: "server";
   readonly cli: "cli";
   readonly mcp: "mcp";
-  /** An effect-drain runtime. */
   readonly drainer: "drainer";
   readonly script: "script";
   readonly test: "test";
@@ -4370,23 +4236,11 @@ export declare const EXECUTION_KINDS: {
 };
 
 /**
- * Execution context — advisory "via what" provenance, stamped on every
- * history entry alongside the actor's "who".
- *
- * Identity is always the token behind the client (`/users/me`); the
- * execution context records the ENVIRONMENT that drove the commit: a
- * studio session, the CLI, an MCP host, a server proxy acting with a
- * user's token. It is self-asserted advisory metadata, configured once at
- * `createEngine` — never per call — and never an authorization input.
- *
- * The `runtime` half is always inferred at construction (best-effort,
- * zero dependencies); the declared `{kind, id}` half is optional. An
- * unlabeled `runtime: "node"` is itself a signal (a script or proxy that
- * didn't declare itself), and a declared/inferred mismatch (`kind:
- * "studio"` on `runtime: "node"`) surfaces SSR passes or lying labels
- * for free.
- */
-/** The stored stamp — `runtime` is always present, the declared half optional. */
+ * The stored stamp: self-asserted advisory provenance — "via what", distinct
+ * from the actor's "who". Configured once at `createEngine`, never per call,
+ * and never an authorization input. `runtime` is always present; the declared
+ * half is optional.
+ */
 export declare interface ExecutionContext {
   /** Inferred JavaScript runtime: `browser` | `node` | `worker` | `edge` | `deno` | `bun` | `unknown`. */
   runtime: string;
@@ -4419,6 +4273,13 @@ export declare const EXECUTOR_CLASSIFICATION_DISPLAY: {
   };
 };
 
+/**
+ * Who, if anyone, fires an activity's actions, derived ahead-of-time from
+ * the activity's shape alone: `'autonomous'` = every action is cascade-fired
+ * (no caller fires anything); `'interactive'` = only fireAction-fired
+ * actions; `'off-system'` = `target` present; `'hybrid'` = mixed. Advisory,
+ * rendered on insight/evaluation nodes — never gating.
+ */
 export declare const EXECUTOR_CLASSIFICATIONS: readonly [
   "autonomous",
   "interactive",
@@ -4492,17 +4353,7 @@ export declare function explainStartRequirement(args: {
  */
 export declare function extractDocumentId(gdrUriString: string): string;
 
-/**
- * Convenience: fetch the grants for a given resource via the supplied
- * client:
- *
- *   GET <resourcePath> → Grant[]
- *
- * `resourcePath` is caller-supplied so the same helper works for
- * project ACLs (`/projects/<id>/datasets/<dataset>/acl`) and for a
- * dedicated workflow-collaboration resource. The client must support
- * the `request<T>({url})` method `@sanity/client` exposes.
- */
+/** `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: {
@@ -4598,13 +4449,21 @@ export declare const FIELD_KIND_DISPLAY: {
   };
 };
 
+/**
+ * The three field scopes a field entry can live in. Also the
+ * group-declaration levels: a `groups` array lives at exactly these three
+ * nodes, so `DefinitionGroupSite.level` reuses this vocabulary.
+ */
 declare const FIELD_SCOPES: readonly ["workflow", "stage", "activity"];
 
 /**
  * The kinds a VALUE can take — scalars aligned to Sanity's names, the
  * reference kinds, the actor/assignee identities, and the two compositional
  * kinds (`object` with named `fields`, `array` of objects shaped by `of`).
- * This is also the set a nested {@link FieldShape} sub-field may use.
+ * This is also the set a nested {@link FieldShape} sub-field may use. Kinds
+ * are bare (unique within their union); namespacing lives only on
+ * engine-owned lake document `_type`s ({@link WORKFLOW_DEFINITION_TYPE}, the
+ * instance type).
  *
  * Exported (module-level, not package API) for the model-surface gate's
  * enum-value coverage test.
@@ -4650,6 +4509,7 @@ export declare interface FieldDescription {
   proposals: InsightPhrase[];
 }
 
+/** One declared field entry as authored and stored: name, value kind, and its scope's sourcing and editability. */
 export declare type FieldEntry = FieldEntryFields<Editable, string[]>;
 
 /** Type-mirror of {@link fieldEntryFields}: a raw field entry of the given
@@ -4662,6 +4522,8 @@ declare type FieldEntryFields<TEditable, TGroup> = FieldBase<
   options?: ChoiceOptions | undefined;
   validation?: ScalarValidation | undefined;
   types?: string[] | undefined;
+  /** Non-empty assignment eligibility constraint. User roles apply aliases; collective roles match literally. */
+  roles?: string[] | undefined;
   fields?: FieldShape[] | undefined;
   of?: FieldShape[] | undefined;
 };
@@ -4715,6 +4577,14 @@ declare type FieldReadExpr = {
 
 export declare type FieldScope = (typeof FIELD_SCOPES)[number];
 
+/**
+ * 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.
+ */
 export declare interface FieldShape {
   type: FieldValueKind;
   name: string;
@@ -4722,10 +4592,19 @@ export declare interface FieldShape {
   description?: string | undefined;
   options?: ChoiceOptions | undefined;
   validation?: ScalarValidation | undefined;
+  /** Non-empty assignment eligibility constraint. User roles apply aliases; collective roles match literally. */
+  roles?: string[] | undefined;
   fields?: FieldShape[] | undefined;
   of?: FieldShape[] | undefined;
 }
 
+/**
+ * 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.
+ */
 export declare type FieldSource = FieldSourceInternal;
 
 declare type FieldSourceInternal =
@@ -4740,12 +4619,9 @@ declare type FieldSourceInternal =
   | FieldReadExpr;
 
 /**
- * The field tree of a persisted value — every leaf replaced by its type name
- * (`null` kept distinct from `object`), object keys sorted by UTF-16 code
- * unit (locale-independent, so the pinned ledgers canonicalise identically
- * on every machine), arrays element-wise so discriminated variants stay
- * visible. The comparison form the model-surface gates pin per model
- * version, and the form ops tooling can diff a live document against.
+ * 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
+ * machine.
  */
 export declare function fieldTreeShape(value: unknown): unknown;
 
@@ -4806,6 +4682,7 @@ export declare class FieldValueShapeError extends WorkflowError<"field-value-sha
  */
 export declare const FILTER_SCOPE_VARS: readonly string[];
 
+/** Returns `undefined`, never throws, for an activity an instance's pinned snapshot names but the definition has since renamed or removed. */
 export declare function findActivityNode(args: {
   activityName: string;
   definition: WorkflowDefinition | undefined;
@@ -4852,6 +4729,7 @@ export declare interface FindPendingEffectsArgs extends InstanceRefArgs {
   names?: string[];
 }
 
+/** Returns `undefined`, never throws, for a stage an instance's pinned snapshot names but the definition has since renamed or removed. */
 export declare function findStageNode(args: {
   definition: WorkflowDefinition | undefined;
   stageName: string;
@@ -5012,6 +4890,11 @@ export declare interface GlobalDocumentReference<
   type: TType;
 }
 
+/**
+ * Filters are GROQ strings evaluated through groq-js with the document as
+ * the dataset and the caller's principal id as `identity()`. Grants compose
+ * most-permissive-wins.
+ */
 export declare interface Grant {
   filter: string;
   permissions: DocumentValuePermission[];
@@ -5033,12 +4916,22 @@ 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}. */
 export declare type GroqRequirement = RequirementBase & {
   type: "groq";
   query: string;
 };
 
-/** Type-mirror of {@link GroupSchema} — one declared group. */
+/**
+ * A declared "what belongs together" tag: the workflow root, a stage, or an
+ * activity declares named groups, and field entries, activities, and actions
+ * opt in via `group`. Purely advisory — the engine stores and validates names
+ * (unique per level, every reference resolves) and never acts on them; a
+ * consumer decides what a group means for its medium. The same name declared
+ * at several levels is intentional nesting, addressed per level; the engine
+ * never merges them.
+ */
 export declare type Group = {
   name: string;
   title?: string | undefined;
@@ -5064,6 +4957,14 @@ export declare const GROUP_KIND_DISPLAY: {
   };
 };
 
+/**
+ * Advisory classification of a declared {@link Group} by its informational
+ * ROLE, never a rendering treatment: `'core'` marks content central to
+ * understanding the workflow (condensed views include these first);
+ * `'details'` marks depth on demand. Unset = a plain group. Consumers
+ * reading a definition as data MUST treat an unknown kind as unset — growing
+ * this list is an engine version bump, like every stored enum.
+ */
 export declare const GROUP_KINDS: readonly ["core", "details"];
 
 export declare type GroupKind = (typeof GROUP_KINDS)[number];
@@ -5116,6 +5017,27 @@ export declare function groupSitesOf(
   definition: WorkflowDefinition,
 ): DefinitionGroupSite[];
 
+/**
+ * A lake mutation guard. A FOREIGN CONTRACT mirrored 1:1: `match`,
+ * `predicate`, and `metadata` are the content lake's persisted guard-document
+ * API, not engine-invented surface — the stored form keeps the lake's
+ * vocabulary verbatim. The engine adds exactly two things: `name` (a
+ * lake-id-segment, `^[a-z0-9][a-z0-9-]*$`, unique per definition — the lake
+ * `_id` derives from `(instanceId, name)` at stage entry) and the deploy-time
+ * read VALUES on `match.idRefs` / `metadata` (a typed {@link GuardRead} when
+ * authoring, resolved to bare values at deploy). `match` selects mutations by
+ * `types` (empty matches any), `idRefs` (field reads resolved to bare ids),
+ * `idPatterns` (bare glob ids), and `actions` (at least one). `predicate` is
+ * lake GROQ in a distinct delta-mode eval context (`before()`/`after()`,
+ * `mutation`, `guard`, `identity()`, bare ids/fields only): strictly `true`
+ * ALLOWS the mutation; anything else — false, null, an evaluation error, or
+ * an omitted/empty predicate — DENIES. `metadata` is the only bridge from
+ * that eval context (which cannot see `$fields`) to workflow fields, read as
+ * `guard.metadata.*` and re-synced by the post-field-op guard refresh. The
+ * lake does not enforce the guard document type yet: a deployed guard denies
+ * optimistically engine-side, and the lake ACL is the only hard gate until
+ * guard enforcement ships.
+ */
 export declare type Guard = v.InferOutput<typeof GuardSchema>;
 
 /**
@@ -5173,6 +5095,17 @@ export declare function guardMatches({
   action: MutationGuardAction;
 }): 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.
+ */
 export declare type GuardRead = v.InferOutput<typeof GuardReadSchema>;
 
 declare const GuardReadSchema: v.VariantSchema<
@@ -5254,14 +5187,8 @@ declare const GuardReadSchema: v.VariantSchema<
   undefined
 >;
 
-/** Stored guards carry the printed string reads (the deploy resolver's input). */
 declare const GuardSchema: v.StrictObjectSchema<
   {
-    /**
-     * Lake-id-segment grammar (`^[a-z0-9][a-z0-9-]*$`, deploy-enforced): the
-     * guard's lake `_id` derives from `(instanceId, name)` at stage entry.
-     * Unique per definition.
-     */
     name: v.SchemaWithPipe<
       readonly [
         v.StringSchema<undefined>,
@@ -5272,7 +5199,6 @@ declare const GuardSchema: v.StrictObjectSchema<
     description: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
     match: v.StrictObjectSchema<
       {
-        /** Subject `_type`(s); empty matches any type. */
         types: v.OptionalSchema<
           v.ArraySchema<
             v.SchemaWithPipe<
@@ -5285,7 +5211,6 @@ declare const GuardSchema: v.StrictObjectSchema<
           >,
           undefined
         >;
-        /** Target docs as field reads (or the instance itself), resolved at deploy to bare ids + the resource. */
         idRefs: v.OptionalSchema<
           v.ArraySchema<
             v.SchemaWithPipe<
@@ -5298,7 +5223,6 @@ declare const GuardSchema: v.StrictObjectSchema<
           >,
           undefined
         >;
-        /** Glob id patterns (bare, resource-local). */
         idPatterns: v.OptionalSchema<
           v.ArraySchema<
             v.SchemaWithPipe<
@@ -5330,22 +5254,7 @@ declare const GuardSchema: v.StrictObjectSchema<
       },
       undefined
     >;
-    /**
-     * Lake GROQ predicate — a distinct eval context: delta-mode GROQ
-     * reading the `before()`/`after()` natives, `mutation`, `guard`, and
-     * `identity()`. Bare ids/fields only. Polarity: a result of strictly
-     * `true` ALLOWS the matched mutation; anything else (false, null, an
-     * evaluation error) DENIES. Omitted or empty means UNCONDITIONAL DENY.
-     */
     predicate: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
-    /**
-     * Projected workflow fields the predicate reads as `guard.metadata.*` —
-     * the only bridge from the lake eval context (which cannot see `$fields`)
-     * to workflow fields. Each value is a deploy-time read — a typed
-     * {@link GuardRead} when authoring, the printed string spelling once
-     * stored — resolved into a bare value at deploy and re-synced by the
-     * post-field-op guard refresh.
-     */
     metadata: v.OptionalSchema<
       v.RecordSchema<
         v.SchemaWithPipe<
@@ -5495,6 +5404,15 @@ export declare const HISTORY_DISPLAY: {
   };
 };
 
+/**
+ * One appended audit row. Every `actor` stamp on one is token-resolved
+ * advisory provenance, never authenticated identity — the lake's own document
+ * history is the authenticated ground truth.
+ *
+ * On the three stage-movement arms, `via` discriminates a condition-driven
+ * transition (`'transition'`, the default when absent) from an admin override
+ * (`'setStage'`), and the `reason` beside it is that override's free text.
+ */
 export declare type HistoryEntry = HistoryEvent & {
   /**
    * The execution environment that committed this entry — inferred
@@ -5514,10 +5432,7 @@ declare type HistoryEvent =
       stage: StageName;
       fromStage?: StageName;
       transition?: string;
-      /** Discriminates filtered transitions ("transition", default) from
-       *  admin overrides ("setStage"). */
       via?: "transition" | "setStage";
-      /** Admin-supplied free-text on setStage. */
       reason?: string;
       actor?: Actor;
     }
@@ -5550,17 +5465,9 @@ declare type HistoryEvent =
       activity: ActivityName;
       action: ActionName;
       actor?: Actor;
-      /**
-       * What KIND of driver fired the action, derived from {@link actor} at
-       * fire time (see `../activity-kind.ts`) — the audit-trail glyph's
-       * person/agent/service/engine axis. Absent when no actor was supplied.
-       */
       driverKind?: DriverKind;
-      /**
-       * The engine fired this action in a cascade (its `when` turned true) —
-       * {@link actor} is the cascading token that happened to execute it,
-       * not a caller who invoked `fireAction`.
-       */
+      /** The engine fired this action in a cascade: `actor` is the cascading token that
+       *  executed it, not a caller who invoked `fireAction`. */
       triggered?: true;
     }
   | {
@@ -5583,9 +5490,6 @@ declare type HistoryEvent =
       origin: EffectOrigin;
     }
   | {
-      /** A queued effect settled — a reported completion (`done`/`failed`),
-       *  or an abort cancelling it before dispatch (`cancelled`). One entry
-       *  per `effectHistory` row, sharing its `effectKey`. */
       _key: string;
       _type: "effectCompleted";
       at: string;
@@ -5602,12 +5506,9 @@ declare type HistoryEvent =
       at: string;
       effectKey: string;
       effect: EffectName;
-      /** The expired claim that was released — who abandoned it and when. */
       claim: PendingEffectClaim;
-      /** How the stale claim was recovered: a drain taking it over for
-       *  redispatch, or `sweepStaleClaims` force-releasing it. */
+      /** `drain-takeover` = a drain redispatched it; `sweep` = `sweepStaleClaims` released it. */
       via: "drain-takeover" | "sweep";
-      /** The drainer/sweeper that released it. */
       actor?: Actor;
     }
   | {
@@ -5615,12 +5516,6 @@ declare type HistoryEvent =
       _type: "spawned";
       at: string;
       activity: ActivityName;
-      /**
-       * GDR pointer at the spawned child workflow instance. Stored as
-       * the typed `{id, type}` envelope — same shape every other GDR
-       * field in the engine uses (`ancestors[]`, the subworkflow registry,
-       * any `doc.ref` field entry). The `id` is the full GDR URI.
-       */
       instanceRef: GlobalDocumentReference;
       /** Identity of the `forEach` row that produced this child. */
       rowKey?: string;
@@ -5632,8 +5527,6 @@ declare type HistoryEvent =
       at: string;
       stage: StageName;
       activity: ActivityName;
-      /** The live child re-bound to the entering stage's cohort instead of
-       *  being duplicated — its `forEach` row was rediscovered on re-entry. */
       instanceRef: GlobalDocumentReference;
       rowKey: string;
     }
@@ -5642,8 +5535,6 @@ declare type HistoryEvent =
       _type: "subworkflowResolved";
       at: string;
       activity: ActivityName;
-      /** The child observed terminal; its registry row now carries the
-       *  terminal cache. */
       instanceRef: GlobalDocumentReference;
       status: "done" | "aborted";
     }
@@ -5651,9 +5542,8 @@ declare type HistoryEvent =
       _key: string;
       _type: "subworkflowOrphaned";
       at: string;
-      /** A child that names this instance in its `ancestors` reached terminal,
-       *  but no registry row matches it — its completion cannot drive any
-       *  gate. Loud audit record of a propagation dead-end. */
+      /** A child naming this instance in its `ancestors` reached terminal, but no registry
+       *  row matches it — its completion cannot drive any gate. A loud dead-end record. */
       instanceRef: GlobalDocumentReference;
       detail: string;
     }
@@ -5661,9 +5551,7 @@ declare type HistoryEvent =
       _key: string;
       _type: "aborted";
       at: string;
-      /** The stage the instance was on when it was hard-stopped. */
       stage: StageName;
-      /** Admin-supplied free-text reason for the abort. */
       reason?: string;
       actor?: Actor;
     }
@@ -5672,27 +5560,17 @@ declare type HistoryEvent =
       _type: "opApplied";
       at: string;
       stage: StageName;
-      /** The boundary that ran the op. For an action fire (caller- or
-       *  cascade-fired), `activity` + `action` are set; for a direct edit
-       *  (the edit seam), `edit` is set and `activity` carries the field's activity when
-       *  the edited field is activity-scope; for an effect's completion ops,
-       *  `effect` names the effect. */
+      /** The op's boundary: an action fire sets `activity` + `action`; an edit sets `edit`
+       *  (plus `activity` for an activity-scope field); completion ops set `effect`. */
       activity?: ActivityName;
       action?: ActionName;
-      /** Set when the op was a direct edit through the edit seam (`editField`),
-       *  not an action. */
       edit?: true;
-      /** Set when the op came from an effect handler's completion (the state
-       *  half of an effect); names the effect. */
       effect?: EffectName;
-      /** The op's `type` (e.g. `field.set`). */
       opType: string;
-      /** Field reference the op targeted (omitted for `status.set`). */
       target?: {
         scope: FieldScope;
         field: string;
       };
-      /** Concrete resolved params the op acted on. Captured for audit. */
       resolved?: Record<string, unknown>;
       actor?: Actor;
     }
@@ -5700,30 +5578,18 @@ declare type HistoryEvent =
       _key: string;
       _type: "fieldQueryDiscarded";
       at: string;
-      /** Scope of the field whose `initialValue: {type:'query'}` result was dropped. */
       scope: FieldScope;
-      /** The field entry name. */
       field: string;
-      /** Why the lake result was discarded — the shape mismatch against the
-       *  declared kind. The field falls back to its default (null / []). */
       detail: string;
     };
 
 export { humanize };
 
-/**
- * The in-memory groq-js dataset filters evaluate against. Built once
- * per cascade entry (in the shell), passed through to `evaluateFilter`
- * (in the core) for every filter check.
- */
+/** The in-memory groq-js dataset the engine's filters evaluate against. */
 export declare interface HydratedSnapshot {
-  /** All hydrated docs, keyed by GDR URI as `_id`. */
+  /** Hydrated docs, keyed by GDR URI as `_id`. */
   docs: SanityDocument[];
-  /**
-   * The set of GDR URIs present in `docs`. Helpful for tests and shells
-   * that want to assert "is this doc in scope?" — the core eval pipeline
-   * itself doesn't read it.
-   */
+  /** Existence-check helper; the core eval pipeline itself doesn't read it. */
   knownIds: Set<string>;
 }
 
@@ -5846,6 +5712,17 @@ export declare type InsightSite =
       activity?: string;
     };
 
+/**
+ * The tag's instance partition as a listen filter — the one shared change
+ * feed a preview store keeps itself fresh from (an event names the touched
+ * instance; the store refetches that preview alone). Deliberately unfiltered
+ * beyond the tag: one upstream listener serves every view, whatever each is
+ * filtered to.
+ */
+export declare function instanceChangesQuery(args: {
+  tag: string;
+}): CompiledQuery;
+
 /**
  * Mint the Sanity document `_id` for a workflow instance — a fresh
  * {@link randomKey} suffix, so every instance (root or spawned child) gets a
@@ -5885,6 +5762,17 @@ export declare class InstanceNotFoundError extends WorkflowError<"instance-not-f
   constructor(args: { instanceId: string; detail?: string });
 }
 
+/**
+ * The preview projection over the same instances {@link instancesQuery}
+ * matches — a `WorkflowInstancePreview` each, kilobytes lighter than the full
+ * document (no snapshot, no audit trails), for surfaces that render many runs
+ * at once. Parse results through `readInstancePreviewDoc`.
+ */
+export declare function instancePreviewsQuery(args: {
+  tag: string;
+  filter?: InstancesQueryFilter;
+}): CompiledQuery;
+
 /** Args for the verbs that address an instance without further input. */
 export declare interface InstanceRefArgs {
   instanceId: string;
@@ -6021,10 +5909,10 @@ export declare interface InstancesQueryFilter {
   document?: GdrUri;
   /**
    * The multi-document form of {@link InstancesQueryFilter.document}: one
-   * predicate matching instances that reference ANY of the given docs,
+   * predicate matching instances that reference any of the given docs,
    * for consumers discovering instances across many open documents at once.
    * Merged with `document` when both are set. Callers may defensively recheck
-   * with {@link instanceWatchesDocument}. A DEFINED-but-EMPTY
+   * with {@link instanceWatchesDocument}. A defined but empty
    * array matches nothing (the GROQ-natural reading of membership in an
    * empty set) — omit the field for the unconstrained every-in-flight read.
    */
@@ -6034,7 +5922,7 @@ export declare interface InstancesQueryFilter {
    * a consumer tracking freshly-started instances (not yet referencing any
    * registered doc) sees them in the same live read. Bare ids only: an
    * instance's `_id` is never a GDR URI, so a URI here is a caller bug and
-   * is rejected. A DEFINED-but-EMPTY array matches nothing, exactly like
+   * is rejected. A defined but empty array matches nothing, exactly like
    * {@link InstancesQueryFilter.documents}.
    */
   ids?: readonly string[];
@@ -6045,13 +5933,25 @@ export declare interface InstancesQueryFilter {
   /** Include completed/aborted instances (default: in-flight only). */
   includeCompleted?: boolean;
   /**
-   * Cap the read to the NEWEST `limit` instances — the query flips to
+   * Cap the read to the newest `limit` instances — the query flips to
    * `startedAt desc` and slices, so a bounded consumer (a dashboard over an
    * unbounded dataset) reads the most recent rows instead of the oldest.
    * Unlimited reads keep the ascending order adapters index by. Must be a
    * positive integer.
    */
   limit?: number;
+  /**
+   * Keyset cursor into the newest-first order: only instances strictly older
+   * than this position. Pass the last row of the previous page, and the next
+   * `limit` rows continue where it ended. A cursor rather than an offset, so
+   * rows starting or concluding between pages can't shift what a page holds.
+   * Requires `limit`: pages only exist in the newest-first sliced read.
+   */
+  before?: {
+    /** The `_id` tiebreak for rows sharing `startedAt`. */
+    id: string;
+    startedAt: string;
+  };
 }
 
 /**
@@ -6071,9 +5971,8 @@ export declare function instanceWatchesDocument(
   document: GdrUri,
 ): boolean;
 
-/** The trigger split: a `when` action is cascade-fired; without one it is
- *  fireAction-fired. The single spelling of that test — structural over
- *  `when` so authoring and stored shapes both qualify. */
+/** The canonical cascade-fired test: structural on `when`, so both authored
+ *  and stored shapes qualify. */
 export declare function isCascadeFired(action: {
   when?: string | undefined;
 }): boolean;
@@ -6145,7 +6044,8 @@ export declare function isInputSourced(
  * apart from other array kinds (e.g. the `todoList` sugar's
  * `{label, status}`). Accepts both vocabularies — a deployed definition
  * entry (`type`) and a resolved instance entry (`_type`) — so start-time
- * and runtime surfaces share one verdict.
+ * and runtime surfaces share one verdict. Resolved-entry overload last, as
+ * on {@link isTodoListEntry}.
  */
 export declare function isNotesEntry(entry: FieldEntry): entry is FieldEntry & {
   type: "array";
@@ -6246,7 +6146,9 @@ export declare function isTerminalStage(stage: Stage): boolean;
  * `status` rows, which tells a todo list apart from other array kinds (e.g.
  * the `notes` sugar's `{body, actor, at}`). Accepts both vocabularies —
  * a deployed definition entry (`type`) and a resolved instance entry
- * (`_type`) — so start-time and runtime surfaces share one verdict.
+ * (`_type`) — so start-time and runtime surfaces share one verdict. The
+ * resolved-entry overload comes last: contextual typing reads an overloaded
+ * argument's FINAL signature, which `.filter(isTodoListEntry)` needs.
  */
 export declare function isTodoListEntry(
   entry: FieldEntry,
@@ -6275,31 +6177,23 @@ export declare function isTodoListItem(row: unknown): row is TodoListItem;
  * did not. The shape is legal and resumable — `startInstance` with the same
  * `instanceId` completes the outstanding commits. Readers should present it
  * as an incomplete start, never as a normal run sitting at its initial
- * stage. Terminal instances are excluded: an aborted never-primed husk
+ * stage. Terminal instances are excluded: an aborted never-primed instance
  * reads as aborted, not as still-resumable.
  */
 export declare function isUnprimed(
   instance: Pick<WorkflowInstance, "stages" | "completedAt" | "abortedAt">,
 ): boolean;
 
-/**
- * Deterministic id so deploy/retract are query-free and idempotent. Derived
- * from the guard's authored `name` — an author-controlled handle that stays
- * stable when guards are reordered or inserted (a positional index would
- * silently shift).
- */
+/** Deterministic id (from the guard's authored `name`) so deploy/retract are query-free and idempotent; a positional index would silently shift if guards are reordered. */
 export declare function lakeGuardId(args: {
   instanceDocId: string;
   guardName: string;
 }): string;
 
 /**
- * The id a lake-facing check binds for an actor: the resource-local
- * principal id when the namespaces diverge, otherwise the actor's own
- * (account-global) id. Every advisory that must agree with the lake's
- * `identity()` — guard previews and pre-flights, the anchor ACL's `$can`
- * grant filters — resolves through this one rule; binding `actor.id`
- * directly at a lake edge reintroduces the divergent-identity mismatch.
+ * The one rule every lake-facing identity check (guard previews/pre-flights, `$can` grant filters)
+ * must resolve through to agree with the lake's own `identity()`; binding `actor.id` directly at a
+ * lake edge reintroduces the divergent-identity mismatch.
  */
 export declare function lakePrincipalId(args: {
   actor: {
@@ -6359,11 +6253,6 @@ declare type LiteralExpr = {
   value: unknown;
 };
 
-/**
- * One loaded doc plus the resource it came from. The shell builds
- * this list by routing reads to the right client for each doc, then
- * hands it to `buildSnapshot`.
- */
 export declare interface LoadedDoc {
   doc: SanityDocument;
   resource: WorkflowResource;
@@ -6380,18 +6269,17 @@ export declare interface LogicalRef {
   version?: number | "latest";
 }
 
+/**
+ * Off-system deep-link target — render-only metadata whose presence marks an
+ * activity as off-system (BPMN Manual Task). Either a static URL, or a field
+ * reference whose resolved document the consumer opens; deploy checks the
+ * `field` variant points at a doc-valued entry.
+ */
 export declare type ManualTarget = v.InferOutput<
   typeof StoredManualTargetSchema
 >;
 
-/**
- * Evaluate a grant's GROQ filter against a single document with the
- * supplied identity. Returns true iff the document survives the filter.
- *
- * The implementation parses `*[<filter>]` once per filter string,
- * evaluates against a singleton dataset, and asks the result for its
- * length — `length === 1` means the doc passed.
- */
+/** Returns true iff `document` survives `filter`'s GROQ predicate under the supplied identity. */
 declare function matchesFilter(args: {
   document: {
     _id?: string;
@@ -6405,10 +6293,9 @@ declare function matchesFilter(args: {
 export { MAX_COUNTERFACTUAL_INDEX };
 
 /**
- * The oldest engine model that can safely read a persisted engine document.
- * The engine always writes the stamp pair, so a `modelVersion`
- * with no `minReaderModel` is malformed foreign data — read conservatively:
- * the stamp itself is the floor. A doc with neither is model 0 (floor 0).
+ * The engine always writes both stamps together, so a bare `modelVersion` with no
+ * `minReaderModel` is malformed foreign data; that case reads the version itself as the
+ * floor (conservative fallback).
  */
 export declare function minReaderModelOf(doc: object): number;
 
@@ -6467,11 +6354,9 @@ export declare function missingRequiredInputs(args: {
 }[];
 
 /**
- * A persisted engine document requires a NEWER reader than this engine: its
- * `minReaderModel` floor is above {@link DATA_MODEL_VERSION}. Reading it
- * could silently misinterpret whatever the newer model reshaped, so every
- * engine read path fails hard instead. The remediation is always the same:
- * upgrade `@sanity/workflow-engine`.
+ * Thrown when a document's reader floor exceeds {@link DATA_MODEL_VERSION} — reading it
+ * could silently misinterpret a newer model's reshape, so the read fails hard instead.
+ * Fix: upgrade `@sanity/workflow-engine`.
  */
 export declare class ModelVersionAheadError extends WorkflowError<"model-version-ahead"> {
   readonly documentId: string;
@@ -6485,13 +6370,10 @@ export declare class ModelVersionAheadError extends WorkflowError<"model-version
   });
 }
 
-/** The data model a persisted engine document conforms to. A document with no
- *  stamp was last written before governance existed — model 0. Reads the
- *  stamp structurally (persisted docs reach the gate as typed docs,
- *  projections, and raw snapshot reads alike); a non-number stamp is foreign
- *  data the engine never wrote and also reads as model 0. */
+/** A document with no stamp, or a non-number stamp (foreign data this engine never wrote), reads as model 0. */
 export declare function modelVersionOf(doc: object): number;
 
+/** The lake operations a guard can gate — see the guard types in ./authorization.ts. */
 declare const MUTATION_GUARD_ACTIONS: readonly [
   "create",
   "update",
@@ -6537,7 +6419,8 @@ export declare type MutationGuardAction =
  * compile inputs, so the field set lives in one place.
  */
 export declare interface MutationGuardBody {
-  /** Engine-layer: the single datasource this guard belongs to. */
+  /** The single datasource this guard belongs to — the engine spans
+   *  datasources and must record which one, since the lake is per-datasource and infers the resource from storage. */
   resourceType: string;
   resourceId: string;
   /**
@@ -6608,6 +6491,13 @@ export declare class MutationGuardDeniedError extends WorkflowError<"mutation-gu
 export declare interface MutationGuardDoc extends MutationGuardBody {
   _id: string;
   _type: typeof GUARD_DOC_TYPE;
+  /**
+   * Deliberately NO engine data-model stamp (`modelVersion`/`minReaderModel`)
+   * — this doc format is the lake's forthcoming contract, and the engine
+   * must not grow fields on a shape it doesn't own. Assigned by the lake on
+   * write — never sent on create (an empty-string value fails datetime
+   * validation).
+   */
   _rev?: string;
   _createdAt?: string;
   _updatedAt?: string;
@@ -6651,15 +6541,14 @@ export declare interface NoteItem {
   at?: string | null;
 }
 
-/**
- * `notes` — an append-only audit/comment log. Sugar over `array of object
- * { body, actor, at }` (the `actor`/`at` sub-fields match the `audit` op's
- * stamp names, so it pairs with it). Never a stored kind.
- */
+/** An append-only audit/comment log: sugar over `array of object {body, actor, at}` — the `actor`/`at`
+ *  names match the `audit` op's stamp fields, so it pairs with it. Never a stored kind. */
 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. */
 export declare type Op = v.InferOutput<typeof StoredOpSchema>;
 
 /**
@@ -6804,22 +6693,26 @@ export declare interface ParsedGdr {
 export declare function parseGdr(uri: string): ParsedGdr;
 
 /**
- * Parse a fetched guard document, failing hard with a
- * {@link PersistedDocShapeError} naming the document and every offending
- * field. No model-version gate: the guard doc carries no stamp by design —
- * its `_type` cutover is its versioning event.
+ * Throws {@link PersistedDocShapeError} on shape mismatch. Unlike other
+ * persisted docs, this doc carries no model-version stamp to gate on.
  */
 export declare function parseGuardDocument(doc: unknown): MutationGuardDoc;
 
 /**
  * Parse a fetched `sanity.workflow.instance` document, failing hard with a
  * {@link PersistedDocShapeError} naming the document and every offending
- * field. The caller's model-version gate (`assertReadableModel`) comes
- * FIRST — a doc from beyond the reader floor is a governed
+ * field. The caller's model-version gate (`assertReadableModel`) must run
+ * first: a doc from beyond the reader floor is a governed
  * `ModelVersionAheadError`, not a shape error.
  */
 export declare function parseInstanceDocument(doc: unknown): WorkflowInstance;
 
+/** {@link parseInstanceDocument}'s row-projection counterpart, with the same
+ *  gate-first contract. */
+export declare function parseInstancePreviewDocument(
+  doc: unknown,
+): WorkflowInstancePreview;
+
 /**
  * Parse a resource-shaped GDR (`<type>:<id>`, no document part) into the
  * {@link WorkflowResource} it names. The one grammar for resource addresses —
@@ -7063,27 +6956,40 @@ export declare interface QueryInScopeArgs extends InstanceRefArgs, QueryArgs {}
 export { quoted };
 
 export declare const READER_MODEL_ROLLOUT_URL =
-  "https://www.sanity.io/docs/editorial-workflows/prerelease";
+  "https://www.sanity.io/docs/workflows/prerelease";
 
-/** A producer has not explicitly acknowledged this engine's writer capability. */
+/** A producer has not acknowledged the floor required by its submitted definitions. */
 export declare class ReaderModelAcknowledgementError extends WorkflowError<"reader-model-acknowledgement"> {
   readonly code = "WORKFLOW_READER_MODEL_ACKNOWLEDGEMENT_MISMATCH";
   readonly expectedMinReaderModel: unknown;
+  readonly requiredMinReaderModel: number;
   readonly engineMinReaderModel = 4;
-  readonly engineModelVersion = 7;
-  readonly documentationUrl =
-    "https://www.sanity.io/docs/editorial-workflows/prerelease";
-  constructor(expectedMinReaderModel: unknown, context?: string);
+  readonly engineMaxReaderModel = 8;
+  readonly engineModelVersion = 8;
+  readonly documentationUrl = "https://www.sanity.io/docs/workflows/prerelease";
+  constructor(
+    expectedMinReaderModel: unknown,
+    options?: {
+      requiredMinReaderModel?: number;
+      context?: string;
+    },
+  );
 }
 
 /**
- * The one spelling of the instance read discipline — model gate
- * ({@link assertReadableModel}) first, shape parse
- * ({@link parseInstanceDocument}) second — shared by the point-read funnel
+ * The single definition of the instance read discipline (model gate
+ * {@link assertReadableModel} first, shape parse
+ * {@link parseInstanceDocument} second), shared by the point-read funnel
  * above and the list-read sites that fetch instance rows in bulk.
  */
 export declare function readInstanceDoc(doc: SanityDocument): WorkflowInstance;
 
+/** {@link readInstanceDoc}'s preview-projection counterpart: the same
+ *  gate-then-parse order over an `instancePreviewsQuery` result. */
+export declare function readInstancePreviewDoc(
+  doc: unknown,
+): WorkflowInstancePreview;
+
 /**
  * Whether a watched ref reads RAW — never perspective-scoped. The
  * instance, its ancestors, and its spawned children (all instance docs), and
@@ -7095,16 +7001,10 @@ export declare function readInstanceDoc(doc: SanityDocument): WorkflowInstance;
  */
 export declare function readsRaw(ref: { type: string }): boolean;
 
-/**
- * Whether a GROQ expression reads its ROOT document — the candidate document
- * a `start.filter` binds as root. A bare attribute access (`_type == 'task'`)
- * or `@` in the OUTER scope reads the root; the same inside a construct that
- * rebinds the implicit `this` per element (`*[...]` filters, projections,
- * `map`/pipe traversals) addresses THOSE items, so it doesn't. `^` (Parent)
- * climbs scopes — one that escapes past the outermost scope lands back on the
- * root and counts, wherever it is nested. A malformed expression reads
- * nothing here ({@link conditionSyntaxIssues} owns the parse error).
- */
+/** Whether a GROQ expression reads its ROOT document — the candidate a
+ *  `start.filter` binds, not an item inside a rebound scope (filters, `map`). A `^`
+ *  that escapes past the outermost scope lands back on the root and counts. A
+ *  malformed expression reads nothing here, so it returns `false`. */
 export declare function readsRootDocument(groq: string): boolean;
 
 /** Make a GDR pointer to a Canvas-resource doc. */
@@ -7172,15 +7072,10 @@ export declare class RefResourceUndeclaredError extends WorkflowError<"ref-resou
 export declare function refsOf(def: WorkflowDefinition): LogicalRef[];
 
 /**
- * The GDR `type`s in a reference-kind ({@link refKindAcceptsTypes}) value
- * that the entry's declared accepted `types` reject — empty when the value
- * conforms, the entry declares no `types`, or the kind isn't a ref. A GDR's
- * `type` names the target document's schema type, so this is the
- * declared-target-type contract. Skips anything that isn't GDR-shaped — the
- * shape schemas scream about those. Boundaries that need their own error
- * framing (the spawn `with` projection gates its remediation hint on the
- * generic `"document"` type being among the rejects) read this; everything
- * else goes through {@link refTypeIssues} / {@link checkFieldValue}.
+ * GDR `type`s in a reference-kind ({@link refKindAcceptsTypes}) value that the
+ * entry's declared `types` reject — empty when it conforms, no `types` are
+ * declared, or the kind isn't a ref. Skips non-GDR-shaped values; the shape
+ * schemas already reject those.
  */
 export declare function rejectedRefTypes(args: {
   entryType: string;
@@ -7246,6 +7141,11 @@ export declare type RemediationVerb =
   | "set-stage"
   | "abort";
 
+/** The reader model a deployment must acknowledge for its submitted definitions. */
+export declare function requiredDefinitionReaderModel(
+  definitions: readonly unknown[],
+): number;
+
 /**
  * Thrown when a workflow is started (or a child spawned) without a value for
  * a field entry marked `required`. Mirrors {@link ActionParamsInvalidError}:
@@ -7301,14 +7201,6 @@ export declare interface RequirementDescriptor {
  */
 export declare const RESERVED_CONDITION_VARS: readonly string[];
 
-/**
- * What to reset a stuck activity INTO — the two non-`failed` outcomes that
- * unstick a stage gated on it. `active` re-runs it (back in progress, so a
- * caller drives it to completion again); `skipped` bypasses it (terminal but
- * resolved, so `$allActivitiesDone` can satisfy and a gated exit transition
- * fire). `done` is deliberately absent: a reset is recovery, not a silent
- * declaration that the work succeeded.
- */
 declare const RESET_ACTIVITY_TARGETS: readonly ["active", "skipped"];
 
 export declare interface ResetActivityArgs extends DedupableOperationArgs {
@@ -7336,6 +7228,14 @@ export declare type ResetActivityResult =
       to: ResetActivityTarget;
     };
 
+/**
+ * What to reset a stuck activity INTO — the two non-`failed` outcomes that
+ * unstick a stage gated on it. `active` re-runs it (back in progress, so a
+ * caller drives it to completion again); `skipped` bypasses it (terminal but
+ * resolved, so `$allActivitiesDone` can satisfy and a gated exit transition
+ * fire). `done` is deliberately absent: a reset is recovery, not a silent
+ * declaration that the work succeeded.
+ */
 export declare type ResetActivityTarget =
   (typeof RESET_ACTIVITY_TARGETS)[number];
 
@@ -7343,8 +7243,9 @@ export declare type ResetActivityTarget =
  * Resolve the engine's `WorkflowAccess` for a client — actor and grants
  * (when a path is supplied) fetched from its token in parallel and cached.
  * Throws if the client can't yield an actor — the engine refuses to operate
- * without an identity. Does **not** fetch User Attributes; see
- * {@link resolveUserAttributes}.
+ * without an identity. A grants-fetch failure degrades open instead: the
+ * rendered `$can` stays undefined and the real Sanity write boundary still
+ * enforces. Does not fetch User Attributes; see {@link resolveUserAttributes}.
  */
 export declare function resolveAccess(
   taggedClient: WorkflowClient,
@@ -7386,8 +7287,9 @@ export declare interface ResolveClientActorArgs {
  * `resolvedAt` — the lake-read time — so `resolvedAt` is provenance-driven,
  * not kind-specific. `object` / `array` entries carry their declared
  * sub-field shape (`fields` / `of`) — and the reference kinds
- * ({@link refKindAcceptsTypes}) their declared accepted `types` — so the
- * instance is self-describing for op-time validation and rendering.
+ * ({@link refKindAcceptsTypes}) their declared accepted `types`, and
+ * assignment kinds their eligible `roles` — so the instance is
+ * self-describing for op-time validation and rendering.
  */
 export declare type ResolvedFieldEntry = {
   [K in FieldKind]: {
@@ -7411,6 +7313,11 @@ export declare type ResolvedFieldEntry = {
           of: FieldShape[];
         }
       : Record<never, never>) &
+    (K extends "assignee" | "assignees"
+      ? {
+          roles?: string[];
+        }
+      : Record<never, never>) &
     (K extends "doc.ref" | "doc.refs" | "subject"
       ? {
           types?: string[];
@@ -7418,14 +7325,8 @@ export declare type ResolvedFieldEntry = {
       : Record<never, never>);
 }[FieldKind];
 
-/**
- * The resolved entry a field site names, read from the instance's runtime
- * `fields[]` at the site's scope — the instance copy that carries what an
- * evaluation doesn't (the declared `of`/`fields` shape). Stage- and
- * activity-scope sites resolve against the OPEN stage. `undefined` when the
- * field hasn't been resolved yet (e.g. an activity-scope field before its
- * activity activated).
- */
+/** Resolves against the OPEN stage for stage/activity scopes; `undefined`
+ *  when the field hasn't resolved yet (e.g. an activity field before activation). */
 export declare function resolveFieldEntry(
   instance: WorkflowInstance,
   site: {
@@ -7459,26 +7360,20 @@ export declare type ResourceAliases = Record<string, WorkflowResource>;
  * Collapse a deployment's `resourceAliases` bindings into the
  * {@link ResourceAliases} map (handle name → physical resource) that
  * `deployDefinitions` expands `@<handle>:` references against. Deploy-time
- * only — the map never reaches any other verb.
+ * only — the map never reaches any other verb. A duplicate binding name
+ * silently overwrites here (last wins), which is why `DeploymentSchema`
+ * rejects one at parse time, before this ever runs.
  */
 export declare function resourceAliasesToMap(
   resourceAliases: WorkflowDeployment["resourceAliases"],
 ): ResourceAliases;
 
 /**
- * Routing override for cross-resource reads (subject + ancestor docs that
- * live in a different Sanity resource than the workflow). Called with a
- * parsed GDR; return a client for that resource, or `undefined` to let the
- * engine route it — its own client for the workflow resource, a derived
- * sibling ({@link WorkflowClient.withConfig}) for anything else.
- *
- * Serving a resource also DECLARES it on the written-ref surface: the write
- * boundaries probe this resolver per ref, so narrowing a resolver rejects
- * refs to the resources it stops serving.
- *
- * Engine-owned verb scopes rebind resolved clients onto
- * `ENGINE_API_VERSION`. Effect handlers derive request-tagged siblings from
- * resolver clients so their concrete APIs remain available and attributed.
+ * Cross-resource read routing override — return a client for the parsed
+ * GDR's resource, or `undefined` to let the engine route it. Serving a
+ * resource also declares it on the written-ref surface, so narrowing this
+ * resolver rejects refs to resources it stops serving; engine verb scopes
+ * also rebind any returned client onto their own API version.
  */
 export declare type ResourceClientResolver = (
   parsed: ParsedGdr,
@@ -7527,38 +7422,22 @@ export declare interface ResourceSurface {
  * the stage and must keep its lock) or gone (leave the lock as the orphan
  * seam rather than silently unlocking a vanished instance — the same
  * over-lock direction as deploy).
+ *
+ * Guard revisions are observed before the live-stage gate, then only those
+ * revisions are deleted: a deploy landing in between changes the revision,
+ * so the delete's revision fence fails instead of deleting the active guard.
  */
 export declare function retractStageGuards(args: StageGuardArgs): Promise<void>;
 
-export declare type RoleAliases = v.InferOutput<typeof RoleAliasesSchema>;
-
 /**
- * Role aliasing — the "can be fulfilled by" map, an authoring convenience.
- * A `roles` gate (or an `assignees` entry) names the role the author writes;
- * but the SAME capability is often carried by different role names depending
- * on how a given project deploys its Content Lake roles, and several roles may
- * legitimately do the job. Rather than enumerate every equivalent role inline
- * in each gate — or fork the definition per deployment — declare once here
- * which other roles also fulfill it.
- *
- * Each key is a role a gate/assignee names; its value lists the roles that
- * also satisfy it. The reserved key `"*"` lists roles that fulfill ANY gate
- * (e.g. `"*": ["administrator"]` — whatever this deployment's broad role is).
- * `"*"` is the spelling authors write; it is rewritten to a lake-safe stored
- * key before the definition is persisted, since the Content Lake rejects `"*"`
- * as a document attribute name (see {@link normalizeRoleAliases}).
- *
- * Applied as an in-place expansion of the REQUIRED side, never the actor's
- * roles: the `roles` gate bakes the expanded membership into its desugared
- * GROQ at define time; `$assigned` expands the assignee's role at match time
- * (see {@link expandRequiredRoles}). Carried into the stored definition for
- * that runtime half.
- *
- * Advisory, like every engine gate — an alias only predicts what the
- * deployment's Content Lake ACLs already allow, it never grants access. An
- * alias the lake won't honor makes the gate predict "allowed" for a write the
- * lake then rejects, so keep it true to what's actually deployed.
+ * Roles that may fulfil each authored role. Aliases widen action gates,
+ * `$assigned`, and assignment-field user eligibility by expanding the required
+ * side; they never alter an actor's roles. Collective role assignees remain
+ * literal ownership values and are not widened by this map. The authored `"*"`
+ * key lists universal fulfillers and is normalized before persistence.
  */
+export declare type RoleAliases = v.InferOutput<typeof RoleAliasesSchema>;
+
 declare const RoleAliasesSchema: v.RecordSchema<
   v.SchemaWithPipe<
     readonly [
@@ -7726,6 +7605,18 @@ export declare class SpawnContractsInvalidError extends WorkflowError<"spawn-con
   constructor(args: { issues: SpawnContractIssue[]; message: string });
 }
 
+/**
+ * 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.
+ */
 export declare type Stage = StageFields<
   FieldEntry,
   Activity,
@@ -7863,6 +7754,19 @@ export declare const START_REQUIREMENT_VARS: readonly {
   description: string;
 }[];
 
+/**
+ * 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.
+ */
 export declare type StartBlock = StartFields & {
   kind: StartKind;
 };
@@ -7924,9 +7828,6 @@ export declare interface StartEvaluation {
   invalidInitialFields: InitialFieldIssue[];
 }
 
-/** Type-mirror of {@link startFields}: how standalone runs of this workflow
- *  begin. Stored requires `kind` (desugar fills the `'interactive'` default);
- *  authoring may omit it — so each variant declares it. */
 declare type StartFields = {
   filter?: string | undefined;
   requirements?: StartRequirement[] | undefined;
@@ -8092,16 +7993,12 @@ export declare class StartNotSettledError extends WorkflowError<"start-not-settl
   });
 }
 
-/**
- * Why a definition can't be started standalone, or `undefined` when it can.
- * Advisory — the engine itself does not refuse ({@link isStartableDefinition})
- * — but a start surface has no way to supply the parent context a spawn-only
- * child expects, so it fails fast with this message instead.
- */
+/** Advisory only, per {@link isStartableDefinition} — a start surface has no parent context to give a spawn-only child, so it rejects fast with this message instead. */
 export declare function startRefusal(definition: {
   lifecycle?: WorkflowLifecycle | undefined;
 }): string | undefined;
 
+/** Every named readiness requirement accepted by workflow `start.requirements`. */
 export declare type StartRequirement =
   | GroqRequirement
   | SingleSubjectRequirement;
@@ -8153,15 +8050,6 @@ export declare interface StartSliceRow {
   completedAt: string | null;
 }
 
-/**
- * Declared editability of a field — the generic edit seam's gate. Default
- * (absent) is NOT editable: a field is op-only engine working memory unless the
- * modeler opens it. The stored form is `true` (editable by anyone within the
- * field's scope window) or an EDIT CONDITION — rendered-scope GROQ (`$actor`,
- * `$can`, `$attributes`, `$fields`, `$assigned`), checked like an action filter
- * to decide who-may-edit. ADVISORY like every engine gate — it disables the
- * inline field and explains; a {@link Guard} declares the intended write-lock.
- */
 declare const StoredEditableSchema: v.UnionSchema<
   [
     v.LiteralSchema<true, undefined>,
@@ -8383,6 +8271,7 @@ declare const StoredFieldOpSchema: v.VariantSchema<
   undefined
 >;
 
+/** A field reference with `scope` already resolved — the form every op target carries. */
 export declare type StoredFieldRef = v.InferOutput<typeof StoredFieldRefSchema>;
 
 declare const StoredFieldRefSchema: v.StrictObjectSchema<
@@ -8668,6 +8557,12 @@ export declare function stripSystemFields(
  * 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.
+ *
+ * `transition-unevaluable` is the recoverable arm: every activity resolved,
+ * but an exit transition's `when` came back GROQ `null` (a referenced operand
+ * is missing or unreadable), so selection halts and the cascade re-fires once
+ * the operand resolves — where `no-transition-fires` means every `when` is a
+ * definite `false`. It carries the undecidable transitions.
  */
 export declare type StuckCause =
   | {
@@ -8685,13 +8580,6 @@ export declare type StuckCause =
   | {
       kind: "no-transition-fires";
     }
-  /**
-   * Every activity resolved, but an exit transition's `when` is *unevaluable*
-   * (GROQ `null` — a referenced operand is missing/unreadable), so selection
-   * halts. Unlike {@link StuckCause} `no-transition-fires` this is recoverable:
-   * the cascade re-fires once the operand resolves (e.g. the subject is
-   * published or the field is filled). Carries the undecidable transitions.
-   */
   | {
       kind: "transition-unevaluable";
       transitions: string[];
@@ -8721,14 +8609,9 @@ export declare interface SubjectPermissionDenial {
   permission: DocumentValuePermission;
 }
 
-/** One foreign resource's forecast inputs: the actor's grants there, and the
- *  actor's principal id in THAT resource's own identity namespace. */
 declare interface SubjectResourceAccess {
   grants: Grant[];
-  /** What that resource's lake `identity()` returns for the acting token —
-   *  resolved through the resource's own routed client, so a dataset
-   *  resource contributes the actor's per-project user id and an org-level
-   *  resource the account-global id. */
+  /** The actor's principal id in this resource's own namespace: per-project user id for a dataset resource, account-global id for an org-level one. */
   actorId: string;
 }
 
@@ -8835,18 +8718,23 @@ 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`.
+ */
 export declare type Subworkflows = v.InferOutput<typeof SubworkflowsSchema>;
 
 declare const SubworkflowsSchema: v.StrictObjectSchema<
   {
-    /**
-     * GROQ producing one row per subworkflow; each row binds as `$row`. Every
-     * row must carry an identity the engine can adopt against on re-entry:
-     * `_key` ?? `_id` ?? GDR `id` for object rows (a GDR value — `{id, type}`
-     * with a GDR-URI `id`, the rows a `doc.refs` field stores — keys on its
-     * `id`; mint a `_key` in the projection for synthetic rows), the value
-     * itself for scalar rows. A row without an identity fails the spawn.
-     */
     readonly forEach: v.SchemaWithPipe<
       readonly [
         v.StringSchema<undefined>,
@@ -8880,7 +8768,6 @@ declare const SubworkflowsSchema: v.StrictObjectSchema<
       },
       undefined
     >;
-    /** Initial fields for each subworkflow — entry name → GROQ over `$row` + the parent scope. */
     readonly with: v.OptionalSchema<
       v.RecordSchema<
         v.SchemaWithPipe<
@@ -8899,11 +8786,6 @@ declare const SubworkflowsSchema: v.StrictObjectSchema<
       >,
       undefined
     >;
-    /**
-     * Extra values evaluated in the parent's rendered scope at spawn time and
-     * delivered into each subworkflow's `$context` bag — the parent→child
-     * handoff.
-     */
     readonly context: v.OptionalSchema<
       v.RecordSchema<
         v.SchemaWithPipe<
@@ -8922,16 +8804,6 @@ declare const SubworkflowsSchema: v.StrictObjectSchema<
       >,
       undefined
     >;
-    /**
-     * What happens to still-live children when their cohort's scope stops
-     * applying — the spawning stage exits, or a re-fire's `forEach` no longer
-     * discovers their row. `'detach'` (the default) lets them run to
-     * completion outside the gate; `'abort'` kills them (recursively). The
-     * engine never destroys in-flight work implicitly — `'abort'` is always
-     * an authored choice. Note this governs only the CHILDREN's fate; whether
-     * the parent may move at all is what gates (conditions over
-     * `$subworkflows`) decide.
-     */
     readonly onExit: v.OptionalSchema<
       v.PicklistSchema<readonly ["detach", "abort"], string>,
       undefined
@@ -8961,6 +8833,10 @@ export declare interface SuggestedRemediation {
  * recovered entries is the next `drainEffects` call's job. To kill a stuck
  * entry WITHOUT redispatching, report it via
  * `completeEffect({status: 'failed'})` instead.
+ *
+ * A standalone export, NOT an `Engine` verb: like the guard-lifecycle
+ * helpers, this is housekeeping for admin/ops tooling, not part of the
+ * editor/runtime verb surface — a drain already self-recovers via takeover.
  */
 export declare function sweepStaleClaims(args: {
   client: WorkflowClient;
@@ -8981,12 +8857,7 @@ export declare interface SweepStaleClaimsResult {
 /** Lake `identity()` sentinel for system-initiated actions. */
 export declare const SYSTEM_IDENTITY = "<system>";
 
-/**
- * The engine's read-partition invariant as a GROQ predicate: a document is
- * visible when its `tag` equals the caller's `$tag` param. The single
- * definition of "tag-scoped" shared by the engine's internal lookups, the
- * `workflow.query` guard, and the CLI/MCP read helpers.
- */
+/** Single source of the tag-scope GROQ predicate; the engine's lookups, `workflow.query`, and CLI/MCP reads all call this instead of hand-rolling the filter. */
 export declare function tagScopeFilter(): string;
 
 /**
@@ -9000,22 +8871,6 @@ declare type Telemetered<T> = T & {
   telemetry?: WorkflowTelemetryLogger;
 };
 
-/**
- * The standard Sanity-intake recipe every workflow app shell shares —
- * consent from `GET /intake/telemetry-status`, transport via
- * `POST /intake/batch` `{projectId, batch}`, and the request tags that
- * keep shell telemetry traffic identifiable in request logs. The shells
- * (App SDK provider, MCP server, CLI) each own their store and
- * environment gates; this module is the one home for the recipe those
- * stores run on, so a change to an endpoint, body shape, or tag lands
- * everywhere at once.
- *
- * Like the event vocabulary (`engine.telemetry.ts`), this module keeps
- * the engine free of a runtime `@sanity/telemetry` dependency: the
- * result is a structural mirror of that package's batched-store options,
- * so a shell passes it straight to `createBatchedStore`. Drift against
- * the real package is pinned by a type-level test (dev dependency).
- */
 /** Mirror of `@sanity/telemetry`'s `ConsentStatus`. */
 export declare type TelemetryConsentStatus =
   | "undetermined"
@@ -9050,6 +8905,14 @@ export declare interface TelemetryIntakeClient {
   }) => Promise<T>;
 }
 
+/**
+ * The statuses an activity can be resolved INTO — what `status.set` accepts.
+ * A health axis, not a decision axis: a routine decision (decline, send back,
+ * hold) resolves `done` and routes via a field write; `failed` means the work
+ * genuinely could not complete. Only `done`/`skipped` satisfy
+ * `$allActivitiesDone` — a `failed` activity blocks it permanently, surfacing
+ * via `$anyActivityFailed`.
+ */
 declare const TERMINAL_ACTIVITY_STATUSES: readonly [
   "done",
   "skipped",
@@ -9063,8 +8926,8 @@ export declare type TerminalActivityStatus =
 export declare type TerminalState = "aborted" | "completed" | "in-flight";
 
 /**
- * Classify an instance by its terminal stamps. The ONE home for the
- * precedence rule: aborted instances carry `completedAt` too (stamped at the
+ * Classify an instance by its terminal stamps. The single definition of the
+ * precedence rule: aborted instances have `completedAt` too (stamped at the
  * abort, so in-flight queries treat both terminals uniformly), so `abortedAt`
  * must be checked first — `'completed'` means completed *without* an abort.
  */
@@ -9080,15 +8943,8 @@ export declare function terminalState(
  */
 export declare function toBareId(id: string): string;
 
-/**
- * `todoList` — ad-hoc, status-tracked work items. Sugar over `array of object
- * { label, status, assignee?, dueDate? }`; a plain checklist is this used with
- * `{label, status}` only (open ↔ done). Never a stored kind.
- *
- * The `dueDate` column is a `date` NAMED `dueDate`, not the {@link
- * FieldValueMap.dueDate} kind — that kind reserves one deadline slot per level,
- * and a repeating row has nothing to reserve.
- */
+/** Ad-hoc, status-tracked work items: sugar over `array of object {label, status, assignee?, dueDate?}`; a plain checklist is that with `{label, status}` alone.
+ *  Its `dueDate` is a `date` column named `dueDate`, not the elevated `dueDate` kind, which reserves one deadline slot per level. Never a stored kind. */
 declare type TodoListField = FieldBase<AuthoringEditable, GroupMembership> & {
   type: "todoList";
 };
@@ -9110,6 +8966,16 @@ export declare interface TodoListItem {
   dueDate?: string | null;
 }
 
+/**
+ * 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).
+ */
 export declare type Transition = TransitionFields & {
   when: string;
 };
@@ -9190,10 +9056,6 @@ export declare function unsatisfiedTransitionSummaries(
   summary: string;
 }[];
 
-/**
- * Normalize Management API user-attribute payloads into the `$attributes`
- * bag. Fetch/caching stays in access resolution; this module is I/O-free.
- */
 /** Flat key → active-value record bound as advisory `$attributes` when present. */
 export declare type UserAttributes = Record<string, unknown>;
 
@@ -9237,6 +9099,12 @@ declare interface ValidationIssue {
   message: string;
 }
 
+/**
+ * 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.
+ */
 export declare type ValueExpr = ValueExprInternal;
 
 declare type ValueExprInternal =
@@ -9337,110 +9205,80 @@ export { WhatIfOutcome };
 
 export { withAssignment };
 
-/**
- * The workflow verbs, bound as one object — write path, admin
- * overrides, pure reads, and permission helpers. The module doc above
- * describes the model.
- */
 export declare const workflow: {
   /**
-   * Deploy a set of workflow definitions as one call. Definitions are
-   * immutable and content-addressed: the author writes no version, and each
-   * deploy compares a definition's content fingerprint to the latest version
-   * already deployed under its name. Identical content is a no-op
-   * (`unchanged`); any change mints the next version (`created`) — deploy
-   * never patches a deployed version, so a definition can't change out from
-   * under the instances pinned to it. `startInstance` picks the highest
-   * version by default. The engine figures out the dependency order itself
-   * (children before parents that spawn them via `action.spawn.definition`)
-   * and reports a per-definition outcome (`created` / `unchanged`).
-   *
-   * Refs may point inside the batch OR at already-deployed definitions
-   * in the lake — both are valid. A ref pointing at neither errors with
-   * a clear message naming the missing target.
-   *
-   * Cycles in the dependency graph error before any write happens.
-   *
-   * Input is authored content or a fetched definition document — the document
-   * envelope (`_*` system fields, `tag`, `version`, `contentHash`) is stripped
-   * at the boundary, never fingerprinted, so a fetched document redeploys as
-   * `unchanged`. Any other unknown key fails loud.
+   * 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.
    */
   deployDefinitions: <T extends WorkflowDefinitionInput<T>>(
     rawArgs: Telemetered<DeployDefinitionsArgs<T> & EngineScopeArgs>,
   ) => Promise<DeployDefinitionsResult>;
   /**
-   * Remove a deployed workflow definition (all versions, or one via
-   * `version`). Refuses while non-terminal instances exist unless
-   * `cascade` aborts them first — instances are never deleted, only
-   * aborted in place; see {@link deleteDefinitionInternal} for the
-   * full contract (spawn-referrer check, guard-doc housekeeping).
+   * Remove a deployed definition (all versions, or one via `version`). Refuses
+   * while non-terminal instances exist unless `cascade` aborts them first —
+   * instances are never deleted, only aborted in place; see
+   * {@link deleteDefinitionInternal} for the full contract (spawn-referrer
+   * check, guard-doc housekeeping).
    */
   deleteDefinition: (
     rawArgs: Clocked<Telemetered<DeleteDefinitionArgs & EngineScopeArgs>>,
   ) => Promise<DeleteDefinitionResult>;
   /**
-   * Spawn a new workflow instance from a deployed definition.
-   *
-   * The gates run before anything is written, in order: supplied rows must be
-   * structurally consumable, required inputs must be present
-   * ({@link RequiredFieldNotProvidedError}), then every declared start
-   * requirement is evaluated in author order. All unmet `groq` and
-   * `singleSubject` nodes are reported by one {@link StartNotAllowedError}
-   * (there is no override arg — pre-flight with `evaluateStart`).
-   * Per-value SHAPE validation fires during field resolution, after the
-   * verdict but still before any write. It does NOT evaluate `start.filter`:
-   * that is a read-side visibility rule (see `definitionsForDocument`).
-   *
-   * Pins the snapshot at start-time, seeds the `context` bag, and enters
-   * the initial stage — fields resolve and every in-scope activity is
-   * born active. Then cascades until stable, so the initial stage's
-   * `when: 'true'` triggers have fired by the time this returns.
+   * Spawn a new instance from a deployed definition: pins the snapshot, seeds
+   * the `context` bag, enters the initial stage with every in-scope activity
+   * born active, then cascades until stable. The gates run before anything is
+   * written — supplied rows must be structurally consumable, required inputs
+   * must be present, then every declared start requirement is evaluated in
+   * author order and all unmet nodes are reported by one
+   * {@link StartNotAllowedError} (no override arg; pre-flight with
+   * `evaluateStart`). `start.filter` is NOT evaluated here — that is a
+   * read-side visibility rule, see `definitionsForDocument`.
    *
    * Start is three commits — create, prime, first cascade — and a supplied
-   * `instanceId` is its idempotency key across them. When that id already
-   * exists under this tag for the same start, the call RESUMES: input gates
-   * and field resolution are skipped (those values were pinned at create)
-   * and the outstanding commits run — the retry path for a start that
-   * failed after its create landed (see `isUnprimed`). Reusing an id for a
-   * DIFFERENT start (definition or explicit version mismatch) — or for an
-   * unfinished start that was aborted (a discarded start) — throws
-   * {@link ContractViolationError}. The mid-sequence failures are typed and
-   * carry the retry id: a prime failure after the create committed throws
-   * `StartNotPrimedError` (failed but resumable), and a cascade failure
-   * after a successful prime throws `StartNotSettledError` — the run exists
-   * by then and must not be reported as a failed start. `changed` is `true`
-   * on a fresh start and rev-derived on a resume; `cascaded` reports how far
-   * the instance auto-advanced.
+   * `instanceId` is the idempotency key across them: reusing it for the SAME
+   * start RESUMES (input gates and field resolution are skipped, those values
+   * were pinned at create), while reusing it for a DIFFERENT start, or for an
+   * unfinished start that was aborted, throws
+   * {@link ContractViolationError}. `changed` is `true` on a fresh start and
+   * rev-derived on a resume; `cascaded` reports how far the instance
+   * auto-advanced.
    */
   startInstance: (
     rawArgs: Clocked<Telemetered<StartInstanceArgs & EngineScopeArgs>>,
   ) => Promise<OperationResult>;
   /**
-   * Fire an action against an active activity. Cascades and propagates to
-   * ancestors after the action commits. A cascade-fired (`when`) action is
-   * rejected — the cascade is its only firing path.
-   *
-   * This is the universal "something happened" call. Editors fire it.
-   * Runtimes fire it in response to webhooks, effect completions, and
-   * timer firings. External signals never bypass this.
+   * Fire an action against an active activity, then cascade and propagate to
+   * ancestors once it commits. The universal "something happened" call —
+   * editors fire it, and runtimes fire it in response to webhooks, effect
+   * completions, and timer firings; external signals never bypass it. A
+   * cascade-fired (`when`) action is rejected: the cascade is its only firing
+   * path.
    */
   fireAction: (
     rawArgs: Clocked<Telemetered<FireActionArgs & EngineScopeArgs>>,
   ) => Promise<OperationResult>;
   /**
    * Edit a declared-editable field directly — reassign, reschedule,
-   * claim-by-hand, append to a running log — through the generic edit seam,
+   * claim-by-hand, append to a running log — through the generic edit seam
    * instead of a bespoke action per field. Soft-gates on the field's declared
    * editability (the same projection a UI renders), applies the edit as a
-   * `field.*` op (so provenance + history are stamped by the op path),
+   * `field.*` op so provenance and history are stamped by the op path,
    * refreshes the stage's guards, then cascades — an edit to a value a
    * transition reads can and should move the instance. Advisory like every
    * engine gate.
    *
    * Each call is a discrete COMMIT (a history entry, a guard refresh, a
    * cascade, an `ifRevisionId` write), not a draft patch — so an inline-field
-   * UI must bind it to a deliberate boundary (blur / Enter / Save / debounce),
+   * UI must bind it to a deliberate boundary (blur, Enter, Save, debounce),
    * never an `onChange` per keystroke.
    */
   editField: (
@@ -9448,94 +9286,87 @@ export declare const workflow: {
   ) => Promise<OperationResult>;
   /**
    * Report a queued effect's outcome. Drains it from `pendingEffects` and
-   * appends an `effectHistory` entry whose `outputs` (when supplied on a
-   * successful run) are what downstream effect bindings and conditions
-   * read as `$effects['<name>'].<output>` — the start-only `context` bag
-   * is never touched. Any `ops` the handler returned (`field.*`) are
-   * validated and applied to the instance in the same commit, through the
-   * same op applier an action's field ops use. Cascades after. A completion
-   * that applies always changes state (the effect drains + history is
-   * appended), so `changed` is `true` — a bad `effectKey`/status throws
-   * instead, and a keyed retry of an already-applied completion replays as
-   * `changed: false`.
+   * appends an `effectHistory` entry whose `outputs` are what downstream
+   * bindings and conditions read as `$effects['<name>'].<output>` — the
+   * start-only `context` bag is never touched. Any `ops` the handler returned
+   * (`field.*`) are validated and applied in the same commit, through the op
+   * applier an action's field ops use. Cascades after. A completion that
+   * applies always changes state, so `changed` is `true`; a bad
+   * `effectKey`/status throws instead, and a keyed retry of an
+   * already-applied completion replays as `changed: false`.
    *
    * Completion is first-writer-wins — see {@link CompleteEffectArgs}. A
-   * completer reporting over a retrying transport (webhook redelivery,
-   * queue, cron) should pass `idempotencyKey`.
+   * completer reporting over a retrying transport (webhook redelivery, queue,
+   * cron) should pass `idempotencyKey`.
    */
   completeEffect: (
     rawArgs: Clocked<Telemetered<CompleteEffectArgs & EngineScopeArgs>>,
   ) => Promise<OperationResult>;
   /**
-   * Commit mid-dispatch field state from a running effect handler — the
-   * engine verb behind `ctx.commitOps`. Gates on the dispatch's exact claim
-   * (token match + unexpired lease; a stale report throws
-   * `StaleEffectClaimError` and writes nothing), validates and applies the
-   * `field.*` ops through the shared op applier, records history and the
-   * mandatory idempotency key, renews the claim's lease in the same
-   * compare-and-swap commit, refreshes the stage's guards, then cascades —
-   * a report that satisfies a transition moves the instance, by design.
+   * Commit mid-dispatch field state from a running effect handler — the engine
+   * verb behind `ctx.commitOps`. Gates on the dispatch's exact claim (token
+   * match plus unexpired lease; a stale report throws `StaleEffectClaimError`
+   * and writes nothing), validates and applies the `field.*` ops through the
+   * shared op applier, records history and the mandatory idempotency key,
+   * renews the claim's lease in the same compare-and-swap commit, refreshes
+   * the stage's guards, then cascades — a report that satisfies a transition
+   * moves the instance, by design.
    *
-   * Completion (`completeEffect`) remains the authoritative final result
-   * and stays claim-blind; this verb only protects the mid-dispatch write
-   * channel from superseded handlers.
+   * `completeEffect` remains the authoritative final result and stays
+   * claim-blind; this verb only protects the mid-dispatch write channel from
+   * superseded handlers.
    */
   commitEffectOps: (
     rawArgs: Clocked<Telemetered<CommitEffectOpsArgs & EngineScopeArgs>>,
   ) => Promise<OperationResult>;
   /**
    * Run the cascade until stable — triggered actions fire, transitions move.
-   *
-   * Used by the runtime after any event that might affect the workflow
-   * but isn't itself an action fire: a subject doc was patched, a sibling
-   * workflow completed, the clock crossed a deadline a `when` reads, etc.
-   * The runtime doesn't need to know what changed — it just nudges
-   * affected instances and the engine re-evaluates. `changed` reports
-   * whether the nudge wrote anything: a fired transition, but also a
-   * hop that fired triggered actions without unlocking a transition yet —
-   * so it's derived from the instance's `_rev`, not from `cascaded` alone.
+   * For a runtime reacting to any event that might affect the workflow but
+   * isn't itself an action fire: a subject doc was patched, a sibling workflow
+   * completed, the clock crossed a deadline a `when` reads. The caller doesn't
+   * need to know what changed — it nudges the affected instance and the engine
+   * re-evaluates. `changed` reports whether the nudge wrote anything, derived
+   * from the instance's `_rev` rather than `cascaded` alone, since a hop can
+   * fire triggered actions without unlocking a transition.
    */
   tick: (
     rawArgs: Clocked<Telemetered<OperationArgs & EngineScopeArgs>>,
   ) => Promise<OperationResult>;
   /**
-   * Admin override — force the instance into `targetStage` regardless
-   * of filters or declared transitions. ACL gating should be enforced
-   * upstream; this verb performs the mechanical move. `changed: false`
-   * means the move was a no-op (already at the target / terminal).
+   * Admin override — force the instance into `targetStage` regardless of
+   * filters or declared transitions. ACL gating is enforced upstream by the
+   * caller; this verb performs no permission pre-flight, only the mechanical
+   * move. `changed: false` means the move was a no-op (already at the target,
+   * or terminal).
    */
   setStage: (
     rawArgs: Clocked<Telemetered<SetStageArgs & EngineScopeArgs>>,
   ) => Promise<OperationResult>;
   /**
-   * Admin override — hard-stop an in-flight instance where it stands.
-   * No stage move, no transition effects, pending effects cancelled;
-   * see {@link abortAndPropagate} for the abort + ancestor-propagation
-   * contract (propagated, not cascaded — the instance is terminal, so
-   * `cascaded` is always `0`; ancestor movement is reported on the
-   * ancestors, not here). `changed: false` means the instance was
-   * already terminal.
+   * Admin override — hard-stop an in-flight instance where it stands. No stage
+   * move, no transition effects, pending effects cancelled; see
+   * {@link abortAndPropagate} for the abort + ancestor-propagation contract.
+   * Propagated, not cascaded — the instance is terminal, so `cascaded` is
+   * always `0` and ancestor movement is reported on the ancestors, not here.
+   * `changed: false` means the instance was already terminal.
    */
   abortInstance: (
     rawArgs: Clocked<Telemetered<AbortInstanceArgs & EngineScopeArgs>>,
   ) => Promise<OperationResult>;
   /**
    * Admin override — reset a failed (or otherwise terminal) activity in the
-   * instance's current stage: `to: 'active'` re-runs it, `to: 'skipped'`
-   * (the bypass) resolves it so a `$allActivitiesDone`-gated exit can fire.
-   * Defaults to `active`. Cascades after the reset, so an unblocked
-   * transition fires in the same call. ACL gating should be enforced
-   * upstream. `changed: false` means the reset was a no-op (instance
-   * terminal, or the activity already at the target status).
+   * instance's current stage. `to: 'active'` (the default) re-runs it;
+   * `to: 'skipped'` is the bypass that resolves it so a `$allActivitiesDone`-gated
+   * exit can fire. Cascades after the reset, so an unblocked transition fires
+   * in the same call. ACL gating is enforced upstream by the caller; this verb
+   * performs no permission pre-flight. `changed: false` means the reset was a
+   * no-op (instance terminal, or the activity already at the target status).
    */
   resetActivity: (
     rawArgs: Clocked<Telemetered<ResetActivityArgs & EngineScopeArgs>>,
   ) => Promise<OperationResult>;
-  /**
-   * Fetch a workflow instance by id, scoped to the engine's tag.
-   * Throws when the instance doesn't exist or isn't visible to this
-   * engine.
-   */
+  /** Fetch a workflow instance by id, scoped to the engine's tag. Throws when
+   *  the instance doesn't exist or isn't visible to this engine. */
   getInstance: (
     rawArgs: InstanceRefArgs & EngineScopeArgs,
   ) => Promise<WorkflowInstance>;
@@ -9546,65 +9377,52 @@ export declare const workflow: {
     rawArgs: GuardsForDefinitionArgs & EngineScopeArgs,
   ) => Promise<MutationGuardDoc[]>;
   /**
-   * Run a caller-supplied GROQ query with the engine's tag bound as
-   * `$tag`. This does NOT rewrite the query — arbitrary GROQ
-   * can't be safely tag-scoped after the fact — so the CALLER MUST
-   * filter on `$tag` (e.g. `tag == $tag`). To guard against accidental
-   * cross-partition reads, a query that never references `$tag` is
-   * rejected before it reaches the lake. Caller is responsible for type
-   * narrowing the result.
+   * Run a caller-supplied GROQ query with the engine's tag bound as `$tag`.
+   * This does NOT rewrite the query — arbitrary GROQ can't be safely
+   * tag-scoped after the fact — so the CALLER MUST filter on `$tag` (e.g.
+   * `tag == $tag`). To guard against accidental cross-partition reads, a query
+   * that never references `$tag` is rejected before it reaches the lake. The
+   * caller is responsible for type-narrowing the result.
    */
   query: <T = unknown>(rawArgs: QueryArgs & EngineScopeArgs) => Promise<T>;
   /**
-   * Snapshot-aware GROQ — runs against the same in-memory view that
-   * filters see for a given instance.
-   *
-   * Hydrates the instance's snapshot (instance + ancestors + every doc
-   * declared by a `doc.ref` / `subject` / `doc.refs` entry in scope), then
-   * evaluates the supplied GROQ in groq-js against that dataset. The
-   * caller-free rendered scope cascade gates evaluate in is auto-bound —
-   * the instance-derived vars ({@link FILTER_SCOPE_VARS}) with the open
-   * stage's overlay merged into `$fields`, `$assigned` at its caller-free
-   * `false`, plus the author's pre-evaluated `$<predicate>` booleans —
-   * ids in GDR URI form to match the snapshot's keying.
-   *
-   * Use when an external consumer (a UI, a debug pane, a test) wants
-   * to ask "what does the engine see for this workflow right now?"
-   * without re-implementing hydration. Pure read — never writes.
+   * Snapshot-aware GROQ — runs against the same in-memory view that filters
+   * see for a given instance. Hydrates the instance's snapshot (instance +
+   * ancestors + every doc declared by a `doc.ref` / `subject` / `doc.refs`
+   * entry in scope), then evaluates the supplied GROQ in groq-js against that
+   * dataset. The caller-free rendered scope cascade gates evaluate in is
+   * auto-bound — the instance-derived vars with the open stage's overlay
+   * merged into `$fields`, `$assigned` at its caller-free `false`, plus the
+   * author's pre-evaluated `$<predicate>` booleans — with ids in GDR URI form
+   * to match the snapshot's keying. Pure read; never writes.
    */
   queryInScope: <T = unknown>(
     rawArgs: Clocked<QueryInScopeArgs & EngineScopeArgs>,
   ) => Promise<T>;
-  /**
-   * List every pending effect on the instance. Returns the same entries
-   * the runtime would see — claimed and unclaimed alike.
-   */
+  /** Every pending effect on the instance — the same entries the runtime would
+   *  see, claimed and unclaimed alike. */
   listPendingEffects: (
     rawArgs: InstanceRefArgs & EngineScopeArgs,
   ) => Promise<PendingEffect[]>;
-  /**
-   * Filter pending effects on the instance by criteria. `claimed`
-   * filters on claim presence; `names` restricts to specific effect
-   * names. Both filters compose (AND).
-   */
+  /** Filter the instance's pending effects: `claimed` on claim presence,
+   *  `names` on specific effect names. Both filters compose (AND). */
   findPendingEffects: (
     rawArgs: FindPendingEffectsArgs & EngineScopeArgs,
   ) => Promise<PendingEffect[]>;
   /**
-   * Project the instance from a given actor's perspective. Returns a
-   * `WorkflowEvaluation` with per-action verdicts (`allowed` + a
-   * structured `disabledReason`). Pure read; never writes.
-   *
-   * Used by UIs to render disabled-with-reason buttons and by
-   * `fireAction` to gate writes via the same logic.
+   * Project the instance from a given actor's perspective — a
+   * {@link WorkflowEvaluation} with per-action verdicts (`allowed` plus a
+   * structured `disabledReason`). Used by UIs to render
+   * disabled-with-reason buttons and by `fireAction` to gate writes through
+   * the same logic. Pure read; never writes.
    */
   evaluate: (
     rawArgs: Clocked<EvaluateArgs & EngineScopeArgs>,
   ) => Promise<WorkflowEvaluation>;
   /**
-   * Diagnose why an instance is or isn't progressing. Projects the
-   * instance (the same read as `evaluate`) and classifies it — terminal,
-   * `progressing`, `waiting` (an action is available — healthy), or `stuck`
+   * Diagnose why an instance is or isn't progressing. Projects the instance
+   * (the same read as `evaluate`) and classifies it — terminal,
+   * `progressing`, `waiting` (an action is available, so healthy), or `stuck`
    * with a structured cause — returning that verdict as a
    * {@link DiagnoseResult} alongside the evaluation it came from, so a
    * consumer can render the supporting evidence without a second projection.
@@ -9613,59 +9431,39 @@ export declare const workflow: {
   diagnose: (
     rawArgs: Clocked<EvaluateArgs & EngineScopeArgs>,
   ) => Promise<DiagnoseResult>;
-  /**
-   * List the actions an actor could fire on an instance's current stage,
-   * each flagged `allowed` (with a structured `disabledReason` when not).
-   * Projects the instance from the actor's perspective and flattens its
-   * activities' actions. Returns the evaluation alongside the actions so a
-   * consumer can read the instance/stage context. Pure read.
-   */
+  /** The actions an actor could fire on the instance's current stage, each
+   *  flagged `allowed` with a structured `disabledReason` when not, returned
+   *  with the evaluation they were projected from. Pure read. */
   availableActions: (
     rawArgs: Clocked<EvaluateArgs & EngineScopeArgs>,
   ) => Promise<AvailableActionsResult>;
   /**
-   * Materialised spawned children of a parent instance.
-   *
-   * Walks `history` for `spawned` events — the durable
-   * record predating the workflow-scope subworkflow registry, and still the
-   * one place adoption/orphan events sit alongside spawns. Strips
-   * the GDR URI on each `instanceRef` to a bare `_id`, fetches the
-   * instances, drops any that aren't visible to this engine's tag, and
-   * returns them sorted by `startedAt` ascending.
-   *
-   * Pass `activity` to restrict to a single spawning activity on the parent.
+   * Materialised spawned children of a parent instance. Walks `history` for
+   * `spawned` events — the durable record, and still the one place adoption
+   * and orphan events sit alongside spawns — strips each `instanceRef`'s GDR
+   * URI to a bare `_id`, fetches the instances, drops any not visible to this
+   * engine's tag, and returns them sorted by `startedAt` ascending. Pass
+   * `activity` to restrict to a single spawning activity on the parent.
    */
   children: (
     rawArgs: ChildrenArgs & EngineScopeArgs,
   ) => Promise<WorkflowInstance[]>;
   /**
    * Every in-flight instance whose reactive watch-set includes `document` —
-   * the reverse of {@link subscriptionDocumentsForInstance}.
-   *
-   * For a non-reactive, content-change-driven runtime (a Sanity Function, an
-   * Inngest/durable worker, any server) that holds no instances in memory: a
-   * document changed; which instances should it `tick`? The watch-set covers
-   * the instance itself, its ancestors, live spawned children, and the docs named by
-   * `doc.ref` / `subject` / `doc.refs` / `release.ref` field entries on the
-   * workflow scope
-   * **and the current stage** — so a hand-rolled GROQ over `fields[]` gets it
-   * subtly wrong (misses stage-scope refs, `release.ref`, ancestors, and children).
-   *
-   * The GROQ filter narrows candidates server-side (in-flight, tag-scoped,
-   * matching workflow/open-stage refs); {@link instanceWatchesDocument},
-   * derived from `collectWatchRefs`, rechecks the result so the reverse stays
+   * the reverse of an instance's subscription document set. For a
+   * content-change-driven runtime holding no instances in memory: a document
+   * changed, which instances should it `tick`? The watch-set covers the
+   * instance itself, its ancestors, live spawned children, and the docs named
+   * by `doc.ref` / `subject` / `doc.refs` / `release.ref` entries on the
+   * workflow scope AND the current stage, so a hand-rolled GROQ over `fields[]`
+   * gets it subtly wrong. The GROQ filter narrows candidates server-side and
+   * {@link instanceWatchesDocument} rechecks each result, keeping the reverse
    * in lockstep with the forward set.
    *
-   * Single-resource: instances always live in the engine's own resource, so
-   * this reads one client (unlike {@link guardsForInstance}, whose guard docs
-   * are scattered across the watched resources). "Routed by resource" applies
-   * to the **subject**: a cross-dataset doc is matched by its full,
-   * resource-qualified GDR URI, never its bare id, so an instance watching
-   * `dataset:A:ds:doc` is not matched by a change to `dataset:B:ds:doc`.
-   *
-   * `document` must be a resource-qualified GDR URI; a bare id is rejected
-   * (it can't be resource-routed and would silently mismatch). Sorted by
-   * `startedAt` ascending.
+   * `document` must be a resource-qualified GDR URI; a bare id is rejected,
+   * since it can't be resource-routed and would silently mismatch — an
+   * instance watching `dataset:A:ds:doc` is never matched by a change to
+   * `dataset:B:ds:doc`. Sorted by `startedAt` ascending.
    */
   instancesForDocument: (
     rawArgs: InstancesForDocumentArgs & EngineScopeArgs,
@@ -9674,51 +9472,46 @@ export declare const workflow: {
    * The startable half of {@link workflow.instancesForDocument}: every
    * deployed definition that APPLIES to `document` — what a start picker for
    * it should offer. Loads the latest deployed version of each definition
-   * visible to the engine's tag and filters it through the derivation
-   * ({@link applicableDefinitions}): startable ∧ the `subject`-kind entry
-   * accepts the doc's `_type` ∧ `start.filter` passes — evaluated in the
-   * browse-time-pure start-filter context with `$tag`/`$definition`/`$now`
-   * bound and the tag's projected start slice (completed included) backing dataset
-   * reads. Start requirements never participate — readiness is a start-time
-   * question; pre-flight it with {@link workflow.evaluateStart}.
+   * visible to the engine's tag and filters it through
+   * {@link applicableDefinitions}: startable ∧ the `subject`-kind entry
+   * accepts the doc's `_type` ∧ `start.filter` passes, evaluated in the
+   * browse-time-pure start-filter context. Start requirements never
+   * participate — readiness is a start-time question; pre-flight it with
+   * {@link workflow.evaluateStart}.
    *
    * Takes the LOADED candidate document, not a ref — applicability evaluates
    * its content under whatever perspective the caller read it with. Surfaces
-   * ALL matches (name ascending), no engine
-   * ranking — presenting a picker or auto-picking is consumer policy.
-   * Advisory like every engine-side check.
+   * ALL matches (name ascending) with no engine ranking: presenting a picker
+   * or auto-picking is consumer policy. Advisory like every engine-side check.
    */
   definitionsForDocument: (
     rawArgs: Clocked<DefinitionsForDocumentArgs & EngineScopeArgs>,
   ) => Promise<DeployedDefinition[]>;
   /**
-   * Pre-flight the start gates for a definition + candidate `initialFields` —
-   * the read `startInstance` enforces, as a {@link StartEvaluation} a surface
-   * can render: `missingRequired` mirrors the input contract
-   * ({@link RequiredFieldNotProvidedError}'s rows), while `requirements`
-   * preserves every declared node's authored descriptor, outcome, and GROQ
-   * insight when applicable. `allowed` / `outcome` aggregate those ordered
-   * results. BINDABILITY-AWARE for partial mid-form inputs: when a predicate
-   * reads an entry `initialFields` doesn't supply — including a
-   * `singleSubject` node's implicit subject read — `outcome` is
-   * `'unevaluable'` and `unboundReads` names the entries ("fill these to
-   * decide") instead of the collapsed answer GROQ equality would give —
-   * this is the ONE deliberate divergence from the gate, where absence is
-   * final, not provisional (a rule like `!defined($fields.rush)` genuinely
-   * passes there when `rush` is absent). A definition declaring no start
-   * requirements is vacuously allowed, exactly like
-   * the verb. Pure read; advisory under races — the enforcement moment is
+   * Pre-flight the start gates for a definition plus candidate
+   * `initialFields` — the read `startInstance` enforces, as a
+   * {@link StartEvaluation} a surface can render: `missingRequired` mirrors
+   * the input contract, while `requirements` preserves every declared node's
+   * authored descriptor, outcome, and GROQ insight where applicable;
+   * `allowed` / `outcome` aggregate those ordered results.
+   *
+   * BINDABILITY-AWARE for partial mid-form inputs: when a predicate reads an
+   * entry `initialFields` doesn't supply — including a `singleSubject` node's
+   * implicit subject read — `outcome` is `'unevaluable'` and `unboundReads`
+   * names the entries ("fill these to decide") instead of the collapsed answer
+   * GROQ equality would give. That is the ONE deliberate divergence from the
+   * gate, where absence is final rather than provisional. A definition
+   * declaring no start requirements is vacuously allowed, exactly like the
+   * verb. Pure read; advisory under races — the enforcement moment is
    * `startInstance` itself.
    */
   evaluateStart: (
     rawArgs: Clocked<EvaluateStartArgs & EngineScopeArgs>,
   ) => Promise<StartEvaluation>;
-  /**
-   * Permission helpers — Sanity ACL grants evaluated against documents
-   * via GROQ. Used by `workflow.evaluate` to soft-gate actions when the
-   * caller supplies grants. Deliberately namespace-only (not mirrored on
-   * `Engine`): pure helpers that need none of the engine's pinned scope.
-   */
+  /** Permission helpers — Sanity ACL grants evaluated against documents via
+   *  GROQ, used by `workflow.evaluate` to soft-gate actions when the caller
+   *  supplies grants. Deliberately namespace-only, not mirrored on `Engine`:
+   *  pure helpers that need none of the engine's pinned scope. */
   permissions: {
     matchesFilter: typeof matchesFilter;
     grantsPermissionOn: typeof grantsPermissionOn;
@@ -9737,7 +9530,7 @@ export declare const WORKFLOW_DEFINITION_TYPE = "sanity.workflow.definition";
  * The lake document type for a workflow instance. Single source of truth — the
  * {@link WorkflowInstance} `_type`, every tag-scoped query, and the create
  * write all derive from here, mirroring {@link WORKFLOW_DEFINITION_TYPE}.
- * Engine-owned standalone documents carry the platform namespace.
+ * Engine-owned standalone documents use the platform namespace.
  */
 export declare const WORKFLOW_INSTANCE_TYPE = "sanity.workflow.instance";
 
@@ -9907,10 +9700,10 @@ export declare interface WorkflowClient {
    */
   withConfig?: (config: WorkflowClientConfig) => this;
   /**
-   * Optional — present on the real `@sanity/client`, absent on the
-   * in-memory test client. The engine probes for it when auto-resolving
-   * ACL grants from an endpoint; absence is the package's signal for
-   * "dry-run mode, don't try to fetch real grants."
+   * Optional — present on the real `@sanity/client`. Without it, ACL grant
+   * 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.
    */
   request?: <T>(opts: {
     /** Raw URL (host + path). One of `url` / `uri` required. */
@@ -9973,6 +9766,16 @@ export declare interface WorkflowCommitOptions {
   tag?: string;
 }
 
+/**
+ * `deployments` names must be unique (the selector deployment-targeted
+ * commands resolve by), and each `(workflowResource, tag)` pair must be
+ * unique — that pair is the storage partition, so two deployments sharing
+ * both would fight over definition versions. `telemetry`, when set, replaces
+ * the CLI's built-in Sanity-intake shell entirely: every event flows to this
+ * logger unconditionally (CI and `DO_NOT_TRACK` included), and consent,
+ * environment suppression, and transport become this implementation's
+ * business.
+ */
 export declare type WorkflowConfig = v.InferOutput<typeof WorkflowConfigSchema>;
 
 /**
@@ -10599,14 +10402,6 @@ declare const WorkflowConfigSchema: v.ObjectSchema<
         >,
       ]
     >;
-    /**
-     * Custom telemetry destination for the CLI. When set, the CLI's built-in
-     * Sanity-intake shell is not constructed and none of its policy applies:
-     * every event — the command trace and the engine vocabulary — flows to
-     * this logger unconditionally (CI and `DO_NOT_TRACK` environments
-     * included). Consent, environment suppression, transport, and destination
-     * are wholly this implementation's business.
-     */
     readonly telemetry: v.OptionalSchema<
       v.CustomSchema<
         WorkflowTelemetryLogger,
@@ -10618,6 +10413,21 @@ declare const WorkflowConfigSchema: v.ObjectSchema<
   undefined
 >;
 
+/**
+ * `name` is a lake-id-segment (`^[a-z0-9][a-z0-9-]*$`) that interpolates into
+ * every deployed document id (`<tag>.<name>.v<version>`) — stable identity
+ * that instances pin to and subworkflows resolve by. `lifecycle: 'child'`
+ * marks a spawn-only definition, instantiated by a parent via an action's
+ * `spawn`, never started cold from a picker (omitted ⇒ `'standalone'`,
+ * startable); advisory only — consumers filter start pickers on it (see
+ * {@link isStartableDefinition}), the engine does not itself refuse a
+ * `startInstance` on a `'child'` definition. `start` is meaningless
+ * (deploy-rejected) on a spawn-only definition; omitted, it means
+ * interactive semantics with no predicates. `predicates` are nullary named
+ * conditions — each `name: groq` entry is pre-evaluated and bound as the
+ * boolean `$name` var; redefining a built-in var is a deploy error, never a
+ * silent shadow.
+ */
 export declare type WorkflowDefinition = v.InferOutput<
   typeof WorkflowDefinitionSchema
 >;
@@ -10690,37 +10500,37 @@ export declare type WorkflowDefinitionInput<T> = string extends keyof T
  * 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.
  *
- * Carries NO `version` — the author never writes one. A definition's version
- * (and its content fingerprint) are stamped onto the deployed *document* at
- * deploy time, derived from the content itself; see `DeployedDefinition` and
- * `planDefinitionDeploy` in `api/deploy.ts`. The author's content is the sole
- * source of identity: redeploying identical content is a no-op, 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>
 >;
 
 /** One deployment as loaded from a config: the floor is optional/unverified so
- *  a command that never selects a deployment can hold a stale or missing
- *  acknowledgement. Deployment-scoped paths assert before they act; authors
- *  write {@link WorkflowDeploymentInput}. */
+ *  commands that do not submit definitions can hold a missing acknowledgement.
+ *  Definition-submission paths compare it with their selected definitions; authors write
+ *  {@link WorkflowDeploymentInput}. */
 export declare type WorkflowDeployment = WorkflowConfig["deployments"][number];
 
 /**
- * What an author writes for one deployment: the current reader floor as the
- * reviewed literal. Compile-time only — omitting it or setting a wrong value
- * is a type error in the editor. Runtime parse still tolerates a stale or
- * missing floor on {@link WorkflowDeployment} so commands that never select a
- * deployment still run; deployment-scoped paths assert the selected
- * deployment (instance-id commands do not).
+ * 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.
  */
 export declare type WorkflowDeploymentInput = Omit<
   WorkflowDeployment,
   "expectedMinReaderModel"
 > & {
-  expectedMinReaderModel: typeof DATA_MODEL_MIN_READER;
+  expectedMinReaderModel: number;
 };
 
 export declare const WorkflowEffectCompleted: WorkflowTelemetryEvent<WorkflowEffectCompletedData>;
@@ -10874,12 +10684,6 @@ export declare interface WorkflowFieldEditedData extends InstanceScopedEventData
 
 /** Type-mirror of {@link workflowFields}, parameterised over field/stage/start. */
 declare type WorkflowFields<TField, TStage, TStart> = {
-  /**
-   * Lake-id-segment grammar (`^[a-z0-9][a-z0-9-]*$`, deploy-enforced): the
-   * name interpolates into every deployed document id
-   * (`<tag>.<name>.v<version>`). Stable identity — instances pin to it,
-   * subworkflows resolve by it.
-   */
   name: string;
   semantics?: Semantic[] | undefined;
   title: string;
@@ -10906,8 +10710,8 @@ export declare interface WorkflowInstance extends SanityDocument {
   modelVersion?: number;
   /**
    * Reader floor — the oldest engine data model that can safely interpret
-   * this document. No lower than the writer's unconditional
-   * {@link DATA_MODEL_MIN_READER}, and written alongside
+   * this document. Derived from its persisted features and the retained
+   * model-4 baseline, and written alongside
    * {@link WorkflowInstance.modelVersion}. Full persists never lower it.
    */
   minReaderModel?: number;
@@ -10933,7 +10737,7 @@ export declare interface WorkflowInstance extends SanityDocument {
    * can detect a deployed definition that drifted from what this instance
    * started on. Advisory — the engine enforces nothing; this enables detection,
    * not prevention. Absent when the instance was started against a definition
-   * deployed before content-addressing (it carried no hash to pin).
+   * deployed before content-addressing (it had no hash to pin).
    */
   pinnedContentHash?: string;
   /** Frozen JSON snapshot of the definition at the moment the instance started. */
@@ -10982,10 +10786,10 @@ export declare interface WorkflowInstance extends SanityDocument {
    */
   stages: StageEntry[];
   /**
-   * Workflow-scope registry of every child this instance ever spawned —
+   * Workflow-scope registry of every child this instance ever spawned;
    * see {@link SubworkflowEntry}. Rows are never deleted; a row without
-   * `resolved` is a LIVE child (watched, hydrated, propagating), one with
-   * it is terminal, and a live row with `abortPending` is CONDEMNED — the
+   * `resolved` is a live child (watched, hydrated, propagating), one with
+   * it is terminal, and a live row with `abortPending` is condemned — the
    * cascade owes it an abort. Rendered as the `$subworkflows` condition
    * var. Absent only on instances persisted before the registry existed.
    */
@@ -11015,6 +10819,63 @@ export declare interface WorkflowInstance extends SanityDocument {
 
 export declare const WorkflowInstanceAborted: WorkflowTelemetryEvent<WorkflowAdminOverrideData>;
 
+/**
+ * The instance list projection — a reduced {@link WorkflowInstance} for
+ * surfaces that render many runs at once, fetched by `instancePreviewsQuery`.
+ *
+ * The reduction keeps the full instance's field names and member shapes so
+ * instance helpers (`terminalState`, `findOpenStageEntry`, `parentRef`, the
+ * identity normalizer) read a preview unchanged; what shrinks is the content:
+ * `stages` holds the open entry alone, every `fields` list keeps only the
+ * identity, date, document-reference, and release-reference kinds, and the unbounded audit
+ * trails are gone — `claimedEffects` and `failedEffects` hold the two facts
+ * a stuck classifier reads in their place. There is deliberately no
+ * `definitionSnapshot`: a consumer titles what it shows from the deployed
+ * catalog, falling back to raw names.
+ */
+export declare interface WorkflowInstancePreview {
+  _id: string;
+  _type: typeof WORKFLOW_INSTANCE_TYPE;
+  /** See {@link WorkflowInstance.modelVersion}. */
+  modelVersion?: number;
+  /** See {@link WorkflowInstance.minReaderModel}. */
+  minReaderModel?: number;
+  workflowResource: WorkflowResource;
+  definition: string;
+  pinnedVersion: number;
+  /** Identity, date, document-reference, and release-reference entries only
+   *  — the kinds list surfaces read. Composite (`object`/`array`) entries are
+   *  dropped, so identities nested inside them are invisible to a preview. */
+  fields: ResolvedFieldEntry[];
+  ancestors: GlobalDocumentReference[];
+  perspective?: WorkflowPerspective;
+  currentStage: StageName;
+  /** The open stage entry alone, its activities' fields reduced like
+   *  {@link fields}. A completed run keeps its terminal entry open, so this
+   *  is empty only for an aborted run (whose entries closed in place) or
+   *  before the run primes. */
+  stages: StageEntry[];
+  /** Pending effects a drainer has claimed — the hung-automation fact. */
+  claimedEffects: WorkflowInstancePreviewEffect[];
+  /** Effect-history rows that reported failure — the failed-automation fact. */
+  failedEffects: WorkflowInstancePreviewEffect[];
+  startedAt: string;
+  completedAt?: string;
+  abortedAt?: string;
+}
+
+/** A stalled automation as a preview reports it — the effect's machine name
+ *  and its display title. */
+export declare interface WorkflowInstancePreviewEffect {
+  name: string;
+  title?: string;
+}
+
+/** The instance list projection (`instancePreviewsQuery` results). The reduced
+ *  members reuse the persisted document's own schemas, so a preview can
+ *  never admit a shape the full parse would refuse. */
+export declare const WorkflowInstancePreviewSchema: v.GenericSchema<WorkflowInstancePreview>;
+
 /**
  * The persisted instance document, root to leaf. Reused verbatim by every
  * engine read boundary through {@link parseInstanceDocument}; the