@sanity/workflow-engine 0.15.0 → 0.17.0

package/dist/define.d.ts

@@ -1,6 +1,8 @@
 import * as v from "valibot";
 
-declare type Action = ActionFields<Op, string[]>;
+declare type Action = ActionFields<Op, string[]> & {
+  roles?: string[] | undefined;
+};
 
 /** Type-mirror of {@link actionFields}, parameterised over the op and
  *  group-membership grammars. */
@@ -9,10 +11,12 @@ declare type ActionFields<TOp, TGroup> = {
   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>;
@@ -58,48 +62,29 @@ declare const ActionParamSchema: v.StrictObjectSchema<
 declare type Activity = ActivityFields<
   FieldEntry,
   Action,
-  Op,
   ManualTarget,
   string[]
 >;
 
-declare const ACTIVITY_KINDS: readonly [
-  "user",
-  "service",
-  "script",
-  "manual",
-  "receive",
-];
-
-/** Type-mirror of {@link activityFields}, parameterised over field/action/op/target/group. */
-declare type ActivityFields<TField, TAction, TOp, TTarget, TGroup> = {
+/** 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;
   groups?: Group[] | undefined;
   group?: TGroup | undefined;
-  kind?: ActivityKind | 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,
   GroupMembership
 >;
@@ -165,6 +150,11 @@ declare type AuthoringGuard = v.InferOutput<typeof AuthoringGuardSchema>;
 
 declare const AuthoringGuardSchema: v.StrictObjectSchema<
   {
+    /**
+     * Lake-id-segment grammar (`^[a-z0-9][a-z0-9-]*$`, deploy-enforced): the
+     * guard's lake `_id` derives from `(instanceId, name)` at stage entry.
+     * Unique per definition.
+     */
     name: v.SchemaWithPipe<
       readonly [
         v.StringSchema<undefined>,
@@ -326,8 +316,9 @@ declare const AuthoringGuardSchema: v.StrictObjectSchema<
     /**
      * 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.
+     * `identity()`. Bare ids/fields only. Polarity: a result of strictly
+     * `true` ALLOWS the matched mutation; anything else (false, null, an
+     * evaluation error) DENIES. Omitted or empty means UNCONDITIONAL DENY.
      */
     predicate: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
     /**
@@ -659,7 +650,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}`
         >;
       },
@@ -724,15 +715,21 @@ 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, GroupMembership> & {
@@ -753,216 +750,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
 >;
 
 /**
@@ -1022,25 +827,33 @@ export declare interface ConditionVar {
  * 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 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
+ * 2. **Cascade gates** — transition `when`s, activity filters, and a
+ *    cascade-fired action's `when`/`filter` must resolve identically no
+ *    matter whose token drives the cascade, so only the `'always'`-bound
+ *    subset carries values there ({@link FILTER_SCOPE_VARS}). Caller-bound
+ *    vars fail closed — `$assigned` binds its caller-free constant `false`,
+ *    the rest evaluate to `undefined` — and deploy rejects them at these
+ *    sites; a cascade-fired action's per-token gate is `roles`, never its
+ *    conditions.
+ * 3. **The start contexts** — a definition's `start.filter` and
+ *    `start.allowed` evaluate against a CANDIDATE (no instance exists yet):
+ *    `*[...]` reads the WORKFLOW resource's dataset and none of the rendered
+ *    condition vars exist. The two split on what a surface can know:
+ *    `filter` is browse-time-pure (candidate document as root,
+ *    {@link START_FILTER_VARS} — no `$fields`, which cannot exist before
+ *    inputs do), `allowed` is the start-time permission predicate
+ *    ({@link START_ALLOWED_VARS} — `$fields` bound, never a root).
+ * 4. **Guard predicates** — NOT conditions. A lake mutation guard's
  *    `predicate` is groq-js **delta-mode** GROQ over a document mutation:
  *    `before()`/`after()`/`identity()` are dialect natives, and the wire
  *    format binds the identifiers in {@link GUARD_PREDICATE_VARS}. None of
@@ -1053,8 +866,8 @@ export declare interface ConditionVar {
  *   instance and its snapshot.
  * - `'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 (the per-row `$row`).
+ *   these — they pre-evaluate caller-free, per evaluation context.
+ * - `'spawn'` — bound only at spawn sites (the per-row `$row`).
  */
 export declare type ConditionVarBinding = "always" | "caller" | "spawn";
 
@@ -1115,8 +928,9 @@ export declare function defineWorkflow(
 /**
  * Validate a deploy config — the binding of each definition's logical resource
  * handles to physical resources, per environment (tag). Throws a formatted,
- * path-prefixed error if the shape is invalid. The CLI hands the selected
- * deployment's {@link resourceAliasesToMap} map to {@link deployDefinitions}.
+ * path-prefixed error if the shape is invalid. The CLI collapses the selected
+ * deployment's bindings via {@link resourceAliasesToMap} into the
+ * `resourceAliases` map `deployDefinitions` expands against.
  */
 export declare function defineWorkflowConfig(
   config: WorkflowConfig,
@@ -1187,8 +1001,9 @@ declare const EffectSchema: v.StrictObjectSchema<
      * 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
+     * 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.
@@ -1254,8 +1069,6 @@ declare type FieldEntryFields<TEditable, TGroup> = FieldBase<
   of?: FieldShape[] | undefined;
 };
 
-declare type FieldOp = v.InferOutput<typeof StoredFieldOpSchema>;
-
 declare type FieldReadExpr = {
   type: "fieldRead";
   scope?: "workflow" | "stage" | undefined;
@@ -1289,9 +1102,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, activity `filter`/
- * `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[];
 
@@ -1356,6 +1168,11 @@ export declare const GUARD_PREDICATE_VARS: readonly {
 /** Stored guards carry the printed string reads (the deploy resolver's input). */
 declare const GuardSchema: v.StrictObjectSchema<
   {
+    /**
+     * Lake-id-segment grammar (`^[a-z0-9][a-z0-9-]*$`, deploy-enforced): the
+     * guard's lake `_id` derives from `(instanceId, name)` at stage entry.
+     * Unique per definition.
+     */
     name: v.SchemaWithPipe<
       readonly [
         v.StringSchema<undefined>,
@@ -1427,8 +1244,9 @@ declare const GuardSchema: v.StrictObjectSchema<
     /**
      * 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.
+     * `identity()`. Bare ids/fields only. Polarity: a result of strictly
+     * `true` ALLOWS the matched mutation; anything else (false, null, an
+     * evaluation error) DENIES. Omitted or empty means UNCONDITIONAL DENY.
      */
     predicate: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
     /**
@@ -1565,6 +1383,31 @@ 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;
+  allowed?: 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
@@ -1587,142 +1430,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",
   [
@@ -1897,7 +1604,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}`
         >;
       },
@@ -1973,8 +1680,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<
@@ -1996,13 +1703,13 @@ declare const SubworkflowsSchema: v.StrictObjectSchema<
     >;
     /**
      * 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
+     * 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 (`completeWhen`, transition
-     * filters over `$subworkflows`) decide.
+     * the parent may move at all is what gates (conditions over
+     * `$subworkflows`) decide.
      */
     readonly onExit: v.OptionalSchema<
       v.PicklistSchema<
@@ -2033,23 +1740,19 @@ 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
@@ -2314,7 +2017,7 @@ declare const WorkflowConfigSchema: v.ObjectSchema<
                         description?: string | undefined;
                         groups?: Group[] | undefined;
                         lifecycle?: WorkflowLifecycle | undefined;
-                        applicableWhen?: string | undefined;
+                        start?: StartBlock | undefined;
                         initialStage: string;
                         fields?: FieldEntry[] | undefined;
                         stages: Stage[];
@@ -2332,7 +2035,7 @@ declare const WorkflowConfigSchema: v.ObjectSchema<
                       description?: string | undefined;
                       groups?: Group[] | undefined;
                       lifecycle?: WorkflowLifecycle | undefined;
-                      applicableWhen?: string | undefined;
+                      start?: StartBlock | undefined;
                       initialStage: string;
                       fields?: FieldEntry[] | undefined;
                       stages: Stage[];
@@ -2398,7 +2101,7 @@ declare const WorkflowConfigSchema: v.ObjectSchema<
               description?: string | undefined;
               groups?: Group[] | undefined;
               lifecycle?: WorkflowLifecycle | undefined;
-              applicableWhen?: string | undefined;
+              start?: StartBlock | undefined;
               initialStage: string;
               fields?: FieldEntry[] | undefined;
               stages: Stage[];
@@ -2458,7 +2161,7 @@ declare const WorkflowConfigSchema: v.ObjectSchema<
               description?: string | undefined;
               groups?: Group[] | undefined;
               lifecycle?: WorkflowLifecycle | undefined;
-              applicableWhen?: string | undefined;
+              start?: StartBlock | undefined;
               initialStage: string;
               fields?: FieldEntry[] | undefined;
               stages: Stage[];
@@ -2507,17 +2210,23 @@ 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> = {
+  /**
+   * Lake-id-segment grammar (`^[a-z0-9][a-z0-9-]*$`, deploy-enforced): the
+   * name interpolates into every deployed document id
+   * (`<tag>.<name>.v<version>`). Stable identity — instances pin to it,
+   * subworkflows resolve by it.
+   */
   name: string;
   title: string;
   description?: string | undefined;
   groups?: Group[] | undefined;
   lifecycle?: WorkflowLifecycle | undefined;
-  applicableWhen?: string | undefined;
+  start?: TStart | undefined;
   initialStage: string;
   fields?: TField[] | undefined;
   stages: TStage[];