@sanity/workflow-engine 0.16.0 → 0.18.0

package/dist/define.d.ts

@@ -4,10 +4,16 @@ declare type Action = ActionFields<Op, string[]> & {
   roles?: string[] | undefined;
 };
 
+declare const ACTION_SEMANTICS: readonly [
+  "decision.accept",
+  "decision.decline",
+];
+
 /** Type-mirror of {@link actionFields}, parameterised over the op and
  *  group-membership grammars. */
 declare type ActionFields<TOp, TGroup> = {
   name: string;
+  semantics?: ActionSemantic[] | undefined;
   title?: string | undefined;
   description?: string | undefined;
   group?: TGroup | undefined;
@@ -27,38 +33,135 @@ declare type ActionParam = v.InferOutput<typeof ActionParamSchema>;
  * effects: missing required params → ActionParamsInvalidError, action
  * does not commit. Resolved values feed `ValueExpr.param` lookups.
  */
-declare const ActionParamSchema: v.StrictObjectSchema<
-  {
-    readonly type: v.PicklistSchema<
-      readonly [
-        "string",
-        "number",
-        "boolean",
-        "url",
-        "dateTime",
-        "actor",
-        "doc.ref",
-        "doc.refs",
-        "json",
-      ],
-      `Invalid option: expected one of ${string}`
-    >;
-    readonly 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>,
+declare const ActionParamSchema: v.SchemaWithPipe<
+  readonly [
+    v.StrictObjectSchema<
+      {
+        readonly type: v.PicklistSchema<
+          readonly [
+            "string",
+            "number",
+            "boolean",
+            "url",
+            "dateTime",
+            "actor",
+            "doc.ref",
+            "doc.refs",
+            "json",
+          ],
+          `Invalid option: expected one of ${string}`
+        >;
+        readonly 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 required: v.OptionalSchema<
+          v.BooleanSchema<undefined>,
+          undefined
+        >;
+        readonly options: v.OptionalSchema<
+          v.GenericSchema<ChoiceOptions>,
+          undefined
+        >;
+        readonly validation: v.OptionalSchema<
+          v.GenericSchema<ScalarValidation>,
+          undefined
+        >;
+      },
       undefined
-    >;
-    readonly required: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
-  },
-  undefined
+    >,
+    v.CheckAction<
+      {
+        type:
+          | "string"
+          | "number"
+          | "boolean"
+          | "doc.ref"
+          | "doc.refs"
+          | "url"
+          | "actor"
+          | "dateTime"
+          | "json";
+        name: string;
+        title?: string | undefined;
+        description?: string | undefined;
+        required?: boolean | undefined;
+        options?: ChoiceOptions | undefined;
+        validation?: ScalarValidation | undefined;
+      },
+      (
+        issue: v.CheckIssue<{
+          type:
+            | "string"
+            | "number"
+            | "boolean"
+            | "doc.ref"
+            | "doc.refs"
+            | "url"
+            | "actor"
+            | "dateTime"
+            | "json";
+          name: string;
+          title?: string | undefined;
+          description?: string | undefined;
+          required?: boolean | undefined;
+          options?: ChoiceOptions | undefined;
+          validation?: ScalarValidation | undefined;
+        }>,
+      ) => string
+    >,
+    v.CheckAction<
+      {
+        type:
+          | "string"
+          | "number"
+          | "boolean"
+          | "doc.ref"
+          | "doc.refs"
+          | "url"
+          | "actor"
+          | "dateTime"
+          | "json";
+        name: string;
+        title?: string | undefined;
+        description?: string | undefined;
+        required?: boolean | undefined;
+        options?: ChoiceOptions | undefined;
+        validation?: ScalarValidation | undefined;
+      },
+      (
+        issue: v.CheckIssue<{
+          type:
+            | "string"
+            | "number"
+            | "boolean"
+            | "doc.ref"
+            | "doc.refs"
+            | "url"
+            | "actor"
+            | "dateTime"
+            | "json";
+          name: string;
+          title?: string | undefined;
+          description?: string | undefined;
+          required?: boolean | undefined;
+          options?: ChoiceOptions | undefined;
+          validation?: ScalarValidation | undefined;
+        }>,
+      ) => string
+    >,
+  ]
 >;
 
+declare type ActionSemantic = (typeof ACTION_SEMANTICS)[number];
+
 declare type Activity = ActivityFields<
   FieldEntry,
   Action,
@@ -150,6 +253,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 +419,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>;
     /**
@@ -764,6 +873,17 @@ declare type AuthoringWorkflow = WorkflowFields<
   AuthoringStartBlock
 >;
 
+declare interface ChoiceOption {
+  title: string;
+  value: ChoiceValue;
+}
+
+declare interface ChoiceOptions {
+  list: ChoiceOption[];
+}
+
+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
@@ -839,11 +959,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,11 +980,20 @@ 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";
 
+/**
+ * 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 = 2;
+
 export declare function defineAction(action: AuthoringAction): AuthoringAction;
 
 export declare function defineActivity(
@@ -919,8 +1051,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,
@@ -1018,6 +1151,7 @@ declare const EffectSchema: v.StrictObjectSchema<
 declare const FIELD_VALUE_KINDS: readonly [
   "doc.ref",
   "doc.refs",
+  "subject",
   "release.ref",
   "string",
   "text",
@@ -1054,6 +1188,8 @@ declare type FieldEntryFields<TEditable, TGroup> = FieldBase<
   TGroup
 > & {
   type: FieldValueKind;
+  options?: ChoiceOptions | undefined;
+  validation?: ScalarValidation | undefined;
   types?: string[] | undefined;
   fields?: FieldShape[] | undefined;
   of?: FieldShape[] | undefined;
@@ -1071,6 +1207,8 @@ declare interface FieldShape {
   name: string;
   title?: string | undefined;
   description?: string | undefined;
+  options?: ChoiceOptions | undefined;
+  validation?: ScalarValidation | undefined;
   fields?: FieldShape[] | undefined;
   of?: FieldShape[] | undefined;
 }
@@ -1158,6 +1296,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 +1372,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>;
     /**
@@ -1281,12 +1425,11 @@ declare type NotesField = FieldBase<AuthoringEditable, GroupMembership> & {
 
 declare type Op = v.InferOutput<typeof StoredOpSchema>;
 
-/**
- * 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}.
- */
+declare type ParsedWorkflowConfig = v.InferOutput<typeof WorkflowConfigSchema>;
+
+declare type ParsedWorkflowDeployment =
+  ParsedWorkflowConfig["deployments"][number];
+
 export declare const RESERVED_CONDITION_VARS: readonly string[];
 
 declare type RoleAliases = v.InferOutput<typeof RoleAliasesSchema>;
@@ -1346,6 +1489,13 @@ declare const RoleAliasesSchema: v.RecordSchema<
   undefined
 >;
 
+/** Inclusive scalar bounds. String/text bounds measure character length;
+ * number bounds measure the numeric value. */
+declare interface ScalarValidation {
+  min?: number | undefined;
+  max?: number | undefined;
+}
+
 declare type Stage = StageFields<
   FieldEntry,
   Activity,
@@ -1378,6 +1528,7 @@ declare type StartBlock = StartFields & {
  *  authoring may omit it — so each variant declares it. */
 declare type StartFields = {
   filter?: string | undefined;
+  allowed?: string | undefined;
 };
 
 /**
@@ -1762,7 +1913,9 @@ declare type ValueExprInternal =
 
 declare const WORKFLOW_LIFECYCLES: readonly ["standalone", "child"];
 
-declare type WorkflowConfig = v.InferOutput<typeof WorkflowConfigSchema>;
+declare type WorkflowConfig = Omit<ParsedWorkflowConfig, "deployments"> & {
+  deployments: WorkflowDeployment[];
+};
 
 declare const WorkflowConfigSchema: v.ObjectSchema<
   {
@@ -1777,6 +1930,10 @@ declare const WorkflowConfigSchema: v.ObjectSchema<
                   v.NonEmptyAction<string, "must not be empty">,
                 ]
               >;
+              readonly expectedMinReaderModel: v.OptionalSchema<
+                v.CustomSchema<2, undefined>,
+                undefined
+              >;
               readonly tag: v.SchemaWithPipe<
                 readonly [
                   v.StringSchema<undefined>,
@@ -2038,6 +2195,7 @@ declare const WorkflowConfigSchema: v.ObjectSchema<
         v.MinLengthAction<
           {
             name: string;
+            expectedMinReaderModel?: 2 | undefined;
             tag: string;
             workflowResource:
               | {
@@ -2098,6 +2256,7 @@ declare const WorkflowConfigSchema: v.ObjectSchema<
         v.CheckAction<
           {
             name: string;
+            expectedMinReaderModel?: 2 | undefined;
             tag: string;
             workflowResource:
               | {
@@ -2196,8 +2355,21 @@ declare const WorkflowDefinitionSchema: v.GenericSchema<
   WorkflowFields<FieldEntry, Stage, StartBlock>
 >;
 
+declare type WorkflowDeployment = Omit<
+  ParsedWorkflowDeployment,
+  "expectedMinReaderModel"
+> & {
+  expectedMinReaderModel: typeof DATA_MODEL_MIN_READER;
+};
+
 /** 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.js

@@ -1,4 +1,4 @@
-import { parseOrThrow, desugarWorkflow, checkWorkflowInvariants, formatValidationError, AuthoringWorkflowSchema, labelFor, WorkflowConfigSchema, AuthoringStageSchema, AuthoringActivitySchema, AuthoringActionSchema, AuthoringTransitionSchema, AuthoringFieldEntrySchema, AuthoringOpSchema, GroupSchema, AuthoringGuardSchema, EffectSchema } from "./_chunks-es/invariants.js";
+import { parseOrThrow, desugarWorkflow, checkWorkflowInvariants, formatValidationError, WorkflowConfigSchema, assertReaderModelAcknowledgement, AuthoringWorkflowSchema, labelFor, AuthoringStageSchema, AuthoringActivitySchema, AuthoringActionSchema, AuthoringTransitionSchema, AuthoringFieldEntrySchema, AuthoringOpSchema, GroupSchema, AuthoringGuardSchema, EffectSchema } from "./_chunks-es/invariants.js";
 
 import { CONDITION_VARS, FILTER_SCOPE_VARS, GUARD_PREDICATE_VARS, RESERVED_CONDITION_VARS, groq } from "./_chunks-es/invariants.js";
 
@@ -13,11 +13,16 @@ function defineWorkflow(definition) {
 }
 
 function defineWorkflowConfig(config) {
-    return parseOrThrow({
+    const parsed = parseOrThrow({
         schema: WorkflowConfigSchema,
         input: config,
         label: "defineWorkflowConfig"
     });
+    return assertDeploymentAcknowledgements(parsed), parsed;
+}
+
+function assertDeploymentAcknowledgements(config) {
+    for (const [index, deployment] of config.deployments.entries()) assertReaderModelAcknowledgement(deployment.expectedMinReaderModel, `Deployment ${deployment.name || `at deployments[${index}]`}`);
 }
 
 function defineStage(stage) {