@sanity/workflow-engine 0.13.0 → 0.15.0

package/dist/define.d.cts

@@ -1,12 +1,14 @@
 import * as v from "valibot";
 
-declare type Action = ActionFields<Op>;
+declare type Action = ActionFields<Op, string[]>;
 
-/** 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;
@@ -53,7 +55,13 @@ declare const ActionParamSchema: v.StrictObjectSchema<
   undefined
 >;
 
-declare type Activity = ActivityFields<FieldEntry, Action, Op, ManualTarget>;
+declare type Activity = ActivityFields<
+  FieldEntry,
+  Action,
+  Op,
+  ManualTarget,
+  string[]
+>;
 
 declare const ACTIVITY_KINDS: readonly [
   "user",
@@ -63,11 +71,13 @@ declare const ACTIVITY_KINDS: readonly [
   "receive",
 ];
 
-/** 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;
@@ -90,7 +100,8 @@ declare type AuthoringActivity = ActivityFields<
   AuthoringFieldEntry,
   AuthoringAction,
   AuthoringOp,
-  AuthoringManualTarget
+  AuthoringManualTarget,
+  GroupMembership
 >;
 
 declare type AuthoringEditable = v.InferOutput<typeof AuthoringEditableSchema>;
@@ -98,7 +109,7 @@ declare type AuthoringEditable = v.InferOutput<typeof AuthoringEditableSchema>;
 /**
  * Authoring editability adds the `role[]` convenience: a non-empty role list
  * desugars to the same `count($actor.roles[@ in [...]]) > 0` membership
- * predicate `action.roles` produces. `true` opens the slot to anyone in its
+ * predicate `action.roles` produces. `true` opens the field to anyone in its
  * window; a bare string is a raw predicate.
  */
 declare const AuthoringEditableSchema: v.UnionSchema<
@@ -150,6 +161,292 @@ declare const AuthoringFieldRefSchema: v.StrictObjectSchema<
   undefined
 >;
 
+declare type AuthoringGuard = v.InferOutput<typeof AuthoringGuardSchema>;
+
+declare const AuthoringGuardSchema: v.StrictObjectSchema<
+  {
+    name: v.SchemaWithPipe<
+      readonly [
+        v.StringSchema<undefined>,
+        v.MinLengthAction<string, 1, "must be a non-empty string">,
+      ]
+    >;
+    title: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    description: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    match: v.StrictObjectSchema<
+      {
+        /** Subject `_type`(s); empty matches any type. */
+        types: v.OptionalSchema<
+          v.ArraySchema<
+            v.SchemaWithPipe<
+              readonly [
+                v.StringSchema<undefined>,
+                v.MinLengthAction<string, 1, "must be a non-empty string">,
+              ]
+            >,
+            undefined
+          >,
+          undefined
+        >;
+        /** Target docs as field reads (or the instance itself), resolved at deploy to bare ids + the resource. */
+        idRefs: v.OptionalSchema<
+          v.ArraySchema<
+            v.VariantSchema<
+              "type",
+              [
+                v.StrictObjectSchema<
+                  {
+                    readonly type: v.LiteralSchema<"self", undefined>;
+                  },
+                  undefined
+                >,
+                v.StrictObjectSchema<
+                  {
+                    readonly type: v.LiteralSchema<"now", undefined>;
+                  },
+                  undefined
+                >,
+                v.StrictObjectSchema<
+                  {
+                    readonly type: v.LiteralSchema<"fieldRead", undefined>;
+                    readonly field: v.SchemaWithPipe<
+                      readonly [
+                        v.StringSchema<undefined>,
+                        v.RegexAction<string, string>,
+                      ]
+                    >;
+                    readonly path: v.OptionalSchema<
+                      v.SchemaWithPipe<
+                        readonly [
+                          v.SchemaWithPipe<
+                            readonly [
+                              v.StringSchema<undefined>,
+                              v.MinLengthAction<
+                                string,
+                                1,
+                                "must be a non-empty string"
+                              >,
+                            ]
+                          >,
+                          v.CheckAction<
+                            string,
+                            "a guard read path cannot contain a line break"
+                          >,
+                        ]
+                      >,
+                      undefined
+                    >;
+                  },
+                  undefined
+                >,
+                v.StrictObjectSchema<
+                  {
+                    readonly type: v.LiteralSchema<"effectsRead", undefined>;
+                    readonly effect: v.SchemaWithPipe<
+                      readonly [
+                        v.SchemaWithPipe<
+                          readonly [
+                            v.StringSchema<undefined>,
+                            v.MinLengthAction<
+                              string,
+                              1,
+                              "must be a non-empty string"
+                            >,
+                          ]
+                        >,
+                        v.CheckAction<
+                          string,
+                          "an effect name cannot contain `'`"
+                        >,
+                      ]
+                    >;
+                    readonly path: v.OptionalSchema<
+                      v.SchemaWithPipe<
+                        readonly [
+                          v.SchemaWithPipe<
+                            readonly [
+                              v.StringSchema<undefined>,
+                              v.MinLengthAction<
+                                string,
+                                1,
+                                "must be a non-empty string"
+                              >,
+                            ]
+                          >,
+                          v.CheckAction<
+                            string,
+                            "a guard read path cannot contain a line break"
+                          >,
+                        ]
+                      >,
+                      undefined
+                    >;
+                  },
+                  undefined
+                >,
+              ],
+              undefined
+            >,
+            undefined
+          >,
+          undefined
+        >;
+        /** Glob id patterns (bare, resource-local). */
+        idPatterns: v.OptionalSchema<
+          v.ArraySchema<
+            v.SchemaWithPipe<
+              readonly [
+                v.StringSchema<undefined>,
+                v.MinLengthAction<string, 1, "must be a non-empty string">,
+              ]
+            >,
+            undefined
+          >,
+          undefined
+        >;
+        actions: v.SchemaWithPipe<
+          readonly [
+            v.ArraySchema<
+              v.PicklistSchema<
+                readonly ["create", "update", "delete", "publish", "unpublish"],
+                `Invalid option: expected one of ${string}`
+              >,
+              undefined
+            >,
+            v.MinLengthAction<
+              ("create" | "update" | "delete" | "publish" | "unpublish")[],
+              1,
+              "a guard must match at least one action"
+            >,
+          ]
+        >;
+      },
+      undefined
+    >;
+    /**
+     * 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.
+     */
+    predicate: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    /**
+     * Projected workflow fields the predicate reads as `guard.metadata.*` —
+     * the only bridge from the lake eval context (which cannot see `$fields`)
+     * to workflow fields. Each value is a deploy-time read — a typed
+     * {@link GuardRead} when authoring, the printed string spelling once
+     * stored — resolved into a bare value at deploy and re-synced by the
+     * post-field-op guard refresh.
+     */
+    metadata: v.OptionalSchema<
+      v.RecordSchema<
+        v.SchemaWithPipe<
+          readonly [
+            v.StringSchema<undefined>,
+            v.MinLengthAction<string, 1, "must be a non-empty string">,
+          ]
+        >,
+        v.VariantSchema<
+          "type",
+          [
+            v.StrictObjectSchema<
+              {
+                readonly type: v.LiteralSchema<"self", undefined>;
+              },
+              undefined
+            >,
+            v.StrictObjectSchema<
+              {
+                readonly type: v.LiteralSchema<"now", undefined>;
+              },
+              undefined
+            >,
+            v.StrictObjectSchema<
+              {
+                readonly type: v.LiteralSchema<"fieldRead", undefined>;
+                readonly field: v.SchemaWithPipe<
+                  readonly [
+                    v.StringSchema<undefined>,
+                    v.RegexAction<string, string>,
+                  ]
+                >;
+                readonly path: v.OptionalSchema<
+                  v.SchemaWithPipe<
+                    readonly [
+                      v.SchemaWithPipe<
+                        readonly [
+                          v.StringSchema<undefined>,
+                          v.MinLengthAction<
+                            string,
+                            1,
+                            "must be a non-empty string"
+                          >,
+                        ]
+                      >,
+                      v.CheckAction<
+                        string,
+                        "a guard read path cannot contain a line break"
+                      >,
+                    ]
+                  >,
+                  undefined
+                >;
+              },
+              undefined
+            >,
+            v.StrictObjectSchema<
+              {
+                readonly type: v.LiteralSchema<"effectsRead", undefined>;
+                readonly effect: v.SchemaWithPipe<
+                  readonly [
+                    v.SchemaWithPipe<
+                      readonly [
+                        v.StringSchema<undefined>,
+                        v.MinLengthAction<
+                          string,
+                          1,
+                          "must be a non-empty string"
+                        >,
+                      ]
+                    >,
+                    v.CheckAction<string, "an effect name cannot contain `'`">,
+                  ]
+                >;
+                readonly path: v.OptionalSchema<
+                  v.SchemaWithPipe<
+                    readonly [
+                      v.SchemaWithPipe<
+                        readonly [
+                          v.StringSchema<undefined>,
+                          v.MinLengthAction<
+                            string,
+                            1,
+                            "must be a non-empty string"
+                          >,
+                        ]
+                      >,
+                      v.CheckAction<
+                        string,
+                        "a guard read path cannot contain a line break"
+                      >,
+                    ]
+                  >,
+                  undefined
+                >;
+              },
+              undefined
+            >,
+          ],
+          undefined
+        >,
+        undefined
+      >,
+      undefined
+    >;
+  },
+  undefined
+>;
+
 declare type AuthoringManualTarget = v.InferOutput<
   typeof AuthoringManualTargetSchema
 >;
@@ -309,7 +606,12 @@ declare const AuthoringOpSchema: v.VariantSchema<
           },
           undefined
         >;
-        readonly where: v.GenericSchema<OpPredicateInternal>;
+        readonly where: v.SchemaWithPipe<
+          readonly [
+            v.StringSchema<undefined>,
+            v.MinLengthAction<string, 1, "must be a non-empty string">,
+          ]
+        >;
         readonly value: v.GenericSchema<ValueExprInternal>;
       },
       undefined
@@ -335,7 +637,12 @@ declare const AuthoringOpSchema: v.VariantSchema<
           },
           undefined
         >;
-        readonly where: v.GenericSchema<OpPredicateInternal>;
+        readonly where: v.SchemaWithPipe<
+          readonly [
+            v.StringSchema<undefined>,
+            v.MinLengthAction<string, 1, "must be a non-empty string">,
+          ]
+        >;
       },
       undefined
     >,
@@ -423,19 +730,26 @@ declare const AuthoringOpSchema: v.VariantSchema<
  *   - `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).
+ *     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
+ *     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,
   AuthoringActivity,
   AuthoringTransition,
+  AuthoringGuard,
   AuthoringEditable
 >;
 
@@ -550,7 +864,12 @@ declare const AuthoringTransitionOpSchema: v.VariantSchema<
           },
           undefined
         >;
-        readonly where: v.GenericSchema<OpPredicateInternal>;
+        readonly where: v.SchemaWithPipe<
+          readonly [
+            v.StringSchema<undefined>,
+            v.MinLengthAction<string, 1, "must be a non-empty string">,
+          ]
+        >;
         readonly value: v.GenericSchema<ValueExprInternal>;
       },
       undefined
@@ -576,7 +895,12 @@ declare const AuthoringTransitionOpSchema: v.VariantSchema<
           },
           undefined
         >;
-        readonly where: v.GenericSchema<OpPredicateInternal>;
+        readonly where: v.SchemaWithPipe<
+          readonly [
+            v.StringSchema<undefined>,
+            v.MinLengthAction<string, 1, "must be a non-empty string">,
+          ]
+        >;
       },
       undefined
     >,
@@ -654,6 +978,7 @@ declare type ClaimAction = {
   name: string;
   title?: string | undefined;
   description?: string | undefined;
+  group?: GroupMembership | undefined;
   field: string | AuthoringFieldRef;
   roles?: string[] | undefined;
   filter?: string | undefined;
@@ -664,7 +989,7 @@ declare type ClaimAction = {
 /**
  * Authoring fields accept the raw entries plus the `claim` sugar type — the
  * field half of the mirrored claim pair. Expansion: an `actor` working-
- * memory slot (no `initialValue`; the claim action's op fills it), strictly
+ * memory field (no `initialValue`; the claim action's op fills it), strictly
  * within this entry.
  */
 declare type ClaimField = {
@@ -672,8 +997,67 @@ declare type ClaimField = {
   name: string;
   title?: string | undefined;
   description?: string | undefined;
+  group?: GroupMembership | undefined;
 };
 
+/**
+ * Every variable the engine binds for conditions, in one place. The
+ * deploy-time shadow check ({@link RESERVED_CONDITION_VARS}) and the docs on
+ * {@link Condition} derive from this list — extend it here when the engine
+ * grows a binding, never in a comment elsewhere.
+ */
+export declare const CONDITION_VARS: readonly ConditionVar[];
+
+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;
+}
+
+/**
+ * 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:
+ *
+ * 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
+ *    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
+ *    `predicate` is groq-js **delta-mode** GROQ over a document mutation:
+ *    `before()`/`after()`/`identity()` are dialect natives, and the wire
+ *    format binds the identifiers in {@link GUARD_PREDICATE_VARS}. None of
+ *    the condition vars exist there.
+ */
+/**
+ * When a condition var holds a value:
+ *
+ * - `'always'` — bound in every condition evaluation, derived from the
+ *   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`).
+ */
+export declare type ConditionVarBinding = "always" | "caller" | "spawn";
+
 export declare function defineAction(action: AuthoringAction): AuthoringAction;
 
 export declare function defineActivity(
@@ -694,7 +1078,15 @@ export declare function defineField(
   entry: AuthoringFieldEntry,
 ): AuthoringFieldEntry;
 
-export declare function defineGuard(guard: Guard): Guard;
+/**
+ * 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;
 
@@ -720,6 +1112,16 @@ export declare function defineWorkflow(
   definition: AuthoringWorkflow,
 ): WorkflowDefinition;
 
+/**
+ * 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}.
+ */
+export declare function defineWorkflowConfig(
+  config: WorkflowConfig,
+): WorkflowConfig;
+
 declare type Editable = v.InferOutput<typeof StoredEditableSchema>;
 
 declare type Effect = v.InferOutput<typeof EffectSchema>;
@@ -775,6 +1177,26 @@ 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
 >;
@@ -784,6 +1206,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",
@@ -803,12 +1228,28 @@ declare const FIELD_VALUE_KINDS: readonly [
   "array",
 ];
 
-declare type FieldEntry = FieldEntryFields<Editable>;
+/** 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, string[]>;
 
 /** Type-mirror of {@link fieldEntryFields}: a raw field entry of the given
- *  editability grammar. */
-declare type FieldEntryFields<TEditable> = SlotFields<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;
 };
@@ -847,6 +1288,13 @@ declare type FieldSourceInternal =
 /** The union a value (or nested {@link FieldShape}) kind may take — see {@link FIELD_VALUE_KINDS}. */
 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`).
+ */
+export declare const FILTER_SCOPE_VARS: readonly string[];
+
 /**
  * Hygienic GROQ interpolation for define-time condition building.
  *
@@ -867,25 +1315,59 @@ 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>;
 
+/**
+ * The identifiers a lake mutation guard's `predicate` reads — the wire
+ * dialect, not the condition scope (so no {@link ConditionVarBinding}: these
+ * bind only when a guard evaluates a mutation). `before()`/`after()`/
+ * `identity()` are groq-js delta-mode natives on top of these. Bound in one
+ * place: `guardPredicateParams` in the guard evaluator.
+ */
+export declare const GUARD_PREDICATE_VARS: readonly {
+  name: string;
+  description: string;
+}[];
+
+/** Stored guards carry the printed string reads (the deploy resolver's input). */
 declare const GuardSchema: v.StrictObjectSchema<
   {
-    readonly name: v.SchemaWithPipe<
+    name: v.SchemaWithPipe<
       readonly [
         v.StringSchema<undefined>,
         v.MinLengthAction<string, 1, "must be a non-empty string">,
       ]
     >;
-    readonly title: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
-    readonly description: v.OptionalSchema<
-      v.StringSchema<undefined>,
-      undefined
-    >;
-    readonly match: v.StrictObjectSchema<
+    title: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    description: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    match: v.StrictObjectSchema<
       {
         /** Subject `_type`(s); empty matches any type. */
-        readonly types: v.OptionalSchema<
+        types: v.OptionalSchema<
           v.ArraySchema<
             v.SchemaWithPipe<
               readonly [
@@ -897,8 +1379,8 @@ declare const GuardSchema: v.StrictObjectSchema<
           >,
           undefined
         >;
-        /** Target docs as `$fields` reads (or `"$self"`), resolved at deploy to bare ids + the resource. */
-        readonly idRefs: v.OptionalSchema<
+        /** Target docs as field reads (or the instance itself), resolved at deploy to bare ids + the resource. */
+        idRefs: v.OptionalSchema<
           v.ArraySchema<
             v.SchemaWithPipe<
               readonly [
@@ -911,7 +1393,7 @@ declare const GuardSchema: v.StrictObjectSchema<
           undefined
         >;
         /** Glob id patterns (bare, resource-local). */
-        readonly idPatterns: v.OptionalSchema<
+        idPatterns: v.OptionalSchema<
           v.ArraySchema<
             v.SchemaWithPipe<
               readonly [
@@ -923,7 +1405,7 @@ declare const GuardSchema: v.StrictObjectSchema<
           >,
           undefined
         >;
-        readonly actions: v.SchemaWithPipe<
+        actions: v.SchemaWithPipe<
           readonly [
             v.ArraySchema<
               v.PicklistSchema<
@@ -943,21 +1425,21 @@ 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.
      */
-    readonly predicate: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    predicate: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
     /**
      * Projected workflow fields the predicate reads as `guard.metadata.*` —
      * the only bridge from the lake eval context (which cannot see `$fields`)
-     * to workflow fields. Values are NOT GROQ: each is a deploy-time read in
-     * the guard mini-language — `"$self"`, `"$now"`, or
-     * `"$fields.<name>[.path]"` — resolved into a bare value at deploy and
-     * re-synced by the post-field-op guard refresh.
+     * to workflow fields. Each value is a deploy-time read — a typed
+     * {@link GuardRead} when authoring, the printed string spelling once
+     * stored — resolved into a bare value at deploy and re-synced by the
+     * post-field-op guard refresh.
      */
-    readonly metadata: v.OptionalSchema<
+    metadata: v.OptionalSchema<
       v.RecordSchema<
         v.SchemaWithPipe<
           readonly [
@@ -991,26 +1473,19 @@ 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 = SlotFields<AuthoringEditable> & {
+declare type NotesField = FieldBase<AuthoringEditable, GroupMembership> & {
   type: "notes";
 };
 
 declare type Op = v.InferOutput<typeof StoredOpSchema>;
 
-declare type OpPredicateInternal =
-  | {
-      type: "field";
-      field: string;
-      equals: ValueExpr;
-    }
-  | {
-      type: "all";
-      of: OpPredicateInternal[];
-    }
-  | {
-      type: "any";
-      of: OpPredicateInternal[];
-    };
+/**
+ * Names an author's predicate may not use — engine-owned and author names
+ * share one namespace, so a predicate redefining a binding would silently
+ * shadow engine behaviour. Rejected at deploy; derived from
+ * {@link CONDITION_VARS}.
+ */
+export declare const RESERVED_CONDITION_VARS: readonly string[];
 
 declare type RoleAliases = v.InferOutput<typeof RoleAliasesSchema>;
 
@@ -1069,38 +1544,35 @@ declare const RoleAliasesSchema: v.RecordSchema<
   undefined
 >;
 
-/** Type-mirror of {@link slotFields}, parameterised over the `editable` grammar. */
-declare type SlotFields<TEditable> = {
-  name: string;
-  title?: string | undefined;
-  description?: string | undefined;
-  required?: boolean | undefined;
-  initialValue?: FieldSource | undefined;
-  editable?: TEditable | undefined;
-};
-
-declare type Stage = StageFields<FieldEntry, Activity, Transition, Editable>;
+declare type Stage = StageFields<
+  FieldEntry,
+  Activity,
+  Transition,
+  Guard,
+  Editable
+>;
 
-/** Type-mirror of {@link stageFields}, parameterised over field/activity/transition/editable. */
-declare type StageFields<TField, TActivity, TTransition, TEditable> = {
+/** Type-mirror of {@link stageFields}, parameterised over field/activity/transition/guard/editable. */
+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?: Guard[] | undefined;
+  guards?: TGuard[] | undefined;
   fields?: TField[] | undefined;
   editable?: Record<string, TEditable> | undefined;
 };
 
 /**
- * Declared editability of a field slot — the generic edit seam's gate. Default
- * (absent) is NOT editable: a slot is op-only engine working memory unless the
+ * Declared editability of a field — the generic edit seam's gate. Default
+ * (absent) is NOT editable: a field is op-only engine working memory unless the
  * modeler opens it. The stored form is `true` (editable by anyone within the
- * slot's scope window) or a GROQ predicate over the rendered scope (`$actor`,
+ * field's scope window) or an EDIT CONDITION — rendered-scope GROQ (`$actor`,
  * `$can`, `$fields`, `$assigned`), checked like an action filter to decide
  * who-may-edit. ADVISORY like every engine gate — it disables the inline field
- * and explains; real immutability needs a lake {@link Guard}.
+ * and explains; a {@link Guard} declares the intended write-lock.
  */
 declare const StoredEditableSchema: v.UnionSchema<
   [
@@ -1210,7 +1682,12 @@ declare const StoredFieldOpSchema: v.VariantSchema<
           },
           undefined
         >;
-        readonly where: v.GenericSchema<OpPredicateInternal>;
+        readonly where: v.SchemaWithPipe<
+          readonly [
+            v.StringSchema<undefined>,
+            v.MinLengthAction<string, 1, "must be a non-empty string">,
+          ]
+        >;
         readonly value: v.GenericSchema<ValueExprInternal>;
       },
       undefined
@@ -1233,7 +1710,12 @@ declare const StoredFieldOpSchema: v.VariantSchema<
           },
           undefined
         >;
-        readonly where: v.GenericSchema<OpPredicateInternal>;
+        readonly where: v.SchemaWithPipe<
+          readonly [
+            v.StringSchema<undefined>,
+            v.MinLengthAction<string, 1, "must be a non-empty string">,
+          ]
+        >;
       },
       undefined
     >,
@@ -1368,7 +1850,12 @@ declare const StoredOpSchema: v.VariantSchema<
           },
           undefined
         >;
-        readonly where: v.GenericSchema<OpPredicateInternal>;
+        readonly where: v.SchemaWithPipe<
+          readonly [
+            v.StringSchema<undefined>,
+            v.MinLengthAction<string, 1, "must be a non-empty string">,
+          ]
+        >;
         readonly value: v.GenericSchema<ValueExprInternal>;
       },
       undefined
@@ -1391,7 +1878,12 @@ declare const StoredOpSchema: v.VariantSchema<
           },
           undefined
         >;
-        readonly where: v.GenericSchema<OpPredicateInternal>;
+        readonly where: v.SchemaWithPipe<
+          readonly [
+            v.StringSchema<undefined>,
+            v.MinLengthAction<string, 1, "must be a non-empty string">,
+          ]
+        >;
       },
       undefined
     >,
@@ -1419,7 +1911,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>,
@@ -1495,6 +1994,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
 >;
@@ -1513,7 +2029,7 @@ 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 = SlotFields<AuthoringEditable> & {
+declare type TodoListField = FieldBase<AuthoringEditable, GroupMembership> & {
   type: "todoList";
 };
 
@@ -1534,8 +2050,6 @@ declare type TransitionFields<TOp> = {
 
 declare type TransitionOp = FieldOp;
 
-declare type ValueExpr = ValueExprInternal;
-
 declare type ValueExprInternal =
   | LiteralExpr
   | FieldReadExpr
@@ -1560,7 +2074,420 @@ declare type ValueExprInternal =
       fields: Record<string, ValueExprInternal>;
     };
 
-declare const WORKFLOW_ROLES: readonly ["workflow", "child"];
+declare const WORKFLOW_LIFECYCLES: readonly ["standalone", "child"];
+
+declare type WorkflowConfig = v.InferOutput<typeof WorkflowConfigSchema>;
+
+declare const WorkflowConfigSchema: v.ObjectSchema<
+  {
+    readonly deployments: v.SchemaWithPipe<
+      readonly [
+        v.ArraySchema<
+          v.ObjectSchema<
+            {
+              readonly name: v.SchemaWithPipe<
+                readonly [
+                  v.StringSchema<undefined>,
+                  v.NonEmptyAction<string, "must not be empty">,
+                ]
+              >;
+              readonly tag: v.SchemaWithPipe<
+                readonly [
+                  v.StringSchema<undefined>,
+                  v.NonEmptyAction<string, undefined>,
+                  v.CheckAction<
+                    string,
+                    "invalid tag — lowercase letters, digits and dashes only, no leading dash, no dots"
+                  >,
+                ]
+              >;
+              readonly workflowResource: v.VariantSchema<
+                "type",
+                [
+                  v.ObjectSchema<
+                    {
+                      readonly type: v.LiteralSchema<"dataset", undefined>;
+                      readonly id: v.SchemaWithPipe<
+                        readonly [
+                          v.SchemaWithPipe<
+                            readonly [
+                              v.StringSchema<undefined>,
+                              v.NonEmptyAction<string, "must not be empty">,
+                            ]
+                          >,
+                          v.CheckAction<
+                            string,
+                            'invalid dataset resource id — expected "<projectId>.<dataset>"'
+                          >,
+                        ]
+                      >;
+                    },
+                    undefined
+                  >,
+                  v.ObjectSchema<
+                    {
+                      readonly type: v.LiteralSchema<"canvas", undefined>;
+                      readonly id: v.SchemaWithPipe<
+                        readonly [
+                          v.StringSchema<undefined>,
+                          v.NonEmptyAction<string, "must not be empty">,
+                        ]
+                      >;
+                    },
+                    undefined
+                  >,
+                  v.ObjectSchema<
+                    {
+                      readonly type: v.LiteralSchema<
+                        "media-library",
+                        undefined
+                      >;
+                      readonly id: v.SchemaWithPipe<
+                        readonly [
+                          v.StringSchema<undefined>,
+                          v.NonEmptyAction<string, "must not be empty">,
+                        ]
+                      >;
+                    },
+                    undefined
+                  >,
+                  v.ObjectSchema<
+                    {
+                      readonly type: v.LiteralSchema<"dashboard", undefined>;
+                      readonly id: v.SchemaWithPipe<
+                        readonly [
+                          v.StringSchema<undefined>,
+                          v.NonEmptyAction<string, "must not be empty">,
+                        ]
+                      >;
+                    },
+                    undefined
+                  >,
+                ],
+                undefined
+              >;
+              readonly resourceAliases: v.OptionalSchema<
+                v.SchemaWithPipe<
+                  readonly [
+                    v.ArraySchema<
+                      v.ObjectSchema<
+                        {
+                          readonly name: v.SchemaWithPipe<
+                            readonly [
+                              v.SchemaWithPipe<
+                                readonly [
+                                  v.StringSchema<undefined>,
+                                  v.NonEmptyAction<string, "must not be empty">,
+                                ]
+                              >,
+                              v.CheckAction<
+                                string,
+                                "invalid resource handle name — lowercase letters, digits and dashes only, no leading dash"
+                              >,
+                            ]
+                          >;
+                          readonly resource: v.VariantSchema<
+                            "type",
+                            [
+                              v.ObjectSchema<
+                                {
+                                  readonly type: v.LiteralSchema<
+                                    "dataset",
+                                    undefined
+                                  >;
+                                  readonly id: v.SchemaWithPipe<
+                                    readonly [
+                                      v.SchemaWithPipe<
+                                        readonly [
+                                          v.StringSchema<undefined>,
+                                          v.NonEmptyAction<
+                                            string,
+                                            "must not be empty"
+                                          >,
+                                        ]
+                                      >,
+                                      v.CheckAction<
+                                        string,
+                                        'invalid dataset resource id — expected "<projectId>.<dataset>"'
+                                      >,
+                                    ]
+                                  >;
+                                },
+                                undefined
+                              >,
+                              v.ObjectSchema<
+                                {
+                                  readonly type: v.LiteralSchema<
+                                    "canvas",
+                                    undefined
+                                  >;
+                                  readonly id: v.SchemaWithPipe<
+                                    readonly [
+                                      v.StringSchema<undefined>,
+                                      v.NonEmptyAction<
+                                        string,
+                                        "must not be empty"
+                                      >,
+                                    ]
+                                  >;
+                                },
+                                undefined
+                              >,
+                              v.ObjectSchema<
+                                {
+                                  readonly type: v.LiteralSchema<
+                                    "media-library",
+                                    undefined
+                                  >;
+                                  readonly id: v.SchemaWithPipe<
+                                    readonly [
+                                      v.StringSchema<undefined>,
+                                      v.NonEmptyAction<
+                                        string,
+                                        "must not be empty"
+                                      >,
+                                    ]
+                                  >;
+                                },
+                                undefined
+                              >,
+                              v.ObjectSchema<
+                                {
+                                  readonly type: v.LiteralSchema<
+                                    "dashboard",
+                                    undefined
+                                  >;
+                                  readonly id: v.SchemaWithPipe<
+                                    readonly [
+                                      v.StringSchema<undefined>,
+                                      v.NonEmptyAction<
+                                        string,
+                                        "must not be empty"
+                                      >,
+                                    ]
+                                  >;
+                                },
+                                undefined
+                              >,
+                            ],
+                            undefined
+                          >;
+                        },
+                        undefined
+                      >,
+                      undefined
+                    >,
+                    v.CheckAction<
+                      {
+                        name: string;
+                        resource:
+                          | {
+                              type: "dataset";
+                              id: string;
+                            }
+                          | {
+                              type: "canvas";
+                              id: string;
+                            }
+                          | {
+                              type: "media-library";
+                              id: string;
+                            }
+                          | {
+                              type: "dashboard";
+                              id: string;
+                            };
+                      }[],
+                      "duplicate resource handle name — each binding name must be unique within a deployment"
+                    >,
+                  ]
+                >,
+                undefined
+              >;
+              readonly definitions: v.SchemaWithPipe<
+                readonly [
+                  v.ArraySchema<
+                    v.CustomSchema<
+                      {
+                        name: string;
+                        title: string;
+                        description?: string | undefined;
+                        groups?: Group[] | undefined;
+                        lifecycle?: WorkflowLifecycle | undefined;
+                        applicableWhen?: string | undefined;
+                        initialStage: string;
+                        fields?: FieldEntry[] | undefined;
+                        stages: Stage[];
+                        predicates?: Record<string, string> | undefined;
+                        roleAliases?: RoleAliases | undefined;
+                      },
+                      v.ErrorMessage<v.CustomIssue> | undefined
+                    >,
+                    undefined
+                  >,
+                  v.MinLengthAction<
+                    {
+                      name: string;
+                      title: string;
+                      description?: string | undefined;
+                      groups?: Group[] | undefined;
+                      lifecycle?: WorkflowLifecycle | undefined;
+                      applicableWhen?: string | undefined;
+                      initialStage: string;
+                      fields?: FieldEntry[] | undefined;
+                      stages: Stage[];
+                      predicates?: Record<string, string> | undefined;
+                      roleAliases?: RoleAliases | undefined;
+                    }[],
+                    1,
+                    "a deployment needs at least one definition"
+                  >,
+                ]
+              >;
+            },
+            undefined
+          >,
+          undefined
+        >,
+        v.MinLengthAction<
+          {
+            name: string;
+            tag: string;
+            workflowResource:
+              | {
+                  type: "dataset";
+                  id: string;
+                }
+              | {
+                  type: "canvas";
+                  id: string;
+                }
+              | {
+                  type: "media-library";
+                  id: string;
+                }
+              | {
+                  type: "dashboard";
+                  id: string;
+                };
+            resourceAliases?:
+              | {
+                  name: string;
+                  resource:
+                    | {
+                        type: "dataset";
+                        id: string;
+                      }
+                    | {
+                        type: "canvas";
+                        id: string;
+                      }
+                    | {
+                        type: "media-library";
+                        id: string;
+                      }
+                    | {
+                        type: "dashboard";
+                        id: string;
+                      };
+                }[]
+              | undefined;
+            definitions: {
+              name: string;
+              title: string;
+              description?: string | undefined;
+              groups?: Group[] | undefined;
+              lifecycle?: WorkflowLifecycle | undefined;
+              applicableWhen?: string | undefined;
+              initialStage: string;
+              fields?: FieldEntry[] | undefined;
+              stages: Stage[];
+              predicates?: Record<string, string> | undefined;
+              roleAliases?: RoleAliases | undefined;
+            }[];
+          }[],
+          1,
+          "a config needs at least one deployment"
+        >,
+        v.CheckAction<
+          {
+            name: string;
+            tag: string;
+            workflowResource:
+              | {
+                  type: "dataset";
+                  id: string;
+                }
+              | {
+                  type: "canvas";
+                  id: string;
+                }
+              | {
+                  type: "media-library";
+                  id: string;
+                }
+              | {
+                  type: "dashboard";
+                  id: string;
+                };
+            resourceAliases?:
+              | {
+                  name: string;
+                  resource:
+                    | {
+                        type: "dataset";
+                        id: string;
+                      }
+                    | {
+                        type: "canvas";
+                        id: string;
+                      }
+                    | {
+                        type: "media-library";
+                        id: string;
+                      }
+                    | {
+                        type: "dashboard";
+                        id: string;
+                      };
+                }[]
+              | undefined;
+            definitions: {
+              name: string;
+              title: string;
+              description?: string | undefined;
+              groups?: Group[] | undefined;
+              lifecycle?: WorkflowLifecycle | undefined;
+              applicableWhen?: string | undefined;
+              initialStage: string;
+              fields?: FieldEntry[] | undefined;
+              stages: Stage[];
+              predicates?: Record<string, string> | undefined;
+              roleAliases?: RoleAliases | undefined;
+            }[];
+          }[],
+          "duplicate deployment tag — each deployment must use a unique tag"
+        >,
+      ]
+    >;
+    /**
+     * 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
+>;
 
 declare type WorkflowDefinition = v.InferOutput<
   typeof WorkflowDefinitionSchema
@@ -1588,7 +2515,9 @@ declare type WorkflowFields<TField, TStage> = {
   name: string;
   title: string;
   description?: string | undefined;
-  role?: WorkflowRole | undefined;
+  groups?: Group[] | undefined;
+  lifecycle?: WorkflowLifecycle | undefined;
+  applicableWhen?: string | undefined;
   initialStage: string;
   fields?: TField[] | undefined;
   stages: TStage[];
@@ -1596,7 +2525,40 @@ declare type WorkflowFields<TField, TStage> = {
   roleAliases?: RoleAliases | undefined;
 };
 
-/** A definition's lifecycle role. `'child'` is spawn-only — see {@link isStartableDefinition}. */
-declare type WorkflowRole = (typeof WORKFLOW_ROLES)[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}. */
+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 {};