@sanity/workflow-engine 0.27.0 → 0.29.0

package/dist/index.d.cts

@@ -86,6 +86,9 @@ export declare type Action = ActionFields<Op, string[]> & {
 export declare const ACTION_SEMANTICS: readonly [
   "decision.accept",
   "decision.decline",
+  "signal.positive",
+  "signal.caution",
+  "signal.critical",
 ];
 
 /**
@@ -358,7 +361,7 @@ export declare function actionRendering(action: {
     | undefined;
 }): "absent" | "automation" | "button";
 
-export declare type ActionSemantic = (typeof ACTION_SEMANTICS)[number];
+export declare type ActionSemantic = DecisionSemantic | Semantic;
 
 /** The fireable-action verdict for one action on an activity — its `allowed`
  *  state, structured `disabledReason`, and declared params, tagged with the
@@ -416,8 +419,9 @@ export declare const ACTIVITY_KINDS: readonly [
 ];
 
 /**
- * Leaf enums — the const arrays (and their derived union types) that both
- * the authoring schema and the engine address by name.
+ * Leaf vocabularies that both the authoring schema and the engine address by
+ * name. Some exported types also include grammar-validated open values that
+ * cannot be enumerated by a const array.
  *
  * This module imports nothing. It is the schema-free foundation that
  * `../define/schema.ts` reads its value constants from, which is what keeps
@@ -478,6 +482,8 @@ export declare interface ActivityEntry {
 
 export declare interface ActivityEvaluation {
   activity: Activity;
+  /** The activity's advisory workflow meaning, unchanged from its definition. */
+  semantics?: Semantic[] | undefined;
   status: ActivityStatus;
   /**
    * The activity's shape-derived {@link ActivityKind}. Advisory: a label so a
@@ -529,6 +535,7 @@ export declare interface ActivityEvaluation {
 /** 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;
@@ -1160,6 +1167,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>;
@@ -1209,6 +1241,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>;
@@ -2288,6 +2376,9 @@ export declare function createTelemetryIntake(args: {
   denied?: boolean;
 }): TelemetryIntake;
 
+/** A define-time validated `custom.<camelCaseMeaning>` value. */
+export declare type CustomSemantic = `custom.${string}`;
+
 /**
  * The append-only, machine-readable counterpart of the model log in
  * `DATAMODEL.md`. It records compatibility decisions; the prose log retains
@@ -2328,7 +2419,7 @@ export declare const DATA_MODEL_CHANGES: readonly [
     documentTypes: readonly ["definition"];
     compatibility: "additive";
     applicability: "detectable";
-    summary: "Ordinary actions may carry a closed bag of advisory workflow semantics.";
+    summary: "Ordinary actions may carry advisory workflow semantics.";
   }>,
   Readonly<{
     id: "inclusive-scalar-bounds";
@@ -2384,6 +2475,33 @@ export declare const DATA_MODEL_CHANGES: readonly [
     applicability: "detectable";
     summary: string;
   }>,
+  Readonly<{
+    id: "node-semantics";
+    introducedInModel: 6;
+    minReaderModel: 0;
+    documentTypes: readonly ["definition"];
+    compatibility: "additive";
+    applicability: "detectable";
+    summary: "Workflow, stage, activity, and action nodes may carry signal or custom advisory semantics.";
+  }>,
+  Readonly<{
+    id: "field-patch-ops";
+    introducedInModel: 6;
+    minReaderModel: 0;
+    documentTypes: readonly ["definition", "instance"];
+    compatibility: "additive";
+    applicability: "detectable";
+    summary: "Field ops may increment, decrement, or initialize a missing field value.";
+  }>,
+  Readonly<{
+    id: "attributes-condition-var";
+    introducedInModel: 7;
+    minReaderModel: 0;
+    documentTypes: readonly ["definition"];
+    compatibility: "additive";
+    applicability: "unconditional";
+    summary: string;
+  }>,
 ];
 
 /**
@@ -2408,7 +2526,7 @@ export declare const DATA_MODEL_MIN_READER = 4;
  * job. Declare every bump in `DATAMODEL.md`; the model-surface snapshot test
  * keeps undeclared drift red.
  */
-export declare const DATA_MODEL_VERSION = 5;
+export declare const DATA_MODEL_VERSION = 7;
 
 export declare interface DataModelChange {
   readonly id: string;
@@ -2433,6 +2551,13 @@ export declare function datasetResourceParts(id: string): {
   dataset: string;
 };
 
+export declare const DECISION_SEMANTICS: readonly [
+  "decision.accept",
+  "decision.decline",
+];
+
+export declare type DecisionSemantic = (typeof DECISION_SEMANTICS)[number];
+
 /** The declarable half of {@link ExecutionContext} — what `createEngine` accepts. */
 export declare type DeclaredExecutionContext = Pick<
   ExecutionContext,
@@ -2967,6 +3092,18 @@ export declare function describeSiteHeading(
   ctx: DescribeContext,
 ): InsightPhrase;
 
+/**
+ * The activity slice the document-derivable stuck causes read: its runtime
+ * status, and the declared actions whose effects a failure is matched against.
+ * Narrowed to exactly this, so one set of cause functions serves both a full
+ * {@link WorkflowEvaluation} and {@link documentStuckCause}'s snapshot-derived
+ * rows.
+ */
+declare interface DiagnosedActivity {
+  status: ActivityStatus;
+  activity: Pick<Activity, "name" | "actions">;
+}
+
 /** The slice of a {@link TransitionEvaluation} the classifier reads — narrowed
  *  so a hand-crafted stuck permutation doesn't have to fabricate insights. */
 export declare type DiagnosedTransition = Pick<
@@ -2980,7 +3117,7 @@ export declare type DiagnosedTransition = Pick<
  * without standing up a full evaluation; {@link diagnoseInputFromEvaluation}
  * builds it from a real {@link WorkflowEvaluation}.
  */
-export declare interface DiagnoseInput {
+export declare interface DiagnoseInput extends DocumentStuckInput {
   instance: Pick<
     WorkflowInstance,
     | "currentStage"
@@ -3269,6 +3406,36 @@ export declare function documentPrefilter(
   params: Record<string, string | string[]>,
 ): string;
 
+/**
+ * Classify an instance from its document alone — no evaluation, no reads, no
+ * actor. The transition-level causes need GROQ `when` results, so only
+ * {@link diagnoseInstance} reaches those.
+ *
+ * Sound but incomplete, and a consumer must present it that way: `undefined`
+ * means "no cause this classifier can see", never "healthy". Flag an instance on
+ * a cause; never word an absence as an all-clear.
+ */
+export declare function documentStuckCause(args: {
+  instance: Pick<
+    WorkflowInstance,
+    "currentStage" | "effectHistory" | "pendingEffects" | "stages"
+  >;
+  /** The instance's parsed snapshot. Absent, the answer narrows — a failed
+   *  effect cannot be tied to the activity it stalls — and never widens. */
+  definition: WorkflowDefinition | undefined;
+}): StuckCause | undefined;
+
+/**
+ * What the document-derivable stuck causes read. Every field is persisted —
+ * on the instance itself or in the definition snapshot pinned to it — so a
+ * caller holding only a committed instance can classify these without an
+ * evaluation.
+ */
+declare interface DocumentStuckInput {
+  instance: Pick<WorkflowInstance, "effectHistory" | "pendingEffects">;
+  activities: readonly DiagnosedActivity[];
+}
+
 export declare type DocumentValuePermission =
   (typeof DOCUMENT_VALUE_PERMISSIONS)[number];
 
@@ -4093,6 +4260,12 @@ export declare interface EvaluateFromSnapshotArgs {
    * write boundary still enforces).
    */
   grants?: Grant[];
+  /**
+   * Resolved org-level user attributes for the actor. Omit to leave the
+   * rendered `$attributes` undefined (conditions referencing it fail
+   * closed).
+   */
+  attributes?: UserAttributes;
   /**
    * The in-memory snapshot to evaluate against. The caller assembles it
    * from whatever source — a fetch (see {@link evaluateInstance}) or a
@@ -4515,6 +4688,10 @@ export declare interface FieldInsight {
 
 export declare type FieldKind = keyof FieldValueMap;
 
+/**
+ * A stored field mutation. `field.inc` and `field.dec` use the same names as
+ * `@sanity/client` patches and default an omitted `value` to a delta of `1`.
+ */
 export declare type FieldOp = v.InferOutput<typeof StoredFieldOpSchema>;
 
 /**
@@ -4629,6 +4806,12 @@ export declare class FieldValueShapeError extends WorkflowError<"field-value-sha
  */
 export declare const FILTER_SCOPE_VARS: readonly string[];
 
+export declare function findActivityNode(args: {
+  activityName: string;
+  definition: WorkflowDefinition | undefined;
+  stageName: string;
+}): Activity | undefined;
+
 /**
  * The current stage's {@link ActivityEntry} named `activityName`, or
  * `undefined` when the open stage holds no such activity (including when
@@ -4669,6 +4852,11 @@ export declare interface FindPendingEffectsArgs extends InstanceRefArgs {
   names?: string[];
 }
 
+export declare function findStageNode(args: {
+  definition: WorkflowDefinition | undefined;
+  stageName: string;
+}): Stage | undefined;
+
 export declare interface FireActionArgs extends DedupableOperationArgs {
   activity: string;
   action: string;
@@ -5975,6 +6163,17 @@ export declare function isNotesEntry(
 /** Whether a project-user API failure explicitly means the user is absent. */
 export declare function isProjectUserNotFoundError(error: unknown): boolean;
 
+/**
+ * True when a write looks like a lost optimistic lock — every `statusCode: 409`
+ * from the real client, or the bench's `ifRevisionId check failed` message.
+ * A bare 409 is not exclusively a lost fence: a `create` against an existing id
+ * (`documentAlreadyExistsError`) carries the same status. Narrow the error to
+ * one rev-guarded write before asking — anything wider (a whole cascade, or a
+ * commit together with its guard deploy) reads a create collision as a lost
+ * race.
+ */
+export declare function isRevisionConflict(error: unknown): boolean;
+
 /** Entry-level {@link isSingleDocRefKind}: narrows a resolved entry to the
  *  single-GDR arms (`doc.ref` / `subject`) — the value is one GDR (or null)
  *  and the entry may carry the accepted-target `types`. */
@@ -6471,6 +6670,10 @@ export declare const OP_DISPLAY: {
     title: string;
     description: string;
   };
+  "field.setIfMissing": {
+    title: string;
+    description: string;
+  };
   "field.unset": {
     title: string;
     description: string;
@@ -6479,6 +6682,14 @@ export declare const OP_DISPLAY: {
     title: string;
     description: string;
   };
+  "field.inc": {
+    title: string;
+    description: string;
+  };
+  "field.dec": {
+    title: string;
+    description: string;
+  };
   "field.updateWhere": {
     title: string;
     description: string;
@@ -6586,11 +6797,6 @@ export declare interface ParsedGdr {
   documentId: string;
 }
 
-declare type ParsedWorkflowConfig = v.InferOutput<typeof WorkflowConfigSchema>;
-
-declare type ParsedWorkflowDeployment =
-  ParsedWorkflowConfig["deployments"][number];
-
 /**
  * Parse a GDR URI into its scheme + addressing parts. Throws on
  * unknown scheme or malformed shape.
@@ -6864,7 +7070,7 @@ export declare class ReaderModelAcknowledgementError extends WorkflowError<"read
   readonly code = "WORKFLOW_READER_MODEL_ACKNOWLEDGEMENT_MISMATCH";
   readonly expectedMinReaderModel: unknown;
   readonly engineMinReaderModel = 4;
-  readonly engineModelVersion = 5;
+  readonly engineModelVersion = 7;
   readonly documentationUrl =
     "https://www.sanity.io/docs/editorial-workflows/prerelease";
   constructor(expectedMinReaderModel: unknown, context?: string);
@@ -7134,10 +7340,11 @@ export declare type ResetActivityTarget =
   (typeof RESET_ACTIVITY_TARGETS)[number];
 
 /**
- * Resolve the engine's `WorkflowAccess` for a client — both halves
- * fetched from its token in parallel and cached. Throws if the client
- * can't yield an actor — the engine refuses to operate without an
- * identity.
+ * Resolve the engine's `WorkflowAccess` for a client — actor and grants
+ * (when a path is supplied) fetched from its token in parallel and cached.
+ * Throws if the client can't yield an actor — the engine refuses to operate
+ * without an identity. Does **not** fetch User Attributes; see
+ * {@link resolveUserAttributes}.
  */
 export declare function resolveAccess(
   taggedClient: WorkflowClient,
@@ -7228,6 +7435,17 @@ export declare function resolveFieldEntry(
   },
 ): ResolvedFieldEntry | undefined;
 
+/**
+ * Resolve advisory `$attributes` for the caller-bound projection — project →
+ * org → global-host attributes page. Cached per (client, orgId). Expected
+ * absences (401–404) leave the bag unbound; unexpected failures throw.
+ * Call only from soft-gate paths (evaluate / fireAction filter re-check /
+ * editField), never from ticks or drainers.
+ */
+export declare function resolveUserAttributes(
+  taggedClient: WorkflowClient,
+): Promise<UserAttributes | undefined>;
+
 /**
  * A map binding each resource-alias name to the physical {@link WorkflowResource}
  * it resolves to at deploy. Parallels the role-alias map: where role aliases map
@@ -7415,6 +7633,8 @@ export declare interface ScopedInitialFieldDeclarations {
   }[];
 }
 
+export declare type Semantic = SignalSemantic | CustomSemantic;
+
 export { sentenceCase };
 
 export declare interface SessionArgs {
@@ -7436,6 +7656,14 @@ export declare interface SetStageArgs extends DedupableOperationArgs {
   initialFields?: InitialFieldValue[];
 }
 
+export declare const SIGNAL_SEMANTICS: readonly [
+  "signal.positive",
+  "signal.caution",
+  "signal.critical",
+];
+
+export declare type SignalSemantic = (typeof SIGNAL_SEMANTICS)[number];
+
 /**
  * No-op logger. Default for library callers that don't want any
  * output unless explicitly opted in.
@@ -7534,6 +7762,8 @@ export declare interface StageEntry {
 
 export declare interface StageEvaluation {
   stage: Stage;
+  /** The stage's advisory workflow meaning, unchanged from its definition. */
+  semantics?: Semantic[] | undefined;
   activities: ActivityEvaluation[];
   transitions: TransitionEvaluation[];
   /** The stage's causal-autonomy rollup — will it progress without a caller,
@@ -7544,6 +7774,7 @@ export declare interface StageEvaluation {
 /** 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;
@@ -7602,10 +7833,12 @@ export declare class StaleEffectClaimError extends WorkflowError<"stale-effect-c
  * not the rendered condition scope (no {@link ConditionVarBinding}: these
  * bind only while the filter is evaluated on the READ side — the
  * `definitionsForDocument` derivation and the Studio start control).
- * `startInstance` never evaluates the filter. BROWSE-TIME-PURE: `$fields` is
- * deliberately absent — a `$fields` read is deploy-rejected with a pointer
- * to start GROQ requirements.
- * Bound in one place: `startContextParams` in the applicability evaluator.
+ * `startInstance` never evaluates the filter. BROWSE-TIME-PURE: `$fields` and
+ * every caller-bound var (`$actor` / `$assigned` / `$can` / `$attributes` /
+ * `$params`) are deliberately absent — a read is deploy-rejected (`$fields`
+ * with a pointer to start GROQ requirements; caller vars as silent
+ * never-match). Bound in one place: `startContextParams` in the applicability
+ * evaluator.
  */
 export declare const START_FILTER_VARS: readonly {
   name: string;
@@ -7925,9 +8158,9 @@ export declare interface StartSliceRow {
  * (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<
   [
@@ -7976,6 +8209,28 @@ declare const StoredFieldOpSchema: 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>;
@@ -8019,6 +8274,56 @@ declare const StoredFieldOpSchema: 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>;
@@ -8162,6 +8467,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>;
@@ -8205,6 +8532,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>;
@@ -8813,6 +9190,13 @@ export declare function unsatisfiedTransitionSummaries(
   summary: string;
 }[];
 
+/**
+ * Normalize Management API user-attribute payloads into the `$attributes`
+ * bag. Fetch/caching stays in access resolution; this module is I/O-free.
+ */
+/** Flat key → active-value record bound as advisory `$attributes` when present. */
+export declare type UserAttributes = Record<string, unknown>;
+
 /** The identity provider under whichever spelling the answering endpoint used
  *  — the ONE place that disagreement is resolved. */
 export declare function userLoginProvider(
@@ -9367,7 +9751,8 @@ declare const WORKFLOW_LIFECYCLES: readonly ["standalone", "child"];
  * can read; there is no engine-side permission verdict. When grants are
  * absent the rendered `$can` is undefined — conditions referencing it
  * fail closed, everything else is ungated engine-side — and the real
- * Sanity write boundary takes over.
+ * Sanity write boundary takes over. See {@link WorkflowAccess.attributes}
+ * for the parallel `$attributes` bag.
  */
 export declare interface WorkflowAccess {
   actor: Actor;
@@ -9382,6 +9767,12 @@ export declare interface WorkflowAccess {
    */
   localPrincipalId?: string;
   grants?: Grant[];
+  /**
+   * Optional bag for callers that compose a {@link WorkflowAccess} by hand
+   * (the test bench). {@link resolveAccess} never populates this — soft-gate
+   * paths load attributes via {@link resolveUserAttributes}.
+   */
+  attributes?: UserAttributes;
 }
 
 export declare const WorkflowActionFired: WorkflowTelemetryEvent<WorkflowActionFiredData>;
@@ -9582,11 +9973,18 @@ export declare interface WorkflowCommitOptions {
   tag?: string;
 }
 
-export declare type WorkflowConfig = Omit<
-  ParsedWorkflowConfig,
+export 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}.
+ */
+export declare type WorkflowConfigInput = Omit<
+  WorkflowConfig,
   "deployments"
 > & {
-  deployments: WorkflowDeployment[];
+  deployments: WorkflowDeploymentInput[];
 };
 
 declare const WorkflowConfigSchema: v.ObjectSchema<
@@ -9852,6 +10250,7 @@ declare const WorkflowConfigSchema: v.ObjectSchema<
                     v.CustomSchema<
                       {
                         name: string;
+                        semantics?: Semantic[] | undefined;
                         title: string;
                         description?: string | undefined;
                         groups?: Group[] | undefined;
@@ -9870,6 +10269,7 @@ declare const WorkflowConfigSchema: v.ObjectSchema<
                   v.MinLengthAction<
                     {
                       name: string;
+                      semantics?: Semantic[] | undefined;
                       title: string;
                       description?: string | undefined;
                       groups?: Group[] | undefined;
@@ -9937,6 +10337,7 @@ declare const WorkflowConfigSchema: v.ObjectSchema<
               | undefined;
             definitions: {
               name: string;
+              semantics?: Semantic[] | undefined;
               title: string;
               description?: string | undefined;
               groups?: Group[] | undefined;
@@ -9998,6 +10399,7 @@ declare const WorkflowConfigSchema: v.ObjectSchema<
               | undefined;
             definitions: {
               name: string;
+              semantics?: Semantic[] | undefined;
               title: string;
               description?: string | undefined;
               groups?: Group[] | undefined;
@@ -10057,6 +10459,7 @@ declare const WorkflowConfigSchema: v.ObjectSchema<
                   | undefined;
                 definitions: {
                   name: string;
+                  semantics?: Semantic[] | undefined;
                   title: string;
                   description?: string | undefined;
                   groups?: Group[] | undefined;
@@ -10118,6 +10521,7 @@ declare const WorkflowConfigSchema: v.ObjectSchema<
               | undefined;
             definitions: {
               name: string;
+              semantics?: Semantic[] | undefined;
               title: string;
               description?: string | undefined;
               groups?: Group[] | undefined;
@@ -10177,6 +10581,7 @@ declare const WorkflowConfigSchema: v.ObjectSchema<
                   | undefined;
                 definitions: {
                   name: string;
+                  semantics?: Semantic[] | undefined;
                   title: string;
                   description?: string | undefined;
                   groups?: Group[] | undefined;
@@ -10297,15 +10702,25 @@ declare const WorkflowDefinitionSchema: v.GenericSchema<
   WorkflowFields<FieldEntry, Stage, StartBlock>
 >;
 
-export 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}. */
+export 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).
+ */
+export 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;
 };
 
 export declare const WorkflowEffectCompleted: WorkflowTelemetryEvent<WorkflowEffectCompletedData>;
@@ -10400,6 +10815,8 @@ export declare type WorkflowErrorKind =
 export declare interface WorkflowEvaluation {
   instance: WorkflowInstance;
   definition: WorkflowDefinition;
+  /** The workflow's advisory meaning, unchanged from its definition. */
+  semantics?: Semantic[] | undefined;
   actor: Actor;
   currentStage: StageEvaluation;
   /** Active activities whose assignees-kind field entry matches the actor. */
@@ -10464,6 +10881,7 @@ declare type WorkflowFields<TField, TStage, TStart> = {
    * subworkflows resolve by it.
    */
   name: string;
+  semantics?: Semantic[] | undefined;
   title: string;
   description?: string | undefined;
   groups?: Group[] | undefined;