@sanity/workflow-engine 0.14.0 → 0.16.0

package/dist/define.d.cts

@@ -1,16 +1,22 @@
 import * as v from "valibot";
 
-declare type Action = ActionFields<Op>;
+declare type Action = ActionFields<Op, string[]> & {
+  roles?: string[] | undefined;
+};
 
-/** 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;
+  when?: string | undefined;
   filter?: string | undefined;
   params?: ActionParam[] | undefined;
   ops?: TOp[] | undefined;
   effects?: Effect[] | undefined;
+  spawn?: Subworkflows | undefined;
 };
 
 declare type ActionParam = v.InferOutput<typeof ActionParamSchema>;
@@ -53,44 +59,34 @@ declare const ActionParamSchema: v.StrictObjectSchema<
   undefined
 >;
 
-declare type Activity = ActivityFields<FieldEntry, Action, Op, ManualTarget>;
-
-declare const ACTIVITY_KINDS: readonly [
-  "user",
-  "service",
-  "script",
-  "manual",
-  "receive",
-];
+declare type Activity = ActivityFields<
+  FieldEntry,
+  Action,
+  ManualTarget,
+  string[]
+>;
 
-/** 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/target/group. */
+declare type ActivityFields<TField, TAction, TTarget, TGroup> = {
   name: string;
   title?: string | undefined;
   description?: string | undefined;
-  kind?: ActivityKind | undefined;
+  groups?: Group[] | undefined;
+  group?: TGroup | undefined;
   target?: TTarget | undefined;
-  activation?: "auto" | "manual" | undefined;
   filter?: string | undefined;
   requirements?: Record<string, string> | undefined;
-  completeWhen?: string | undefined;
-  failWhen?: string | undefined;
-  ops?: TOp[] | undefined;
-  effects?: Effect[] | undefined;
   actions?: TAction[] | undefined;
-  subworkflows?: Subworkflows | undefined;
   fields?: TField[] | undefined;
 };
 
-declare type ActivityKind = (typeof ACTIVITY_KINDS)[number];
-
 declare type AuthoringAction = AuthoringRawAction | ClaimAction;
 
 declare type AuthoringActivity = ActivityFields<
   AuthoringFieldEntry,
   AuthoringAction,
-  AuthoringOp,
-  AuthoringManualTarget
+  AuthoringManualTarget,
+  GroupMembership
 >;
 
 declare type AuthoringEditable = v.InferOutput<typeof AuthoringEditableSchema>;
@@ -313,8 +309,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.
      */
@@ -648,7 +644,7 @@ declare const AuthoringOpSchema: v.VariantSchema<
           undefined
         >;
         readonly status: v.PicklistSchema<
-          readonly ["pending", "active", "done", "skipped", "failed"],
+          readonly ["active", "done", "skipped", "failed"],
           `Invalid option: expected one of ${string}`
         >;
       },
@@ -713,23 +709,32 @@ declare const AuthoringOpSchema: v.VariantSchema<
  * Authoring action — the stored fields plus two field sugars with one
  * defined expansion each:
  *
- *   - `roles` → a `count($actor.roles[@ in [...]]) > 0` membership condition
- *     ANDed with the authored `filter`. The definition's `roleAliases`
- *     ({@link RoleAliasesSchema}) widen that membership at desugar time.
+ *   - `roles` — on a fireAction-fired action (no `when`) it desugars to a
+ *     `count($actor.roles[@ in [...]]) > 0` membership condition ANDed with
+ *     the authored `filter` (for a caller, "not yours to fire" and "doesn't
+ *     exist for you" are the same advisory answer). On a CASCADE-FIRED
+ *     action it stores VERBATIM — the pin on which identities may execute
+ *     the trigger; folding it into `filter` would make the action's
+ *     existence depend on whose token happens to cascade. The definition's
+ *     `roleAliases` ({@link RoleAliasesSchema}) widen the membership either
+ *     way.
  *   - `status` → a `status.set` op on the firing activity, appended **after**
  *     the authored ops (deliberately never implied: a forgotten explicit
  *     `status` is a visible stall, an implied default silently completes
  *     claim-like actions). Status is the health axis: a decision action
  *     (decline, send back) resolves `done` and writes the decision into a
- *     field the transition filter reads — `failed` is for work that
+ *     field the transition trigger 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
+>;
 
 declare type AuthoringStage = StageFields<
   AuthoringFieldEntry,
@@ -739,216 +744,24 @@ declare type AuthoringStage = StageFields<
   AuthoringEditable
 >;
 
-declare type AuthoringTransition = TransitionFields<AuthoringTransitionOp> & {
-  filter?: string | undefined;
+declare type AuthoringStartBlock = StartFields & {
+  kind?: StartKind | undefined;
 };
 
-declare type AuthoringTransitionOp = v.InferOutput<
-  typeof AuthoringTransitionOpSchema
->;
-
 /**
- * Authoring transitions may omit `filter`; desugar fills the safe,
- * overwhelmingly-common gate `"$allActivitiesDone"`. "Fire unconditionally"
- * stays spellable as an explicit `filter: "true"`.
+ * Authoring transitions may omit `when`; desugar fills the safe,
+ * overwhelmingly-common trigger `"$allActivitiesDone"`. "Fire unconditionally"
+ * stays spellable as an explicit `when: "true"`.
  */
-declare const AuthoringTransitionOpSchema: v.VariantSchema<
-  "type",
-  [
-    v.StrictObjectSchema<
-      {
-        readonly type: v.LiteralSchema<"field.set", undefined>;
-        readonly target: v.StrictObjectSchema<
-          {
-            readonly scope: v.OptionalSchema<
-              v.PicklistSchema<
-                readonly ["workflow", "stage", "activity"],
-                `Invalid option: expected one of ${string}`
-              >,
-              undefined
-            >;
-            readonly field: v.SchemaWithPipe<
-              readonly [
-                v.StringSchema<undefined>,
-                v.MinLengthAction<string, 1, "must be a non-empty string">,
-              ]
-            >;
-          },
-          undefined
-        >;
-        readonly value: v.GenericSchema<ValueExprInternal>;
-      },
-      undefined
-    >,
-    v.StrictObjectSchema<
-      {
-        readonly type: v.LiteralSchema<"field.unset", undefined>;
-        readonly target: v.StrictObjectSchema<
-          {
-            readonly scope: v.OptionalSchema<
-              v.PicklistSchema<
-                readonly ["workflow", "stage", "activity"],
-                `Invalid option: expected one of ${string}`
-              >,
-              undefined
-            >;
-            readonly field: v.SchemaWithPipe<
-              readonly [
-                v.StringSchema<undefined>,
-                v.MinLengthAction<string, 1, "must be a non-empty string">,
-              ]
-            >;
-          },
-          undefined
-        >;
-      },
-      undefined
-    >,
-    v.StrictObjectSchema<
-      {
-        readonly type: v.LiteralSchema<"field.append", undefined>;
-        readonly target: v.StrictObjectSchema<
-          {
-            readonly scope: v.OptionalSchema<
-              v.PicklistSchema<
-                readonly ["workflow", "stage", "activity"],
-                `Invalid option: expected one of ${string}`
-              >,
-              undefined
-            >;
-            readonly field: v.SchemaWithPipe<
-              readonly [
-                v.StringSchema<undefined>,
-                v.MinLengthAction<string, 1, "must be a non-empty string">,
-              ]
-            >;
-          },
-          undefined
-        >;
-        readonly value: v.GenericSchema<ValueExprInternal>;
-      },
-      undefined
-    >,
-    v.StrictObjectSchema<
-      {
-        readonly type: v.LiteralSchema<"field.updateWhere", undefined>;
-        readonly target: v.StrictObjectSchema<
-          {
-            readonly scope: v.OptionalSchema<
-              v.PicklistSchema<
-                readonly ["workflow", "stage", "activity"],
-                `Invalid option: expected one of ${string}`
-              >,
-              undefined
-            >;
-            readonly field: v.SchemaWithPipe<
-              readonly [
-                v.StringSchema<undefined>,
-                v.MinLengthAction<string, 1, "must be a non-empty string">,
-              ]
-            >;
-          },
-          undefined
-        >;
-        readonly where: v.SchemaWithPipe<
-          readonly [
-            v.StringSchema<undefined>,
-            v.MinLengthAction<string, 1, "must be a non-empty string">,
-          ]
-        >;
-        readonly value: v.GenericSchema<ValueExprInternal>;
-      },
-      undefined
-    >,
-    v.StrictObjectSchema<
-      {
-        readonly type: v.LiteralSchema<"field.removeWhere", undefined>;
-        readonly target: v.StrictObjectSchema<
-          {
-            readonly scope: v.OptionalSchema<
-              v.PicklistSchema<
-                readonly ["workflow", "stage", "activity"],
-                `Invalid option: expected one of ${string}`
-              >,
-              undefined
-            >;
-            readonly field: v.SchemaWithPipe<
-              readonly [
-                v.StringSchema<undefined>,
-                v.MinLengthAction<string, 1, "must be a non-empty string">,
-              ]
-            >;
-          },
-          undefined
-        >;
-        readonly where: v.SchemaWithPipe<
-          readonly [
-            v.StringSchema<undefined>,
-            v.MinLengthAction<string, 1, "must be a non-empty string">,
-          ]
-        >;
-      },
-      undefined
-    >,
-    v.StrictObjectSchema<
-      {
-        readonly type: v.LiteralSchema<"audit", undefined>;
-        readonly target: v.StrictObjectSchema<
-          {
-            readonly scope: v.OptionalSchema<
-              v.PicklistSchema<
-                readonly ["workflow", "stage", "activity"],
-                `Invalid option: expected one of ${string}`
-              >,
-              undefined
-            >;
-            readonly field: v.SchemaWithPipe<
-              readonly [
-                v.StringSchema<undefined>,
-                v.MinLengthAction<string, 1, "must be a non-empty string">,
-              ]
-            >;
-          },
-          undefined
-        >;
-        readonly value: v.GenericSchema<ValueExprInternal>;
-        readonly stampFields: v.OptionalSchema<
-          v.StrictObjectSchema<
-            {
-              readonly actor: v.OptionalSchema<
-                v.SchemaWithPipe<
-                  readonly [
-                    v.StringSchema<undefined>,
-                    v.MinLengthAction<string, 1, "must be a non-empty string">,
-                  ]
-                >,
-                undefined
-              >;
-              readonly at: v.OptionalSchema<
-                v.SchemaWithPipe<
-                  readonly [
-                    v.StringSchema<undefined>,
-                    v.MinLengthAction<string, 1, "must be a non-empty string">,
-                  ]
-                >,
-                undefined
-              >;
-            },
-            undefined
-          >,
-          undefined
-        >;
-      },
-      undefined
-    >,
-  ],
-  undefined
->;
+declare type AuthoringTransition = TransitionFields & {
+  when?: string | undefined;
+};
 
 /** The authoring surface: stored primitives plus the define-time sugar. */
 declare type AuthoringWorkflow = WorkflowFields<
   AuthoringFieldEntry,
-  AuthoringStage
+  AuthoringStage,
+  AuthoringStartBlock
 >;
 
 /**
@@ -964,6 +777,7 @@ declare type ClaimAction = {
   name: string;
   title?: string | undefined;
   description?: string | undefined;
+  group?: GroupMembership | undefined;
   field: string | AuthoringFieldRef;
   roles?: string[] | undefined;
   filter?: string | undefined;
@@ -982,6 +796,7 @@ declare type ClaimField = {
   name: string;
   title?: string | undefined;
   description?: string | undefined;
+  group?: GroupMembership | undefined;
 };
 
 /**
@@ -997,27 +812,39 @@ export declare interface ConditionVar {
   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;
 }
 
 /**
  * The condition-variable inventory — the single source of truth for every
  * `$var` the engine binds when it evaluates a {@link Condition}.
  *
- * Three evaluation contexts read a definition's GROQ:
+ * Four evaluation contexts read a definition's GROQ:
  *
  * 1. **Rendered condition scope** — every condition site in a definition
- *    (transition filters, `completeWhen`/`failWhen`, action filters, effect
- *    bindings, `subworkflows` reads, where-op `where`s, editability
- *    predicates, author predicates). {@link CONDITION_VARS} is its inventory;
- *    each entry's `binding` says when the var actually holds a value. The
+ *    (transition `when`s, activity filters, action `when`s/filters, effect
+ *    bindings, `spawn` reads, where-op `where`s, editability predicates,
+ *    author predicates). {@link CONDITION_VARS} is its inventory; each
+ *    entry's `binding` says when the var actually holds a value. The
  *    where-op context is the one closed subset — its bound set is statically
  *    fixed and deploy-enforced (see the op-where scope's param-name list in
  *    the op applier).
- * 2. **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.
- * 3. **Guard predicates** — NOT conditions. A lake mutation guard's
+ * 2. **Cascade gates** — transition `when`s, activity filters, and a
+ *    cascade-fired action's `when`/`filter` must resolve identically no
+ *    matter whose token drives the cascade, so only the `'always'`-bound
+ *    subset carries values there ({@link FILTER_SCOPE_VARS}). Caller-bound
+ *    vars fail closed — `$assigned` binds its caller-free constant `false`,
+ *    the rest evaluate to `undefined` — and deploy rejects them at these
+ *    sites; a cascade-fired action's per-token gate is `roles`, never its
+ *    conditions.
+ * 3. **The start-filter context** — a definition's `start.filter` evaluates
+ *    against a CANDIDATE (no instance exists yet): the candidate document is
+ *    the root, {@link START_FILTER_VARS} are the only bound vars, and
+ *    `*[...]` reads the WORKFLOW resource's dataset. None of the rendered
+ *    condition vars exist there.
+ * 4. **Guard predicates** — NOT conditions. A lake mutation guard's
  *    `predicate` is groq-js **delta-mode** GROQ over a document mutation:
  *    `before()`/`after()`/`identity()` are dialect natives, and the wire
  *    format binds the identifiers in {@link GUARD_PREDICATE_VARS}. None of
@@ -1031,7 +858,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 spawn sites (the per-row `$row`).
  */
 export declare type ConditionVarBinding = "always" | "caller" | "spawn";
 
@@ -1055,6 +882,14 @@ export declare function defineField(
   entry: AuthoringFieldEntry,
 ): AuthoringFieldEntry;
 
+/**
+ * Validate and return a group declaration — advisory "what belongs together"
+ * metadata. Declared in a `groups` array (workflow root, stage, or activity);
+ * fields, activities, and actions join via `group`. The engine stores and
+ * deploy-checks groups but never acts on them.
+ */
+export declare function defineGroup(group: Group): Group;
+
 export declare function defineGuard(guard: AuthoringGuard): AuthoringGuard;
 
 export declare function defineOp(op: AuthoringOp): AuthoringOp;
@@ -1146,6 +981,27 @@ 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: outputs land on the instance document's `effectHistory`, so
+     * the allowlist keeps it bounded — a handler can't accidentally spread a
+     * whole API response
+     * into the instance — and the declared shapes let tooling (e.g. the simulator's
+     * drain UI) suggest an effect's exact output keys. Declaring outputs also
+     * powers the advisory deploy-time producer/consumer lint.
+     */
+    readonly outputs: v.OptionalSchema<
+      v.ArraySchema<v.GenericSchema<FieldShape>, undefined>,
+      undefined
+    >;
   },
   undefined
 >;
@@ -1155,6 +1011,9 @@ declare const EffectSchema: v.StrictObjectSchema<
  * 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",
@@ -1174,28 +1033,32 @@ 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;
 };
 
-declare type FieldEntry = FieldEntryFields<Editable>;
+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;
 };
 
-declare type FieldOp = v.InferOutput<typeof StoredFieldOpSchema>;
-
 declare type FieldReadExpr = {
   type: "fieldRead";
   scope?: "workflow" | "stage" | undefined;
@@ -1229,8 +1092,8 @@ declare type FieldSourceInternal =
 declare type FieldValueKind = (typeof FIELD_VALUE_KINDS)[number];
 
 /**
- * The subset that holds a value when the engine evaluates filters without a
- * caller (the cascade path: transition filters, `completeWhen`/`failWhen`).
+ * The subset that holds a value in the cascade gates (transition `when`s,
+ * activity filters, a cascade-fired action's `when`/`filter`).
  */
 export declare const FILTER_SCOPE_VARS: readonly string[];
 
@@ -1254,6 +1117,30 @@ export declare function groq(
   ...values: unknown[]
 ): string;
 
+/** Type-mirror of {@link GroupSchema} — one declared group. */
+declare type Group = {
+  name: string;
+  title?: string | undefined;
+  description?: string | undefined;
+  kind?: GroupKind | undefined;
+};
+
+declare const GROUP_KINDS: readonly ["core", "details"];
+
+declare type GroupKind = (typeof GROUP_KINDS)[number];
+
+/**
+ * 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.
+ */
+declare type GroupMembership = string | string[];
+
 declare type Guard = v.InferOutput<typeof GuardSchema>;
 
 /**
@@ -1340,8 +1227,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.
      */
@@ -1388,7 +1275,7 @@ declare type ManualTarget = v.InferOutput<typeof StoredManualTargetSchema>;
  * { 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";
 };
 
@@ -1472,6 +1359,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;
@@ -1479,6 +1367,30 @@ declare type StageFields<TField, TActivity, TTransition, TGuard, TEditable> = {
   editable?: Record<string, TEditable> | undefined;
 };
 
+declare const START_KINDS: readonly ["interactive", "autonomous"];
+
+declare type StartBlock = StartFields & {
+  kind: StartKind;
+};
+
+/** Type-mirror of {@link startFields}: how standalone runs of this workflow
+ *  begin. Stored requires `kind` (desugar fills the `'interactive'` default);
+ *  authoring may omit it — so each variant declares it. */
+declare type StartFields = {
+  filter?: string | undefined;
+};
+
+/**
+ * Who initiates a standalone run of this workflow: a person picking it from a
+ * start surface (`'interactive'`, the default) or a system reacting to a
+ * document event (`'autonomous'`). PURE CLASSIFICATION — consumers use it to
+ * shape their surfaces (hide autonomous workflows from human pickers, list
+ * interactive ones for editors); `startInstance` is one verb and one code
+ * path for every kind, and an interactive start of an autonomous workflow is
+ * legal.
+ */
+declare type StartKind = (typeof START_KINDS)[number];
+
 /**
  * Declared editability of a field — the generic edit seam's gate. Default
  * (absent) is NOT editable: a field is op-only engine working memory unless the
@@ -1501,142 +1413,6 @@ declare const StoredEditableSchema: v.UnionSchema<
   undefined
 >;
 
-/**
- * The `field.*` subset — every mutation op EXCEPT `status.set`. Shared by the
- * boundaries that write fields but must not set an activity status: a transition
- * (its stage's activities are tearing down, so `status.set` has no coherent
- * target) and an effect's completion (an effect is OUTSIDE the activity's own
- * awaiting — it reports its result through fields, never by flipping a status;
- * the activity/stage gate then reads those fields). The full {@link StoredOpSchema}
- * (these plus `status.set`) is what actions and activity boundaries carry.
- */
-declare const StoredFieldOpSchema: v.VariantSchema<
-  "type",
-  [
-    v.StrictObjectSchema<
-      {
-        readonly type: v.LiteralSchema<"field.set", undefined>;
-        readonly target: v.StrictObjectSchema<
-          {
-            readonly scope: v.PicklistSchema<
-              readonly ["workflow", "stage", "activity"],
-              `Invalid option: expected one of ${string}`
-            >;
-            readonly field: v.SchemaWithPipe<
-              readonly [
-                v.StringSchema<undefined>,
-                v.MinLengthAction<string, 1, "must be a non-empty string">,
-              ]
-            >;
-          },
-          undefined
-        >;
-        readonly value: v.GenericSchema<ValueExprInternal>;
-      },
-      undefined
-    >,
-    v.StrictObjectSchema<
-      {
-        readonly type: v.LiteralSchema<"field.unset", undefined>;
-        readonly target: v.StrictObjectSchema<
-          {
-            readonly scope: v.PicklistSchema<
-              readonly ["workflow", "stage", "activity"],
-              `Invalid option: expected one of ${string}`
-            >;
-            readonly field: v.SchemaWithPipe<
-              readonly [
-                v.StringSchema<undefined>,
-                v.MinLengthAction<string, 1, "must be a non-empty string">,
-              ]
-            >;
-          },
-          undefined
-        >;
-      },
-      undefined
-    >,
-    v.StrictObjectSchema<
-      {
-        readonly type: v.LiteralSchema<"field.append", undefined>;
-        readonly target: v.StrictObjectSchema<
-          {
-            readonly scope: v.PicklistSchema<
-              readonly ["workflow", "stage", "activity"],
-              `Invalid option: expected one of ${string}`
-            >;
-            readonly field: v.SchemaWithPipe<
-              readonly [
-                v.StringSchema<undefined>,
-                v.MinLengthAction<string, 1, "must be a non-empty string">,
-              ]
-            >;
-          },
-          undefined
-        >;
-        readonly value: v.GenericSchema<ValueExprInternal>;
-      },
-      undefined
-    >,
-    v.StrictObjectSchema<
-      {
-        readonly type: v.LiteralSchema<"field.updateWhere", undefined>;
-        readonly target: v.StrictObjectSchema<
-          {
-            readonly scope: v.PicklistSchema<
-              readonly ["workflow", "stage", "activity"],
-              `Invalid option: expected one of ${string}`
-            >;
-            readonly field: v.SchemaWithPipe<
-              readonly [
-                v.StringSchema<undefined>,
-                v.MinLengthAction<string, 1, "must be a non-empty string">,
-              ]
-            >;
-          },
-          undefined
-        >;
-        readonly where: v.SchemaWithPipe<
-          readonly [
-            v.StringSchema<undefined>,
-            v.MinLengthAction<string, 1, "must be a non-empty string">,
-          ]
-        >;
-        readonly value: v.GenericSchema<ValueExprInternal>;
-      },
-      undefined
-    >,
-    v.StrictObjectSchema<
-      {
-        readonly type: v.LiteralSchema<"field.removeWhere", undefined>;
-        readonly target: v.StrictObjectSchema<
-          {
-            readonly scope: v.PicklistSchema<
-              readonly ["workflow", "stage", "activity"],
-              `Invalid option: expected one of ${string}`
-            >;
-            readonly field: v.SchemaWithPipe<
-              readonly [
-                v.StringSchema<undefined>,
-                v.MinLengthAction<string, 1, "must be a non-empty string">,
-              ]
-            >;
-          },
-          undefined
-        >;
-        readonly where: v.SchemaWithPipe<
-          readonly [
-            v.StringSchema<undefined>,
-            v.MinLengthAction<string, 1, "must be a non-empty string">,
-          ]
-        >;
-      },
-      undefined
-    >,
-  ],
-  undefined
->;
-
 declare const StoredManualTargetSchema: v.VariantSchema<
   "type",
   [
@@ -1811,7 +1587,7 @@ declare const StoredOpSchema: v.VariantSchema<
           ]
         >;
         readonly status: v.PicklistSchema<
-          readonly ["pending", "active", "done", "skipped", "failed"],
+          readonly ["active", "done", "skipped", "failed"],
           `Invalid option: expected one of ${string}`
         >;
       },
@@ -1825,7 +1601,14 @@ 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>,
@@ -1880,8 +1663,8 @@ declare const SubworkflowsSchema: v.StrictObjectSchema<
     >;
     /**
      * Extra values evaluated in the parent's rendered scope at spawn time and
-     * delivered into each subworkflow's `$effects` bag — the parent→child
-     * handoff, read exactly like an effect output.
+     * delivered into each subworkflow's `$context` bag — the parent→child
+     * handoff.
      */
     readonly context: v.OptionalSchema<
       v.RecordSchema<
@@ -1901,6 +1684,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-fire's `forEach` no longer
+     * discovers their row. `'detach'` (the default) lets them run to
+     * completion outside the gate; `'abort'` kills them (recursively). The
+     * engine never destroys in-flight work implicitly — `'abort'` is always
+     * an authored choice. Note this governs only the CHILDREN's fate; whether
+     * the parent may move at all is what gates (conditions over
+     * `$subworkflows`) decide.
+     */
+    readonly onExit: v.OptionalSchema<
+      v.PicklistSchema<
+        readonly ["detach", "abort"],
+        `Invalid option: expected one of ${string}`
+      >,
+      undefined
+    >;
   },
   undefined
 >;
@@ -1919,27 +1719,23 @@ declare type TerminalActivityStatus =
  * { 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";
 };
 
-declare type Transition = TransitionFields<TransitionOp> & {
-  filter: string;
+declare type Transition = TransitionFields & {
+  when: string;
 };
 
-/** Type-mirror of {@link transitionFields} minus `filter` — stored requires it,
+/** Type-mirror of {@link transitionFields} minus `when` — stored requires it,
  *  authoring omits it (desugar fills the default), so each variant declares it. */
-declare type TransitionFields<TOp> = {
+declare type TransitionFields = {
   name: string;
   title?: string | undefined;
   description?: string | undefined;
   to: string;
-  ops?: TOp[] | undefined;
-  effects?: Effect[] | undefined;
 };
 
-declare type TransitionOp = FieldOp;
-
 declare type ValueExprInternal =
   | LiteralExpr
   | FieldReadExpr
@@ -2202,7 +1998,9 @@ declare const WorkflowConfigSchema: v.ObjectSchema<
                         name: string;
                         title: string;
                         description?: string | undefined;
+                        groups?: Group[] | undefined;
                         lifecycle?: WorkflowLifecycle | undefined;
+                        start?: StartBlock | undefined;
                         initialStage: string;
                         fields?: FieldEntry[] | undefined;
                         stages: Stage[];
@@ -2218,7 +2016,9 @@ declare const WorkflowConfigSchema: v.ObjectSchema<
                       name: string;
                       title: string;
                       description?: string | undefined;
+                      groups?: Group[] | undefined;
                       lifecycle?: WorkflowLifecycle | undefined;
+                      start?: StartBlock | undefined;
                       initialStage: string;
                       fields?: FieldEntry[] | undefined;
                       stages: Stage[];
@@ -2282,7 +2082,9 @@ declare const WorkflowConfigSchema: v.ObjectSchema<
               name: string;
               title: string;
               description?: string | undefined;
+              groups?: Group[] | undefined;
               lifecycle?: WorkflowLifecycle | undefined;
+              start?: StartBlock | undefined;
               initialStage: string;
               fields?: FieldEntry[] | undefined;
               stages: Stage[];
@@ -2340,7 +2142,9 @@ declare const WorkflowConfigSchema: v.ObjectSchema<
               name: string;
               title: string;
               description?: string | undefined;
+              groups?: Group[] | undefined;
               lifecycle?: WorkflowLifecycle | undefined;
+              start?: StartBlock | undefined;
               initialStage: string;
               fields?: FieldEntry[] | undefined;
               stages: Stage[];
@@ -2352,6 +2156,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
 >;
@@ -2374,15 +2193,17 @@ declare type WorkflowDefinition = v.InferOutput<
  * mints the next version.
  */
 declare const WorkflowDefinitionSchema: v.GenericSchema<
-  WorkflowFields<FieldEntry, Stage>
+  WorkflowFields<FieldEntry, Stage, StartBlock>
 >;
 
-/** Type-mirror of {@link workflowFields}, parameterised over field/stage. */
-declare type WorkflowFields<TField, TStage> = {
+/** Type-mirror of {@link workflowFields}, parameterised over field/stage/start. */
+declare type WorkflowFields<TField, TStage, TStart> = {
   name: string;
   title: string;
   description?: string | undefined;
+  groups?: Group[] | undefined;
   lifecycle?: WorkflowLifecycle | undefined;
+  start?: TStart | undefined;
   initialStage: string;
   fields?: TField[] | undefined;
   stages: TStage[];
@@ -2395,4 +2216,35 @@ declare type WorkflowFields<TField, TStage> = {
  *  {@link isStartableDefinition}. */
 declare type WorkflowLifecycle = (typeof WORKFLOW_LIFECYCLES)[number];
 
+/**
+ * A telemetry event descriptor — a structural mirror of `@sanity/telemetry`'s
+ * `DefinedTelemetryLog`, so shells hand these straight to their store logger.
+ */
+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.
+ */
+declare interface WorkflowTelemetryLogger {
+  log<Data>(event: WorkflowTelemetryEvent<Data>, data: Data): void;
+  log(event: WorkflowTelemetryEvent<void>): void;
+}
+
 export {};