@sanity/workflow-engine 0.14.0 → 0.15.0

package/dist/index.d.cts

@@ -1,7 +1,34 @@
+import { analyzeCondition } from "@sanity/groq-condition-describe";
+import { AtomInsight } from "@sanity/groq-condition-describe";
+import { AtomRequirement } from "@sanity/groq-condition-describe";
+import { checklistLines as checklistLines_2 } from "@sanity/groq-condition-describe";
+import { ComparisonOp } from "@sanity/groq-condition-describe";
+import { ConditionAnalysis } from "@sanity/groq-condition-describe";
+import { ConditionAtom } from "@sanity/groq-condition-describe";
+import { ConditionClause } from "@sanity/groq-condition-describe";
+import { ConditionDescription } from "@sanity/groq-condition-describe";
+import { ConditionInsight } from "@sanity/groq-condition-describe";
+import { ConditionOutcome } from "@sanity/groq-condition-describe";
+import { ConditionRead } from "@sanity/groq-condition-describe";
+import { DescribedClause } from "@sanity/groq-condition-describe";
+import { explainCondition } from "@sanity/groq-condition-describe";
+import { ExplainConditionArgs } from "@sanity/groq-condition-describe";
+import { formatRead } from "@sanity/groq-condition-describe";
+import { guillemets } from "@sanity/groq-condition-describe";
+import { humanize } from "@sanity/groq-condition-describe";
+import { InsightPhrase } from "@sanity/groq-condition-describe";
+import { isComparisonOp } from "@sanity/groq-condition-describe";
+import { MAX_COUNTERFACTUAL_INDEX } from "@sanity/groq-condition-describe";
+import { quoted } from "@sanity/groq-condition-describe";
 import type { SanityDocument } from "@sanity/types";
+import { ScopeAssignment } from "@sanity/groq-condition-describe";
+import { sentenceCase } from "@sanity/groq-condition-describe";
 import * as v from "valibot";
+import { whatIfCondition } from "@sanity/groq-condition-describe";
+import { WhatIfOutcome } from "@sanity/groq-condition-describe";
+import { withAssignment } from "@sanity/groq-condition-describe";
 
-export declare interface AbortInstanceArgs extends OperationArgs {
+export declare interface AbortInstanceArgs extends DedupableOperationArgs {
   /** Free-text reason — surfaces on the `workflow.history.aborted` entry for audit. */
   reason?: string;
 }
@@ -11,7 +38,58 @@ export declare function abortReason(
   instance: Pick<WorkflowInstance, "history">,
 ): string | undefined;
 
-export declare type Action = ActionFields<Op>;
+/**
+ * The structured half of applicability: does a required subject entry
+ * (`doc.ref` / `doc.refs`, workflow scope) accept `documentType`? Name-blind
+ * and EXISTENTIAL: ANY required ref entry counts — a multi-input definition
+ * (say, contract + counterparty) surfaces from either document's picker, and
+ * the start dialog collects the remaining required entries (their fail-hard
+ * validation backstops). An entry without `types` accepts any type; a
+ * definition with NO required ref entry takes no subject and never matches.
+ * Cheap and indexable — no GROQ evaluation — so a consumer can pre-filter
+ * before loading document content. (`required` is pinned to caller-filled
+ * `input` entries by a deploy invariant, so it alone identifies the handoff.)
+ */
+export declare function acceptsDocumentType(
+  definition: Pick<ApplicabilitySource, "fields">,
+  documentType: string,
+): boolean;
+
+/**
+ * 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
+ * a caller passes as `grantsFromPath`). Known for `dataset`
+ * (`/projects/<id>/datasets/<ds>/acl`) and `canvas`
+ * (`/canvases/<resourceId>/acl`); `undefined` for resource types without a
+ * known grants endpoint, so a caller can degrade open (no grants → no
+ * advisory forecast) instead of guessing a path.
+ */
+export declare function aclPathForResource(
+  res: Extract<
+    WorkflowResource,
+    {
+      type: "dataset" | "canvas";
+    }
+  >,
+): string;
+
+export declare function aclPathForResource(
+  res: WorkflowResource,
+): string | undefined;
+
+export declare type Action = ActionFields<Op, string[]>;
+
+/**
+ * The engine's per-reason detail fragment — the same wording
+ * {@link ActionDisabledError} embeds in its message. Exported so a dev-facing
+ * host (the CLI) renders the one canonical detail instead of maintaining a
+ * parallel per-kind copy. Covers every reason but `mutation-guard-denied`,
+ * which escalates to {@link MutationGuardDeniedError} and renders through
+ * {@link deniedGuardLabels}.
+ */
+export declare function actionDisabledDetail(
+  reason: ActionDisabledReason,
+): string;
 
 /**
  * Thrown by `fireAction` when the requested action's verdict is
@@ -45,13 +123,18 @@ export declare interface ActionEvaluation {
   allowed: boolean;
   /** Present iff `allowed === false`. The first failing gate wins. */
   disabledReason?: DisabledReason;
+  /** Derived state of the action's `filter` gate — why it holds or fails,
+   *  atom by atom. Present iff the action declares a filter. */
+  insight?: ConditionInsight;
 }
 
-/** Type-mirror of {@link actionFields}, parameterised over the op grammar. */
-declare type ActionFields<TOp> = {
+/** Type-mirror of {@link actionFields}, parameterised over the op and
+ *  group-membership grammars. */
+declare type ActionFields<TOp, TGroup> = {
   name: string;
   title?: string | undefined;
   description?: string | undefined;
+  group?: TGroup | undefined;
   filter?: string | undefined;
   params?: ActionParam[] | undefined;
   ops?: TOp[] | undefined;
@@ -137,7 +220,8 @@ export declare type Activity = ActivityFields<
   FieldEntry,
   Action,
   Op,
-  ManualTarget
+  ManualTarget,
+  string[]
 >;
 
 /**
@@ -194,6 +278,14 @@ declare const ACTIVITY_STATUSES: readonly [
   "failed",
 ];
 
+/** An activity's four gates, each described — absent keys mirror undeclared gates. */
+export declare interface ActivityDescription {
+  requirements?: Record<string, ConditionDescription>;
+  filter?: ConditionDescription;
+  completeWhen?: ConditionDescription;
+  failWhen?: ConditionDescription;
+}
+
 export declare interface ActivityEntry {
   _key: string;
   /** Matches the authoring `Activity.name`. */
@@ -214,13 +306,6 @@ export declare interface ActivityEntry {
     unevaluable?: boolean;
     detail?: string;
   };
-  /**
-   * Subworkflows started by this activity (via `activity.subworkflows`). Each entry
-   * is a GDR pointing at an instance document. Used by ancestor propagation
-   * to walk back up the tree, and rendered as `$subworkflows` for the activity's
-   * `completeWhen` / `failWhen`.
-   */
-  spawnedInstances?: GlobalDocumentReference[];
   /** Activity-scoped resolved field entries. Absent until the engine writes to it. */
   fields?: ResolvedFieldEntry[];
 }
@@ -243,14 +328,29 @@ export declare interface ActivityEvaluation {
    * carries the matching `requirements-unmet` `disabledReason`).
    */
   unmetRequirements?: string[];
+  /** Derived state per declared requirement, keyed by requirement name.
+   *  Present iff the activity declares requirements; `unmetRequirements`
+   *  is exactly the keys whose insight isn't satisfied. */
+  requirementInsights?: Record<string, ConditionInsight>;
+  /** Derived state of the activity's `filter` skip-gate. Present iff declared.
+   *  Advisory read: the engine's cascade owns the gate itself. */
+  filterInsight?: ConditionInsight;
+  /** Derived state of `completeWhen` — what would auto-complete this activity.
+   *  Present iff declared. */
+  completeWhenInsight?: ConditionInsight;
+  /** Derived state of `failWhen` — what would auto-fail this activity.
+   *  Present iff declared. */
+  failWhenInsight?: ConditionInsight;
   actions: ActionEvaluation[];
 }
 
-/** Type-mirror of {@link activityFields}, parameterised over field/action/op/target. */
-declare type ActivityFields<TField, TAction, TOp, TTarget> = {
+/** Type-mirror of {@link activityFields}, parameterised over field/action/op/target/group. */
+declare type ActivityFields<TField, TAction, TOp, TTarget, TGroup> = {
   name: string;
   title?: string | undefined;
   description?: string | undefined;
+  groups?: Group[] | undefined;
+  group?: TGroup | undefined;
   kind?: ActivityKind | undefined;
   target?: TTarget | undefined;
   activation?: "auto" | "manual" | undefined;
@@ -276,12 +376,11 @@ export declare type ActivityName = string;
 export declare type ActivityStatus = (typeof ACTIVITY_STATUSES)[number];
 
 /**
- * Who is acting, as asserted by the caller — advisory provenance, not an
- * authenticated principal. The engine resolves it from the client's token by
- * default (`/users/me`), but every acting verb accepts an `access.actor`
- * override and nothing verifies the asserted id against the token performing
- * the writes. Only the lake's own token identity is authenticated; hard
- * enforcement lives there.
+ * Who is acting — advisory provenance, not an authenticated principal. The
+ * engine always resolves it from the client's token (`/users/me`); there is
+ * no way to pass or synthesize one. The stamp is still advisory: nothing
+ * re-verifies it at read time, and only the lake's own token identity is
+ * authenticated — hard enforcement lives there.
  */
 export declare interface Actor {
   kind: ActorKind;
@@ -307,6 +406,47 @@ export declare const ACTOR_KINDS: readonly ["person", "agent", "system"];
 
 export declare type ActorKind = (typeof ACTOR_KINDS)[number];
 
+export { analyzeCondition };
+
+/** The definition surface applicability reads — structural, so authored,
+ *  stored, and deployed definition shapes all fit. `name` is error context
+ *  only: a broken `applicableWhen` fails naming its definition. */
+export declare interface ApplicabilitySource {
+  name?: string | undefined;
+  lifecycle?: WorkflowLifecycle | undefined;
+  fields?: FieldEntry[] | undefined;
+  applicableWhen?: string | undefined;
+}
+
+/**
+ * Filter `definitions` to the ones applicable to `document`, preserving
+ * input order — surface ALL matches; the engine ranks nothing.
+ */
+export declare function applicableDefinitions<
+  T extends ApplicabilitySource,
+>(args: {
+  definitions: readonly T[];
+  document: CandidateDocument;
+}): 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.
+ */
+export declare function assertReadableModel<
+  T extends {
+    _id: string;
+  },
+>(doc: T): T;
+
 /**
  * One member of an `assignees`-kind entry's value — and the value of the
  * singular `assignee` kind. The WHO-FOR spec the inbox reverse-query and the
@@ -325,6 +465,10 @@ export declare type Assignee =
       role: string;
     };
 
+export { AtomInsight };
+
+export { AtomRequirement };
+
 /**
  * Persisted document and effect-queue `_type` discriminators.
  */
@@ -353,7 +497,8 @@ export declare type AuthoringActivity = ActivityFields<
   AuthoringFieldEntry,
   AuthoringAction,
   AuthoringOp,
-  AuthoringManualTarget
+  AuthoringManualTarget,
+  GroupMembership
 >;
 
 export declare type AuthoringEditable = v.InferOutput<
@@ -578,8 +723,8 @@ declare const AuthoringGuardSchema: v.StrictObjectSchema<
       undefined
     >;
     /**
-     * Lake GROQ predicate — a distinct eval context reading
-     * `document.before`/`document.after`, `mutation`, `guard`, and
+     * Lake GROQ predicate — a distinct eval context: delta-mode GROQ
+     * reading the `before()`/`after()` natives, `mutation`, `guard`, and
      * `identity()`. Bare ids/fields only. Omitted or empty means
      * UNCONDITIONAL DENY.
      */
@@ -989,12 +1134,15 @@ declare const AuthoringOpSchema: v.VariantSchema<
  *     field the transition filter reads — `failed` is for work that
  *     genuinely could not complete.
  */
-declare type AuthoringRawAction = ActionFields<AuthoringOp> & {
+declare type AuthoringRawAction = ActionFields<AuthoringOp, GroupMembership> & {
   roles?: string[] | undefined;
   status?: TerminalActivityStatus | undefined;
 };
 
-declare type AuthoringRawFieldEntry = FieldEntryFields<AuthoringEditable>;
+declare type AuthoringRawFieldEntry = FieldEntryFields<
+  AuthoringEditable,
+  GroupMembership
+>;
 
 export declare type AuthoringStage = StageFields<
   AuthoringFieldEntry,
@@ -1259,6 +1407,17 @@ export declare function buildSnapshot(args: {
   docs: LoadedDoc[];
 }): HydratedSnapshot;
 
+/**
+ * A LOADED candidate document. Applicability evaluates content, so a ref or
+ * bare id is not enough: the doc must carry its schema `_type` plus whatever
+ * attributes `applicableWhen` predicates read — under whatever perspective
+ * the caller loaded it with.
+ */
+export declare interface CandidateDocument {
+  _type: string;
+  [key: string]: unknown;
+}
+
 /**
  * Thrown when auto-transitions on an instance fail to stabilise within
  * {@link CascadeLimitError.limit} passes — the signature of a runaway
@@ -1276,6 +1435,9 @@ export declare class CascadeLimitError extends WorkflowError<"cascade-limit"> {
   constructor(args: { instanceId: string; limit: number });
 }
 
+/** Flatten a description to indented English lines (✓ / ✗ / ? per outcome). */
+export declare const checklistLines: typeof checklistLines_2;
+
 export declare interface ChildrenArgs extends InstanceRefArgs {
   /** Restrict to children spawned by this activity on the parent. */
   activity?: string;
@@ -1294,6 +1456,7 @@ declare type ClaimAction = {
   name: string;
   title?: string | undefined;
   description?: string | undefined;
+  group?: GroupMembership | undefined;
   field: string | AuthoringFieldRef;
   roles?: string[] | undefined;
   filter?: string | undefined;
@@ -1312,8 +1475,34 @@ declare type ClaimField = {
   name: string;
   title?: string | undefined;
   description?: string | undefined;
+  group?: GroupMembership | undefined;
 };
 
+/**
+ * The `@sanity/client`-config fragment that addresses a {@link WorkflowResource}
+ * — the one home for the dataset-vs-resource branch every client-building host
+ * (CLI, MCP) would otherwise reimplement. A dataset addresses via the classic
+ * `{projectId, dataset}` config (the proven path, and it keeps
+ * `client.listen()` on well-trodden ground); the other resource types have no
+ * projectId/dataset split, so they pass through as a `resource` directly.
+ *
+ * Returns a plain fragment (not a client) so the engine stays free of a
+ * runtime `@sanity/client` dependency — callers spread it into their own
+ * `createClient` call alongside their auth/host params.
+ */
+export declare function clientConfigFromResource(res: WorkflowResource):
+  | {
+      projectId: string;
+      dataset: string;
+    }
+  | {
+      resource: WorkflowResource;
+    };
+
+/** The router {@link buildClientForGdr} builds — total: every parsed GDR
+ *  resolves to a client, or the router throws. */
+declare type ClientForGdr = (parsed: ParsedGdr) => WorkflowClient;
+
 /**
  * The engine's single source of "now".
  *
@@ -1331,10 +1520,9 @@ declare type ClaimField = {
  * accept it only through the internal {@link Clocked} seam, so prod code
  * can't trivially override engine time by accident.
  *
- * Out of scope: `drainEffects` (the external runtime worker claiming and
- * executing effects) still stamps `claimedAt` from wall-clock — it is not
- * a verb and the bench never drives it. Thread a clock there too if the
- * simulator ever needs deterministic drain timing.
+ * `drainEffects` and `sweepStaleClaims` read the same engine clock for
+ * their claim / lease-expiry stamps, so lease timing is deterministic
+ * under a pinned clock too.
  */
 export declare type Clock = () => string;
 
@@ -1351,6 +1539,8 @@ declare type Clocked<T> = T & {
   clock?: Clock;
 };
 
+export { ComparisonOp };
+
 /**
  * A compiled lake read — what the engine's query builders return and what a
  * reactive adapter's live-query store subscribes with, so the stateless and
@@ -1358,26 +1548,40 @@ declare type Clocked<T> = T & {
  */
 export declare interface CompiledQuery {
   query: string;
-  params: Record<string, string>;
+  params: Record<string, string | string[]>;
 }
 
-/** Assemble a persisted guard doc from resolved pieces. */
+/** 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). */
 export declare function compileGuard(args: CompileGuardArgs): MutationGuardDoc;
 
 declare interface CompileGuardArgs extends MutationGuardBody {
   id: string;
 }
 
-export declare interface CompleteEffectArgs extends OperationArgs {
+/**
+ * Completion is FIRST-WRITER-WINS: reporting on an entry that already
+ * settled throws `EffectNotFoundError`, whose `settled` field says how it
+ * settled — another party's completion (a lease takeover, a manual
+ * recovery), or an abort cancelling the entry before dispatch. A completer
+ * on a retrying transport (webhook redelivery, queue, cron) should pass
+ * {@link DedupableOperationArgs.idempotencyKey} — its own lost-response
+ * retries then replay as `changed: false` instead of throwing.
+ */
+export declare interface CompleteEffectArgs extends DedupableOperationArgs {
   /** The `_key` of the pending effect being reported on. */
   effectKey: string;
-  status: "done" | "failed";
+  status: EffectCompletionStatus;
   /**
    * Named values produced by the effect. If supplied, these are merged
    * into `effectsContext` (replace-by-key) and become available to
-   * downstream effect bindings on the same instance.
+   * downstream effect bindings on the same instance. Each value may be any
+   * JSON — scalar, {@link GlobalDocumentReference}, or an arbitrary
+   * object/array (the whole record stores as one `effectsContext.json` entry).
    */
-  outputs?: Record<string, string | number | boolean | GlobalDocumentReference>;
+  outputs?: EffectsContext;
   /**
    * The state half of the effect: `field.*` ops to apply in the completion
    * commit, computed from the effect's real result (e.g. a `field.set` of a
@@ -1400,13 +1604,15 @@ export declare interface CompleteEffectArgs extends OperationArgs {
 }
 
 /** Compare each definition against the latest deployed version of its name. */
-export declare function computeDiffEntries({
+export declare function computeDiffEntries<
+  T extends WorkflowDefinitionInput<T>,
+>({
   client,
   defs,
   target,
 }: {
   client: Pick<WorkflowClient, "fetch">;
-  defs: WorkflowDefinition[];
+  defs: T[];
   target: DeployTarget;
 }): Promise<DiffEntry[]>;
 
@@ -1475,11 +1681,43 @@ export declare type Condition = string;
  */
 export declare const CONDITION_VARS: readonly ConditionVar[];
 
+export { ConditionAnalysis };
+
+export { ConditionAtom };
+
+export { ConditionClause };
+
+export { ConditionDescription };
+
+export { ConditionInsight };
+
+export { ConditionOutcome };
+
+export { ConditionRead };
+
+/**
+ * Every condition a definition declares, in stable order: author predicates,
+ * then per stage — transitions, activities (filter, requirements,
+ * completeWhen, failWhen, action filters), editable gates, tighten-overrides.
+ * Editable gates resolve through the same helper the runtime projection uses
+ * ({@link editableFieldsInStage}: entry `editable` ANDed with the stage
+ * tighten-override), so every live editable-field address exists here with
+ * the same EFFECTIVE predicate the edit insight explains — including
+ * override-only gates on `editable: true` entries, and workflow-scope fields
+ * once per stage (the effective predicate is per-stage).
+ */
+export declare function conditionSitesOf(
+  definition: WorkflowDefinition,
+): DefinitionConditionSite[];
+
 export declare interface ConditionVar {
   /** The GROQ param name, read as `$<name>`. */
   name: string;
   binding: ConditionVarBinding;
   description: string;
+  /** Short human phrase for rendered explanations ("all activities in this
+   *  stage are finished") — consumer-facing, unlike `description`. */
+  label: string;
 }
 
 /**
@@ -1497,9 +1735,13 @@ export declare interface ConditionVar {
  *    fixed and deploy-enforced (see the op-where scope's param-name list in
  *    the op applier).
  * 2. **Filter evaluation without a caller** — the engine's cascade evaluates
- *    transition filters and `completeWhen`/`failWhen` with no caller, so only
- *    the `'always'`-bound subset carries values there ({@link FILTER_SCOPE_VARS}).
- *    Caller-bound vars evaluate to `undefined` and fail closed.
+ *    transition filters and the activity gates (`filter`, `completeWhen`,
+ *    `failWhen`) with no caller, 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: routing and gate
+ *    resolution must resolve identically no matter whose token triggers the
+ *    evaluation.
  * 3. **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
@@ -1514,7 +1756,7 @@ export declare interface ConditionVar {
  * - `'caller'` — rides the acting caller; without one the var is `undefined`
  *   (conditions referencing it fail closed). Author predicates may not read
  *   these — they pre-evaluate once per instance, caller-free.
- * - `'spawn'` — bound only at `subworkflows` sites.
+ * - `'spawn'` — bound only at `subworkflows` sites (the per-row `$row`).
  */
 export declare type ConditionVarBinding = "always" | "caller" | "spawn";
 
@@ -1590,6 +1832,15 @@ export declare interface CreateEngineArgs extends EngineScopeArgs {
   effectHandlers?: Record<string, EffectHandler>;
   missingHandler?: MissingHandlerPolicy;
   loggerFactory?: LoggerFactory;
+  /**
+   * Lease duration `drainEffects` stamps on each pending-effect claim.
+   * Past the lease the claimer is presumed dead: the entry becomes
+   * recoverable by another drain's takeover or by
+   * the standalone `sweepStaleClaims` export. Default 5 minutes — size it well above
+   * the slowest handler's honest runtime, since a live-but-slow dispatch
+   * that outlives its lease can be redispatched (see {@link EffectHandler}).
+   */
+  effectLeaseMs?: number;
   /**
    * Deterministic-time seam, pinned once for this engine and threaded
    * into every verb it drives — `$now`, the `now` op-source, and the
@@ -1600,8 +1851,61 @@ export declare interface CreateEngineArgs extends EngineScopeArgs {
    * option.
    */
   clock?: Clock;
+  /**
+   * Product-telemetry seam, pinned once for this engine and threaded into
+   * every verb it drives. The core engine ships no metrics pipeline — it
+   * cannot know the environment's output rules (consent, transport, data
+   * governance), so it only DEFINES events (exported from the package
+   * root) and logs them through this logger; the app shell that does know
+   * those rules owns store creation, consent resolution, and transport.
+   * Omit (the default) to emit nothing. Any `@sanity/telemetry`
+   * `TelemetryLogger` satisfies this seam — the engine mirrors the shape
+   * rather than depending on the package. Same rule as the clock:
+   * engine-construction config, never a per-verb option.
+   */
+  telemetry?: WorkflowTelemetryLogger;
 }
 
+/**
+ * Build the consent/transport pair a shell's batched store runs on.
+ * Consent is the account-level status from the authenticated client —
+ * anything but `granted` (including a fetch error) means the store sends
+ * nothing. `denied` short-circuits without a request: process shells
+ * resolve their environment denial (see {@link isTelemetryEnvDenied})
+ * once and pass it here; browser shells omit it.
+ */
+export declare function createTelemetryIntake(args: {
+  client: TelemetryIntakeClient;
+  projectId: string;
+  denied?: boolean;
+}): TelemetryIntake;
+
+/**
+ * The reader floor the current model imposes — the compatibility half of
+ * {@link MODEL_STAMP}, stamped as `minReaderModel`: the oldest engine model
+ * that can safely interpret a document written at {@link DATA_MODEL_VERSION}.
+ * An additive change leaves it untouched (older engines read newer docs
+ * fine — mixed fleets of Functions, Studios, and CLIs are the steady state);
+ * ONLY a breaking shape change raises it, and doing so is a declared,
+ * DATAMODEL.md-logged decision to fence out older readers.
+ */
+export declare const DATA_MODEL_MIN_READER = 0;
+
+/**
+ * The engine's persisted data-model version — the provenance half of
+ * {@link MODEL_STAMP}, stamped as `modelVersion` on every engine-owned
+ * document at its construction and persist choke-points. Conforms-to
+ * semantics: the stamp means "this document conforms to model N now" —
+ * instances are re-stamped on every full persist, so mixed-version fleets
+ * 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.
+ */
+export declare const DATA_MODEL_VERSION = 1;
+
 /**
  * Split a dataset resource id (`<projectId>.<dataset>`) into its parts — the
  * one parser for the format, shared by {@link gdrFromResource} and the React
@@ -1613,6 +1917,39 @@ export declare function datasetResourceParts(id: string): {
   dataset: string;
 };
 
+/** The declarable half of {@link ExecutionContext} — what `createEngine` accepts. */
+export declare type DeclaredExecutionContext = Pick<
+  ExecutionContext,
+  "kind" | "id"
+>;
+
+/**
+ * The {@link OperationArgs} of the verbs that own a discrete commit —
+ * `fireAction`, `editField`, `completeEffect`, `setStage`, `abortInstance`.
+ * `tick` deliberately takes the plain base: it owns no commit of its own and
+ * re-derives everything, so retrying it blind is already safe.
+ */
+export declare interface DedupableOperationArgs extends OperationArgs {
+  /**
+   * Caller-supplied key that makes this call safe to retry blind (a network
+   * failure ate the response; a queue redelivered the message). The first
+   * commit records the key on the instance's `processedRequests[]` ledger —
+   * in the same CAS write as the operation itself — and a retry carrying the
+   * same key replays instead of double-applying (or, for a completed effect,
+   * throwing `EffectNotFoundError`): the operation is NOT re-applied, but
+   * the cascade runs to convergence (the original may have died before its
+   * own cascade), so `changed` is `false` unless that cascade repaired
+   * something. Keys live for the engine's `idempotencyTtlMs` (default 24h);
+   * reusing a live key on a different verb throws. The caller owns key
+   * uniqueness per logical request.
+   *
+   * Only a commit records the key: a keyed call that no-ops (a `setStage`
+   * already at its target, an abort of a terminal instance) leaves no ledger
+   * row, so retrying it later re-evaluates fresh rather than replaying.
+   */
+  idempotencyKey?: string;
+}
+
 /**
  * The perspective a content read falls back to when the instance has no
  * explicit release perspective: `drafts` overlay published (Sanity
@@ -1623,6 +1960,14 @@ export declare function datasetResourceParts(id: string): {
  */
 export declare const DEFAULT_CONTENT_PERSPECTIVE = "drafts";
 
+/** How long a fresh claim's lease runs unless the engine configured
+ *  `effectLeaseMs`. */
+export declare const DEFAULT_EFFECT_LEASE_MS: number;
+
+/** How long a recorded idempotency key dedupes retries, unless the caller
+ *  configured `idempotencyTtlMs`. */
+export declare const DEFAULT_IDEMPOTENCY_TTL_MS: number;
+
 /**
  * Default LoggerFactory — writes through the global `console`. Exposed
  * so callers outside `createEngine` (drive scripts, the
@@ -1632,9 +1977,36 @@ export declare const DEFAULT_CONTENT_PERSPECTIVE = "drafts";
  */
 export declare const defaultLoggerFactory: LoggerFactory;
 
+export declare interface DefinitionConditionSite {
+  /** The stage the condition applies in; absent only for author predicates. */
+  stage?: string;
+  address: DefinitionSiteAddress;
+  condition: Condition;
+}
+
+/** Derive the deploy event payload from a definition's structure. */
+export declare function definitionDeployedData(
+  definition: WorkflowDefinition,
+  outcome: {
+    contentHash: string;
+    status: WorkflowDefinitionDeployedData["status"];
+    deployId: string;
+  },
+): WorkflowDefinitionDeployedData;
+
+/** One declared group at one level, with the members lexically attributed to it. */
+export declare interface DefinitionGroupSite {
+  group: Group;
+  /** The declaration level; `stage`/`activity` name the declaring node. */
+  level: FieldScope;
+  stage?: string;
+  activity?: string;
+  members: GroupMember[];
+}
+
 declare interface DefinitionGuardsQueryArgs {
   client: WorkflowClient;
-  clientForGdr: (parsed: ParsedGdr) => WorkflowClient;
+  clientForGdr: ClientForGdr;
   workflowResource: WorkflowResource;
   definition: string;
   /** Every deployed version of {@link DefinitionGuardsQueryArgs.definition}. */
@@ -1669,6 +2041,24 @@ export declare class DefinitionInUseError extends WorkflowError<"definition-in-u
   constructor(args: { definition: string; blockedBy: DefinitionInUseBlocker });
 }
 
+/**
+ * Pure GROQ builder for resolving a deployed workflow definition. 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.
+ */
+/**
+ * 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.
+ */
+export declare function definitionLookupGroq(explicit: boolean): string;
+
 /** No deployed workflow definition matches the requested name (and version,
  *  when given) under this engine's tag. */
 export declare class DefinitionNotFoundError extends WorkflowError<"definition-not-found"> {
@@ -1677,6 +2067,44 @@ export declare class DefinitionNotFoundError extends WorkflowError<"definition-n
   constructor(args: { definition: string; version?: number });
 }
 
+export declare interface DefinitionsForDocumentArgs {
+  /**
+   * The LOADED candidate document — unlike {@link InstancesForDocumentArgs},
+   * a ref won't do: applicability evaluates content (`_type` against subject
+   * entry `types`, `applicableWhen` against the attributes), under whatever
+   * perspective the caller loaded the document with.
+   */
+  document: CandidateDocument;
+}
+
+/** A definition-level site address: every runtime {@link InsightSite}, plus
+ *  the two shapes that only exist at the definition level — author
+ *  predicates, and stage `editable` tighten-overrides (runtime folds an
+ *  override into the field's effective predicate; statically it is also its
+ *  own authored gate). */
+export declare type DefinitionSiteAddress =
+  | InsightSite
+  | {
+      kind: "predicate";
+      predicate: string;
+    }
+  | {
+      kind: "editable-override";
+      name: string;
+    };
+
+/**
+ * GROQ listing EVERY deployed {@link WORKFLOW_DEFINITION_TYPE} visible to the
+ * caller's tag, grouped by name. `versionOrder` picks the in-group direction:
+ * `'desc'` puts each name's latest first (discovery keeps the head per name),
+ * `'asc'` walks history oldest-first (handler verification reads them all).
+ *
+ * Params: `$tag`.
+ */
+export declare function definitionsListGroq(
+  versionOrder: "asc" | "desc",
+): string;
+
 export declare interface DeleteDefinitionArgs {
   /** The definition's `name` — delete addresses the workflow, not a doc id. */
   definition: string;
@@ -1691,8 +2119,6 @@ export declare interface DeleteDefinitionArgs {
   cascade?: boolean;
   /** Free-text reason stamped on each cascade-abort history entry. */
   reason?: string;
-  /** Optional access-state override — see `StartInstanceArgs.access`. */
-  access?: WorkflowAccessOverride;
   /** URL path for grant resolution — see `StartInstanceArgs.grantsFromPath`. */
   grantsFromPath?: string;
 }
@@ -1733,6 +2159,15 @@ export declare interface DeniedGuardRef {
   name?: string;
 }
 
+/**
+ * The one mapping from {@link MutationGuardDoc} to the structured
+ * {@link DeniedGuardRef} payload — shared by the thrown error and the
+ * read-side `mutation-guard-denied` verdict, so the two can't drift.
+ */
+export declare function deniedGuardRefs(
+  guards: readonly MutationGuardDoc[],
+): DeniedGuardRef[];
+
 /**
  * Run every guard whose `match` applies and collect those that DENY. Empty
  * result ⇒ allowed (optimistically).
@@ -1752,9 +2187,18 @@ export declare interface DeployDefinitionResult {
   /** The deploy-assigned version this deploy created or matched. */
   version: number;
   status: "created" | "unchanged";
+  /**
+   * Advisory producer/consumer warnings from the effect-output lint — a
+   * `$effects['<name>'].<key>` read of a key a declared effect does not produce.
+   * Non-blocking: deploy still succeeds. Absent when the definition is clean.
+   * See {@link lintEffectOutputs}.
+   */
+  warnings?: string[];
 }
 
-export declare interface DeployDefinitionsArgs {
+export declare interface DeployDefinitionsArgs<
+  T extends WorkflowDefinitionInput<T> = WorkflowDefinition,
+> {
   /**
    * Resource-alias bindings for this deploy (alias name → physical resource).
    * Every `@<alias>:` reference in a definition is expanded to its bound
@@ -1764,12 +2208,21 @@ export declare interface DeployDefinitionsArgs {
    * reference no aliases).
    */
   resourceAliases?: ResourceAliases;
-  definitions: WorkflowDefinition[];
+  /** Authored definitions (the default — full compile-time checking) or
+   *  loosely-typed fetched definition documents — the boundary parse
+   *  normalizes either ({@link WorkflowDefinitionInput}). */
+  definitions: T[];
 }
 
 export declare interface DeployDefinitionsResult {
   /** Per-definition outcome, ordered by the resolved deploy order (children first). */
   results: DeployDefinitionResult[];
+  /**
+   * Random id grouping this call's per-definition deploy telemetry events.
+   * Returned so a caller reporting on the same deploy (e.g. definition
+   * sharing) can carry the id the events already minted.
+   */
+  deployId: string;
 }
 
 /** A definition as fetched back from the lake. The document carries `_id` plus
@@ -1784,6 +2237,12 @@ export declare type DeployedDefinition = WorkflowDefinition & {
   /** Optional: a document deployed before content-addressing has none — see
    *  {@link LatestDeployed}. Every version this engine deploys carries one. */
   contentHash?: string;
+  /** 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. */
+  minReaderModel?: number;
 };
 
 /**
@@ -1823,6 +2282,106 @@ export declare interface DeployTarget {
  */
 export declare function deriveActivityKind(activity: Activity): ActivityKind;
 
+export declare type Describable =
+  | ConditionInsight
+  | FieldInsight
+  | TransitionEvaluation
+  | ActionEvaluation
+  | ActivityEvaluation
+  | EditableFieldEvaluation;
+
+/** One atom as a phrase in the workflow vocabulary. */
+export declare function describeAtom(
+  atom: AtomInsight,
+  ctx: DescribeContext,
+): {
+  phrase: InsightPhrase;
+  fallback: boolean;
+};
+
+/** Render one condition's insight as a checklist + frontier summary, in the
+ *  workflow vocabulary. */
+export declare function describeCondition(
+  insight: ConditionInsight,
+  ctx: DescribeContext,
+): ConditionDescription;
+
+/** The engine's rendering context: everything phrases resolve titles and
+ *  vocabulary from is on the definition. */
+export declare interface DescribeContext {
+  definition: WorkflowDefinition;
+}
+
+/** The return shape {@link describeNode} owes each input — conditional on the node. */
+export declare type Described<T extends Describable> = T extends FieldInsight
+  ? FieldDescription
+  : T extends ActivityEvaluation
+    ? ActivityDescription
+    : T extends ConditionInsight | TransitionEvaluation
+      ? ConditionDescription
+      : ConditionDescription | undefined;
+
+export { DescribedClause };
+
+/** One described definition site: the address plus its phrased checklist. */
+export declare type DescribedDefinitionSite = DefinitionConditionSite & {
+  description: ConditionDescription;
+};
+
+/**
+ * Explain the whole workflow in human language, without an instance: every
+ * condition site phrased against an EMPTY scope, in the workflow vocabulary.
+ * Outcome marks are placeholders (no values to judge) — the checklists and
+ * summaries carry the "what this needs" story; live verdicts come from
+ * evaluation insight where a run's current stage overlaps these addresses.
+ */
+export declare function describeDefinition(
+  definition: WorkflowDefinition,
+): Promise<DescribedDefinitionSite[]>;
+
+/** A field's insight as phrases: involvement plus verified proposals. */
+export declare function describeFieldInsight(
+  field: FieldInsight,
+  ctx: DescribeContext,
+): FieldDescription;
+
+/**
+ * The one front door: feed it any insight-bearing node off an evaluation and
+ * get its description — a checklist for gate nodes (undefined when the node
+ * declares no gate), all four gates for an activity, involvement + proposals
+ * for a field. Dispatch is by each node's defining property, which is
+ * unambiguous across the union.
+ */
+export declare function describeNode<T extends Describable>(
+  node: T,
+  ctx: DescribeContext,
+): Described<T>;
+
+/** A site address as a noun phrase, using declared titles where present. */
+export declare function describeSite(
+  site: InsightSite,
+  ctx: DescribeContext,
+): InsightPhrase;
+
+/**
+ * A site address as a checklist lead-in that flows into the atom lines —
+ * "«Approval» completes automatically when:" over "✗ «Approved» must be
+ * true". The connective mood for tooltips/panels; {@link describeSite} is
+ * the noun-phrase mood for mid-sentence composition. Accepts the
+ * definition-level address superset so the static tier heads the same way.
+ */
+export declare function describeSiteHeading(
+  address: DefinitionSiteAddress,
+  ctx: DescribeContext,
+): InsightPhrase;
+
+/** The slice of a {@link TransitionEvaluation} the classifier reads — narrowed
+ *  so a hand-crafted stuck permutation doesn't have to fabricate insights. */
+export declare type DiagnosedTransition = Pick<
+  TransitionEvaluation,
+  "transition" | "filterSatisfied" | "unevaluable"
+>;
+
 /**
  * The slice of an instance + its {@link WorkflowEvaluation} the classifier
  * reads. Narrowed so callers (and tests) can craft an exact stuck permutation
@@ -1838,9 +2397,10 @@ export declare interface DiagnoseInput {
     | "effectHistory"
     | "pendingEffects"
     | "history"
+    | "subworkflows"
   >;
   activities: ActivityEvaluation[];
-  transitions: TransitionEvaluation[];
+  transitions: DiagnosedTransition[];
   assignees: Record<string, Assignee[]>;
 }
 
@@ -1888,11 +2448,13 @@ export declare type Diagnosis =
   | {
       state: "completed";
       at: string;
+      liveChildren?: number;
     }
   | {
       state: "aborted";
       at: string;
       reason?: string;
+      liveChildren?: number;
     }
   | {
       state: "stuck";
@@ -1918,14 +2480,19 @@ export declare interface DiffEntry {
  * 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.
- */
-export declare function diffEntry({
-  def,
+ * 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.
+ */
+export declare function diffEntry<T extends WorkflowDefinitionInput<T>>({
+  def: rawDef,
   latestRaw,
   target,
 }: {
-  def: WorkflowDefinition;
+  def: T;
   latestRaw: Record<string, unknown> | undefined;
   target: DeployTarget;
 }): DiffEntry;
@@ -1974,6 +2541,13 @@ export declare type DisabledReason =
       kind: "instance-completed";
       completedAt: string;
     }
+  | {
+      /** The instance was hard-stopped via `abortInstance`. Aborted instances
+       *  carry `completedAt` too, so this arm wins over `instance-completed`
+       *  (the {@link terminalState} precedence). */
+      kind: "instance-aborted";
+      abortedAt: string;
+    }
   | {
       /**
        * The activity's declared {@link Activity.requirements} aren't all satisfied —
@@ -1985,6 +2559,19 @@ export declare type DisabledReason =
        */
       kind: "requirements-unmet";
       unmetRequirements: string[];
+    }
+  | {
+      /**
+       * The actor's grants on an involved subject's resource don't allow the
+       * content write the action's effects would perform there. Forecast
+       * per-resource: each subject named by a `doc.ref`/`doc.refs`/`release.ref`
+       * field entry outside the workflow's own resource is checked against
+       * THAT resource's ACL. Advisory like every engine verdict — the subject's
+       * lake still enforces; and it degrades open: a resource whose grants
+       * can't be fetched is simply not forecast.
+       */
+      kind: "subject-permission-denied";
+      denied: SubjectPermissionDenial[];
     };
 
 /**
@@ -2029,20 +2616,69 @@ export declare function displayTitle(typeKey: string | undefined): string;
 
 declare const DOCUMENT_VALUE_PERMISSIONS: readonly ["create", "read", "update"];
 
+/**
+ * The guards that would deny a PROSPECTIVE lake action on a document — the
+ * disable-this-button pre-flight, evaluated before any concrete mutation
+ * exists. Advisory, like every guard verdict: the check explains and
+ * disables, it never enforces.
+ */
+export declare function documentActionDenials(
+  args: DocumentActionDenialsArgs,
+): Promise<MutationGuardDoc[]>;
+
+export declare interface DocumentActionDenialsArgs {
+  /** The document's current value — both `before` and `after` of the
+   *  pre-flighted action (a prospective check has no concrete mutation, so
+   *  delta predicates see "no change"). */
+  doc: {
+    _id: string;
+    _type: string;
+  } & Record<string, unknown>;
+  /** The datasource the document lives in. A guard applies solely within the
+   *  datasource it is registered in, so a same-id match from a foreign
+   *  datasource can never gate this action and must not flip verdicts. */
+  resource: {
+    type: string;
+    id: string;
+  };
+  action: MutationGuardAction;
+  guards: readonly MutationGuardDoc[];
+  /** Actor id, resolved as `identity()` in predicates. */
+  identity?: string;
+}
+
+/** Compile-time mirror of {@link isDocumentEnvelopeKey}: the keys the
+ *  boundary strips rather than rejects. */
+declare type DocumentEnvelopeKey =
+  | `_${string}`
+  | "tag"
+  | "version"
+  | "contentHash"
+  | "modelVersion"
+  | "minReaderModel";
+
 export declare type DocumentValuePermission =
   (typeof DOCUMENT_VALUE_PERMISSIONS)[number];
 
-export declare interface DrainEffectsArgs extends InstanceRefArgs {
-  /** Override the drainer's identity (e.g. impersonate a real user whose
-   *  grants the dispatch should respect). Defaults to a
-   *  `{ kind: "system", id: "engine.drainEffects" }` actor. */
-  access?: WorkflowAccessOverride;
-}
+/** Args for {@link Engine.drainEffects} — the drainer's identity is the
+ *  engine client's token, like every other verb. */
+export declare type DrainEffectsArgs = InstanceRefArgs;
 
 export declare interface DrainEffectsResult {
+  /** The drained instance's pinned definition fingerprint — carried so the
+   *  drain telemetry event can slice per definition. Absent only for
+   *  instances pinned before content fingerprinting. */
+  definitionContentHash?: string;
   drained: PendingEffect[];
   failed: PendingEffect[];
   skipped: PendingEffect[];
+  /**
+   * Entries this drainer dispatched whose completion lost to another party
+   * (a lease-expiry takeover finishing first, or a manual recovery). The
+   * handler's side effect ran here too — the at-least-once overlap the
+   * {@link EffectHandler} contract tells handlers to tolerate.
+   */
+  lost: PendingEffect[];
 }
 
 /**
@@ -2080,8 +2716,12 @@ 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}; a `system` actor is the
- * `engine` itself ({@link isEngineActor}) or otherwise an external `service`.
+ * 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),
@@ -2115,6 +2755,9 @@ export declare interface EditableFieldEvaluation {
   setBy?: Actor;
   /** When the field was last written (ISO); absent if never written. */
   setAt?: string;
+  /** Derived state of the who-may-edit predicate. Present iff the effective
+   *  editability is a predicate (not the unconditional `true`). */
+  insight?: ConditionInsight;
 }
 
 /**
@@ -2133,6 +2776,12 @@ export declare type EditDisabledReason =
       kind: "instance-completed";
       completedAt: string;
     }
+  | {
+      /** The instance was hard-stopped via `abortInstance` — wins over
+       *  `instance-completed` (aborted instances carry `completedAt` too). */
+      kind: "instance-aborted";
+      abortedAt: string;
+    }
   | {
       /** The field's scope window is closed: an activity-scope field whose activity isn't
        *  active, or otherwise out of its editable window. */
@@ -2147,11 +2796,12 @@ export declare type EditDisabledReason =
     }
   | MutationGuardDenial;
 
-export declare interface EditFieldArgs extends OperationArgs {
+export declare interface EditFieldArgs extends DedupableOperationArgs {
   /**
    * Which declared-editable field to write. Omit `scope` to resolve lexically
-   * (a `activity` implies activity scope; otherwise the nearest declaring scope, stage
-   * before workflow). `activity` is required to address an activity-scope field.
+   * — the nearest declaring scope wins (activity, then stage, then workflow);
+   * an explicit `activity` pins the match to that activity's field when the
+   * bare name is ambiguous.
    */
   target: EditFieldTarget;
   /**
@@ -2198,30 +2848,25 @@ export declare type EditFieldDeniedReason = Exclude<
 >;
 
 export declare interface EditFieldTarget {
-  /** Omit to resolve lexically (activity field if `activity` set, else stage then workflow). */
+  /** Omit to resolve lexically — the nearest declaring scope wins (activity, then stage, then workflow). */
   scope?: FieldScope;
   field: string;
-  /** Required to address an activity-scope field. */
+  /** Pins the match to that activity's field. A bare name already resolves activity-first; set this to disambiguate. */
   activity?: string;
 }
 
-/**
- * The generic edit seam. `editField` writes a declared-editable
- * field directly — reassign, reschedule, claim-by-hand, append to a log —
- * without a bespoke action per field. It is NOT a raw patch: the edit applies
- * as a `field.*` op through the shared op path (so it stamps `opApplied`
- * provenance + history), gates on the field's declared editability the same way
- * an action gates on its filter, then refreshes the stage's guards and lets the
- * caller cascade. Editing a value a transition reads can and should move the
- * instance — that rippling is intended.
- *
- * Gating is ONE mechanism (advisory, like every engine check): the field's
- * effective `editable` predicate over the rendered scope.
- */
 export declare type EditMode = "set" | "append" | "unset";
 
 export declare type Effect = v.InferOutput<typeof EffectSchema>;
 
+/** The outcomes a completer may report through `completeEffect` — a run
+ *  either succeeded or failed. `cancelled` is not reportable: only an abort
+ *  stamps it, on entries that never dispatched. */
+export declare type EffectCompletionStatus = Exclude<
+  EffectRunStatus,
+  "cancelled"
+>;
+
 /**
  * External effect handler — invoked at drain time with the resolved
  * `params` and a context. Returning `outputs` upserts them into
@@ -2233,6 +2878,22 @@ export declare type Effect = v.InferOutput<typeof EffectSchema>;
  * report results as field state, never by flipping an activity status, so `ops`
  * excludes `status.set`. Throwing marks the effect as failed (and returns no
  * `ops`).
+ *
+ * **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.
  */
 export declare type EffectHandler = (
   params: Record<string, unknown>,
@@ -2251,11 +2912,11 @@ export declare type EffectHandler = (
      *
      * 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 resolver's client for
-     * that resource, falling back to {@link client} when the engine has no
-     * `resourceClients` mapping for it. Throws if `ref` isn't a GDR — a
-     * bare id can't be routed, so failing loud beats silently patching the
-     * wrong dataset.
+     * {@link GlobalDocumentReference}. Returns the `resourceClients` client
+     * for that resource when one is mapped, {@link client} for the workflow
+     * resource itself, and a sibling derived from {@link client}'s
+     * credentials otherwise. Throws if `ref` isn't a GDR — a bare id can't
+     * be routed, so failing loud beats silently patching the wrong dataset.
      */
     clientFor: (ref: GdrUri | GlobalDocumentReference) => WorkflowClient;
     instanceId: string;
@@ -2263,7 +2924,7 @@ export declare type EffectHandler = (
     log: (message: string, extra?: Record<string, unknown>) => void;
   },
 ) => Promise<{
-  outputs?: Record<string, string | number | boolean | GlobalDocumentReference>;
+  outputs?: EffectsContext;
   ops?: FieldOp[];
 } | void>;
 
@@ -2286,7 +2947,7 @@ export declare interface EffectHistoryEntry {
   stageEntryKey?: string;
   ranAt: string;
   durationMs?: number;
-  status: "done" | "failed";
+  status: EffectRunStatus;
   detail?: string;
   error?: {
     message: string;
@@ -2303,15 +2964,25 @@ export declare interface EffectHistoryEntry {
 export declare type EffectName = string;
 
 /**
- * The effect key does not match any pending effect on the instance. Besides a
- * typo'd key, an at-least-once runtime hits this on a double delivery — the
- * first completion drained the effect — so a consumer can branch on this kind
- * to treat the second attempt as already-done rather than as a failure.
+ * The effect key does not match any pending effect on the instance. When the
+ * key matches an `effectHistory` row instead, `settled` carries that row's
+ * outcome so a consumer can branch on WHY the entry is gone: a double
+ * delivery on an at-least-once runtime (`done`/`failed` — the first
+ * completion drained it, treat the retry as already-done), or an abort that
+ * cancelled the entry before dispatch (`cancelled` — the reported work was
+ * discarded, not recorded). `settled` absent means the key never existed.
  */
 export declare class EffectNotFoundError extends WorkflowError<"effect-not-found"> {
   readonly instanceId: string;
   readonly effectKey: string;
-  constructor(args: { instanceId: string; effectKey: string });
+  /** The matching `effectHistory` outcome, when the effect settled rather
+   *  than never existed. */
+  readonly settled?: EffectSettledInfo;
+  constructor(args: {
+    instanceId: string;
+    effectKey: string;
+    settled?: EffectSettledInfo;
+  });
 }
 
 /**
@@ -2336,6 +3007,29 @@ export declare interface EffectOrigin {
 /** The lifecycle boundary that queued an effect — the node IS the moment. */
 export declare type EffectOriginKind = "activity" | "transition" | "action";
 
+/**
+ * Thrown when an effect completes with a returned output its declaration doesn't
+ * allow — an undeclared key or a value that doesn't fit the declared shape. The
+ * declared `outputs` are a strict allowlist bounding what an effect may persist
+ * into `effectsContext`, so the completion does NOT commit rather than silently
+ * storing off-contract data. An effect that declares no `outputs` has an EMPTY
+ * allowlist (produces nothing), so any returned output fails here.
+ */
+export declare class EffectOutputsInvalidError extends WorkflowError<"effect-outputs-invalid"> {
+  readonly effect: string;
+  readonly issues: string[];
+  constructor(args: { effect: string; issues: string[] });
+}
+
+/**
+ * Every terminal state an effect run can record. `done` and `failed` are
+ * reported through completion ({@link EffectCompletionStatus}); `cancelled`
+ * is engine-stamped only — an abort cancelling the entry before dispatch.
+ * A cancellation is not a failure: anything counting failures (dashboards,
+ * retry tooling) must not count aborted-away effects among them.
+ */
+export declare type EffectRunStatus = "done" | "failed" | "cancelled";
+
 /**
  * EffectsContext entry kinds.
  */
@@ -2394,10 +3088,42 @@ declare const EffectSchema: v.StrictObjectSchema<
       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: `effectsContext` lives on the instance document, 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
+    >;
   },
   undefined
 >;
 
+/**
+ * The named-params record effects bind against: what a caller supplies at
+ * `startInstance` (stored as {@link WorkflowInstance.effectsContext} entries)
+ * and what a handler's `outputs` merges back in (replace-by-key).
+ *
+ * Each value may be any JSON — a scalar, a {@link GlobalDocumentReference}, or
+ * an arbitrary object/array. Scalars and GDRs store as their typed
+ * `effectsContext` entries; anything else stores as one `effectsContext.json`
+ * entry, so all forms read back the same under `$effects.<name>`.
+ */
+export declare type EffectsContext = Record<string, unknown>;
+
 /**
  * Each entry is a named param the runtime hands to effect handlers via
  * binding resolution, rendered to conditions as `$effects.<name>`. **Set at
@@ -2452,6 +3178,15 @@ export declare function effectsContextMap(
   instance: Pick<WorkflowInstance, "effectsContext">,
 ): Record<string, unknown>;
 
+/** The `effectHistory` outcome {@link EffectNotFoundError} reports when the
+ *  missing key belongs to a settled run. `detail` is the row's recorded
+ *  detail — for a cancellation, the cause the canceller stamped. */
+export declare interface EffectSettledInfo {
+  status: EffectRunStatus;
+  ranAt: string;
+  detail?: string;
+}
+
 export declare interface Engine {
   /** Engine-scoped bindings — exposed for the few advanced consumers
    *  (e.g. test bench, drain workers) that need them; the verbs already
@@ -2462,8 +3197,11 @@ export declare interface Engine {
   readonly effectHandlers: Readonly<Record<string, EffectHandler>>;
   readonly missingHandler: MissingHandlerPolicy;
   readonly logger: LoggerFactory;
-  deployDefinitions: (
-    args: DeployDefinitionsArgs,
+  /** The resolved telemetry logger ({@link noopTelemetry} unless injected) —
+   *  exposed so adapters built on the engine log through the same seam. */
+  readonly telemetry: WorkflowTelemetryLogger;
+  deployDefinitions: <T extends WorkflowDefinitionInput<T>>(
+    args: DeployDefinitionsArgs<T>,
   ) => Promise<DeployDefinitionsResult>;
   startInstance: (args: StartInstanceArgs) => Promise<OperationResult>;
   fireAction: (args: FireActionArgs) => Promise<OperationResult>;
@@ -2533,6 +3271,14 @@ export declare interface Engine {
   instancesForDocument: (
     args: InstancesForDocumentArgs,
   ) => Promise<WorkflowInstance[]>;
+  /** The startable half of {@link Engine.instancesForDocument}: the latest
+   *  deployed version of every definition that applies to the LOADED candidate
+   *  document — startable, a required subject entry accepts its `_type`, and
+   *  `applicableWhen` passes. All matches, name ascending; advisory — a start
+   *  picker's filter, never enforcement. */
+  definitionsForDocument: (
+    args: DefinitionsForDocumentArgs,
+  ) => Promise<DeployedDefinition[]>;
   /** GROQ query against the engine's workflow resource. `$tag`
    *  is bound for tag-scoped filtering. */
   query: <T = unknown>(args: QueryArgs) => Promise<T>;
@@ -2547,10 +3293,13 @@ export declare interface Engine {
   findPendingEffects: (
     args: FindPendingEffectsArgs,
   ) => Promise<PendingEffect[]>;
-  /** Dispatch unclaimed effects through registered handlers. The
-   *  drainer's identity defaults to a `{ kind: "system", id: "engine.drainEffects" }`
-   *  actor; pass `access` to override (e.g. impersonate a real user
-   *  whose grants you want the dispatch to respect). */
+  /** Dispatch unclaimed effects through registered handlers — including
+   *  entries whose claim's lease expired, which are taken over (audit row)
+   *  and redispatched. The drainer's identity is the engine client's token —
+   *  a drain runtime supplies its own token-bearing client and declares
+   *  itself via `executionContext`. Release-without-dispatch housekeeping is
+   *  the standalone {@link sweepStaleClaims} export, deliberately off the
+   *  engine surface. */
   drainEffects: (args: DrainEffectsArgs) => Promise<DrainEffectsResult>;
   /**
    * Inspect every deployed definition in the engine's tag and apply
@@ -2566,8 +3315,15 @@ export declare interface Engine {
 }
 
 /**
- * The API surface the engine's reads and writes assume. Every client bound to
- * the engine pins this one version so they cannot drift apart.
+ * The API surface the engine's reads and writes assume. The engine owns this
+ * pin: every entry point — `createEngine`, each raw `workflow.*` verb, the
+ * housekeeping exports — derives its working client onto this version via
+ * {@link WorkflowClient.withConfig}, and `resourceClients`-resolved clients
+ * are rebound the same way. A caller's configured `apiVersion` therefore
+ * never reaches engine traffic (the caller's own client instance is
+ * untouched). The one exception is a client that lacks `withConfig` and so
+ * cannot be rebound — it must be built to serve this version; see
+ * {@link WorkflowClient.withConfig}.
  */
 export declare const ENGINE_API_VERSION = "2026-04-29";
 
@@ -2583,6 +3339,17 @@ export declare interface EngineLogger {
  * these — they were supplied at construction.
  */
 export declare interface EngineScopeArgs {
+  /**
+   * The engine resolves its acting identity from this client's token and
+   * caches the resolution per client object — the client's auth must be
+   * stable for the engine's lifetime. To act as someone else, construct
+   * an engine over a client bound to their token (`withConfig({token})`),
+   * never mutate this client's auth in place.
+   *
+   * Any configured `apiVersion` works: every verb derives its working
+   * client onto `ENGINE_API_VERSION`, on the raw namespace as much as
+   * through `createEngine` — see {@link WorkflowClient.withConfig}.
+   */
   client: WorkflowClient;
   /** Engine-scope environment partition — required. See {@link validateTag} + `tags.ts`. */
   tag: string;
@@ -2593,29 +3360,52 @@ export declare interface EngineScopeArgs {
    */
   workflowResource: WorkflowResource;
   /**
-   * Optional routing 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 fall back
-   * to `client`. Engine-scope configuration — see `CreateEngineArgs`.
+   * Optional 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 — `client` for the workflow resource itself, a
+   * sibling derived from `client`'s credentials for anything else. Engine-scope
+   * configuration — see `CreateEngineArgs`.
    */
   resourceClients?: ResourceClientResolver;
+  /**
+   * Declared execution context — the advisory "via what" stamped on every
+   * history entry alongside the token-resolved actor. Construction-scope
+   * configuration, never per-call: the runtime half is always inferred, and
+   * the declared `{kind, id}` half labels the host (see `EXECUTION_KINDS`).
+   * Omitted ⇒ runtime-only stamps.
+   */
+  executionContext?: DeclaredExecutionContext;
+  /**
+   * How long a recorded `idempotencyKey` dedupes retries (the
+   * `processedRequests[]` row's lifetime). Default 24 hours. Size it to the
+   * caller's longest retry horizon — a retry arriving after the row expired
+   * re-executes the operation.
+   */
+  idempotencyTtlMs?: number;
 }
 
+/**
+ * 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.
+ */
+export declare function errorMessage(err: unknown): string;
+
 export declare interface EvaluateArgs {
   instanceId: string;
-  /**
-   * Optional access-state override. By default the engine resolves
-   * `(actor, grants)` from the supplied client's token via
-   * `/users/me` (+ `grantsFromPath`). The bench supplies its
-   * `ALL_ACCESS` default here; admin tooling can use this for
-   * "view as another user" or "preview with restricted grants" flows.
-   */
-  access?: WorkflowAccessOverride;
   /**
    * URL path on the supplied client where the engine should fetch
-   * grants when `access.grants` isn't supplied. Without grants the
-   * rendered `$can` is undefined, so conditions referencing it fail
-   * closed — and the real Sanity write boundary still enforces.
+   * grants. The actor always token-resolves via `/users/me`; without
+   * a grants path the rendered `$can` is undefined, so conditions
+   * referencing it fail closed — and the real Sanity write boundary
+   * still enforces.
    *
    * Canvas resource example: `/canvases/<resourceId>/acl`.
    * Project/dataset example: `/projects/<id>/datasets/<dataset>/acl`.
@@ -2671,6 +3461,15 @@ export declare interface EvaluateFromSnapshotArgs {
    * commit time ({@link evaluateInstance} fetches them itself).
    */
   guards?: readonly MutationGuardDoc[];
+  /**
+   * The actor's ACL grants per FOREIGN subject resource, keyed by
+   * resource-shaped GDR (`<type>:<id>`) — feeds the subject-write forecast on
+   * effects-bearing actions ({@link SubjectPermissionDenial}). Omit, or omit a
+   * resource, to skip that resource's forecast (degrade open — the subject's
+   * lake still enforces). {@link evaluateInstance} resolves this through each
+   * resource's own client via {@link subjectResourceGrants}.
+   */
+  resourceGrants?: ReadonlyMap<string, Grant[]>;
 }
 
 /**
@@ -2683,6 +3482,56 @@ export declare function evaluateMutationGuard(args: {
   context: MutationContext;
 }): Promise<boolean>;
 
+/**
+ * Well-known {@link ExecutionContext.kind} values. The field is a free
+ * string — these are the shipped vocabulary, not a closed set.
+ */
+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";
+  readonly studio: "studio";
+  readonly sdkApp: "sdk-app";
+};
+
+/**
+ * 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. */
+export declare interface ExecutionContext {
+  /** Inferred JavaScript runtime: `browser` | `node` | `worker` | `edge` | `deno` | `bun` | `unknown`. */
+  runtime: string;
+  /** Declared role — free string; see {@link EXECUTION_KINDS} for the shipped vocabulary. */
+  kind?: string;
+  /** Declared instance label, e.g. `workflow-cli` or `publish-proxy`. */
+  id?: string;
+}
+
+export { explainCondition };
+
+export { ExplainConditionArgs };
+
 /**
  * Extract the bare document `_id` from a GDR URI — what
  * `*[_id == $docId]` in GROQ needs.
@@ -2702,7 +3551,11 @@ export declare function extractDocumentId(gdrUriString: string): string;
  */
 declare function fetchGrants(args: {
   client: {
-    request: <T>(opts: { url: string; signal?: AbortSignal }) => Promise<T>;
+    request: <T>(opts: {
+      url: string;
+      signal?: AbortSignal;
+      tag?: string;
+    }) => Promise<T>;
   };
   resourcePath: string;
   signal?: AbortSignal;
@@ -2782,6 +3635,9 @@ declare const FIELD_SCOPES: readonly ["workflow", "stage", "activity"];
  * 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.
+ *
+ * Exported (module-level, not package API) for the model-surface gate's
+ * enum-value coverage test.
  */
 declare const FIELD_VALUE_KINDS: readonly [
   "doc.ref",
@@ -2801,30 +3657,75 @@ declare const FIELD_VALUE_KINDS: readonly [
   "array",
 ];
 
-/** Type-mirror of {@link fieldBase}, parameterised over the `editable` grammar. */
-declare type FieldBase<TEditable> = {
+/** Type-mirror of {@link fieldBase}, parameterised over the `editable` and
+ *  `group` grammars (stored membership is the canonical list form). */
+declare type FieldBase<TEditable, TGroup> = {
   name: string;
   title?: string | undefined;
   description?: string | undefined;
+  group?: TGroup | undefined;
   required?: boolean | undefined;
   initialValue?: FieldSource | undefined;
   editable?: TEditable | undefined;
 };
 
-export declare type FieldEntry = FieldEntryFields<Editable>;
+export declare interface FieldDescription {
+  /** The field's footprint — present even when nothing is proposable. */
+  involvement: InsightPhrase;
+  /** One phrase per verified proposal. */
+  proposals: InsightPhrase[];
+}
+
+export declare type FieldEntry = FieldEntryFields<Editable, string[]>;
 
 /** Type-mirror of {@link fieldEntryFields}: a raw field entry of the given
- *  editability grammar. */
-declare type FieldEntryFields<TEditable> = FieldBase<TEditable> & {
+ *  editability and group-membership grammars. */
+declare type FieldEntryFields<TEditable, TGroup> = FieldBase<
+  TEditable,
+  TGroup
+> & {
   type: FieldValueKind;
+  types?: string[] | undefined;
   fields?: FieldShape[] | undefined;
   of?: FieldShape[] | undefined;
 };
 
+/**
+ * Everything the evaluation derived about one `$fields` entry. `involvedIn`
+ * is the field's full footprint — every gate whose condition reads it —
+ * independent of whether any single value flips anything. Scope caveat: the
+ * name is the RENDERED scope name; a stage-/activity-scope declaration
+ * shadows a workflow-scope one lexically, so the same name in two sites'
+ * scopes can denote two declarations.
+ */
+export declare interface FieldInsight {
+  /** The field entry name — the head segment of every read below. */
+  field: string;
+  /** The distinct `$fields` reads naming this field across all sites. */
+  reads: ConditionRead[];
+  /** Every site whose condition reads this field. */
+  involvedIn: InsightSite[];
+  /** Verified single-value proposals harvested from blocking atoms; empty
+   *  when nothing solvable blocks on this field. */
+  proposals: FieldProposal[];
+}
+
 export declare type FieldKind = keyof FieldValueMap;
 
 export declare type FieldOp = v.InferOutput<typeof StoredFieldOpSchema>;
 
+/**
+ * A concrete value a blocking atom pins for this field, with the verified
+ * consequences of assigning it — "setting `legalApproved` to `true` flips
+ * transition `to-publish` to satisfied". Verified by re-evaluating every
+ * site that reads the field, so a listed consequence is what the engine
+ * would actually conclude, not a syntactic guess.
+ */
+export declare interface FieldProposal {
+  assign: ScopeAssignment;
+  consequences: SiteConsequence[];
+}
+
 declare type FieldReadExpr = {
   type: "fieldRead";
   scope?: "workflow" | "stage" | undefined;
@@ -2856,6 +3757,15 @@ declare type FieldSourceInternal =
   | LiteralExpr
   | FieldReadExpr;
 
+/**
+ * The field tree of a persisted value — every leaf replaced by its type name
+ * (`null` kept distinct from `object`), object keys sorted, 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.
+ */
+export declare function fieldTreeShape(value: unknown): unknown;
+
 /** The union a value (or nested {@link FieldShape}) kind may take — see {@link FIELD_VALUE_KINDS}. */
 declare type FieldValueKind = (typeof FIELD_VALUE_KINDS)[number];
 
@@ -2897,20 +3807,54 @@ export declare class FieldValueShapeError extends WorkflowError<"field-value-sha
 
 /**
  * The subset that holds a value when the engine evaluates filters without a
- * caller (the cascade path: transition filters, `completeWhen`/`failWhen`).
+ * caller (the cascade path: transition filters, activity `filter`/
+ * `completeWhen`/`failWhen`).
  */
 export declare const FILTER_SCOPE_VARS: readonly string[];
 
-export declare interface FindPendingEffectsArgs extends InstanceRefArgs {
-  /** Filter on claim presence. */
-  claimed?: boolean;
-  /** Restrict to specific effect names. */
-  names?: string[];
-}
+/**
+ * The current stage's {@link ActivityEntry} named `activityName`, or
+ * `undefined` when the open stage holds no such activity (including when
+ * `activityName` is itself `undefined`). Composes {@link findOpenStageEntry}
+ * with the by-name lookup that activity ops, editability, params, and the
+ * operation pre-flights all need — callers keep their own `.status` / `.fields`
+ * chain off the result.
+ */
+export declare function findCurrentActivityEntry(
+  host: {
+    stages: StageEntry[];
+    currentStage: StageName;
+  },
+  activityName: ActivityName | undefined,
+): ActivityEntry | undefined;
 
-export declare interface FireActionArgs extends OperationArgs {
-  activity: string;
-  action: string;
+/**
+ * The open (un-exited) {@link StageEntry} matching `currentStage`, or
+ * `undefined`. On loop-backs (re-entering a stage) several entries share
+ * a name — the prior ones have `exitedAt` set, the current one does not.
+ * Reads the `stages` + `currentStage` shape shared by the persisted
+ * `WorkflowInstance` and the engine's mutable copy.
+ */
+export declare function findOpenStageEntry(host: {
+  stages: StageEntry[];
+  currentStage: StageName;
+}): StageEntry | undefined;
+
+export declare interface FindPendingEffectsArgs extends InstanceRefArgs {
+  /**
+   * Filter on claim PRESENCE — not protection. An entry whose claim's lease
+   * expired still reports `claimed: true` here, yet a drain may take it
+   * over; mirror the drainable set with {@link isClaimExpired} over the
+   * returned entries' claims.
+   */
+  claimed?: boolean;
+  /** Restrict to specific effect names. */
+  names?: string[];
+}
+
+export declare interface FireActionArgs extends DedupableOperationArgs {
+  activity: string;
+  action: string;
   /**
    * Caller-supplied params for the action. Validated against
    * `Action.params[]` before commit; missing/required mismatch throws
@@ -2921,13 +3865,18 @@ export declare interface FireActionArgs extends OperationArgs {
   /**
    * If true, no-op (instead of throwing) when the activity is missing from
    * the current stage's `activityStatus` — typically because the workflow
-   * has already advanced past it. Useful for drive scripts and
-   * at-least-once delivery semantics: the second call returns the
-   * unchanged instance with `changed: false` rather than blowing up.
+   * has already advanced past it. Distinct from `idempotencyKey`: this flag
+   * tolerates a *state* the fire no longer applies to (however it got
+   * there, including someone else's action), while the key dedupes a retry
+   * of *this specific request*. A drive script tolerating advanced
+   * workflows wants the flag; a queue consumer redelivering a message
+   * wants the key.
    */
   idempotent?: boolean;
 }
 
+export { formatRead };
+
 /**
  * Build a GDR URI from a workflow resource config + a document id
  * within that resource. This is how the engine mints `_id`s for
@@ -2939,15 +3888,15 @@ export declare function gdrFromResource(
 ): GdrUri;
 
 /** Build a GDR (id + type) pointing at a document within a workflow resource. */
-export declare function gdrRef({
+export declare function gdrRef<TType extends string = string>({
   res,
   documentId,
   type,
 }: {
   res: WorkflowResource;
   documentId: string;
-  type: string;
-}): GlobalDocumentReference;
+  type: TType;
+}): GlobalDocumentReference<TType>;
 
 /**
  * Global Document References (GDR).
@@ -3001,11 +3950,18 @@ export declare function gdrUri(
       },
 ): GdrUri;
 
-export declare interface GlobalDocumentReference {
+/**
+ * `TType` preserves the `type` literal the constructors ({@link refDataset},
+ * {@link gdrRef}, …) were called with, so a constructed ref satisfies
+ * literal-typed targets (e.g. a `release.ref` value's `"system.release"`).
+ */
+export declare interface GlobalDocumentReference<
+  TType extends string = string,
+> {
   /** URI: `<scheme>:<...id-parts>` */
   id: GdrUri;
   /** Document `_type` (schema name) */
-  type: string;
+  type: TType;
 }
 
 export declare interface Grant {
@@ -3029,6 +3985,84 @@ declare function grantsPermissionOn(args: {
   userId?: string;
 }): Promise<boolean>;
 
+/** Type-mirror of {@link GroupSchema} — one declared group. */
+export declare type Group = {
+  name: string;
+  title?: string | undefined;
+  description?: string | undefined;
+  kind?: GroupKind | undefined;
+};
+
+/**
+ * Group-kind labels — the informational role of a declared group. Standalone
+ * for the same reason as {@link ACTIVITY_KIND_DISPLAY}. A consumer reading a
+ * definition as data and meeting an unknown kind (deployed by a newer engine)
+ * must treat it as unset — a plain group; the strict engine parse itself
+ * rejects unknown kinds, like every stored enum.
+ */
+export declare const GROUP_KIND_DISPLAY: {
+  core: {
+    title: string;
+    description: string;
+  };
+  details: {
+    title: string;
+    description: string;
+  };
+};
+
+export declare const GROUP_KINDS: readonly ["core", "details"];
+
+export declare type GroupKind = (typeof GROUP_KINDS)[number];
+
+/** A group member's address — enough to locate the node without the definition. */
+export declare type GroupMember =
+  | {
+      kind: "field";
+      scope: FieldScope;
+      stage?: string;
+      activity?: string;
+      name: string;
+    }
+  | {
+      kind: "activity";
+      stage: string;
+      name: string;
+    }
+  | {
+      kind: "action";
+      stage: string;
+      activity: string;
+      name: string;
+    };
+
+/**
+ * Group membership — the declared group(s) a node belongs to. A reference
+ * resolves lexically up the node's enclosing chain (host activity → stage →
+ * workflow; an activity's OWN membership sees stage → workflow — a node is
+ * never a member of a group only it declares). An empty list is an author
+ * error (it would name no groups) — omit `group` instead, and each group is
+ * listed once. Authoring accepts a bare name as convenience; the STORED form
+ * is always a list, so `'seo'` and `['seo']` hash identically under content
+ * addressing and lake-side reads see one shape.
+ */
+export declare type GroupMembership = string | string[];
+
+/** The names in a `group` membership, normalised to a fresh list ([] when absent). */
+export declare function groupMembershipNames(
+  group: GroupMembership | undefined,
+): string[];
+
+/**
+ * Every group a definition declares, in stable order: workflow groups, then
+ * per stage — the stage's groups, then per activity — the activity's groups.
+ * A membership that resolves to no declaration (rejected at deploy) is
+ * omitted — no site is invented for it.
+ */
+export declare function groupSitesOf(
+  definition: WorkflowDefinition,
+): DefinitionGroupSite[];
+
 export declare type Guard = v.InferOutput<typeof GuardSchema>;
 
 /**
@@ -3242,8 +4276,8 @@ declare const GuardSchema: v.StrictObjectSchema<
       undefined
     >;
     /**
-     * Lake GROQ predicate — a distinct eval context reading
-     * `document.before`/`document.after`, `mutation`, `guard`, and
+     * Lake GROQ predicate — a distinct eval context: delta-mode GROQ
+     * reading the `before()`/`after()` natives, `mutation`, `guard`, and
      * `identity()`. Bare ids/fields only. Omitted or empty means
      * UNCONDITIONAL DENY.
      */
@@ -3318,6 +4352,8 @@ export declare function guardsForResource(
   client: WorkflowClient,
 ): Promise<MutationGuardDoc[]>;
 
+export { guillemets };
+
 /**
  * Content fingerprint of an authored definition: the canonical JSON of its
  * content, hashed. Stamped on the deployed document ({@link DeployedDefinition})
@@ -3368,10 +4404,26 @@ export declare const HISTORY_DISPLAY: {
     title: string;
     description: string;
   };
+  effectClaimReleased: {
+    title: string;
+    description: string;
+  };
   spawned: {
     title: string;
     description: string;
   };
+  subworkflowAdopted: {
+    title: string;
+    description: string;
+  };
+  subworkflowResolved: {
+    title: string;
+    description: string;
+  };
+  subworkflowOrphaned: {
+    title: string;
+    description: string;
+  };
   aborted: {
     title: string;
     description: string;
@@ -3386,7 +4438,18 @@ export declare const HISTORY_DISPLAY: {
   };
 };
 
-export declare type HistoryEntry =
+export declare type HistoryEntry = HistoryEvent & {
+  /**
+   * The execution environment that committed this entry — inferred
+   * runtime plus the host's declared `{kind, id}` (see
+   * {@link ExecutionContext}). Stamped centrally at persist time on every
+   * entry the engine appends; absent only on entries stored before the
+   * stamp existed.
+   */
+  executionContext?: ExecutionContext;
+};
+
+declare type HistoryEvent =
   | {
       _key: string;
       _type: "stageEntered";
@@ -3465,16 +4528,33 @@ export declare type HistoryEntry =
       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;
       effectKey: string;
       effect: EffectName;
-      status: "done" | "failed";
+      status: EffectRunStatus;
       outputs?: Record<string, unknown>;
       detail?: string;
       actor?: Actor;
     }
+  | {
+      _key: string;
+      _type: "effectClaimReleased";
+      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. */
+      via: "drain-takeover" | "sweep";
+      /** The drainer/sweeper that released it. */
+      actor?: Actor;
+    }
   | {
       _key: string;
       _type: "spawned";
@@ -3483,12 +4563,45 @@ export declare type HistoryEntry =
       /**
        * 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[]`, `spawnedInstances[]`,
+       * 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;
       actor?: Actor;
     }
+  | {
+      _key: string;
+      _type: "subworkflowAdopted";
+      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;
+    }
+  | {
+      _key: string;
+      _type: "subworkflowResolved";
+      at: string;
+      activity: ActivityName;
+      /** The child observed terminal; its registry row now carries the
+       *  terminal cache. */
+      instanceRef: GlobalDocumentReference;
+      status: "done" | "aborted";
+    }
+  | {
+      _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. */
+      instanceRef: GlobalDocumentReference;
+      detail: string;
+    }
   | {
       _key: string;
       _type: "aborted";
@@ -3542,6 +4655,8 @@ export declare type HistoryEntry =
       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`
@@ -3572,6 +4687,44 @@ export declare type InitialFieldValue = {
   };
 }[FieldKind];
 
+export { InsightPhrase };
+
+/** Where a condition lives in the current stage — the address a consumer
+ *  joins back onto the matching evaluation node. */
+export declare type InsightSite =
+  | {
+      kind: "transition";
+      transition: string;
+    }
+  | {
+      kind: "activity-filter";
+      activity: string;
+    }
+  | {
+      kind: "requirement";
+      activity: string;
+      requirement: string;
+    }
+  | {
+      kind: "complete-when";
+      activity: string;
+    }
+  | {
+      kind: "fail-when";
+      activity: string;
+    }
+  | {
+      kind: "action";
+      activity: string;
+      action: string;
+    }
+  | {
+      kind: "editable-field";
+      scope: FieldScope;
+      name: string;
+      activity?: string;
+    };
+
 /**
  * The per-instance guard filter — the single definition of "this instance's
  * guards in one datasource". The engine's verdict load
@@ -3585,7 +4738,7 @@ export declare function instanceGuardQuery(instanceId: string): CompiledQuery;
 
 declare interface InstanceGuardsQueryArgs {
   client: WorkflowClient;
-  clientForGdr: (parsed: ParsedGdr) => WorkflowClient;
+  clientForGdr: ClientForGdr;
   instance: WorkflowInstance;
 }
 
@@ -3605,6 +4758,21 @@ export declare interface InstanceRefArgs {
   instanceId: string;
 }
 
+/**
+ * The two join keys every instance-scoped event carries — one home for the
+ * fields, their docs, and the policy, so a new event can't forget half the
+ * pair or drift its wording.
+ */
+declare interface InstanceScopedEventData {
+  /** Absent only when the definition predates content fingerprinting. */
+  definitionContentHash?: string;
+  /** The instance document `_id` — the per-instance join key (engine-minted
+   *  `<tag>.wf-instance.<random>`; caller-supplied ids ride verbatim). One of
+   *  the payload policy's two deliberate customer-string exceptions — see the
+   *  module doc. */
+  instanceId: string;
+}
+
 export declare interface InstanceSession {
   /** The watch-set to feed via {@link InstanceSession.update}, derived from the
    *  held instance. Recompute after the instance changes (a new stage changes it). */
@@ -3622,8 +4790,11 @@ export declare interface InstanceSession {
    *  behind an in-flight commit — guards aren't part of the held-snapshot
    *  consistency story, and tick's pre-flight reads them at commit start. */
   updateGuards(guards: readonly MutationGuardDoc[]): void;
-  /** Best-effort projection against the held content + held guards. No network
-   *  (async only because filter evaluation runs on groq-js). */
+  /** Best-effort projection against the held content + held guards. The first
+   *  call resolves the caller's identity/grants from the client's token over
+   *  the network (cached per client) — plus each foreign subject resource's
+   *  grants through its own client, for the subject-write forecast;
+   *  evaluation itself runs in-memory on groq-js. */
   evaluate(): Promise<WorkflowEvaluation>;
   /** Advance the instance against the held content: cascade auto-transitions,
    *  deploy guards, queue effects, commit with `ifRevisionId`. */
@@ -3635,12 +4806,35 @@ export declare interface InstanceSession {
     params?: Record<string, unknown>;
   }): Promise<OperationResult>;
   /** Edit a declared-editable field against the held content (the generic edit
-   *  seam), gated on the held projection, then cascade. */
+   *  seam), gated on the held projection, then cascade. Stages its own
+   *  optimistic preview on entry and drops the target's previews when the
+   *  commit settles — success lands the reloaded value, failure reverts the
+   *  projection to the held committed state. */
   editField(args: {
     target: EditFieldTarget;
     mode?: EditMode;
     value?: unknown;
   }): Promise<OperationResult>;
+  /** Stage an optimistic preview of a field edit: {@link InstanceSession.evaluate}
+   *  projects against the held instance with staged previews applied, so field
+   *  values and the advisory verdicts derived from them move instantly, while
+   *  everything the engine writes (stage, activity statuses, history) stays
+   *  committed by construction — previews apply `field.*` ops only. Set/unset
+   *  replace the target's staged rows (last write wins); appends accumulate.
+   *  Tolerant where commits are loud: a target that doesn't resolve in the
+   *  current stage (it moved under a mounted editor), a closed edit window
+   *  (a pending activity's field before activation), or a value that doesn't
+   *  fit the field's shape yet (a half-typed date) stages an INERT preview —
+   *  no echo, no throw; the commit at the semantic boundary is the loud
+   *  surface. Never persisted — commit via {@link InstanceSession.editField}. */
+  previewField(args: {
+    target: EditFieldTarget;
+    mode?: EditMode;
+    value?: unknown;
+  }): void;
+  /** Drop staged previews for one target — or all, when omitted — reverting
+   *  the projection to the held committed state on the next evaluate. */
+  discardFieldPreview(target?: EditFieldTarget): void;
 }
 
 export declare interface InstancesForDocumentArgs {
@@ -3670,6 +4864,25 @@ export declare interface InstancesQueryFilter {
    * watch-set with {@link instanceWatchesDocument}.
    */
   document?: GdrUri;
+  /**
+   * The multi-document form of {@link InstancesQueryFilter.document}: one
+   * prefilter matching instances that may reference ANY of the given docs,
+   * for consumers discovering instances across many open documents at once.
+   * Merged with `document` when both are set; per-document narrowing is the
+   * caller's ({@link instanceWatchesDocument} again). 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.
+   */
+  documents?: readonly GdrUri[];
+  /**
+   * Specific instances by bare doc id — OR'd with the document prefilter, so
+   * 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
+   * {@link InstancesQueryFilter.documents}.
+   */
+  ids?: readonly string[];
   /** Version-less definition `name` the instances were started from. */
   definition?: string;
   /** Current stage name. */
@@ -3695,6 +4908,35 @@ export declare function instanceWatchesDocument(
   document: GdrUri,
 ): boolean;
 
+/**
+ * A claim whose lease has lapsed no longer protects the entry. A claim
+ * without `leaseExpiresAt` (persisted before leases existed) counts as
+ * expired — those are exactly the stuck-forever entries leases recover.
+ */
+export declare function isClaimExpired(
+  claim: PendingEffectClaim,
+  now: string,
+): boolean;
+
+export { isComparisonOp };
+
+/**
+ * The full applicability derivation for one definition against one loaded
+ * document: startable ∧ {@link acceptsDocumentType} ∧ `applicableWhen`.
+ * "Deployed" is the caller's premise — feed it deployed definitions (the
+ * engine verb `definitionsForDocument` does). Throws when `document` carries
+ * no `_type` — that's a ref or a projection, not a loaded document. An
+ * `applicableWhen` that doesn't PARSE also throws, naming the definition —
+ * that's a malformed definition (only writable by bypassing deploy
+ * validation), and silently excluding it would make it vanish from every
+ * picker with nothing screaming; only an evaluation result of GROQ null
+ * ("can't decide") fails closed.
+ */
+export declare function isDefinitionApplicable(args: {
+  definition: ApplicabilitySource;
+  document: CandidateDocument;
+}): Promise<boolean>;
+
 /** Type filter for GDR shape. */
 export declare function isGdr(value: unknown): value is GlobalDocumentReference;
 
@@ -3708,6 +4950,27 @@ export declare function isGuardLifted(
   guard: Pick<MutationGuardDoc, "predicate">,
 ): boolean;
 
+/**
+ * A notes-shaped `array` entry: the sugar's fixed `of` declares
+ * `{body, actor, at}` rows ({@link NoteItem}), which tells the audit log
+ * 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.
+ */
+export declare function isNotesEntry(entry: FieldEntry): entry is FieldEntry & {
+  type: "array";
+};
+
+export declare function isNotesEntry(
+  entry: ResolvedFieldEntry,
+): entry is Extract<
+  ResolvedFieldEntry,
+  {
+    _type: "array";
+  }
+>;
+
 /**
  * Whether a human may start this definition standalone (the default). A
  * `lifecycle: 'child'` definition is spawn-only — instantiated by a parent via
@@ -3720,12 +4983,53 @@ export declare function isStartableDefinition(definition: {
   lifecycle?: WorkflowLifecycle | undefined;
 }): boolean;
 
+/**
+ * The environment denial process shells (CLI, MCP server) feed
+ * {@link createTelemetryIntake}: CI and `DO_NOT_TRACK` are trueish
+ * opt-outs — the standard Sanity CLI consent recipe.
+ */
+export declare function isTelemetryEnvDenied(
+  env: Record<string, string | undefined>,
+): boolean;
+
+export declare function isTerminalActivityStatus(
+  status: ActivityStatus,
+): status is TerminalActivityStatus;
+
 /**
  * A stage with no transitions out IS terminal — structural, not declared.
  * Reaching one completes the instance.
  */
 export declare function isTerminalStage(stage: Stage): boolean;
 
+/**
+ * A todoList-shaped `array` entry: the sugar's fixed `of` declares `label` +
+ * `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.
+ */
+export declare function isTodoListEntry(
+  entry: FieldEntry,
+): entry is FieldEntry & {
+  type: "array";
+};
+
+export declare function isTodoListEntry(
+  entry: ResolvedFieldEntry,
+): entry is Extract<
+  ResolvedFieldEntry,
+  {
+    _type: "array";
+  }
+>;
+
+/** Per-row narrowing for {@link TodoListItem}: `_key` + `label` must be
+ *  strings; `status`, when present, must be a string — a non-string status is
+ *  rejected, while null counts as unset (GROQ materializes absent attributes
+ *  as null). The remaining columns stay loose (field validation owns them). */
+export declare function isTodoListItem(row: unknown): row is TodoListItem;
+
 /**
  * Deterministic id so deploy/retract are query-free and idempotent. Derived
  * from the guard's authored `name` — an author-controlled handle that stays
@@ -3737,6 +5041,44 @@ export declare function lakeGuardId(args: {
   guardName: string;
 }): string;
 
+/**
+ * The latest deployed version of each definition name — the reduction every
+ * "what would a start load?" consumer applies over a
+ * {@link definitionsListGroq} read (GROQ has no group-by, so it happens
+ * client-side). Order-independent: the highest version per name wins under
+ * either `versionOrder`; names keep first-appearance order, so a
+ * name-ascending read stays name-ascending.
+ */
+export declare function latestDeployedDefinitions<
+  T extends {
+    name: string;
+    version: number;
+  },
+>(rows: readonly T[]): T[];
+
+/**
+ * Advisory producer/consumer check for a deployed definition: every
+ * `$effects['<name>'].<key>` read whose `<name>` is a declared effect that
+ * declares its `outputs` but does not list `<key>`. Returns human-readable
+ * warning strings (empty when clean) — deploy surfaces them, it never rejects.
+ * (Runtime completion is where declared `outputs` are ENFORCED; this only warns
+ * the author at deploy about a consumer read of a key no producer declares.)
+ *
+ * Advisory-strength by design: it flags reads against DECLARED effects only. A
+ * name that is not a declared effect is left alone — it may be a `startInstance`
+ * `effectsContext` seed key or a `subworkflows.context` handoff key, runtime
+ * producers the static definition cannot see. An effect that declares no
+ * `outputs` produces nothing (an empty allowlist), so a keyed read of it is
+ * flagged like any undeclared key.
+ *
+ * Reads are collected from the primary consumer sites: condition GROQ
+ * ({@link conditionSitesOf}), effect binding GROQ, and guard reads (the
+ * `$effects['<name>'].<path>` mini-language on `match.idRefs` / `metadata`).
+ */
+export declare function lintEffectOutputs(
+  definition: WorkflowDefinition,
+): string[];
+
 declare type LiteralExpr = {
   type: "literal";
   value: unknown;
@@ -3776,6 +5118,16 @@ declare function matchesFilter(args: {
   userId?: string;
 }): Promise<boolean>;
 
+export { MAX_COUNTERFACTUAL_INDEX };
+
+/**
+ * The oldest engine model that can safely read a persisted engine document.
+ * The engine always writes the {@link MODEL_STAMP} pair, so a `modelVersion`
+ * with no `minReaderModel` is malformed foreign data — read conservatively:
+ * the stamp itself is the floor. A doc with neither is model 0 (floor 0).
+ */
+export declare function minReaderModelOf(doc: object): number;
+
 export declare interface MissingHandlerDeployInfo {
   phase: "deploy";
   name: string;
@@ -3810,6 +5162,52 @@ export declare type MissingHandlerPolicy =
   | "skip"
   | ((info: MissingHandlerInfo) => void | Promise<void>);
 
+/**
+ * The `required` input entries `initialFields` fails to provide — the pure
+ * predicate behind {@link RequiredFieldNotProvidedError}: an entry counts as
+ * required when it is `required` AND `input`-sourced (the only combination
+ * deploy admits), and as provided when a supplied value matches its name AND
+ * kind with a real (non-null) value. Keys on the same name+type as the input
+ * read in {@link resolveInputValue}, but is stricter: a present-but-null/
+ * undefined value counts as absent here (a required field needs a real
+ * value), whereas {@link resolveInputValue} passes a null fill straight
+ * through. Exported so pre-flight validators (e.g. a start gate) share the
+ * engine's own rule instead of mirroring it.
+ */
+export declare function missingRequiredInputs(args: {
+  entryDefs: readonly FieldEntry[];
+  initialFields: readonly InitialFieldValue[];
+}): {
+  name: string;
+  type: FieldEntry["type"];
+}[];
+
+/**
+ * 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`.
+ */
+export declare class ModelVersionAheadError extends WorkflowError<"model-version-ahead"> {
+  readonly documentId: string;
+  readonly documentModelVersion: number;
+  readonly requiredReaderModel: number;
+  readonly engineModelVersion: number;
+  constructor(args: {
+    documentId: string;
+    documentModelVersion: number;
+    requiredReaderModel: number;
+  });
+}
+
+/** 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. */
+export declare function modelVersionOf(doc: object): number;
+
 declare const MUTATION_GUARD_ACTIONS: readonly [
   "create",
   "update",
@@ -3819,9 +5217,9 @@ declare const MUTATION_GUARD_ACTIONS: readonly [
 ];
 
 /**
- * Inputs to predicate evaluation: `document.before`/`after`, the `mutation`,
- * the `guard`, and `identity()`. `before` is null on create, `after` null on
- * delete.
+ * Inputs to predicate evaluation: the delta-mode natives `before()`/`after()`,
+ * the `mutation`, the `guard`, and `identity()`. `before` is null on create,
+ * `after` null on delete.
  */
 export declare interface MutationContext {
   before:
@@ -3938,12 +5336,30 @@ export declare interface MutationGuardMatch {
   actions: MutationGuardAction[];
 }
 
+/** The default logger: emit nothing. The engine's twin of `@sanity/telemetry`'s `noopLogger`. */
+export declare const noopTelemetry: WorkflowTelemetryLogger;
+
+/**
+ * One row of a `notes`-sugar `array` entry, as the desugared `of` persists
+ * it: `_key` + the domain `body`, with the `actor`/`at` audit stamps. Like
+ * {@link TodoListItem}, the sugar guarantees the COLUMNS in the schema, not
+ * values per row — `actor`/`at` are per-row optional (an appender that
+ * doesn't know the author writes a stamp-less row, and rows are lake data
+ * any client can write).
+ */
+export declare interface NoteItem {
+  _key: string;
+  body: string;
+  actor?: Actor | null;
+  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.
  */
-declare type NotesField = FieldBase<AuthoringEditable> & {
+declare type NotesField = FieldBase<AuthoringEditable, GroupMembership> & {
   type: "notes";
 };
 
@@ -3990,16 +5406,10 @@ export declare interface OpAppliedSummary {
 
 export declare interface OperationArgs {
   instanceId: string;
-  /**
-   * Optional access-state override. See `StartInstanceArgs.access`
-   * for the resolution contract.
-   */
-  access?: WorkflowAccessOverride;
   /**
    * URL path for grant resolution — see `StartInstanceArgs.grantsFromPath`.
    */
   grantsFromPath?: string;
-  idempotencyKey?: string;
 }
 
 /**
@@ -4017,7 +5427,8 @@ export declare interface OperationResult {
    * Whether this call changed the instance's workflow state. `false` means
    * the call succeeded but was a no-op: an idempotent re-fire of an already
    * resolved activity, a `tick` that wrote nothing, a `setStage` already at
-   * the target, an abort of an already-terminal instance. Failures throw —
+   * the target, an abort of an already-terminal instance, or a retry whose
+   * `idempotencyKey` was already processed. Failures throw —
    * `changed: false` never signals an error.
    */
   changed: boolean;
@@ -4027,6 +5438,24 @@ export declare interface OperationResult {
   ranOps?: OpAppliedSummary[];
 }
 
+/**
+ * The instance's direct parent — the last entry of the root-first
+ * {@link WorkflowInstance.ancestors} chain; `undefined` for a root instance.
+ */
+export declare function parentRef(
+  instance: Pick<WorkflowInstance, "ancestors">,
+): GlobalDocumentReference | undefined;
+
+/**
+ * The ONE way to read an instance's frozen {@link WorkflowInstance.definitionSnapshot}
+ * back into a {@link WorkflowDefinition} — wraps the parse so a corrupt
+ * snapshot fails with the instance id attached instead of a bare
+ * `SyntaxError`.
+ */
+export declare function parseDefinitionSnapshot(
+  instance: WorkflowInstance,
+): WorkflowDefinition;
+
 export declare interface ParsedGdr {
   scheme: GdrScheme;
   /** For `dataset`: `<projectId>` */
@@ -4045,6 +5474,15 @@ export declare interface ParsedGdr {
  */
 export declare function parseGdr(uri: string): ParsedGdr;
 
+/**
+ * Parse a resource-shaped GDR (`<type>:<id>`, no document part) into the
+ * {@link WorkflowResource} it names. The one grammar for resource addresses —
+ * hosts validate/parse through this instead of hand-rolling the split.
+ * Throws on unknown type, extra `:` parts (that shape is a document GDR —
+ * see {@link parseGdr}), or a malformed dataset id.
+ */
+export declare function parseResourceGdr(uri: string): WorkflowResource;
+
 /**
  * A stage's multi-guard deploy failed *after* at least one guard already landed.
  * Those partial locks can't be cleanly undone (guard docs have no transactional
@@ -4090,9 +5528,9 @@ export declare interface PendingEffect {
   stageEntryKey?: string;
   /**
    * Presence = a drainer is dispatching this entry. Absence = the entry
-   * is unclaimed and eligible for drain. Entries in terminal states
-   * (done / failed) don't live on `pendingEffects[]` at all; they move
-   * to `effectHistory[]`.
+   * is unclaimed and eligible for drain. Settled entries (any
+   * {@link EffectRunStatus}) don't live on `pendingEffects[]` at all; they
+   * move to `effectHistory[]`.
    */
   claim?: PendingEffectClaim;
 }
@@ -4103,15 +5541,66 @@ export declare interface PendingEffect {
  * available. There is intentionally no `status` enum; presence of
  * `claim` is the sole marker.
  *
- * Wire format includes `_type` so future fields (lease expiry, attempt
- * counters, etc.) can land additively without parsing strings.
+ * Wire format includes `_type` so future fields can land additively
+ * without parsing strings.
  */
 export declare interface PendingEffectClaim {
   _type: "pendingEffect.claim";
   claimedAt: string;
   claimedBy: Actor;
+  /**
+   * When this claim's lease lapses. Past this instant the claimer is
+   * presumed dead: a drain may take the claim over and `sweepStaleClaims`
+   * may force-release it. Absent only on claims persisted before leases
+   * existed — treated as already expired, so the exact entries leases
+   * exist to recover (claimed-then-abandoned) stay recoverable.
+   *
+   * There is deliberately no attempt counter here: the retry count is the
+   * `effectClaimReleased` history rows for the entry's `_key` (plus the
+   * live claim), and a field would drift from that trail across releases.
+   */
+  leaseExpiresAt?: string;
 }
 
+/**
+ * One row of the instance's idempotency ledger — a caller-supplied
+ * `idempotencyKey` a state-changing verb already committed under. Recorded in
+ * the same CAS commit as the operation it dedupes, so "the op applied" and
+ * "the key is recorded" can never diverge. Rows expire at `expiresAt` and are
+ * pruned lazily whenever a later keyed operation commits.
+ */
+export declare interface ProcessedRequest {
+  _key: string;
+  _type: "processedRequest";
+  /** The caller-supplied idempotency key. */
+  key: string;
+  /** The verb the key was processed under. Reusing a live key on a
+   *  different verb is a caller bug and throws. */
+  op: string;
+  processedAt: string;
+  expiresAt: string;
+}
+
+/**
+ * The execution-environment user properties a process shell (CLI, MCP
+ * server) attaches to its store — the sanity CLI's precedent set, joined
+ * to events by sessionId downstream. The `surface` marker is what lets
+ * intake data slice per shell; user identity is deliberately absent
+ * (the intake service resolves the sender from the authenticated session
+ * on every event).
+ */
+export declare function processShellUserProperties<
+  Surface extends "cli" | "mcp",
+>(
+  surface: Surface,
+): {
+  surface: Surface;
+  machinePlatform: string;
+  cpuArchitecture: string;
+  runtime: string;
+  runtimeVersion: string;
+};
+
 export declare interface QueryArgs {
   groq: string;
   params?: Record<string, unknown>;
@@ -4119,10 +5608,12 @@ export declare interface QueryArgs {
 
 export declare interface QueryInScopeArgs extends InstanceRefArgs, QueryArgs {}
 
+export { quoted };
+
 /**
  * Whether a watched ref reads RAW — never perspective-scoped. The
- * instance, its ancestors (both instance docs), and `release.ref`
- * system docs (`system.release`) are not versioned by a release
+ * instance, its ancestors, and its spawned children (all instance docs), and
+ * `release.ref` system docs (`system.release`) are not versioned by a release
  * perspective; everything else is content and resolves to its
  * version/draft/published form. This is the single encoding of the rule
  * the {@link WatchSet} `perspective` contract describes to consumers, and
@@ -4131,21 +5622,21 @@ export declare interface QueryInScopeArgs extends InstanceRefArgs, QueryArgs {}
 export declare function readsRaw(ref: { type: string }): boolean;
 
 /** Make a GDR pointer to a Canvas-resource doc. */
-export declare function refCanvas({
+export declare function refCanvas<TType extends string = string>({
   resourceId,
   documentId,
   type,
-}: ResourceRefArgs): GlobalDocumentReference;
+}: ResourceRefArgs<TType>): GlobalDocumentReference<TType>;
 
 /** Make a GDR pointer to a Dashboard-resource doc. */
-export declare function refDashboard({
+export declare function refDashboard<TType extends string = string>({
   resourceId,
   documentId,
   type,
-}: ResourceRefArgs): GlobalDocumentReference;
+}: ResourceRefArgs<TType>): GlobalDocumentReference<TType>;
 
 /** Make a GDR pointer to a project-dataset doc. */
-export declare function refDataset({
+export declare function refDataset<TType extends string = string>({
   projectId,
   dataset,
   documentId,
@@ -4154,15 +5645,39 @@ export declare function refDataset({
   projectId: string;
   dataset: string;
   documentId: string;
-  type: string;
-}): GlobalDocumentReference;
+  type: TType;
+}): GlobalDocumentReference<TType>;
 
 /** Make a GDR pointer to a Media-Library-resource doc. */
-export declare function refMediaLibrary({
+export declare function refMediaLibrary<TType extends string = string>({
   resourceId,
   documentId,
   type,
-}: ResourceRefArgs): GlobalDocumentReference;
+}: ResourceRefArgs<TType>): GlobalDocumentReference<TType>;
+
+/**
+ * The GDR `type`s in a `doc.ref` / `doc.refs` value that the entry's declared
+ * accepted `types` reject — empty when the value conforms, the entry declares
+ * no `types`, or the kind isn't a ref. A GDR's `type` names the target
+ * document's schema type, so this is the declared-subject-type contract.
+ * Skips anything that isn't GDR-shaped — the shape schemas scream about
+ * those. Boundaries that need their own error framing (the spawn `with`
+ * projection gates its remediation hint on the generic `"document"` type
+ * being among the rejects) read this; everything else goes through
+ * {@link refTypeIssues} / {@link checkFieldValue}.
+ */
+export declare function rejectedRefTypes(args: {
+  entryType: string;
+  types: readonly string[] | undefined;
+  value: unknown;
+}): string[];
+
+/**
+ * The `_id` of a release's system document — the one owner of the
+ * `_.releases.<name>` spelling, shared by {@link releaseRef} and the
+ * validation cross-check so the id scheme can't drift between them.
+ */
+export declare function releaseDocId(releaseName: string): string;
 
 /**
  * A reference to a Content Release. Extends the GDR shape (so existing
@@ -4174,11 +5689,23 @@ export declare function refMediaLibrary({
  * workflow resource); `type` is always `"system.release"`;
  * `releaseName` is the final segment of the release id.
  */
-export declare interface ReleaseRef extends GlobalDocumentReference {
-  type: "system.release";
+export declare interface ReleaseRef extends GlobalDocumentReference<"system.release"> {
   releaseName: string;
 }
 
+/**
+ * Build a {@link ReleaseRef} — the one constructor for the id ↔
+ * `releaseName` pairing, so the envelope can't be assembled out of step
+ * (validation cross-checks the pairing, but only at instance-write time).
+ */
+export declare function releaseRef({
+  res,
+  releaseName,
+}: {
+  res: WorkflowResource;
+  releaseName: string;
+}): ReleaseRef;
+
 /**
  * The remediations that would unstick a diagnosis — the *what to do about it*
  * half. Empty unless the instance is `stuck`: a `waiting` instance advances on
@@ -4234,41 +5761,22 @@ export declare class RequiredFieldNotProvidedError extends WorkflowError<"requir
 export declare const RESERVED_CONDITION_VARS: readonly string[];
 
 /**
- * Resolve the engine's `WorkflowAccess` for a client. Override wins
- * outright; otherwise both halves are fetched in parallel and
- * cached. Throws if neither path yields an actor — the engine
- * refuses to operate without an identity.
+ * Resolve the engine's `WorkflowAccess` for a client — both halves
+ * 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.
  */
 export declare function resolveAccess(
-  client: WorkflowClient,
+  taggedClient: WorkflowClient,
   args?: ResolveAccessArgs,
 ): Promise<WorkflowAccess>;
 
 export declare interface ResolveAccessArgs {
   /**
-   * Partial override. Any field set here wins outright; any field
-   * left unset falls through to token resolution.
-   *
-   *  - `override.actor` set + `override.grants` set → returned as-is.
-   *  - `override.actor` set + `override.grants` unset → actor from
-   *    override; grants fetched from `grantsFromPath` (or undefined).
-   *  - `override.actor` unset + `override.grants` set → actor from
-   *    `/users/me`; grants from override.
-   *  - `override` undefined entirely → both halves fetched.
-   *
-   * The test bench passes a fully-populated `{ actor, grants }` so
-   * the underlying TestClient (no `request` method) never hits the
-   * token path. Admin/preview tooling passes one or the other.
-   */
-  override?: {
-    actor?: Actor;
-    grants?: Grant[];
-  };
-  /**
-   * Where the engine should fetch grants from the supplied client
-   * when `override.grants` isn't given, e.g. a Canvas resource at
-   * `/canvases/<resourceId>/acl` or a dataset at
-   * `/projects/<id>/datasets/<ds>/acl`.
+   * Where the engine should fetch grants from the supplied client,
+   * e.g. a Canvas resource at `/canvases/<resourceId>/acl` or a
+   * dataset at `/projects/<id>/datasets/<ds>/acl`. Omit to skip the
+   * grants fetch (the rendered `$can` stays undefined).
    */
   grantsFromPath?: string;
 }
@@ -4280,7 +5788,8 @@ export declare interface ResolveAccessArgs {
  * `initialValue` is `{type:'query'}`, of any kind) additionally carries
  * `resolvedAt` — the lake-read time — so `resolvedAt` is provenance-driven,
  * not kind-specific. `object` / `array` entries carry their declared
- * sub-field shape (`fields` / `of`) so the instance is self-describing for
+ * sub-field shape (`fields` / `of`) — and `doc.ref` / `doc.refs` entries
+ * their declared accepted `types` — so the instance is self-describing for
  * op-time validation and rendering.
  */
 export declare type ResolvedFieldEntry = {
@@ -4302,9 +5811,31 @@ export declare type ResolvedFieldEntry = {
       ? {
           of: FieldShape[];
         }
+      : Record<never, never>) &
+    (K extends "doc.ref" | "doc.refs"
+      ? {
+          types?: string[];
+        }
       : 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).
+ */
+export declare function resolveFieldEntry(
+  instance: WorkflowInstance,
+  site: {
+    scope: FieldScope;
+    activity?: ActivityName;
+    name: string;
+  },
+): ResolvedFieldEntry | undefined;
+
 /**
  * A map binding each resource-alias name to the physical {@link WorkflowResource}
  * it resolves to at deploy. Parallels the role-alias map: where role aliases map
@@ -4324,15 +5855,16 @@ export declare function resourceAliasesToMap(
 ): ResourceAliases;
 
 /**
- * Resolver for cross-resource reads. The engine has ONE `client` bound
- * to its own resource (where definition / instance
- * docs live). When the engine reads a doc in a different resource —
- * a subject in a project dataset while the workflow lives in canvas,
- * say — it consults this resolver with the parsed GDR. Return `undefined`
- * to fall back to the engine's default client.
+ * 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.
  *
- * The resolver receives the parsed pieces, not the raw URI, so it can
- * pattern-match on scheme + resource id without re-parsing.
+ * Resolved clients ride the engine's API version like every other engine
+ * client: the verb scope rebinds them onto `ENGINE_API_VERSION` when they
+ * carry {@link WorkflowClient.withConfig} (one without it is used as
+ * returned and must be built to serve that version).
  */
 export declare type ResourceClientResolver = (
   parsed: ParsedGdr,
@@ -4347,11 +5879,20 @@ export declare type ResourceClientResolver = (
  */
 export declare function resourceFromParsed(parsed: ParsedGdr): WorkflowResource;
 
+/**
+ * Format a {@link WorkflowResource} as a resource-shaped GDR — `<type>:<id>`
+ * with no document part (`dataset:abc123.production`, `media-library:mlXyz`).
+ * The string form for naming a *resource* (not a document in it) across an
+ * API boundary — e.g. the per-call workflow-environment address an MCP tool
+ * takes. Inverse of {@link parseResourceGdr}.
+ */
+export declare function resourceGdr(res: WorkflowResource): string;
+
 /** Args for the single-resource ref constructors ({@link refCanvas}, {@link refMediaLibrary}, {@link refDashboard}). */
-declare interface ResourceRefArgs {
+declare interface ResourceRefArgs<TType extends string> {
   resourceId: string;
   documentId: string;
-  type: string;
+  type: TType;
 }
 
 /**
@@ -4425,16 +5966,18 @@ declare const RoleAliasesSchema: v.RecordSchema<
   undefined
 >;
 
+export { ScopeAssignment };
+
+export { sentenceCase };
+
 export declare interface SessionArgs {
   /** The instance document to bind — typically the consumer's live-store value. */
   instance: WorkflowInstance;
-  /** Optional access-state override — see `StartInstanceArgs.access`. */
-  access?: WorkflowAccessOverride | undefined;
   /** URL path for grant resolution — see `StartInstanceArgs.grantsFromPath`. */
   grantsFromPath?: string | undefined;
 }
 
-export declare interface SetStageArgs extends OperationArgs {
+export declare interface SetStageArgs extends DedupableOperationArgs {
   /** Stage id to force the instance into. */
   targetStage: string;
   /** Free-text reason — surfaces on history entries for audit. */
@@ -4452,6 +5995,13 @@ export declare interface SetStageArgs extends OperationArgs {
  */
 export declare const silentLogger: EngineLogger;
 
+/** One site whose verdict a proposed assignment flips. */
+export declare interface SiteConsequence {
+  site: InsightSite;
+  before: ConditionOutcome;
+  after: ConditionOutcome;
+}
+
 export declare type Stage = StageFields<
   FieldEntry,
   Activity,
@@ -4482,6 +6032,7 @@ declare type StageFields<TField, TActivity, TTransition, TGuard, TEditable> = {
   name: string;
   title?: string | undefined;
   description?: string | undefined;
+  groups?: Group[] | undefined;
   activities?: TActivity[] | undefined;
   transitions?: TTransition[] | undefined;
   guards?: TGuard[] | undefined;
@@ -4491,12 +6042,17 @@ declare type StageFields<TField, TActivity, TTransition, TGuard, TEditable> = {
 
 declare interface StageGuardArgs {
   client: WorkflowClient;
-  clientForGdr: (parsed: ParsedGdr) => WorkflowClient;
+  clientForGdr: ClientForGdr;
   instance: WorkflowInstance;
   definition: WorkflowDefinition;
   stageName: string;
   /** Shell-supplied clock reading (ISO) backing guard `$now` reads. */
   now: string;
+  /** The commit's hydrated snapshot, so a `metadata` read dereferences a
+   *  `doc.ref` into content. `undefined` → identity-only resolution (content
+   *  reads resolve `null`). Required (not optional) so a new call site can't
+   *  silently drop it — pass `undefined` deliberately. */
+  snapshot: HydratedSnapshot | undefined;
 }
 
 export declare type StageName = string;
@@ -4526,30 +6082,19 @@ export declare interface StartInstanceArgs {
    * Stable named params for effect handlers, set at start time. The
    * runtime resolves effect bindings against these to materialise
    * handler params at queue time. **Not read by transition filters.**
+   *
+   * Each value may be any JSON — a scalar, a {@link GlobalDocumentReference},
+   * or an arbitrary object/array. Scalars and GDRs store as their typed
+   * `effectsContext` entries; anything else stores as one `effectsContext.json`
+   * entry, so all forms read back the same under `$effects.<name>`.
    */
-  effectsContext?: Record<
-    string,
-    string | number | boolean | GlobalDocumentReference
-  >;
+  effectsContext?: EffectsContext;
   /** Caller-supplied id; auto-generated otherwise. */
   instanceId?: string;
-  /**
-   * Optional access-state override. By default the engine resolves
-   * `(actor, grants)` from the supplied client's token:
-   *
-   *   - `actor` ← `client.request({ url: "/users/me" })`
-   *   - `grants` ← `client.request({ url: grantsFromPath })` (when path supplied)
-   *
-   * Pass `access` to override either or both — the test bench does
-   * this with its `ALL_ACCESS` default, admin tooling can do it for
-   * impersonation flows. If neither the explicit override nor a
-   * token-bearing client is available, the engine throws rather than
-   * fabricating an identity.
-   */
-  access?: WorkflowAccessOverride;
   /**
    * URL path on the supplied client where the engine fetches the
-   * actor's ACL grants when `access.grants` isn't supplied. Grants
+   * caller's ACL grants. Identity is always token-resolved — `actor`
+   * comes from `client.request({ uri: "/users/me" })` — and grants
    * feed the advisory `$can.*` params action conditions can read;
    * omitting this leaves the rendered `$can` undefined (conditions
    * referencing it fail closed, nothing else is gated engine-side —
@@ -4973,6 +6518,30 @@ export declare type StuckCause =
       transitions: string[];
     };
 
+/**
+ * Display label per {@link SubjectPermissionDenial} —
+ * `<permission> on <subject> (<resource>)`. The one display convention for
+ * rendering the subject-write shortfall to a person (the subject-forecast
+ * twin of {@link deniedGuardLabels}); consumers phrase their own sentence
+ * around the labels instead of re-deriving them from the payload.
+ */
+export declare function subjectDenialLabels(
+  denied: SubjectPermissionDenial[],
+): string[];
+
+/**
+ * One prospective subject write the actor's grants don't allow — the payload
+ * of the `subject-permission-denied` {@link DisabledReason} arm.
+ */
+export declare interface SubjectPermissionDenial {
+  /** GDR URI of the subject document the write would target. */
+  subject: GdrUri;
+  /** Resource-shaped GDR (`<type>:<id>`) of the resource whose ACL denied. */
+  resource: string;
+  /** The forecast write permission the resource's grants don't confer. */
+  permission: DocumentValuePermission;
+}
+
 /**
  * A document the reactive layer should subscribe to, with its GDR
  * exploded so consumers never re-parse: the resource-addressing parts
@@ -5002,11 +6571,86 @@ export declare function subscriptionDocumentsForInstance(
   instance: WorkflowInstance,
 ): WatchSet;
 
+/**
+ * One spawned child in the instance's workflow-scope registry
+ * (`instance.subworkflows`). A child instance is a real lake document whose
+ * lifetime is not bound to any stage, so its record lives at workflow scope —
+ * rows are never deleted, and a child's status is always derived from its
+ * document (or from {@link SubworkflowEntry.resolved} once it terminated).
+ */
+export declare interface SubworkflowEntry {
+  _key: string;
+  /** The spawning activity's name. */
+  activity: ActivityName;
+  /** The child definition's `name` — adoption never crosses definitions. */
+  definition: string;
+  /**
+   * `_key` of the {@link StageEntry} whose cohort this row currently belongs
+   * to. Re-adoption on a stage re-entry re-binds the row to the new entry;
+   * a row bound to an exited entry is a *detached* child — still tracked,
+   * still propagating, just outside any activity's implicit gate.
+   */
+  stageEntry: string;
+  /**
+   * The cohort's stage NAME (denormalized from {@link SubworkflowEntry.stageEntry}
+   * for lake queries/inspectors). Deliberately not called `stage`: the child's
+   * own stage lives on `resolved.stage` and the `$subworkflows` var row.
+   */
+  cohortStage: StageName;
+  /**
+   * Identity of the `forEach` row that produced this child — what adopt
+   * matching keys on: `_key` ?? `_id` ?? GDR `id` (a `{id, type}` row with
+   * a GDR-URI `id`) for object rows, the value itself for scalar rows.
+   */
+  rowKey: string;
+  /** GDR of the child instance document. */
+  ref: GlobalDocumentReference;
+  spawnedAt: string;
+  /**
+   * An abort the engine owes this child but could not perform inside the
+   * condemning commit (children are separate documents — aborting one is its
+   * own commit). Lives ON the row — a condemned child's whole story is one
+   * record — and survives a crash because the row persists; the cascade
+   * drains condemned rows (abort child → stamp {@link SubworkflowEntry.resolved})
+   * idempotently, and the field stays afterwards as the audit of WHY. Set by
+   * a parent abort or an `onExit: "abort"` stage exit; a condemned row is
+   * never adopted into a fresh cohort.
+   */
+  abortPending?: {
+    /** The condemning commit's clock reading. */
+    at: string;
+    /** Why — recorded on the child's own abort history when the drain runs. */
+    reason: string;
+  };
+  /**
+   * Terminal cache, stamped when the engine observes the child terminal.
+   * Terminal state is immutable, so once stamped the child leaves the
+   * watch-set and status derives from here instead of its document.
+   */
+  resolved?: {
+    /** The child's `completedAt` — or the drain's clock reading when the
+     *  child document was already gone and only the disposition is known. */
+    at: string;
+    /** The child's final stage. Absent when the child document vanished
+     *  before the engine could observe it. */
+    stage?: StageName;
+    /** Set when the child was aborted rather than completing normally. */
+    aborted?: true;
+  };
+}
+
 export declare type Subworkflows = v.InferOutput<typeof SubworkflowsSchema>;
 
 declare const SubworkflowsSchema: v.StrictObjectSchema<
   {
-    /** GROQ producing one row per subworkflow; each row binds as `$row`. */
+    /**
+     * 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>,
@@ -5082,6 +6726,23 @@ 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-entry'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 (`completeWhen`, transition
+     * filters over `$subworkflows`) decide.
+     */
+    readonly onExit: v.OptionalSchema<
+      v.PicklistSchema<
+        readonly ["detach", "abort"],
+        `Invalid option: expected one of ${string}`
+      >,
+      undefined
+    >;
   },
   undefined
 >;
@@ -5097,6 +6758,33 @@ export declare interface SuggestedRemediation {
   rationale: string;
 }
 
+/**
+ * Force-release every pending-effect claim whose lease has expired, so the
+ * entries become drainable again after their claimer died between claim and
+ * complete. One CAS write per pass (all expired claims at once) with an
+ * `effectClaimReleased` audit row per release; the `ifRevisionId` guard is
+ * the sweeper election — concurrent sweepers or drainers race safely, the
+ * loser re-reads (bounded, then fails loud). Release only: dispatching the
+ * recovered entries is the next `drainEffects` call's job. To kill a stuck
+ * entry WITHOUT redispatching, report it via
+ * `completeEffect({status: 'failed'})` instead.
+ */
+export declare function sweepStaleClaims(args: {
+  client: WorkflowClient;
+  tag: string;
+  instanceId: string;
+  clock?: Clock;
+  /** Declared execution context stamped on the release audit rows —
+   *  a sweeper runtime declares itself here (identity is its token). */
+  executionContext?: DeclaredExecutionContext;
+}): Promise<SweepStaleClaimsResult>;
+
+export declare interface SweepStaleClaimsResult {
+  /** The entries whose expired claims were force-released, as they stood
+   *  before the release (each still carries the expired `claim`). */
+  released: PendingEffect[];
+}
+
 /**
  * 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
@@ -5105,6 +6793,67 @@ export declare interface SuggestedRemediation {
  */
 export declare function tagScopeFilter(): string;
 
+/**
+ * Internal telemetry-injection seam for the raw `workflow.*` verbs — the
+ * telemetry twin of the `Clocked` seam in `clock.ts`, deliberately not
+ * re-exported from the package root. Production injects a logger ONCE via
+ * `createEngine({ telemetry })`; a raw-namespace caller that omits it
+ * emits nothing (the verbs default to {@link noopTelemetry}).
+ */
+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"
+  | "unset"
+  | "granted"
+  | "denied";
+
+/**
+ * Structural mirror of the `resolveConsent`/`sendEvents` pair in
+ * `@sanity/telemetry`'s `CreateBatchedStoreOptions` — assignable to it
+ * verbatim.
+ */
+export declare interface TelemetryIntake {
+  resolveConsent: () => Promise<{
+    status: TelemetryConsentStatus;
+  }>;
+  sendEvents: (batch: unknown[]) => Promise<unknown>;
+}
+
+/** The slice of a `SanityClient` the intake recipe needs — narrow so
+ *  shells can hand in any authenticated client and tests fake exactly
+ *  what the recipe reads. `timeout` is the per-request cap in ms — the
+ *  real client honors it by aborting the request, which is what actually
+ *  closes the socket (a `Promise.race` alone cannot). */
+export declare interface TelemetryIntakeClient {
+  request: <T>(opts: {
+    uri: string;
+    method?: string;
+    body?: unknown;
+    tag?: string;
+    timeout?: number;
+  }) => Promise<T>;
+}
+
 declare const TERMINAL_ACTIVITY_STATUSES: readonly [
   "done",
   "skipped",
@@ -5114,22 +6863,64 @@ declare const TERMINAL_ACTIVITY_STATUSES: readonly [
 export declare type TerminalActivityStatus =
   (typeof TERMINAL_ACTIVITY_STATUSES)[number];
 
+/** See {@link terminalState}. */
+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
+ * abort, so in-flight queries treat both terminals uniformly), so `abortedAt`
+ * must be checked first — `'completed'` means completed *without* an abort.
+ */
+export declare function terminalState(
+  instance: Pick<WorkflowInstance, "completedAt" | "abortedAt">,
+): TerminalState;
+
+/**
+ * A GDR URI stripped back to its bare document `_id`; a non-GDR string passes
+ * through unchanged. The one canonical "URI → bare id" transform — use it
+ * wherever a stored ref (which may be a full GDR URI, or already bare) must
+ * become a lake-queryable `_id`.
+ */
+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.
  */
-declare type TodoListField = FieldBase<AuthoringEditable> & {
+declare type TodoListField = FieldBase<AuthoringEditable, GroupMembership> & {
   type: "todoList";
 };
 
+/**
+ * One row of a `todoList`-sugar `array` entry, as the desugared `of`
+ * persists it. The sugar guarantees the COLUMNS in the schema, not values
+ * per row — field validation wraps every declared column in optional, so a
+ * `status`-less row is valid lake data. `_key` + `label` identify a row;
+ * `status` / `assignee` / `dueDate` are per-row optional. Rows are lake
+ * data any client can write — read them through {@link isTodoListItem},
+ * never a cast.
+ */
+export declare interface TodoListItem {
+  _key: string;
+  label: string;
+  status?: string | null;
+  assignee?: Assignee | null;
+  dueDate?: string | null;
+}
+
 export declare type Transition = TransitionFields<TransitionOp> & {
   filter: string;
 };
 
 export declare interface TransitionEvaluation {
   transition: Transition;
-  /** Whether the transition's filter is definitively satisfied at read time. */
+  /**
+   * Whether the transition's filter is definitively satisfied at read time.
+   * Projected caller-free, exactly as the engine's cascade evaluates it — the
+   * evaluation's actor and grants never participate.
+   */
   filterSatisfied: boolean;
   /**
    * The filter evaluated to GROQ `null` — a referenced operand was missing or
@@ -5140,6 +6931,10 @@ export declare interface TransitionEvaluation {
    * hold apart from a genuine routing dead-end.
    */
   unevaluable: boolean;
+  /** Derived state of the transition's filter — the atoms standing between
+   *  here and the next stage. `filterSatisfied`/`unevaluable` are projections
+   *  of `insight.outcome`; one evaluation feeds all three. */
+  insight: ConditionInsight;
 }
 
 /** Type-mirror of {@link transitionFields} minus `filter` — stored requires it,
@@ -5156,14 +6951,47 @@ declare type TransitionFields<TOp> = {
 export declare type TransitionOp = FieldOp;
 
 /**
- * Parse-validate every GROQ string in a (stored, desugared) definition
- * before deploy. Surfaces malformed predicates, conditions, bindings, and
- * `activity.completeWhen`/`failWhen` expressions early — long before any
- * instance runs.
+ * Parse a GDR URI, returning `undefined` instead of throwing when the string
+ * is not a GDR (or is malformed). The "is this a GDR, and if so its parts"
+ * primitive — every "parse a ref, treat unparseable as not-a-GDR" call site
+ * routes through this rather than re-spelling the try/catch.
+ */
+export declare function tryParseGdr(uri: string): ParsedGdr | undefined;
+
+/**
+ * The diagnose idiom shared by every consumer: each unsatisfied exit
+ * transition with its insight summary. Consumers shape the result (the CLI
+ * maps by name, the MCP prefixes the site phrase) — the selection lives here
+ * so it can't drift between them.
+ */
+export declare function unsatisfiedTransitionSummaries(
+  evaluation: WorkflowEvaluation,
+): {
+  transition: string;
+  summary: string;
+}[];
+
+/**
+ * Validate a (stored, desugared) definition before deploy: parse-check every
+ * GROQ string (malformed predicates, conditions, bindings, `completeWhen`/
+ * `failWhen`) and re-run the cross-field invariants. `defineWorkflow` already
+ * ran the invariants at authoring time, but deploy must reject what authoring
+ * rejects — a stored-shape definition handed straight to the verb (raw JSON,
+ * a foreign tool) would otherwise bypass every invariant.
  *
- * Throws an `Error` with all problems aggregated. Doesn't try to
- * type-check semantics (just syntax). Reserved params don't need to be
- * declared here — groq-js's parser doesn't know about runtime params,
+ * Plain condition sites come from {@link conditionSitesOf} — the same walker
+ * the insight surface renders from — so a condition the runtime will parse
+ * cannot escape the deploy check. Editability is checked at its AUTHORED
+ * sites: an entry's `editable` string alongside its other attributes (with
+ * `initialValue.query`), a stage tighten-override at its walker site. The
+ * walker's `editable-field` sites carry the derived per-stage EFFECTIVE
+ * predicate instead — a composition of those authored parts, parseable
+ * whenever they are — so they are the one site kind this check skips. GROQ
+ * strings that are not condition sites (effect bindings, op `where`s,
+ * subworkflow reads, guard reads) keep their own checks below.
+ *
+ * Throws an `Error` with all problems aggregated. Reserved params don't need
+ * to be declared here — groq-js's parser doesn't know about runtime params,
  * just syntax.
  */
 export declare function validateDefinition(
@@ -5282,6 +7110,12 @@ export declare interface WatchSet {
   perspective?: WorkflowPerspective;
 }
 
+export { whatIfCondition };
+
+export { WhatIfOutcome };
+
+export { withAssignment };
+
 /**
  * The workflow verbs, bound as one object — write path, admin
  * overrides, pure reads, and permission helpers. The module doc above
@@ -5305,9 +7139,14 @@ export declare const workflow: {
    * 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.
    */
-  deployDefinitions: (
-    args: DeployDefinitionsArgs & EngineScopeArgs,
+  deployDefinitions: <T extends WorkflowDefinitionInput<T>>(
+    rawArgs: Telemetered<DeployDefinitionsArgs<T> & EngineScopeArgs>,
   ) => Promise<DeployDefinitionsResult>;
   /**
    * Remove a deployed workflow definition (all versions, or one via
@@ -5317,7 +7156,7 @@ export declare const workflow: {
    * full contract (spawn-referrer check, guard-doc housekeeping).
    */
   deleteDefinition: (
-    args: Clocked<DeleteDefinitionArgs & EngineScopeArgs>,
+    rawArgs: Clocked<Telemetered<DeleteDefinitionArgs & EngineScopeArgs>>,
   ) => Promise<DeleteDefinitionResult>;
   /**
    * Spawn a new workflow instance from a deployed definition.
@@ -5329,7 +7168,7 @@ export declare const workflow: {
    * `cascaded` reports how far the new instance auto-advanced.
    */
   startInstance: (
-    args: Clocked<StartInstanceArgs & EngineScopeArgs>,
+    rawArgs: Clocked<Telemetered<StartInstanceArgs & EngineScopeArgs>>,
   ) => Promise<OperationResult>;
   /**
    * Fire an action against an activity. If the activity is pending, it is
@@ -5342,7 +7181,7 @@ export declare const workflow: {
    * timer firings. External signals never bypass this.
    */
   fireAction: (
-    args: Clocked<FireActionArgs & EngineScopeArgs>,
+    rawArgs: Clocked<Telemetered<FireActionArgs & EngineScopeArgs>>,
   ) => Promise<OperationResult>;
   /**
    * Edit a declared-editable field directly — reassign, reschedule,
@@ -5360,7 +7199,7 @@ export declare const workflow: {
    * never an `onChange` per keystroke.
    */
   editField: (
-    args: Clocked<EditFieldArgs & EngineScopeArgs>,
+    rawArgs: Clocked<Telemetered<EditFieldArgs & EngineScopeArgs>>,
   ) => Promise<OperationResult>;
   /**
    * Report a queued effect's outcome. Drains it from `pendingEffects`,
@@ -5370,11 +7209,17 @@ export declare const workflow: {
    * reference them. 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
-   * always changes state (the effect drains + history is appended), so
-   * `changed` is always `true` — a bad `effectKey`/status throws instead.
+   * 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`.
+   *
+   * Completion is first-writer-wins — see {@link CompleteEffectArgs}. A
+   * completer reporting over a retrying transport (webhook redelivery,
+   * queue, cron) should pass `idempotencyKey`.
    */
   completeEffect: (
-    args: Clocked<CompleteEffectArgs & EngineScopeArgs>,
+    rawArgs: Clocked<Telemetered<CompleteEffectArgs & EngineScopeArgs>>,
   ) => Promise<OperationResult>;
   /**
    * Re-evaluate auto-transitions and resolve due waits until stable.
@@ -5390,7 +7235,7 @@ export declare const workflow: {
    * not from `cascaded` alone.
    */
   tick: (
-    args: Clocked<OperationArgs & EngineScopeArgs>,
+    rawArgs: Clocked<Telemetered<OperationArgs & EngineScopeArgs>>,
   ) => Promise<OperationResult>;
   /**
    * Admin override — force the instance into `targetStage` regardless
@@ -5399,7 +7244,7 @@ export declare const workflow: {
    * means the move was a no-op (already at the target / terminal).
    */
   setStage: (
-    args: Clocked<SetStageArgs & EngineScopeArgs>,
+    rawArgs: Clocked<Telemetered<SetStageArgs & EngineScopeArgs>>,
   ) => Promise<OperationResult>;
   /**
    * Admin override — hard-stop an in-flight instance where it stands.
@@ -5411,7 +7256,7 @@ export declare const workflow: {
    * already terminal.
    */
   abortInstance: (
-    args: Clocked<AbortInstanceArgs & EngineScopeArgs>,
+    rawArgs: Clocked<Telemetered<AbortInstanceArgs & EngineScopeArgs>>,
   ) => Promise<OperationResult>;
   /**
    * Fetch a workflow instance by id, scoped to the engine's tag.
@@ -5419,13 +7264,13 @@ export declare const workflow: {
    * engine.
    */
   getInstance: (
-    args: InstanceRefArgs & EngineScopeArgs,
+    rawArgs: InstanceRefArgs & EngineScopeArgs,
   ) => Promise<WorkflowInstance>;
   guardsForInstance: (
-    args: InstanceRefArgs & EngineScopeArgs,
+    rawArgs: InstanceRefArgs & EngineScopeArgs,
   ) => Promise<MutationGuardDoc[]>;
   guardsForDefinition: (
-    args: GuardsForDefinitionArgs & EngineScopeArgs,
+    rawArgs: GuardsForDefinitionArgs & EngineScopeArgs,
   ) => Promise<MutationGuardDoc[]>;
   /**
    * Run a caller-supplied GROQ query with the engine's tag bound as
@@ -5436,7 +7281,7 @@ export declare const workflow: {
    * rejected before it reaches the lake. Caller is responsible for type
    * narrowing the result.
    */
-  query: <T = unknown>(args: QueryArgs & EngineScopeArgs) => Promise<T>;
+  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.
@@ -5452,14 +7297,14 @@ export declare const workflow: {
    * without re-implementing hydration. Pure read — never writes.
    */
   queryInScope: <T = unknown>(
-    args: Clocked<QueryInScopeArgs & EngineScopeArgs>,
+    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.
    */
   listPendingEffects: (
-    args: InstanceRefArgs & EngineScopeArgs,
+    rawArgs: InstanceRefArgs & EngineScopeArgs,
   ) => Promise<PendingEffect[]>;
   /**
    * Filter pending effects on the instance by criteria. `claimed`
@@ -5467,7 +7312,7 @@ export declare const workflow: {
    * names. Both filters compose (AND).
    */
   findPendingEffects: (
-    args: FindPendingEffectsArgs & EngineScopeArgs,
+    rawArgs: FindPendingEffectsArgs & EngineScopeArgs,
   ) => Promise<PendingEffect[]>;
   /**
    * Project the instance from a given actor's perspective. Returns a
@@ -5478,7 +7323,7 @@ export declare const workflow: {
    * `fireAction` to gate writes via the same logic.
    */
   evaluate: (
-    args: Clocked<EvaluateArgs & EngineScopeArgs>,
+    rawArgs: Clocked<EvaluateArgs & EngineScopeArgs>,
   ) => Promise<WorkflowEvaluation>;
   /**
    * Diagnose why an instance is or isn't progressing. Projects the
@@ -5490,7 +7335,7 @@ export declare const workflow: {
    * Pure read.
    */
   diagnose: (
-    args: Clocked<EvaluateArgs & EngineScopeArgs>,
+    rawArgs: Clocked<EvaluateArgs & EngineScopeArgs>,
   ) => Promise<DiagnoseResult>;
   /**
    * List the actions an actor could fire on an instance's current stage,
@@ -5500,14 +7345,14 @@ export declare const workflow: {
    * consumer can read the instance/stage context. Pure read.
    */
   availableActions: (
-    args: Clocked<EvaluateArgs & EngineScopeArgs>,
+    rawArgs: Clocked<EvaluateArgs & EngineScopeArgs>,
   ) => Promise<AvailableActionsResult>;
   /**
    * Materialised spawned children of a parent instance.
    *
    * Walks `history` for `spawned` events — the durable
-   * record. (The per-activity `spawnedInstances` field on the active stage
-   * only exists while that stage is current; history survives.) Strips
+   * 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.
@@ -5515,7 +7360,7 @@ export declare const workflow: {
    * Pass `activity` to restrict to a single spawning activity on the parent.
    */
   children: (
-    args: ChildrenArgs & EngineScopeArgs,
+    rawArgs: ChildrenArgs & EngineScopeArgs,
   ) => Promise<WorkflowInstance[]>;
   /**
    * Every in-flight instance whose reactive watch-set includes `document` —
@@ -5547,8 +7392,24 @@ export declare const workflow: {
    * `startedAt` ascending.
    */
   instancesForDocument: (
-    args: InstancesForDocumentArgs & EngineScopeArgs,
+    rawArgs: InstancesForDocumentArgs & EngineScopeArgs,
   ) => Promise<WorkflowInstance[]>;
+  /**
+   * 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 pure derivation
+   * ({@link applicableDefinitions}): startable ∧ a required subject entry
+   * accepts the doc's `_type` ∧ `applicableWhen` passes.
+   *
+   * 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.
+   */
+  definitionsForDocument: (
+    rawArgs: DefinitionsForDocumentArgs & EngineScopeArgs,
+  ) => Promise<DeployedDefinition[]>;
   /**
    * Permission helpers — Sanity ACL grants evaluated against documents
    * via GROQ. Used by `workflow.evaluate` to soft-gate actions when the
@@ -5582,36 +7443,33 @@ declare const WORKFLOW_LIFECYCLES: readonly ["standalone", "child"];
 /**
  * The engine's view of "who am I, what can I do?". `actor` is who
  * the engine stamps onto history / `completedBy` / `ValueExpr.actor` —
- * caller-asserted advisory provenance (see {@link Actor}), never an
- * authenticated principal. `grants` (when present) feed the advisory
- * `$can.*` params action conditions can read; there is no engine-side
- * permission verdict. When grants are absent the rendered `$can` is
- * undefined — conditions referencing it fail closed, everything else
- * is ungated engine-side — and the real Sanity write boundary takes
- * over.
- *
- * This is the RESOLVED shape — `actor` is guaranteed. For the
- * partial-override shape callers pass on verb args, see
- * `WorkflowAccessOverride`.
+ * token-resolved advisory provenance (see {@link Actor}). `grants`
+ * (when present) feed the advisory `$can.*` params action conditions
+ * can read; there is no engine-side permission verdict. When grants are
+ * absent the rendered `$can` is undefined — conditions referencing it
+ * fail closed, everything else is ungated engine-side — and the real
+ * Sanity write boundary takes over.
  */
 export declare interface WorkflowAccess {
   actor: Actor;
   grants?: Grant[];
 }
 
-/**
- * Partial override accepted by every acting verb's `access?:`
- * argument. Any field present wins; missing halves token-resolve.
- *
- *   `{ actor, grants }` — bench's all-access default; both halves
- *     injected, no token round-trip.
- *   `{ actor }` — "act as another user"; grants come from
- *     `grantsFromPath` (or the rendered `$can` stays undefined).
- *   `{ grants }` — "preview with restricted permissions"; actor
- *     comes from `/users/me`.
- *   omitted entirely — both halves token-resolved.
- */
-export declare type WorkflowAccessOverride = Partial<WorkflowAccess>;
+export declare const WorkflowActionFired: WorkflowTelemetryEvent<WorkflowActionFiredData>;
+
+export declare interface WorkflowActionFiredData extends InstanceScopedEventData {
+  /** Effective kind of the activity the action fired on. */
+  activityKind?: ActivityKind;
+  hasParams: boolean;
+  /** Auto-transitions fired during the post-action cascade. */
+  cascaded: number;
+}
+
+/** Outcome flag for the admin-override events — the attempt emits either way. */
+export declare interface WorkflowAdminOverrideData extends InstanceScopedEventData {
+  /** `false` = the override was a no-op (already at the target / already terminal). */
+  changed: boolean;
+}
 
 export declare interface WorkflowClient {
   fetch: <T = unknown>(
@@ -5621,6 +7479,9 @@ export declare interface WorkflowClient {
   ) => Promise<T>;
   getDocument: <T = SanityDocument>(
     id: string,
+    options?: {
+      tag?: string;
+    },
   ) => Promise<T | null | undefined>;
   patch: (documentId: string) => WorkflowPatch;
   /**
@@ -5675,6 +7536,33 @@ export declare interface WorkflowClient {
       tag?: string;
     },
   ) => Promise<any>;
+  /**
+   * Optional — present on the real `@sanity/client` and the in-memory test
+   * fake. Returns a sibling client with the given config overrides,
+   * inheriting everything else from the source (token, apiHost). The engine
+   * derives two things from it:
+   *
+   * - **Cross-resource routing** (`resource` + the dataset pair): a sibling
+   *   for a foreign GDR when `resourceClients` doesn't map it. A client
+   *   without `withConfig` makes foreign GDRs a loud routing error rather
+   *   than a silent read of the wrong resource.
+   * - **API-version normalization** (`apiVersion`): every engine entry
+   *   derives its working client with
+   *   `withConfig({apiVersion: ENGINE_API_VERSION})`, so the caller's
+   *   configured version never reaches engine traffic (the caller's own
+   *   instance is untouched). A client without `withConfig` cannot be
+   *   rebound and is used as-is — it must be built to serve
+   *   {@link ENGINE_API_VERSION} already; older dated versions fail
+   *   silently incomplete, not loud.
+   *
+   * Dataset resources carry the `{projectId, dataset}` pair alongside
+   * `resource`: the real client routes by `resource` (it takes precedence in
+   * URL building), while the test fake keys its dataset registry by the pair.
+   * Known gap: the fake ignores `resource`, so it derives DATASET siblings
+   * only — a canvas/media-library derivation on the fake aliases the current
+   * store until the fake learns `resource` upstream.
+   */
+  withConfig?: (config: WorkflowClientConfig) => WorkflowClient;
   /**
    * Optional — present on the real `@sanity/client`, absent on the
    * in-memory test client. The engine probes for it when auto-resolving
@@ -5697,6 +7585,19 @@ export declare interface WorkflowClient {
   }) => Promise<T>;
 }
 
+/**
+ * The config bag {@link WorkflowClient.withConfig} accepts — all optional: a
+ * resource rebind (`resource`, plus the dataset pair for dataset targets), an
+ * `apiVersion` rebind, or both. Everything omitted is inherited from the
+ * source client.
+ */
+export declare interface WorkflowClientConfig {
+  resource?: WorkflowResource;
+  projectId?: string;
+  dataset?: string;
+  apiVersion?: string;
+}
+
 export declare interface WorkflowCommitOptions {
   /**
    * When the mutation becomes visible to subsequent queries. The engine
@@ -5710,6 +7611,13 @@ export declare interface WorkflowCommitOptions {
    * {@link WorkflowTransaction.commit}.)
    */
   visibility?: WorkflowVisibility;
+  /**
+   * Request tag for request-log attribution — see
+   * {@link WorkflowFetchOptions.tag}; not the workflow-domain deployment
+   * tag. The engine stamps every write with an operation-scoped
+   * `workflow.*` tag.
+   */
+  tag?: string;
 }
 
 export declare type WorkflowConfig = v.InferOutput<typeof WorkflowConfigSchema>;
@@ -5948,7 +7856,9 @@ declare const WorkflowConfigSchema: v.ObjectSchema<
                         name: string;
                         title: string;
                         description?: string | undefined;
+                        groups?: Group[] | undefined;
                         lifecycle?: WorkflowLifecycle | undefined;
+                        applicableWhen?: string | undefined;
                         initialStage: string;
                         fields?: FieldEntry[] | undefined;
                         stages: Stage[];
@@ -5964,7 +7874,9 @@ declare const WorkflowConfigSchema: v.ObjectSchema<
                       name: string;
                       title: string;
                       description?: string | undefined;
+                      groups?: Group[] | undefined;
                       lifecycle?: WorkflowLifecycle | undefined;
+                      applicableWhen?: string | undefined;
                       initialStage: string;
                       fields?: FieldEntry[] | undefined;
                       stages: Stage[];
@@ -6028,7 +7940,9 @@ declare const WorkflowConfigSchema: v.ObjectSchema<
               name: string;
               title: string;
               description?: string | undefined;
+              groups?: Group[] | undefined;
               lifecycle?: WorkflowLifecycle | undefined;
+              applicableWhen?: string | undefined;
               initialStage: string;
               fields?: FieldEntry[] | undefined;
               stages: Stage[];
@@ -6086,7 +8000,9 @@ declare const WorkflowConfigSchema: v.ObjectSchema<
               name: string;
               title: string;
               description?: string | undefined;
+              groups?: Group[] | undefined;
               lifecycle?: WorkflowLifecycle | undefined;
+              applicableWhen?: string | undefined;
               initialStage: string;
               fields?: FieldEntry[] | undefined;
               stages: Stage[];
@@ -6098,6 +8014,21 @@ 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,
+        v.ErrorMessage<v.CustomIssue> | undefined
+      >,
+      undefined
+    >;
   },
   undefined
 >;
@@ -6106,6 +8037,69 @@ export declare type WorkflowDefinition = v.InferOutput<
   typeof WorkflowDefinitionSchema
 >;
 
+export declare const WorkflowDefinitionDeleted: WorkflowTelemetryEvent<WorkflowDefinitionDeletedData>;
+
+export declare interface WorkflowDefinitionDeletedData {
+  /** Deployed versions removed by this delete. */
+  deletedVersionCount: number;
+  /** Non-terminal instances cascade-aborted before the delete. */
+  cascadeAbortedCount: number;
+  /** Orphaned guard docs removed (populated only when the last version goes). */
+  deletedGuardCount: number;
+}
+
+export declare const WorkflowDefinitionDeployed: WorkflowTelemetryEvent<WorkflowDefinitionDeployedData>;
+
+export declare interface WorkflowDefinitionDeployedData {
+  /** Content fingerprint of the deployed content. */
+  contentHash: string;
+  /** Whether this deploy minted a new version or matched the latest one.
+   *  Unchanged redeploys emit too — the attempt is the adoption signal. */
+  status: "created" | "unchanged";
+  /** Groups every definition event minted by one `deployDefinitions` call —
+   *  a random run id, never derived from names or resource coordinates, so
+   *  deployment-level rollups are a group-by without carrying customer
+   *  strings. Distinct from the workflow-domain deployment tag. */
+  deployId: string;
+  stageCount: number;
+  activityCount: number;
+  actionCount: number;
+  transitionCount: number;
+  /** Declared field entries across workflow, stage, and activity scopes. */
+  fieldCount: number;
+  /** Distinct effective activity kinds used, sorted. */
+  activityKinds: ActivityKind[];
+  /** Distinct declared field kinds across workflow, stage, and activity
+   *  scopes, sorted. */
+  fieldKinds: FieldKind[];
+  guardCount: number;
+  /** Effects declared across activities, actions, and transitions. */
+  effectCount: number;
+  /** Activities carrying a `subworkflows` block. */
+  subworkflowCount: number;
+  lifecycle: WorkflowLifecycle;
+}
+
+/**
+ * What deploy/diff accept, conditioned on how the value is typed. The
+ * `string extends keyof T` test matches ONLY index-signature types (`keyof`
+ * of a literal is a finite key union that `string` never extends) — i.e. how
+ * fetch results are typed (`Record<string, unknown>`), which pass through to
+ * the runtime boundary parse. Everything precisely typed gets the exact
+ * {@link WorkflowDefinition} contract: beyond the document envelope
+ * ({@link DocumentEnvelopeKey}, so a typed {@link DeployedDefinition} passes
+ * castless), unknown keys are `never` — a typo'd literal is a compile error,
+ * never a silent collapse to the record arm.
+ */
+export declare type WorkflowDefinitionInput<T> = string extends keyof T
+  ? Record<string, unknown>
+  : WorkflowDefinition & {
+      [K in Exclude<
+        keyof T,
+        keyof WorkflowDefinition | DocumentEnvelopeKey
+      >]?: never;
+    };
+
 /**
  * Structural schema for a STORED workflow definition — primitives only,
  * every reference scope resolved. Cross-field invariants (unique names,
@@ -6125,6 +8119,35 @@ declare const WorkflowDefinitionSchema: v.GenericSchema<
 
 export declare type WorkflowDeployment = WorkflowConfig["deployments"][number];
 
+export declare const WorkflowEffectCompleted: WorkflowTelemetryEvent<WorkflowEffectCompletedData>;
+
+export declare interface WorkflowEffectCompletedData extends InstanceScopedEventData {
+  /** The effect's author-chosen name — one of the payload policy's two
+   *  deliberate customer-string exceptions (module doc); unique per
+   *  definition. */
+  effect: EffectName;
+  /** The recorded outcome of the effect — `cancelled` when an abort
+   *  discarded it rather than a completer reporting. */
+  status: EffectRunStatus;
+  /** Which declaration boundary queued the effect. */
+  origin: EffectOriginKind;
+  /** Auto-transitions fired during the post-completion cascade — always 0
+   *  for a cancellation (the instance is terminal). */
+  cascaded: number;
+}
+
+export declare const WorkflowEffectsDrained: WorkflowTelemetryEvent<WorkflowEffectsDrainedData>;
+
+export declare interface WorkflowEffectsDrainedData extends InstanceScopedEventData {
+  /** Pending effects dispatched to a registered handler in this drain —
+   *  0 for an empty poll (the pass itself is the signal). */
+  drainedCount: number;
+  /** The dispatched effects' author-chosen names, in drain order — one of
+   *  the payload policy's two deliberate customer-string exceptions (module
+   *  doc). */
+  drainedEffects: EffectName[];
+}
+
 /**
  * Base class of the engine's structured errors. `kind` is the stable
  * discriminant — render on it; `name` mirrors the concrete class for logs.
@@ -6140,28 +8163,13 @@ export declare abstract class WorkflowError<
   constructor(kind: K, message: string, options?: ErrorOptions);
 }
 
-/**
- * The engine's error model — one base class, one discriminant.
- *
- * Every structured error the engine throws at a caller extends
- * {@link WorkflowError} and carries a {@link WorkflowErrorKind}, so a consumer
- * can write ONE catch-and-render path: `instanceof WorkflowError`, then switch
- * on `kind` (or `instanceof` a concrete class to read its typed payload). The
- * model covers the runtime verbs' refusals, denials, races and lookups.
- * Three things deliberately stay plain `Error`: deploy/authoring validation
- * (a structured issue-report design of its own), transient transport
- * failures (retryable, carrying `cause` — not engine verdicts), and internal
- * invariant violations (the remediation is a bug report, not a catch branch).
- *
- * How thrown errors relate to the read-side verdicts is documented on
- * {@link DisabledReason}.
- */
 export declare type WorkflowErrorKind =
   | "action-disabled"
   | "edit-field-denied"
   | "mutation-guard-denied"
   | "action-params-invalid"
   | "effect-ops-invalid"
+  | "effect-outputs-invalid"
   | "required-field-not-provided"
   | "workflow-state-diverged"
   | "partial-guard-deploy"
@@ -6169,6 +8177,7 @@ export declare type WorkflowErrorKind =
   | "concurrent-edit-field"
   | "cascade-limit"
   | "field-value-shape"
+  | "model-version-ahead"
   | "instance-not-found"
   | "definition-not-found"
   | "definition-in-use"
@@ -6192,6 +8201,13 @@ export declare interface WorkflowEvaluation {
    * declares no editable fields.
    */
   editableFields: EditableFieldEvaluation[];
+  /**
+   * Per-field derived state across every condition site in the current stage:
+   * which gates read each field (involvement) and the counterfactually
+   * verified consequences of the values that would unblock blocking atoms.
+   * Empty when no condition reads a field.
+   */
+  fieldInsights: FieldInsight[];
 }
 
 export declare interface WorkflowFetchOptions {
@@ -6201,6 +8217,22 @@ export declare interface WorkflowFetchOptions {
    * reads to the instance's `perspective` field.
    */
   perspective?: WorkflowPerspective;
+  /**
+   * Request tag for request-log attribution (`?tag=` — combined with any
+   * client-configured `requestTagPrefix` as `prefix.tag`). Unrelated to
+   * the workflow-domain deployment tag ({@link validateTag}'s `$tag`
+   * partition): same word, disjoint concepts. The engine stamps every
+   * read with an operation-scoped `workflow.*` tag.
+   */
+  tag?: string;
+}
+
+export declare const WorkflowFieldEdited: WorkflowTelemetryEvent<WorkflowFieldEditedData>;
+
+export declare interface WorkflowFieldEditedData extends InstanceScopedEventData {
+  /** Declared kind of the edited field entry. */
+  fieldKind?: FieldKind;
+  mode: EditMode;
 }
 
 /** Type-mirror of {@link workflowFields}, parameterised over field/stage. */
@@ -6208,7 +8240,9 @@ declare type WorkflowFields<TField, TStage> = {
   name: string;
   title: string;
   description?: string | undefined;
+  groups?: Group[] | undefined;
   lifecycle?: WorkflowLifecycle | undefined;
+  applicableWhen?: string | undefined;
   initialStage: string;
   fields?: TField[] | undefined;
   stages: TStage[];
@@ -6218,6 +8252,21 @@ declare type WorkflowFields<TField, TStage> = {
 
 export declare interface WorkflowInstance extends SanityDocument {
   _type: typeof WORKFLOW_INSTANCE_TYPE;
+  /**
+   * Engine data-model stamp — the shape contract this document conforms to
+   * (see {@link DATA_MODEL_VERSION}), orthogonal to the definition-content
+   * pins (`pinnedVersion` / `pinnedContentHash`). Stamped at create and
+   * re-asserted on every full persist; absent on documents last written
+   * before the stamp existed (model 0).
+   */
+  modelVersion?: number;
+  /**
+   * Reader floor — the oldest engine data model that can safely interpret
+   * this document (see {@link DATA_MODEL_MIN_READER}). Written alongside
+   * {@link WorkflowInstance.modelVersion}; additive model changes leave it,
+   * only breaking ones raise it.
+   */
+  minReaderModel?: number;
   /**
    * Engine-scope environment partition stamped on the instance at create
    * time. Reads are scoped to a single tag, so an engine only sees
@@ -6287,9 +8336,25 @@ export declare interface WorkflowInstance extends SanityDocument {
    * Each entry owns its activities.
    */
   stages: StageEntry[];
+  /**
+   * 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
+   * cascade owes it an abort. Rendered as the `$subworkflows` condition
+   * var. Absent only on instances persisted before the registry existed.
+   */
+  subworkflows?: SubworkflowEntry[];
   pendingEffects: PendingEffect[];
   effectHistory: EffectHistoryEntry[];
   history: HistoryEntry[];
+  /**
+   * Idempotency ledger — see {@link ProcessedRequest}. Optional because
+   * instances persisted before the ledger existed lack it (any commit
+   * materialises it, empty). Only keyed operations add rows — it never
+   * grows on instances whose callers pass no `idempotencyKey`.
+   */
+  processedRequests?: ProcessedRequest[];
   startedAt: string;
   lastChangedAt: string;
   completedAt?: string;
@@ -6303,6 +8368,27 @@ export declare interface WorkflowInstance extends SanityDocument {
   abortedAt?: string;
 }
 
+export declare const WorkflowInstanceAborted: WorkflowTelemetryEvent<WorkflowAdminOverrideData>;
+
+export declare const WorkflowInstanceStarted: WorkflowTelemetryEvent<WorkflowInstanceStartedData>;
+
+export declare interface WorkflowInstanceStartedData extends InstanceScopedEventData {
+  /** Caller-supplied initial-field entries — `initialFields` for a direct
+   *  start, the parent's projected `with` bindings for a spawned child. */
+  initialFieldCount: number;
+  /** Started by a parent's subworkflow spawn rather than a direct
+   *  `startInstance` — automation vs. hands-on at instance creation. */
+  viaSpawn: boolean;
+  lifecycle: WorkflowLifecycle;
+}
+
+export declare const WorkflowInstanceTicked: WorkflowTelemetryEvent<WorkflowInstanceTickedData>;
+
+export declare interface WorkflowInstanceTickedData extends InstanceScopedEventData {
+  /** Auto-transitions fired during the cascade. */
+  cascaded: number;
+}
+
 /** How instances of a definition come to exist: started standalone (the
  *  default) or spawned by a parent. `'child'` is spawn-only — see
  *  {@link isStartableDefinition}. */
@@ -6373,6 +8459,28 @@ export declare type WorkflowResource =
       id: string;
     };
 
+export declare const WorkflowStageSet: WorkflowTelemetryEvent<WorkflowAdminOverrideData>;
+
+export declare const WorkflowStageTransitioned: WorkflowTelemetryEvent<WorkflowStageTransitionedData>;
+
+export declare interface WorkflowStageTransitionedData extends InstanceScopedEventData {
+  /** Positional index of the exited stage in the definition's `stages[]`
+   *  order — indexes, never names, so the payload stays content-free. */
+  fromStageIndex: number;
+  /** Positional index of the entered stage in the definition's `stages[]` order. */
+  toStageIndex: number;
+  /** The entered stage is terminal (no transitions out) — reaching it
+   *  completes the instance. */
+  toIsTerminal: boolean;
+  /** The entered stage was already visited on this instance — a loop-back. */
+  isRevisit: boolean;
+  /** Time spent in the exited stage (its entry's `enteredAt` to this exit,
+   *  on the engine clock). Omitted when the exited entry is unavailable. */
+  dwellMs?: number;
+  /** Condition-driven transition vs. the setStage admin override. */
+  via: "transition" | "setStage";
+}
+
 /**
  * Thrown when a guard deploy fails *after* its state move committed and the
  * engine could not cleanly undo the result — any of: the rollback write itself
@@ -6397,6 +8505,37 @@ export declare class WorkflowStateDivergedError extends WorkflowError<"workflow-
   });
 }
 
+/**
+ * A telemetry event descriptor — a structural mirror of `@sanity/telemetry`'s
+ * `DefinedTelemetryLog`, so shells hand these straight to their store logger.
+ */
+export declare interface WorkflowTelemetryEvent<Data = void> {
+  type: "log";
+  /** Matched verbatim downstream — frozen once shipped. */
+  name: string;
+  /** Bumped on any payload shape change; the name never changes. */
+  version: number;
+  /** Optional to match the real package's event shape, so an event built
+   *  with the real `defineEvent` flows into this seam; the engine's own
+   *  vocabulary always sets it. */
+  description?: string;
+  /** Advisory volume cap enforced by the shell's store — at most one
+   *  submission per interval (ms). */
+  maxSampleRate?: number;
+  /** Type-level payload carrier — never set at runtime (the real package's
+   *  `defineEvent` leaves it unset the same way). */
+  schema: Data;
+}
+
+/**
+ * The logger surface the engine emits through — the `log` subset of
+ * `@sanity/telemetry`'s `TelemetryLogger`, so any real logger satisfies it.
+ */
+export declare interface WorkflowTelemetryLogger {
+  log<Data>(event: WorkflowTelemetryEvent<Data>, data: Data): void;
+  log(event: WorkflowTelemetryEvent<void>): void;
+}
+
 export declare interface WorkflowTransaction {
   /**
    * Queue a `create` mutation. Fails the transaction on `_id` collision,
@@ -6432,17 +8571,17 @@ export declare interface WorkflowTransaction {
    */
   delete: (id: string) => WorkflowTransaction;
   /**
-   * Commit the batch. No options — a transaction rides the client's *default*
-   * `visibility`: `'sync'` in `@sanity/client` (so a post-spawn `listInstances`
-   * GROQ sees freshly-created children), immediate in the in-memory test fake.
-   * This is a standing engine assumption — a consumer that configured an
-   * `async` default would make spawn read-backs racy. Single-document writes
-   * state `'sync'` explicitly via {@link WorkflowCommitOptions}; transactions
-   * can't (yet) — the test fake's commit options don't carry `visibility`, and
-   * per repo convention that gap is closed upstream in the fake, not worked
-   * around here.
+   * Commit the batch. The options bag carries only the request tag
+   * ({@link WorkflowFetchOptions.tag} — attribution, not the deployment
+   * tag). Deliberately no `visibility`: a transaction rides the client's
+   * *default* `visibility` — `'sync'` in `@sanity/client` (so a post-spawn
+   * `listInstances` GROQ sees freshly-created children), immediate in the
+   * in-memory test fake. This is a standing engine assumption — a consumer
+   * that configured an `async` default would make spawn read-backs racy.
+   * Single-document writes state `'sync'` explicitly via
+   * {@link WorkflowCommitOptions}.
    */
-  commit: () => Promise<unknown>;
+  commit: (options?: { tag?: string }) => Promise<unknown>;
 }
 
 export declare type WorkflowVisibility = "sync" | "async" | "deferred";