@sanity/workflow-engine 0.29.0 → 0.30.0

package/dist/define.d.cts

@@ -1,5 +1,20 @@
 import * as v from "valibot";
 
+/**
+ * A stored action. `semantics` is engine-owned advisory meaning, independent
+ * of execution and presentation — an array so the vocabulary can grow without
+ * reshaping this field. `when`'s presence makes the action CASCADE-FIRED: the
+ * engine fires it the moment the condition turns true, at most once per stage
+ * visit, and it is never invocable via `fireAction`; absent, the action must
+ * be invoked via `fireAction` by any caller holding a token (fire-on-entry is
+ * `when: 'true'`). `filter` is existence with GROQ semantics — a non-matching
+ * action might as well not exist (invisible to UI and LLMs, never merely
+ * disabled); on a `when` action it composes: `filter` scopes whether the
+ * automation exists, `when` is its firing trigger. `roles` is kept VERBATIM
+ * only when cascade-fired (the pin on which identities may execute the
+ * trigger); a fireAction-fired action's `roles` folds into `filter` at
+ * desugar instead.
+ */
 declare type Action = ActionFields<Op, string[]> & {
   roles?: string[] | undefined;
 };
@@ -20,14 +35,14 @@ declare type ActionFields<TOp, TGroup> = {
   spawn?: Subworkflows | undefined;
 };
 
-declare type ActionParam = v.InferOutput<typeof ActionParamSchema>;
-
 /**
- * Caller-supplied params declared on an action. The engine validates
- * incoming `params` against this list before running ops or queuing
- * effects: missing required params → ActionParamsInvalidError, action
- * does not commit. Resolved values feed `ValueExpr.param` lookups.
+ * Caller-supplied params declared on an action, validated before running ops
+ * or queuing effects: a missing required param throws
+ * `ActionParamsInvalidError` and the action does not commit. Resolved values
+ * feed `ValueExpr.param` lookups.
  */
+declare type ActionParam = v.InferOutput<typeof ActionParamSchema>;
+
 declare const ActionParamSchema: v.SchemaWithPipe<
   readonly [
     v.StrictObjectSchema<
@@ -157,6 +172,20 @@ declare const ActionParamSchema: v.SchemaWithPipe<
 
 declare type ActionSemantic = DecisionSemantic | Semantic;
 
+/**
+ * A unit of work carrying no payload of its own — every op, effect, and
+ * spawn lives on an action; an activity contributes scoped `fields`
+ * (resolved at stage entry), existence (`filter`), advisory readiness
+ * (`requirements`), and the off-system marker (`target`, a BPMN Manual Task
+ * deep-link, render-only and never gating). All in-scope activities are
+ * ACTIVE from stage entry until an action's terminal `status` resolves them —
+ * there is no activation moment. `filter` is existence with GROQ semantics,
+ * evaluated once against the stage's entry state: a definite `false`
+ * excludes the activity from UI, LLMs, and `$allActivitiesDone`.
+ * `requirements` are readiness gates orthogonal to `filter` — an unmet one
+ * keeps the activity visible but disables its actions with a
+ * `requirements-unmet` verdict; distinct from ACL and guards.
+ */
 declare type Activity = ActivityFields<
   FieldEntry,
   Action,
@@ -179,6 +208,18 @@ declare type ActivityFields<TField, TAction, TTarget, TGroup> = {
   fields?: TField[] | undefined;
 };
 
+/**
+ * The stored action fields plus two authoring sugars, or the
+ * {@link ClaimAction} pair-half. `roles`: on a fireAction-fired action (no
+ * `when`) it desugars into a `count($actor.roles[@ in [...]]) > 0` condition
+ * ANDed with `filter`; on a CASCADE-FIRED action it stores VERBATIM instead —
+ * the pin on which identities may execute the trigger, since folding it into
+ * `filter` would make the action's existence depend on whose token cascades.
+ * `roleAliases` widens the membership either way. `status` compiles to a
+ * `status.set` op on the firing activity, appended AFTER the authored ops —
+ * deliberately never implied, so a forgotten `status` is a visible stall
+ * rather than a silently completed action.
+ */
 declare type AuthoringAction = AuthoringRawAction | ClaimAction;
 
 declare type AuthoringActivity = ActivityFields<
@@ -188,14 +229,14 @@ declare type AuthoringActivity = ActivityFields<
   GroupMembership
 >;
 
-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 field to anyone in its
  * window; a bare string is a raw predicate.
  */
+declare type AuthoringEditable = v.InferOutput<typeof AuthoringEditableSchema>;
+
 declare const AuthoringEditableSchema: v.UnionSchema<
   [
     v.LiteralSchema<true, undefined>,
@@ -224,6 +265,8 @@ declare type AuthoringFieldEntry =
   | TodoListField
   | NotesField;
 
+/** A field reference with `scope` optional; desugar resolves it lexically
+ *  (activity → stage → workflow) into {@link StoredFieldRef}. */
 declare type AuthoringFieldRef = v.InferOutput<typeof AuthoringFieldRefSchema>;
 
 declare const AuthoringFieldRefSchema: v.StrictObjectSchema<
@@ -242,15 +285,12 @@ declare const AuthoringFieldRefSchema: v.StrictObjectSchema<
   undefined
 >;
 
+/** {@link Guard}'s contract as authored: `match.idRefs` and `metadata` carry
+ *  typed {@link GuardRead} values that deploy resolves to bare ones. */
 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>,
@@ -261,7 +301,6 @@ declare const AuthoringGuardSchema: v.StrictObjectSchema<
     description: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
     match: v.StrictObjectSchema<
       {
-        /** Subject `_type`(s); empty matches any type. */
         types: v.OptionalSchema<
           v.ArraySchema<
             v.SchemaWithPipe<
@@ -274,7 +313,6 @@ declare const AuthoringGuardSchema: v.StrictObjectSchema<
           >,
           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<
@@ -377,7 +415,6 @@ declare const AuthoringGuardSchema: v.StrictObjectSchema<
           >,
           undefined
         >;
-        /** Glob id patterns (bare, resource-local). */
         idPatterns: v.OptionalSchema<
           v.ArraySchema<
             v.SchemaWithPipe<
@@ -409,22 +446,7 @@ declare const AuthoringGuardSchema: v.StrictObjectSchema<
       },
       undefined
     >;
-    /**
-     * Lake GROQ predicate — a distinct eval context: delta-mode GROQ
-     * reading the `before()`/`after()` natives, `mutation`, `guard`, and
-     * `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>;
-    /**
-     * 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<
@@ -534,6 +556,8 @@ declare const AuthoringGuardSchema: v.StrictObjectSchema<
   undefined
 >;
 
+/** Like {@link ManualTarget}, but the `field` variant also accepts a bare
+ *  field name; desugar normalises it into {@link AuthoringFieldRef}. */
 declare type AuthoringManualTarget = v.InferOutput<
   typeof AuthoringManualTargetSchema
 >;
@@ -593,6 +617,9 @@ declare const AuthoringManualTargetSchema: v.VariantSchema<
   undefined
 >;
 
+/** Like {@link Op}, plus: `status.set`'s `activity` is optional (desugar fills
+ *  the firing activity), and the `audit` sugar — a stamped append merging
+ *  `actor`/`at` {@link ValueExpr} fields into its own value. */
 declare type AuthoringOp = v.InferOutput<typeof AuthoringOpSchema>;
 
 declare const AuthoringOpSchema: v.VariantSchema<
@@ -888,27 +915,6 @@ declare const AuthoringOpSchema: v.VariantSchema<
   undefined
 >;
 
-/**
- * Authoring action — the stored fields plus two field sugars with one
- * defined expansion each:
- *
- *   - `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 trigger reads — `failed` is for work that
- *     genuinely could not complete.
- */
 declare type AuthoringRawAction = ActionFields<AuthoringOp, GroupMembership> & {
   roles?: string[] | undefined;
   status?: TerminalActivityStatus | undefined;
@@ -958,14 +964,8 @@ declare interface ChoiceOptions {
 
 declare type ChoiceValue = string | number;
 
-/**
- * The action half of the mirrored claim pair. `field` references an
- * author-declared actor-valued entry (the pair's other half), resolved
- * lexically. Expansion, strictly within this action: a no-steal
- * `!defined($fields.<field>)` filter ANDed with `roles`/`filter`, plus a
- * `field.set` ← actor op. `ops` and `status` are reserved (the expansion
- * owns them) — strictObject rejects them as unknown keys.
- */
+/** The action half of the mirrored claim pair: `field` names the actor-valued entry this action claims, resolved lexically, and the expansion
+ *  adds a no-steal `!defined($fields.<field>)` filter ANDed with `roles`/`filter` plus a `field.set` ← actor op. `ops`/`status` are reserved (strictObject rejects them). */
 declare type ClaimAction = {
   type: "claim";
   name: string;
@@ -979,12 +979,8 @@ declare type ClaimAction = {
   effects?: Effect[] | undefined;
 };
 
-/**
- * Authoring fields accept the raw entries plus the `claim` sugar type — the
- * field half of the mirrored claim pair. Expansion: an `actor` working-
- * memory field (no `initialValue`; the claim action's op fills it), strictly
- * within this entry.
- */
+/** The field half of the mirrored claim pair, expanding strictly within this entry: an `actor`
+ *  working-memory field with no `initialValue` — the paired {@link ClaimAction}'s op fills it. */
 declare type ClaimField = {
   type: "claim";
   name: string;
@@ -994,10 +990,23 @@ declare type ClaimField = {
 };
 
 /**
- * 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.
+ * Every variable the engine binds for the RENDERED condition scope (every
+ * condition site: transition `when`s, activity filters, action
+ * `when`s/filters, effect bindings, `spawn` reads, where-op `where`s,
+ * editability predicates, author predicates) — 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.
+ *
+ * Three other GROQ contexts read a definition and do NOT share this
+ * inventory: cascade gates (transition/activity/cascade-action gates, which
+ * must resolve identically regardless of caller — only the `'always'`-bound
+ * subset carries values, {@link FILTER_SCOPE_VARS}); the start contexts
+ * (`start.filter` is browse-time-pure over a candidate document,
+ * {@link START_FILTER_VARS}; a start `groq` requirement binds `$fields`
+ * instead, {@link START_REQUIREMENT_VARS}); and lake guard predicates, which
+ * are not conditions at all — delta-mode GROQ over a mutation, binding
+ * {@link GUARD_PREDICATE_VARS} instead.
  */
 export declare const CONDITION_VARS: readonly ConditionVar[];
 
@@ -1011,43 +1020,6 @@ export declare interface ConditionVar {
   label: string;
 }
 
-/**
- * The condition-variable inventory — the single source of truth for every
- * `$var` the engine binds when it evaluates a {@link Condition}.
- *
- * Four evaluation contexts read a definition's GROQ:
- *
- * 1. **Rendered condition scope** — every condition site in a definition
- *    (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. **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 GROQ
- *    requirements evaluate against a CANDIDATE (no instance exists yet):
- *    `*[...]` reads the engine-owned `{definition, subject, completedAt}`
- *    projection of the tag's instances 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), a `groq` requirement is the start-time readiness predicate
- *    ({@link START_REQUIREMENT_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
- *    the condition vars exist there.
- */
 /**
  * When a condition var holds a value:
  *
@@ -1063,15 +1035,6 @@ export declare type ConditionVarBinding = "always" | "caller" | "spawn";
 /** A define-time validated `custom.<camelCaseMeaning>` value. */
 declare type CustomSemantic = `custom.${string}`;
 
-/**
- * The maximum reader floor this writer can emit. Individual documents derive
- * their `minReaderModel` from the compatibility-bearing features actually
- * present; a document written at {@link DATA_MODEL_VERSION} may therefore
- * carry a lower floor. Raising this maximum is a declared, DATAMODEL.md-logged
- * decision that requires readers-first fleet sequencing.
- */
-declare const DATA_MODEL_MIN_READER = 4;
-
 declare const DECISION_SEMANTICS: readonly [
   "decision.accept",
   "decision.decline",
@@ -1140,21 +1103,42 @@ export declare function defineWorkflow(
  * deployment's bindings via {@link resourceAliasesToMap} into the
  * `resourceAliases` map `deployDefinitions` expands against.
  *
- * Validates shape only — NOT the reader-floor acknowledgement. That is a
- * selected-deployment gate (`deployDefinitions`, the CLI's
- * `deploymentToTarget` / `buildBatches` / `resolveContext`, and blueprint
- * provision each assert the deployment they target), so a command that never
- * selects a deployment loads a config with a stale or missing floor on an
- * untargeted entry without failing. Authors must still acknowledge the floor
- * at compile time — each {@link WorkflowDeploymentInput} requires it; the
- * returned {@link WorkflowConfig} is the looser parsed shape.
+ * Validates shape only; reader-floor acknowledgement belongs to paths that
+ * submit definitions (`deployDefinitions`, the CLI deploy and definition-diff
+ * commands, and blueprint provision). Other commands may load a selected
+ * deployment with a missing floor.
+ *
+ * Each `WorkflowDeploymentInput` carries an acknowledgement; definition-submission
+ * paths compare it with the submitted definitions. The returned {@link WorkflowConfig}
+ * is the looser parsed shape.
  */
 export declare function defineWorkflowConfig(
   config: WorkflowConfigInput,
 ): WorkflowConfig;
 
+/**
+ * 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
+ * field's scope window) or an EDIT CONDITION — rendered-scope GROQ (`$actor`,
+ * `$can`, `$attributes`, `$fields`, `$assigned`), checked like an action filter
+ * to decide who-may-edit. ADVISORY like every engine gate — it disables the
+ * inline field and explains; a {@link Guard} declares the intended write-lock.
+ */
 declare type Editable = v.InferOutput<typeof StoredEditableSchema>;
 
+/**
+ * A registered effect: `name` is its only identity (unique per definition,
+ * read downstream as `$effects.<name>`) — the host app registers a handler
+ * against it 1:1, and the stored definition never references code.
+ * `bindings` are GROQ reads over the rendered scope, resolved to concrete
+ * JSON at queue time; `input` is static config passed through verbatim.
+ * `outputs` (typed {@link FieldShape}s) is a STRICT allowlist: at completion
+ * an undeclared output key, or a value that doesn't fit its shape, fails the
+ * completion and nothing is stored. Omitting `outputs` is an EMPTY allowlist,
+ * so ANY returned output is rejected and fails the completion — the bound is
+ * universal, not opt-in.
+ */
 declare type Effect = v.InferOutput<typeof EffectSchema>;
 
 /**
@@ -1189,7 +1173,6 @@ declare const EffectSchema: v.StrictObjectSchema<
       v.StringSchema<undefined>,
       undefined
     >;
-    /** GROQ reads over the rendered scope, resolved to concrete JSON at queue time. */
     readonly bindings: v.OptionalSchema<
       v.RecordSchema<
         v.StringSchema<undefined>,
@@ -1203,28 +1186,10 @@ declare const EffectSchema: v.StrictObjectSchema<
       >,
       undefined
     >;
-    /** Static config, passed through to the handler verbatim. */
     readonly input: v.OptionalSchema<
       v.RecordSchema<v.StringSchema<undefined>, v.UnknownSchema, undefined>,
       undefined
     >;
-    /**
-     * The outputs this effect is allowed to produce, as typed {@link FieldShape}s
-     * (each `name` is an output key, read downstream as `$effects['<name>'].<key>`;
-     * an `array` output is an array of objects shaped by `of`).
-     *
-     * A STRICT allowlist: at completion the handler's returned `outputs` are
-     * validated against these shapes and an undeclared key — or a value that
-     * doesn't fit its shape — fails the completion (nothing is stored). Omitting
-     * `outputs` is an EMPTY allowlist: the effect produces nothing, so any returned
-     * output is rejected — the bound is universal, not opt-in.
-     * Why strict: outputs land on the instance document's `effectHistory`, so
-     * the allowlist keeps it bounded — a handler can't accidentally spread a
-     * whole API response
-     * into the instance — and the declared shapes let tooling (e.g. the simulator's
-     * drain UI) suggest an effect's exact output keys. Declaring outputs also
-     * powers the advisory deploy-time producer/consumer lint.
-     */
     readonly outputs: v.OptionalSchema<
       v.ArraySchema<v.GenericSchema<FieldShape>, undefined>,
       undefined
@@ -1237,7 +1202,10 @@ declare const EffectSchema: v.StrictObjectSchema<
  * The kinds a VALUE can take — scalars aligned to Sanity's names, the
  * 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.
+ * This is also the set a nested {@link FieldShape} sub-field may use. Kinds
+ * are bare (unique within their union); namespacing lives only on
+ * engine-owned lake document `_type`s ({@link WORKFLOW_DEFINITION_TYPE}, the
+ * instance type).
  *
  * Exported (module-level, not package API) for the model-surface gate's
  * enum-value coverage test.
@@ -1276,6 +1244,7 @@ declare type FieldBase<TEditable, TGroup> = {
   editable?: TEditable | undefined;
 };
 
+/** One declared field entry as authored and stored: name, value kind, and its scope's sourcing and editability. */
 declare type FieldEntry = FieldEntryFields<Editable, string[]>;
 
 /** Type-mirror of {@link fieldEntryFields}: a raw field entry of the given
@@ -1288,6 +1257,8 @@ declare type FieldEntryFields<TEditable, TGroup> = FieldBase<
   options?: ChoiceOptions | undefined;
   validation?: ScalarValidation | undefined;
   types?: string[] | undefined;
+  /** Non-empty assignment eligibility constraint. User roles apply aliases; collective roles match literally. */
+  roles?: string[] | undefined;
   fields?: FieldShape[] | undefined;
   of?: FieldShape[] | undefined;
 };
@@ -1299,6 +1270,14 @@ declare type FieldReadExpr = {
   path?: string | undefined;
 };
 
+/**
+ * A sub-field shape used inside an `object`'s `fields` or an `array`'s `of` —
+ * lighter than {@link FieldEntry}: no `initialValue`/`editable`/`required`,
+ * since a sub-field's value comes from the parent. An `object` kind requires
+ * non-empty `fields` and no `of`; an `array` kind requires non-empty `of` and
+ * no `fields`; every other kind requires neither — enforced at parse, not
+ * visible in this type.
+ */
 declare interface FieldShape {
   type: FieldValueKind;
   name: string;
@@ -1306,10 +1285,19 @@ declare interface FieldShape {
   description?: string | undefined;
   options?: ChoiceOptions | undefined;
   validation?: ScalarValidation | undefined;
+  /** Non-empty assignment eligibility constraint. User roles apply aliases; collective roles match literally. */
+  roles?: string[] | undefined;
   fields?: FieldShape[] | undefined;
   of?: FieldShape[] | undefined;
 }
 
+/**
+ * How a field seeds its `initialValue`, once at materialisation (advisory
+ * after — the field stays freely editable). Absent means working memory: the
+ * field starts empty and an op fills it later, spelled by omission rather
+ * than an arm. Distinct from {@link ValueExpr}, an op's write payload; they
+ * overlap only on the literal and field-read arms.
+ */
 declare type FieldSource = FieldSourceInternal;
 
 declare type FieldSourceInternal =
@@ -1352,12 +1340,22 @@ export declare function groq(
   ...values: unknown[]
 ): string;
 
+/** A named readiness condition. Activities accept only `'groq'`; workflow
+ *  `start.requirements` also accepts `'singleSubject'` — see {@link StartRequirement}. */
 declare type GroqRequirement = RequirementBase & {
   type: "groq";
   query: string;
 };
 
-/** Type-mirror of {@link GroupSchema} — one declared group. */
+/**
+ * A declared "what belongs together" tag: the workflow root, a stage, or an
+ * activity declares named groups, and field entries, activities, and actions
+ * opt in via `group`. Purely advisory — the engine stores and validates names
+ * (unique per level, every reference resolves) and never acts on them; a
+ * consumer decides what a group means for its medium. The same name declared
+ * at several levels is intentional nesting, addressed per level; the engine
+ * never merges them.
+ */
 declare type Group = {
   name: string;
   title?: string | undefined;
@@ -1365,6 +1363,14 @@ declare type Group = {
   kind?: GroupKind | undefined;
 };
 
+/**
+ * Advisory classification of a declared {@link Group} by its informational
+ * ROLE, never a rendering treatment: `'core'` marks content central to
+ * understanding the workflow (condensed views include these first);
+ * `'details'` marks depth on demand. Unset = a plain group. Consumers
+ * reading a definition as data MUST treat an unknown kind as unset — growing
+ * this list is an engine version bump, like every stored enum.
+ */
 declare const GROUP_KINDS: readonly ["core", "details"];
 
 declare type GroupKind = (typeof GROUP_KINDS)[number];
@@ -1381,6 +1387,27 @@ declare type GroupKind = (typeof GROUP_KINDS)[number];
  */
 declare type GroupMembership = string | string[];
 
+/**
+ * A lake mutation guard. A FOREIGN CONTRACT mirrored 1:1: `match`,
+ * `predicate`, and `metadata` are the content lake's persisted guard-document
+ * API, not engine-invented surface — the stored form keeps the lake's
+ * vocabulary verbatim. The engine adds exactly two things: `name` (a
+ * lake-id-segment, `^[a-z0-9][a-z0-9-]*$`, unique per definition — the lake
+ * `_id` derives from `(instanceId, name)` at stage entry) and the deploy-time
+ * read VALUES on `match.idRefs` / `metadata` (a typed {@link GuardRead} when
+ * authoring, resolved to bare values at deploy). `match` selects mutations by
+ * `types` (empty matches any), `idRefs` (field reads resolved to bare ids),
+ * `idPatterns` (bare glob ids), and `actions` (at least one). `predicate` is
+ * lake GROQ in a distinct delta-mode eval context (`before()`/`after()`,
+ * `mutation`, `guard`, `identity()`, bare ids/fields only): strictly `true`
+ * ALLOWS the mutation; anything else — false, null, an evaluation error, or
+ * an omitted/empty predicate — DENIES. `metadata` is the only bridge from
+ * that eval context (which cannot see `$fields`) to workflow fields, read as
+ * `guard.metadata.*` and re-synced by the post-field-op guard refresh. The
+ * lake does not enforce the guard document type yet: a deployed guard denies
+ * optimistically engine-side, and the lake ACL is the only hard gate until
+ * guard enforcement ships.
+ */
 declare type Guard = v.InferOutput<typeof GuardSchema>;
 
 /**
@@ -1395,14 +1422,8 @@ export declare const GUARD_PREDICATE_VARS: readonly {
   description: string;
 }[];
 
-/** 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>,
@@ -1413,7 +1434,6 @@ declare const GuardSchema: v.StrictObjectSchema<
     description: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
     match: v.StrictObjectSchema<
       {
-        /** Subject `_type`(s); empty matches any type. */
         types: v.OptionalSchema<
           v.ArraySchema<
             v.SchemaWithPipe<
@@ -1426,7 +1446,6 @@ declare const GuardSchema: v.StrictObjectSchema<
           >,
           undefined
         >;
-        /** Target docs as field reads (or the instance itself), resolved at deploy to bare ids + the resource. */
         idRefs: v.OptionalSchema<
           v.ArraySchema<
             v.SchemaWithPipe<
@@ -1439,7 +1458,6 @@ declare const GuardSchema: v.StrictObjectSchema<
           >,
           undefined
         >;
-        /** Glob id patterns (bare, resource-local). */
         idPatterns: v.OptionalSchema<
           v.ArraySchema<
             v.SchemaWithPipe<
@@ -1471,22 +1489,7 @@ declare const GuardSchema: v.StrictObjectSchema<
       },
       undefined
     >;
-    /**
-     * Lake GROQ predicate — a distinct eval context: delta-mode GROQ
-     * reading the `before()`/`after()` natives, `mutation`, `guard`, and
-     * `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>;
-    /**
-     * 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<
@@ -1514,17 +1517,22 @@ declare type LiteralExpr = {
   value: unknown;
 };
 
-declare type ManualTarget = v.InferOutput<typeof StoredManualTargetSchema>;
-
 /**
- * `notes` — an append-only audit/comment log. Sugar over `array of object
- * { body, actor, at }` (the `actor`/`at` sub-fields match the `audit` op's
- * stamp names, so it pairs with it). Never a stored kind.
+ * Off-system deep-link target — render-only metadata whose presence marks an
+ * activity as off-system (BPMN Manual Task). Either a static URL, or a field
+ * reference whose resolved document the consumer opens; deploy checks the
+ * `field` variant points at a doc-valued entry.
  */
+declare type ManualTarget = v.InferOutput<typeof StoredManualTargetSchema>;
+
+/** An append-only audit/comment log: sugar over `array of object {body, actor, at}` — the `actor`/`at`
+ *  names match the `audit` op's stamp fields, so it pairs with it. Never a stored kind. */
 declare type NotesField = FieldBase<AuthoringEditable, GroupMembership> & {
   type: "notes";
 };
 
+/** A `field.updateWhere` / `field.removeWhere` op's `where` selects rows to
+ *  mutate with rendered-scope GROQ (`$row`, `$params` bound) — row selection, not a gate; an unevaluable row never matches. */
 declare type Op = v.InferOutput<typeof StoredOpSchema>;
 
 declare type RequirementBase = {
@@ -1541,35 +1549,15 @@ declare type RequirementBase = {
  */
 export declare const RESERVED_CONDITION_VARS: readonly string[];
 
-declare type RoleAliases = v.InferOutput<typeof RoleAliasesSchema>;
-
 /**
- * Role aliasing — the "can be fulfilled by" map, an authoring convenience.
- * A `roles` gate (or an `assignees` entry) names the role the author writes;
- * but the SAME capability is often carried by different role names depending
- * on how a given project deploys its Content Lake roles, and several roles may
- * legitimately do the job. Rather than enumerate every equivalent role inline
- * in each gate — or fork the definition per deployment — declare once here
- * which other roles also fulfill it.
- *
- * Each key is a role a gate/assignee names; its value lists the roles that
- * also satisfy it. The reserved key `"*"` lists roles that fulfill ANY gate
- * (e.g. `"*": ["administrator"]` — whatever this deployment's broad role is).
- * `"*"` is the spelling authors write; it is rewritten to a lake-safe stored
- * key before the definition is persisted, since the Content Lake rejects `"*"`
- * as a document attribute name (see {@link normalizeRoleAliases}).
- *
- * Applied as an in-place expansion of the REQUIRED side, never the actor's
- * roles: the `roles` gate bakes the expanded membership into its desugared
- * GROQ at define time; `$assigned` expands the assignee's role at match time
- * (see {@link expandRequiredRoles}). Carried into the stored definition for
- * that runtime half.
- *
- * Advisory, like every engine gate — an alias only predicts what the
- * deployment's Content Lake ACLs already allow, it never grants access. An
- * alias the lake won't honor makes the gate predict "allowed" for a write the
- * lake then rejects, so keep it true to what's actually deployed.
+ * Roles that may fulfil each authored role. Aliases widen action gates,
+ * `$assigned`, and assignment-field user eligibility by expanding the required
+ * side; they never alter an actor's roles. Collective role assignees remain
+ * literal ownership values and are not widened by this map. The authored `"*"`
+ * key lists universal fulfillers and is normalized before persistence.
  */
+declare type RoleAliases = v.InferOutput<typeof RoleAliasesSchema>;
+
 declare const RoleAliasesSchema: v.RecordSchema<
   v.SchemaWithPipe<
     readonly [
@@ -1619,6 +1607,18 @@ declare type SingleSubjectRequirement = RequirementBase & {
   type: "singleSubject";
 };
 
+/**
+ * A pure container — name, fields, guards, activities, transitions, no
+ * behaviour of its own. Activities own enter, transitions own exit and
+ * arrival; a stage with no transitions IS terminal (structural, nothing to
+ * declare or mis-declare). `guards` are lake mutation guards active while
+ * the stage holds, each compiling to a persisted guard document deployed on
+ * stage entry and retracted on exit. `editable` is a tighten-only override
+ * for the time the stage holds, keyed by an in-scope field name: the field's
+ * own `editable` is the ceiling, ANDed with the stage value at runtime, so an
+ * override can only NARROW — never open a field the baseline left closed. An
+ * unlisted field inherits its baseline.
+ */
 declare type Stage = StageFields<
   FieldEntry,
   Activity,
@@ -1643,13 +1643,23 @@ declare type StageFields<TField, TActivity, TTransition, TGuard, TEditable> = {
 
 declare const START_KINDS: readonly ["interactive", "autonomous"];
 
+/**
+ * How standalone runs of this workflow begin. `filter` is a READ-SIDE
+ * visibility predicate — "should a start surface offer this workflow for
+ * this document?" — evaluated by `definitionsForDocument`/applicability in
+ * the browse-time-pure start-filter context (`$tag`/`$definition`/`$now`
+ * bound; `$fields` cannot exist before inputs do, so a `$fields` read here
+ * is deploy-rejected). It is NOT a `startInstance` gate; the verb never
+ * reads it. `requirements` are named readiness checks evaluated in author
+ * order in the start-time context (GROQ nodes add `$fields`; `singleSubject`
+ * is the one-in-flight-run-per-subject rule) — every node must pass before
+ * `startInstance` commits. Both are advisory like every engine-side check;
+ * the Content Lake remains the only enforcement point.
+ */
 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;
   requirements?: StartRequirement[] | undefined;
@@ -1666,17 +1676,9 @@ declare type StartFields = {
  */
 declare type StartKind = (typeof START_KINDS)[number];
 
+/** Every named readiness requirement accepted by workflow `start.requirements`. */
 declare type StartRequirement = GroqRequirement | SingleSubjectRequirement;
 
-/**
- * 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
- * field's scope window) or an EDIT CONDITION — rendered-scope GROQ (`$actor`,
- * `$can`, `$attributes`, `$fields`, `$assigned`), checked like an action filter
- * to decide who-may-edit. ADVISORY like every engine gate — it disables the
- * inline field and explains; a {@link Guard} declares the intended write-lock.
- */
 declare const StoredEditableSchema: v.UnionSchema<
   [
     v.LiteralSchema<true, undefined>,
@@ -1946,18 +1948,23 @@ declare const StoredOpSchema: v.VariantSchema<
   undefined
 >;
 
+/**
+ * Fan-out declared as an action's `spawn`, read back as `$subworkflows`.
+ * `forEach` is GROQ producing one row per subworkflow (bound as `$row`); each
+ * row needs an identity the engine can adopt on re-entry (`_key` ?? `_id` ??
+ * GDR `id`, or the value itself for a scalar row) or the spawn fails.
+ * `definition` resolves by stable `name`, ordered `version desc` unless
+ * pinned. `with` seeds each child's initial fields; `context` delivers extra
+ * parent-scope values into the child's `$context`. `onExit` governs only
+ * still-live children when the cohort's scope stops applying: `'detach'`
+ * (default) lets them run to completion, `'abort'` kills them recursively —
+ * always an authored choice, never automatic. Whether the PARENT may move at
+ * all is a separate gate over `$subworkflows`.
+ */
 declare type Subworkflows = v.InferOutput<typeof SubworkflowsSchema>;
 
 declare const SubworkflowsSchema: v.StrictObjectSchema<
   {
-    /**
-     * 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>,
@@ -1991,7 +1998,6 @@ declare const SubworkflowsSchema: v.StrictObjectSchema<
       },
       undefined
     >;
-    /** Initial fields for each subworkflow — entry name → GROQ over `$row` + the parent scope. */
     readonly with: v.OptionalSchema<
       v.RecordSchema<
         v.SchemaWithPipe<
@@ -2010,11 +2016,6 @@ declare const SubworkflowsSchema: v.StrictObjectSchema<
       >,
       undefined
     >;
-    /**
-     * Extra values evaluated in the parent's rendered scope at spawn time and
-     * delivered into each subworkflow's `$context` bag — the parent→child
-     * handoff.
-     */
     readonly context: v.OptionalSchema<
       v.RecordSchema<
         v.SchemaWithPipe<
@@ -2033,16 +2034,6 @@ declare const SubworkflowsSchema: v.StrictObjectSchema<
       >,
       undefined
     >;
-    /**
-     * What happens to still-live children when their cohort's scope stops
-     * applying — the spawning stage exits, or a re-fire's `forEach` no longer
-     * discovers their row. `'detach'` (the default) lets them run to
-     * completion outside the gate; `'abort'` kills them (recursively). The
-     * engine never destroys in-flight work implicitly — `'abort'` is always
-     * an authored choice. Note this governs only the CHILDREN's fate; whether
-     * the parent may move at all is what gates (conditions over
-     * `$subworkflows`) decide.
-     */
     readonly onExit: v.OptionalSchema<
       v.PicklistSchema<readonly ["detach", "abort"], string>,
       undefined
@@ -2051,6 +2042,14 @@ declare const SubworkflowsSchema: v.StrictObjectSchema<
   undefined
 >;
 
+/**
+ * The statuses an activity can be resolved INTO — what `status.set` accepts.
+ * A health axis, not a decision axis: a routine decision (decline, send back,
+ * hold) resolves `done` and routes via a field write; `failed` means the work
+ * genuinely could not complete. Only `done`/`skipped` satisfy
+ * `$allActivitiesDone` — a `failed` activity blocks it permanently, surfacing
+ * via `$anyActivityFailed`.
+ */
 declare const TERMINAL_ACTIVITY_STATUSES: readonly [
   "done",
   "skipped",
@@ -2060,19 +2059,22 @@ declare const TERMINAL_ACTIVITY_STATUSES: readonly [
 declare type TerminalActivityStatus =
   (typeof TERMINAL_ACTIVITY_STATUSES)[number];
 
-/**
- * `todoList` — ad-hoc, status-tracked work items. Sugar over `array of object
- * { label, status, assignee?, dueDate? }`; a plain checklist is this used with
- * `{label, status}` only (open ↔ done). Never a stored kind.
- *
- * The `dueDate` column is a `date` NAMED `dueDate`, not the {@link
- * FieldValueMap.dueDate} kind — that kind reserves one deadline slot per level,
- * and a repeating row has nothing to reserve.
- */
+/** Ad-hoc, status-tracked work items: sugar over `array of object {label, status, assignee?, dueDate?}`; a plain checklist is that with `{label, status}` alone.
+ *  Its `dueDate` is a `date` column named `dueDate`, not the elevated `dueDate` kind, which reserves one deadline slot per level. Never a stored kind. */
 declare type TodoListField = FieldBase<AuthoringEditable, GroupMembership> & {
   type: "todoList";
 };
 
+/**
+ * A pure edge — `{name, when, to}` plus presentation, no ops or effects
+ * (structure never does; only actions do). Every transition is evaluated on
+ * every commit and cascade; the first truthy `when` in declaration order
+ * fires. No action coupling: a routing difference is written into fields by
+ * an action and read by the trigger — arrival work is a `when: 'true'`
+ * action in the destination stage, and exit work is an action in the source
+ * stage whose `when` repeats this transition's condition (the hop rule
+ * guarantees it commits before the move).
+ */
 declare type Transition = TransitionFields & {
   when: string;
 };
@@ -2112,6 +2114,16 @@ declare type ValueExprInternal =
 
 declare const WORKFLOW_LIFECYCLES: readonly ["standalone", "child"];
 
+/**
+ * `deployments` names must be unique (the selector deployment-targeted
+ * commands resolve by), and each `(workflowResource, tag)` pair must be
+ * unique — that pair is the storage partition, so two deployments sharing
+ * both would fight over definition versions. `telemetry`, when set, replaces
+ * the CLI's built-in Sanity-intake shell entirely: every event flows to this
+ * logger unconditionally (CI and `DO_NOT_TRACK` included), and consent,
+ * environment suppression, and transport become this implementation's
+ * business.
+ */
 declare type WorkflowConfig = v.InferOutput<typeof WorkflowConfigSchema>;
 
 /**
@@ -2735,14 +2747,6 @@ 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,
@@ -2754,6 +2758,21 @@ declare const WorkflowConfigSchema: v.ObjectSchema<
   undefined
 >;
 
+/**
+ * `name` is a lake-id-segment (`^[a-z0-9][a-z0-9-]*$`) that interpolates into
+ * every deployed document id (`<tag>.<name>.v<version>`) — stable identity
+ * that instances pin to and subworkflows resolve by. `lifecycle: 'child'`
+ * marks a spawn-only definition, instantiated by a parent via an action's
+ * `spawn`, never started cold from a picker (omitted ⇒ `'standalone'`,
+ * startable); advisory only — consumers filter start pickers on it (see
+ * {@link isStartableDefinition}), the engine does not itself refuse a
+ * `startInstance` on a `'child'` definition. `start` is meaningless
+ * (deploy-rejected) on a spawn-only definition; omitted, it means
+ * interactive semantics with no predicates. `predicates` are nullary named
+ * conditions — each `name: groq` entry is pre-evaluated and bound as the
+ * boolean `$name` var; redefining a built-in var is a deploy error, never a
+ * silent shadow.
+ */
 declare type WorkflowDefinition = v.InferOutput<
   typeof WorkflowDefinitionSchema
 >;
@@ -2763,47 +2782,41 @@ declare type WorkflowDefinition = v.InferOutput<
  * every reference scope resolved. Cross-field invariants (unique names,
  * transition targets, effect-name uniqueness, predicate shadowing) are
  * checked by `checkWorkflowInvariants` after desugar — see `defineWorkflow`.
+ * Carries NO `version`: a definition's version and content fingerprint are
+ * stamped onto the deployed document at deploy time, derived from the
+ * content itself, so redeploying identical content is a no-op and any
+ * change mints the next version.
  *
- * Carries NO `version` — the author never writes one. A definition's version
- * (and its content fingerprint) are stamped onto the deployed *document* at
- * deploy time, derived from the content itself; see `DeployedDefinition` and
- * `planDefinitionDeploy` in `api/deploy.ts`. The author's content is the sole
- * source of identity: redeploying identical content is a no-op, any change
- * mints the next version.
+ * Exported (module-level, not package API) for the model-surface gate's
+ * coverage test and for `parseStoredDefinition` — the boundary parse for a
+ * definition that did not come out of `defineWorkflow` in-process; trusted
+ * in-process desugar output is never re-parsed.
  */
 declare const WorkflowDefinitionSchema: v.GenericSchema<
   WorkflowFields<FieldEntry, Stage, StartBlock>
 >;
 
 /** One deployment as loaded from a config: the floor is optional/unverified so
- *  a command that never selects a deployment can hold a stale or missing
- *  acknowledgement. Deployment-scoped paths assert before they act; authors
- *  write {@link WorkflowDeploymentInput}. */
+ *  commands that do not submit definitions can hold a missing acknowledgement.
+ *  Definition-submission paths compare it with their selected definitions; authors write
+ *  {@link WorkflowDeploymentInput}. */
 declare type WorkflowDeployment = WorkflowConfig["deployments"][number];
 
 /**
- * What an author writes for one deployment: the current reader floor as the
- * reviewed literal. Compile-time only — omitting it or setting a wrong value
- * is a type error in the editor. Runtime parse still tolerates a stale or
- * missing floor on {@link WorkflowDeployment} so commands that never select a
- * deployment still run; deployment-scoped paths assert the selected
- * deployment (instance-id commands do not).
+ * What an author writes for one deployment: the highest reader model verified
+ * across runtimes sharing its workflow resource. Runtime validation compares
+ * it with the submitted definitions, so a dependency upgrade alone does not
+ * require changing the literal.
  */
 declare type WorkflowDeploymentInput = Omit<
   WorkflowDeployment,
   "expectedMinReaderModel"
 > & {
-  expectedMinReaderModel: typeof DATA_MODEL_MIN_READER;
+  expectedMinReaderModel: number;
 };
 
 /** 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;
   semantics?: Semantic[] | undefined;
   title: string;