@sanity/workflow-engine 0.14.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>;
@@ -313,8 +324,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.
      */
@@ -724,12 +735,15 @@ declare const AuthoringOpSchema: v.VariantSchema<
  *     field the transition filter reads — `failed` is for work that
  *     genuinely could not complete.
  */
-declare type AuthoringRawAction = ActionFields<AuthoringOp> & {
+declare type AuthoringRawAction = ActionFields<AuthoringOp, GroupMembership> & {
   roles?: string[] | undefined;
   status?: TerminalActivityStatus | undefined;
 };
 
-declare type AuthoringRawFieldEntry = FieldEntryFields<AuthoringEditable>;
+declare type AuthoringRawFieldEntry = FieldEntryFields<
+  AuthoringEditable,
+  GroupMembership
+>;
 
 declare type AuthoringStage = StageFields<
   AuthoringFieldEntry,
@@ -964,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;
@@ -982,6 +997,7 @@ declare type ClaimField = {
   name: string;
   title?: string | undefined;
   description?: string | undefined;
+  group?: GroupMembership | undefined;
 };
 
 /**
@@ -997,6 +1013,9 @@ 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;
 }
 
 /**
@@ -1014,9 +1033,13 @@ export declare interface ConditionVar {
  *    fixed and deploy-enforced (see the op-where scope's param-name list in
  *    the op applier).
  * 2. **Filter evaluation without a caller** — the engine's cascade evaluates
- *    transition filters and `completeWhen`/`failWhen` with no caller, so only
- *    the `'always'`-bound subset carries values there ({@link FILTER_SCOPE_VARS}).
- *    Caller-bound vars evaluate to `undefined` and fail closed.
+ *    transition filters and the activity gates (`filter`, `completeWhen`,
+ *    `failWhen`) with no caller, so only the `'always'`-bound subset carries
+ *    values there ({@link FILTER_SCOPE_VARS}). Caller-bound vars fail closed —
+ *    `$assigned` binds its caller-free constant `false`, the rest evaluate to
+ *    `undefined` — and deploy rejects them at these sites: routing and gate
+ *    resolution must resolve identically no matter whose token triggers the
+ *    evaluation.
  * 3. **Guard predicates** — NOT conditions. A lake mutation guard's
  *    `predicate` is groq-js **delta-mode** GROQ over a document mutation:
  *    `before()`/`after()`/`identity()` are dialect natives, and the wire
@@ -1031,7 +1054,7 @@ export declare interface ConditionVar {
  * - `'caller'` — rides the acting caller; without one the var is `undefined`
  *   (conditions referencing it fail closed). Author predicates may not read
  *   these — they pre-evaluate once per instance, caller-free.
- * - `'spawn'` — bound only at `subworkflows` sites.
+ * - `'spawn'` — bound only at `subworkflows` sites (the per-row `$row`).
  */
 export declare type ConditionVarBinding = "always" | "caller" | "spawn";
 
@@ -1055,6 +1078,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 +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
 >;
@@ -1155,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",
@@ -1174,22 +1228,28 @@ 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;
 };
@@ -1230,7 +1290,8 @@ 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`).
+ * caller (the cascade path: transition filters, activity `filter`/
+ * `completeWhen`/`failWhen`).
  */
 export declare const FILTER_SCOPE_VARS: readonly string[];
 
@@ -1254,6 +1315,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 +1425,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 +1473,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 +1557,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;
@@ -1825,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>,
@@ -1901,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
 >;
@@ -1919,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 = FieldBase<AuthoringEditable> & {
+declare type TodoListField = FieldBase<AuthoringEditable, GroupMembership> & {
   type: "todoList";
 };
 
@@ -2202,7 +2312,9 @@ declare const WorkflowConfigSchema: v.ObjectSchema<
                         name: string;
                         title: string;
                         description?: string | undefined;
+                        groups?: Group[] | undefined;
                         lifecycle?: WorkflowLifecycle | undefined;
+                        applicableWhen?: string | undefined;
                         initialStage: string;
                         fields?: FieldEntry[] | undefined;
                         stages: Stage[];
@@ -2218,7 +2330,9 @@ declare const WorkflowConfigSchema: v.ObjectSchema<
                       name: string;
                       title: string;
                       description?: string | undefined;
+                      groups?: Group[] | undefined;
                       lifecycle?: WorkflowLifecycle | undefined;
+                      applicableWhen?: string | undefined;
                       initialStage: string;
                       fields?: FieldEntry[] | undefined;
                       stages: Stage[];
@@ -2282,7 +2396,9 @@ declare const WorkflowConfigSchema: v.ObjectSchema<
               name: string;
               title: string;
               description?: string | undefined;
+              groups?: Group[] | undefined;
               lifecycle?: WorkflowLifecycle | undefined;
+              applicableWhen?: string | undefined;
               initialStage: string;
               fields?: FieldEntry[] | undefined;
               stages: Stage[];
@@ -2340,7 +2456,9 @@ declare const WorkflowConfigSchema: v.ObjectSchema<
               name: string;
               title: string;
               description?: string | undefined;
+              groups?: Group[] | undefined;
               lifecycle?: WorkflowLifecycle | undefined;
+              applicableWhen?: string | undefined;
               initialStage: string;
               fields?: FieldEntry[] | undefined;
               stages: Stage[];
@@ -2352,6 +2470,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
 >;
@@ -2382,7 +2515,9 @@ declare type WorkflowFields<TField, TStage> = {
   name: string;
   title: string;
   description?: string | undefined;
+  groups?: Group[] | undefined;
   lifecycle?: WorkflowLifecycle | undefined;
+  applicableWhen?: string | undefined;
   initialStage: string;
   fields?: TField[] | undefined;
   stages: TStage[];
@@ -2395,4 +2530,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 {};