@sanity/workflow-engine 0.16.0 → 0.17.0

package/dist/define.d.cts

@@ -150,6 +150,11 @@ declare type AuthoringGuard = v.InferOutput<typeof AuthoringGuardSchema>;
 
 declare const AuthoringGuardSchema: v.StrictObjectSchema<
   {
+    /**
+     * Lake-id-segment grammar (`^[a-z0-9][a-z0-9-]*$`, deploy-enforced): the
+     * guard's lake `_id` derives from `(instanceId, name)` at stage entry.
+     * Unique per definition.
+     */
     name: v.SchemaWithPipe<
       readonly [
         v.StringSchema<undefined>,
@@ -311,8 +316,9 @@ declare const AuthoringGuardSchema: v.StrictObjectSchema<
     /**
      * Lake GROQ predicate — a distinct eval context: delta-mode GROQ
      * reading the `before()`/`after()` natives, `mutation`, `guard`, and
-     * `identity()`. Bare ids/fields only. Omitted or empty means
-     * UNCONDITIONAL DENY.
+     * `identity()`. Bare ids/fields only. Polarity: a result of strictly
+     * `true` ALLOWS the matched mutation; anything else (false, null, an
+     * evaluation error) DENIES. Omitted or empty means UNCONDITIONAL DENY.
      */
     predicate: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
     /**
@@ -839,11 +845,14 @@ export declare interface ConditionVar {
  *    the rest evaluate to `undefined` — and deploy rejects them at these
  *    sites; a cascade-fired action's per-token gate is `roles`, never its
  *    conditions.
- * 3. **The start-filter context** — a definition's `start.filter` evaluates
- *    against a CANDIDATE (no instance exists yet): the candidate document is
- *    the root, {@link START_FILTER_VARS} are the only bound vars, and
- *    `*[...]` reads the WORKFLOW resource's dataset. None of the rendered
- *    condition vars exist there.
+ * 3. **The start contexts** — a definition's `start.filter` and
+ *    `start.allowed` evaluate against a CANDIDATE (no instance exists yet):
+ *    `*[...]` reads the WORKFLOW resource's dataset and none of the rendered
+ *    condition vars exist. The two split on what a surface can know:
+ *    `filter` is browse-time-pure (candidate document as root,
+ *    {@link START_FILTER_VARS} — no `$fields`, which cannot exist before
+ *    inputs do), `allowed` is the start-time permission predicate
+ *    ({@link START_ALLOWED_VARS} — `$fields` bound, never a root).
  * 4. **Guard predicates** — NOT conditions. A lake mutation guard's
  *    `predicate` is groq-js **delta-mode** GROQ over a document mutation:
  *    `before()`/`after()`/`identity()` are dialect natives, and the wire
@@ -857,7 +866,7 @@ export declare interface ConditionVar {
  *   instance and its snapshot.
  * - `'caller'` — rides the acting caller; without one the var is `undefined`
  *   (conditions referencing it fail closed). Author predicates may not read
- *   these — they pre-evaluate once per instance, caller-free.
+ *   these — they pre-evaluate caller-free, per evaluation context.
  * - `'spawn'` — bound only at spawn sites (the per-row `$row`).
  */
 export declare type ConditionVarBinding = "always" | "caller" | "spawn";
@@ -919,8 +928,9 @@ export declare function defineWorkflow(
 /**
  * Validate a deploy config — the binding of each definition's logical resource
  * handles to physical resources, per environment (tag). Throws a formatted,
- * path-prefixed error if the shape is invalid. The CLI hands the selected
- * deployment's {@link resourceAliasesToMap} map to {@link deployDefinitions}.
+ * path-prefixed error if the shape is invalid. The CLI collapses the selected
+ * deployment's bindings via {@link resourceAliasesToMap} into the
+ * `resourceAliases` map `deployDefinitions` expands against.
  */
 export declare function defineWorkflowConfig(
   config: WorkflowConfig,
@@ -1158,6 +1168,11 @@ export declare const GUARD_PREDICATE_VARS: readonly {
 /** Stored guards carry the printed string reads (the deploy resolver's input). */
 declare const GuardSchema: v.StrictObjectSchema<
   {
+    /**
+     * Lake-id-segment grammar (`^[a-z0-9][a-z0-9-]*$`, deploy-enforced): the
+     * guard's lake `_id` derives from `(instanceId, name)` at stage entry.
+     * Unique per definition.
+     */
     name: v.SchemaWithPipe<
       readonly [
         v.StringSchema<undefined>,
@@ -1229,8 +1244,9 @@ declare const GuardSchema: v.StrictObjectSchema<
     /**
      * Lake GROQ predicate — a distinct eval context: delta-mode GROQ
      * reading the `before()`/`after()` natives, `mutation`, `guard`, and
-     * `identity()`. Bare ids/fields only. Omitted or empty means
-     * UNCONDITIONAL DENY.
+     * `identity()`. Bare ids/fields only. Polarity: a result of strictly
+     * `true` ALLOWS the matched mutation; anything else (false, null, an
+     * evaluation error) DENIES. Omitted or empty means UNCONDITIONAL DENY.
      */
     predicate: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
     /**
@@ -1378,6 +1394,7 @@ declare type StartBlock = StartFields & {
  *  authoring may omit it — so each variant declares it. */
 declare type StartFields = {
   filter?: string | undefined;
+  allowed?: string | undefined;
 };
 
 /**
@@ -2198,6 +2215,12 @@ declare const WorkflowDefinitionSchema: v.GenericSchema<
 
 /** Type-mirror of {@link workflowFields}, parameterised over field/stage/start. */
 declare type WorkflowFields<TField, TStage, TStart> = {
+  /**
+   * Lake-id-segment grammar (`^[a-z0-9][a-z0-9-]*$`, deploy-enforced): the
+   * name interpolates into every deployed document id
+   * (`<tag>.<name>.v<version>`). Stable identity — instances pin to it,
+   * subworkflows resolve by it.
+   */
   name: string;
   title: string;
   description?: string | undefined;

package/dist/define.d.ts

@@ -150,6 +150,11 @@ declare type AuthoringGuard = v.InferOutput<typeof AuthoringGuardSchema>;
 
 declare const AuthoringGuardSchema: v.StrictObjectSchema<
   {
+    /**
+     * Lake-id-segment grammar (`^[a-z0-9][a-z0-9-]*$`, deploy-enforced): the
+     * guard's lake `_id` derives from `(instanceId, name)` at stage entry.
+     * Unique per definition.
+     */
     name: v.SchemaWithPipe<
       readonly [
         v.StringSchema<undefined>,
@@ -311,8 +316,9 @@ declare const AuthoringGuardSchema: v.StrictObjectSchema<
     /**
      * Lake GROQ predicate — a distinct eval context: delta-mode GROQ
      * reading the `before()`/`after()` natives, `mutation`, `guard`, and
-     * `identity()`. Bare ids/fields only. Omitted or empty means
-     * UNCONDITIONAL DENY.
+     * `identity()`. Bare ids/fields only. Polarity: a result of strictly
+     * `true` ALLOWS the matched mutation; anything else (false, null, an
+     * evaluation error) DENIES. Omitted or empty means UNCONDITIONAL DENY.
      */
     predicate: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
     /**
@@ -839,11 +845,14 @@ export declare interface ConditionVar {
  *    the rest evaluate to `undefined` — and deploy rejects them at these
  *    sites; a cascade-fired action's per-token gate is `roles`, never its
  *    conditions.
- * 3. **The start-filter context** — a definition's `start.filter` evaluates
- *    against a CANDIDATE (no instance exists yet): the candidate document is
- *    the root, {@link START_FILTER_VARS} are the only bound vars, and
- *    `*[...]` reads the WORKFLOW resource's dataset. None of the rendered
- *    condition vars exist there.
+ * 3. **The start contexts** — a definition's `start.filter` and
+ *    `start.allowed` evaluate against a CANDIDATE (no instance exists yet):
+ *    `*[...]` reads the WORKFLOW resource's dataset and none of the rendered
+ *    condition vars exist. The two split on what a surface can know:
+ *    `filter` is browse-time-pure (candidate document as root,
+ *    {@link START_FILTER_VARS} — no `$fields`, which cannot exist before
+ *    inputs do), `allowed` is the start-time permission predicate
+ *    ({@link START_ALLOWED_VARS} — `$fields` bound, never a root).
  * 4. **Guard predicates** — NOT conditions. A lake mutation guard's
  *    `predicate` is groq-js **delta-mode** GROQ over a document mutation:
  *    `before()`/`after()`/`identity()` are dialect natives, and the wire
@@ -857,7 +866,7 @@ export declare interface ConditionVar {
  *   instance and its snapshot.
  * - `'caller'` — rides the acting caller; without one the var is `undefined`
  *   (conditions referencing it fail closed). Author predicates may not read
- *   these — they pre-evaluate once per instance, caller-free.
+ *   these — they pre-evaluate caller-free, per evaluation context.
  * - `'spawn'` — bound only at spawn sites (the per-row `$row`).
  */
 export declare type ConditionVarBinding = "always" | "caller" | "spawn";
@@ -919,8 +928,9 @@ export declare function defineWorkflow(
 /**
  * Validate a deploy config — the binding of each definition's logical resource
  * handles to physical resources, per environment (tag). Throws a formatted,
- * path-prefixed error if the shape is invalid. The CLI hands the selected
- * deployment's {@link resourceAliasesToMap} map to {@link deployDefinitions}.
+ * path-prefixed error if the shape is invalid. The CLI collapses the selected
+ * deployment's bindings via {@link resourceAliasesToMap} into the
+ * `resourceAliases` map `deployDefinitions` expands against.
  */
 export declare function defineWorkflowConfig(
   config: WorkflowConfig,
@@ -1158,6 +1168,11 @@ export declare const GUARD_PREDICATE_VARS: readonly {
 /** Stored guards carry the printed string reads (the deploy resolver's input). */
 declare const GuardSchema: v.StrictObjectSchema<
   {
+    /**
+     * Lake-id-segment grammar (`^[a-z0-9][a-z0-9-]*$`, deploy-enforced): the
+     * guard's lake `_id` derives from `(instanceId, name)` at stage entry.
+     * Unique per definition.
+     */
     name: v.SchemaWithPipe<
       readonly [
         v.StringSchema<undefined>,
@@ -1229,8 +1244,9 @@ declare const GuardSchema: v.StrictObjectSchema<
     /**
      * Lake GROQ predicate — a distinct eval context: delta-mode GROQ
      * reading the `before()`/`after()` natives, `mutation`, `guard`, and
-     * `identity()`. Bare ids/fields only. Omitted or empty means
-     * UNCONDITIONAL DENY.
+     * `identity()`. Bare ids/fields only. Polarity: a result of strictly
+     * `true` ALLOWS the matched mutation; anything else (false, null, an
+     * evaluation error) DENIES. Omitted or empty means UNCONDITIONAL DENY.
      */
     predicate: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
     /**
@@ -1378,6 +1394,7 @@ declare type StartBlock = StartFields & {
  *  authoring may omit it — so each variant declares it. */
 declare type StartFields = {
   filter?: string | undefined;
+  allowed?: string | undefined;
 };
 
 /**
@@ -2198,6 +2215,12 @@ declare const WorkflowDefinitionSchema: v.GenericSchema<
 
 /** Type-mirror of {@link workflowFields}, parameterised over field/stage/start. */
 declare type WorkflowFields<TField, TStage, TStart> = {
+  /**
+   * Lake-id-segment grammar (`^[a-z0-9][a-z0-9-]*$`, deploy-enforced): the
+   * name interpolates into every deployed document id
+   * (`<tag>.<name>.v<version>`). Stable identity — instances pin to it,
+   * subworkflows resolve by it.
+   */
   name: string;
   title: string;
   description?: string | undefined;