@sanity/workflow-engine 0.27.0 → 0.29.0

package/dist/define.d.ts

@@ -4,11 +4,6 @@ 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> = {
@@ -160,7 +155,7 @@ declare const ActionParamSchema: v.SchemaWithPipe<
   ]
 >;
 
-declare type ActionSemantic = (typeof ACTION_SEMANTICS)[number];
+declare type ActionSemantic = DecisionSemantic | Semantic;
 
 declare type Activity = ActivityFields<
   FieldEntry,
@@ -172,6 +167,7 @@ declare type Activity = ActivityFields<
 /** Type-mirror of {@link activityFields}, parameterised over field/action/target/group. */
 declare type ActivityFields<TField, TAction, TTarget, TGroup> = {
   name: string;
+  semantics?: Semantic[] | undefined;
   title?: string | undefined;
   description?: string | undefined;
   groups?: Group[] | undefined;
@@ -627,6 +623,31 @@ declare const AuthoringOpSchema: v.VariantSchema<
       },
       undefined
     >,
+    v.StrictObjectSchema<
+      {
+        readonly type: v.LiteralSchema<"field.setIfMissing", undefined>;
+        readonly target: v.StrictObjectSchema<
+          {
+            readonly scope: v.OptionalSchema<
+              v.PicklistSchema<
+                readonly ["workflow", "stage", "activity"],
+                string
+              >,
+              undefined
+            >;
+            readonly field: v.SchemaWithPipe<
+              readonly [
+                v.StringSchema<undefined>,
+                v.MinLengthAction<string, 1, "must be a non-empty string">,
+              ]
+            >;
+          },
+          undefined
+        >;
+        readonly value: v.GenericSchema<ValueExprInternal>;
+      },
+      undefined
+    >,
     v.StrictObjectSchema<
       {
         readonly type: v.LiteralSchema<"field.unset", undefined>;
@@ -676,6 +697,62 @@ declare const AuthoringOpSchema: v.VariantSchema<
       },
       undefined
     >,
+    v.StrictObjectSchema<
+      {
+        readonly type: v.LiteralSchema<"field.inc", undefined>;
+        readonly target: v.StrictObjectSchema<
+          {
+            readonly scope: v.OptionalSchema<
+              v.PicklistSchema<
+                readonly ["workflow", "stage", "activity"],
+                string
+              >,
+              undefined
+            >;
+            readonly field: v.SchemaWithPipe<
+              readonly [
+                v.StringSchema<undefined>,
+                v.MinLengthAction<string, 1, "must be a non-empty string">,
+              ]
+            >;
+          },
+          undefined
+        >;
+        readonly value: v.OptionalSchema<
+          v.GenericSchema<ValueExprInternal>,
+          undefined
+        >;
+      },
+      undefined
+    >,
+    v.StrictObjectSchema<
+      {
+        readonly type: v.LiteralSchema<"field.dec", undefined>;
+        readonly target: v.StrictObjectSchema<
+          {
+            readonly scope: v.OptionalSchema<
+              v.PicklistSchema<
+                readonly ["workflow", "stage", "activity"],
+                string
+              >,
+              undefined
+            >;
+            readonly field: v.SchemaWithPipe<
+              readonly [
+                v.StringSchema<undefined>,
+                v.MinLengthAction<string, 1, "must be a non-empty string">,
+              ]
+            >;
+          },
+          undefined
+        >;
+        readonly value: v.OptionalSchema<
+          v.GenericSchema<ValueExprInternal>,
+          undefined
+        >;
+      },
+      undefined
+    >,
     v.StrictObjectSchema<
       {
         readonly type: v.LiteralSchema<"field.updateWhere", undefined>;
@@ -983,6 +1060,25 @@ export declare interface ConditionVar {
  */
 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",
+];
+
+declare type DecisionSemantic = (typeof DECISION_SEMANTICS)[number];
+
 export declare function defineAction(action: AuthoringAction): AuthoringAction;
 
 export declare function defineActivity(
@@ -1043,9 +1139,18 @@ export declare function defineWorkflow(
  * 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.
+ *
+ * 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.
  */
 export declare function defineWorkflowConfig(
-  config: WorkflowConfig,
+  config: WorkflowConfigInput,
 ): WorkflowConfig;
 
 declare type Editable = v.InferOutput<typeof StoredEditableSchema>;
@@ -1422,11 +1527,6 @@ declare type NotesField = FieldBase<AuthoringEditable, GroupMembership> & {
 
 declare type Op = v.InferOutput<typeof StoredOpSchema>;
 
-declare type ParsedWorkflowConfig = v.InferOutput<typeof WorkflowConfigSchema>;
-
-declare type ParsedWorkflowDeployment =
-  ParsedWorkflowConfig["deployments"][number];
-
 declare type RequirementBase = {
   name: string;
   title?: string | undefined;
@@ -1505,6 +1605,16 @@ declare interface ScalarValidation {
   max?: number | undefined;
 }
 
+declare type Semantic = SignalSemantic | CustomSemantic;
+
+declare const SIGNAL_SEMANTICS: readonly [
+  "signal.positive",
+  "signal.caution",
+  "signal.critical",
+];
+
+declare type SignalSemantic = (typeof SIGNAL_SEMANTICS)[number];
+
 declare type SingleSubjectRequirement = RequirementBase & {
   type: "singleSubject";
 };
@@ -1520,6 +1630,7 @@ declare type Stage = StageFields<
 /** Type-mirror of {@link stageFields}, parameterised over field/activity/transition/guard/editable. */
 declare type StageFields<TField, TActivity, TTransition, TGuard, TEditable> = {
   name: string;
+  semantics?: Semantic[] | undefined;
   title?: string | undefined;
   description?: string | undefined;
   groups?: Group[] | undefined;
@@ -1562,9 +1673,9 @@ declare type StartRequirement = GroqRequirement | SingleSubjectRequirement;
  * (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`, `$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.
+ * `$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<
   [
@@ -1645,6 +1756,28 @@ declare const StoredOpSchema: v.VariantSchema<
       },
       undefined
     >,
+    v.StrictObjectSchema<
+      {
+        readonly type: v.LiteralSchema<"field.setIfMissing", undefined>;
+        readonly target: v.StrictObjectSchema<
+          {
+            readonly scope: v.PicklistSchema<
+              readonly ["workflow", "stage", "activity"],
+              string
+            >;
+            readonly field: v.SchemaWithPipe<
+              readonly [
+                v.StringSchema<undefined>,
+                v.MinLengthAction<string, 1, "must be a non-empty string">,
+              ]
+            >;
+          },
+          undefined
+        >;
+        readonly value: v.GenericSchema<ValueExprInternal>;
+      },
+      undefined
+    >,
     v.StrictObjectSchema<
       {
         readonly type: v.LiteralSchema<"field.unset", undefined>;
@@ -1688,6 +1821,56 @@ declare const StoredOpSchema: v.VariantSchema<
       },
       undefined
     >,
+    v.StrictObjectSchema<
+      {
+        readonly type: v.LiteralSchema<"field.inc", undefined>;
+        readonly target: v.StrictObjectSchema<
+          {
+            readonly scope: v.PicklistSchema<
+              readonly ["workflow", "stage", "activity"],
+              string
+            >;
+            readonly field: v.SchemaWithPipe<
+              readonly [
+                v.StringSchema<undefined>,
+                v.MinLengthAction<string, 1, "must be a non-empty string">,
+              ]
+            >;
+          },
+          undefined
+        >;
+        readonly value: v.OptionalSchema<
+          v.GenericSchema<ValueExprInternal>,
+          undefined
+        >;
+      },
+      undefined
+    >,
+    v.StrictObjectSchema<
+      {
+        readonly type: v.LiteralSchema<"field.dec", undefined>;
+        readonly target: v.StrictObjectSchema<
+          {
+            readonly scope: v.PicklistSchema<
+              readonly ["workflow", "stage", "activity"],
+              string
+            >;
+            readonly field: v.SchemaWithPipe<
+              readonly [
+                v.StringSchema<undefined>,
+                v.MinLengthAction<string, 1, "must be a non-empty string">,
+              ]
+            >;
+          },
+          undefined
+        >;
+        readonly value: v.OptionalSchema<
+          v.GenericSchema<ValueExprInternal>,
+          undefined
+        >;
+      },
+      undefined
+    >,
     v.StrictObjectSchema<
       {
         readonly type: v.LiteralSchema<"field.updateWhere", undefined>;
@@ -1929,8 +2112,15 @@ declare type ValueExprInternal =
 
 declare const WORKFLOW_LIFECYCLES: readonly ["standalone", "child"];
 
-declare type WorkflowConfig = Omit<ParsedWorkflowConfig, "deployments"> & {
-  deployments: WorkflowDeployment[];
+declare type WorkflowConfig = v.InferOutput<typeof WorkflowConfigSchema>;
+
+/**
+ * What an author writes for a whole config: every deployment is a
+ * {@link WorkflowDeploymentInput}. `defineWorkflowConfig` accepts this and
+ * returns the looser {@link WorkflowConfig}.
+ */
+declare type WorkflowConfigInput = Omit<WorkflowConfig, "deployments"> & {
+  deployments: WorkflowDeploymentInput[];
 };
 
 declare const WorkflowConfigSchema: v.ObjectSchema<
@@ -2196,6 +2386,7 @@ declare const WorkflowConfigSchema: v.ObjectSchema<
                     v.CustomSchema<
                       {
                         name: string;
+                        semantics?: Semantic[] | undefined;
                         title: string;
                         description?: string | undefined;
                         groups?: Group[] | undefined;
@@ -2214,6 +2405,7 @@ declare const WorkflowConfigSchema: v.ObjectSchema<
                   v.MinLengthAction<
                     {
                       name: string;
+                      semantics?: Semantic[] | undefined;
                       title: string;
                       description?: string | undefined;
                       groups?: Group[] | undefined;
@@ -2281,6 +2473,7 @@ declare const WorkflowConfigSchema: v.ObjectSchema<
               | undefined;
             definitions: {
               name: string;
+              semantics?: Semantic[] | undefined;
               title: string;
               description?: string | undefined;
               groups?: Group[] | undefined;
@@ -2342,6 +2535,7 @@ declare const WorkflowConfigSchema: v.ObjectSchema<
               | undefined;
             definitions: {
               name: string;
+              semantics?: Semantic[] | undefined;
               title: string;
               description?: string | undefined;
               groups?: Group[] | undefined;
@@ -2401,6 +2595,7 @@ declare const WorkflowConfigSchema: v.ObjectSchema<
                   | undefined;
                 definitions: {
                   name: string;
+                  semantics?: Semantic[] | undefined;
                   title: string;
                   description?: string | undefined;
                   groups?: Group[] | undefined;
@@ -2462,6 +2657,7 @@ declare const WorkflowConfigSchema: v.ObjectSchema<
               | undefined;
             definitions: {
               name: string;
+              semantics?: Semantic[] | undefined;
               title: string;
               description?: string | undefined;
               groups?: Group[] | undefined;
@@ -2521,6 +2717,7 @@ declare const WorkflowConfigSchema: v.ObjectSchema<
                   | undefined;
                 definitions: {
                   name: string;
+                  semantics?: Semantic[] | undefined;
                   title: string;
                   description?: string | undefined;
                   groups?: Group[] | undefined;
@@ -2578,15 +2775,25 @@ declare const WorkflowDefinitionSchema: v.GenericSchema<
   WorkflowFields<FieldEntry, Stage, StartBlock>
 >;
 
-declare type WorkflowDeployment = Omit<
-  ParsedWorkflowDeployment,
+/** 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}. */
+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).
+ */
+declare type WorkflowDeploymentInput = Omit<
+  WorkflowDeployment,
   "expectedMinReaderModel"
 > & {
-  /**
-   * Reviewed numeric literal. Runtime validation owns the exact installed-floor check so a stale
-   * acknowledgement reaches the readers-first rollout guidance instead of becoming a type error.
-   */
-  expectedMinReaderModel: number;
+  expectedMinReaderModel: typeof DATA_MODEL_MIN_READER;
 };
 
 /** Type-mirror of {@link workflowFields}, parameterised over field/stage/start. */
@@ -2598,6 +2805,7 @@ declare type WorkflowFields<TField, TStage, TStart> = {
    * subworkflows resolve by it.
    */
   name: string;
+  semantics?: Semantic[] | undefined;
   title: string;
   description?: string | undefined;
   groups?: Group[] | undefined;

package/dist/define.js

@@ -1,4 +1,4 @@
-import { parseOrThrow, desugarWorkflow, checkWorkflowInvariants, formatValidationError, WorkflowConfigSchema, assertReaderModelAcknowledgement, AuthoringWorkflowSchema, labelFor, AuthoringStageSchema, AuthoringActivitySchema, AuthoringActionSchema, AuthoringTransitionSchema, AuthoringFieldEntrySchema, AuthoringOpSchema, GroupSchema, AuthoringGuardSchema, EffectSchema } from "./_chunks-es/invariants.js";
+import { parseOrThrow, desugarWorkflow, checkWorkflowInvariants, formatValidationError, AuthoringWorkflowSchema, labelFor, WorkflowConfigSchema, 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,16 +13,11 @@ function defineWorkflow(definition) {
 }
 
 function defineWorkflowConfig(config) {
-    const parsed = parseOrThrow({
+    return 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) {