@sanity/workflow-engine 0.27.0 → 0.29.0

package/CHANGELOG.md

@@ -1,5 +1,202 @@
 # @sanity/workflow-engine
 
+## 0.29.0
+
+### Minor Changes
+
+- f44fc33: Workflow conditions can now read the caller's org-level User Attributes (Enterprise) through the advisory `$attributes` variable — for example `$attributes.department == "politics"` on a fireAction action filter, activity requirement, or editable predicate. Values match what lake role filters read via `user::attributes()`, keyed by attribute name with each active scalar or array value. Soft-gate paths (`evaluate`, fireAction filter re-check, editField) fetch the bag; ticks and drainers do not. Expected absences (401/402/403/404 — non-Enterprise, missing feature, forbidden) leave `$attributes` unbound so conditions that read it fail closed; unexpected fetch failures (5xx, network) throw on those soft-gate paths only and are not cached so the next call retries. An empty successful page binds `{}`. When the Management API envelope reports `hasMore: true`, the engine still binds the partial bag and warns (`nextCursor` makes follow-up pagination a small engine change). Engine checks remain advisory; the Content Lake is still the only enforcement point. `$attributes` is never persisted on `Actor` / history. The MCP authoring guide names the new variable alongside the other caller-bound vars. The test bench accepts an `attributes` bag (construction shortcuts and per-call overrides) the same way it accepts `grants`.
+
+  **No upgrade action required.** Existing definitions are unchanged. Authors who want attribute-gated actions opt in by writing `$attributes` in caller-bound condition sites; cascade gates continue to reject caller-bound vars at deploy.
+
+  **Docs impact:** Update the condition-variables reference (`docs/reference.md` § context-bound variables) and any guide that lists `$actor` / `$can` / `$assigned` so `$attributes` and the Enterprise / fail-closed semantics are named; note the spelling difference vs lake `user::attributes()`.
+
+- 26f25e0: Definition authors and effect runtimes can now use `field.inc`, `field.dec`, and
+  `field.setIfMissing` operations. Arithmetic operations accept an optional
+  numeric value expression that defaults to `1`, validate number-field targets,
+  reject non-finite results, and participate in the same atomic engine commits as
+  existing field operations. A retry is deduplicated only when the caller supplies
+  an idempotency key; the arithmetic operation itself is not idempotent.
+  `field.setIfMissing` targets nullable fields; list fields are always arrays and
+  are rejected. When the target already has a value, `field.setIfMissing` does
+  nothing and writes no `opApplied` history row. Like Sanity Content Lake patches,
+  `field.inc` and `field.dec` require the target to already hold a number: a
+  declared number without an initial value is `null`, so arithmetic rejects without
+  committing. Initialize counters with `field.setIfMissing` set to `0` before
+  incrementing when the value may be absent.
+
+  Persisted-model version 6 adds the three operation discriminators. The change is
+  additive and the reader floor remains 4, so existing definitions and instances
+  require no migration. Before deploying a definition that uses these operations,
+  upgrade every Studio, CLI, MCP server, Function, and other runtime that can
+  process workflow data in the shared environment. The unchanged reader floor
+  does not fence out an older engine, which rejects or aborts when it encounters a
+  new operation rather than executing it with different semantics.
+
+  **Docs impact:** Update the Operations guide and operation reference with all
+  three forms, their defaults and validation, effect-completion availability, the
+  Sanity-compatible `field.setIfMissing(0)` then `field.inc` initialization
+  pattern, the warning that arithmetic never assumes a missing value is zero, and
+  the bounded-retry counting pattern that loops below a fixed total-attempt limit
+  and routes exhausted work to manual recovery. Note that no-op
+  `field.setIfMissing` attempts write no `opApplied` history row, and include the
+  readers-first rollout guidance for model 6 operations.
+
+- 25bd1fb: Each card in the Studio plugin's Workflows tab now carries what the definition
+  is doing, not just its name: how many of its documents have work in flight, when
+  one of them last changed stage, how many hold a task past its due date, and one
+  alert glyph when something is wrong. The card reports live state only — what a
+  workflow runs on and what it says about itself change on a deploy, and that
+  workflow's own Definition page already names both. The
+  grid bands into "Assigned to you" and "Other workflows", so whether the reader
+  has work in a workflow is carried by where its card sits; rows keep the
+  catalog's alphabetical order inside each band. A card wears one alert, and it
+  means a run of that workflow cannot continue without help. The engine's
+  `blocked` readiness hold earns none, because it is an expected transient state
+  and flagging it would mark most cards most of the time; a rejected
+  document-type binding earns none either, because it belongs to the definition
+  rather than to any of its runs and is reported on that workflow's Definition
+  page.
+
+  The age on a card is a STAGE ARRIVAL, not a last-modified stamp. Every engine
+  commit moves an instance's change stamp — an assignment, a date, a drained
+  effect — and a workflow can absorb a great deal of that without advancing, so
+  the arrival is the event a catalog can read as progress. The consequence is
+  deliberate: a busy workflow held inside one stage reads as old, which is the
+  pathology worth seeing. Hovering that age names the move — which document went
+  to which stage, and the exact time — resolving the document's title through the
+  preview store only once the tooltip opens.
+
+  Overdue is the only signal drawn in a tone — caution, where the alert glyph
+  takes critical — and the only one that disappears when it reads zero: it reports
+  that something is wrong rather than how things stand, so a card with nothing
+  late spends no room saying so. A
+  document counts as overdue while an unsettled task on it is past its due date;
+  a finished task's date, however old, is not a debt. Overdue is measured on one
+  shared rule with the todo rows, so a card's count and a row's face can no
+  longer disagree about a single date.
+
+  The grid counts DOCUMENTS where it used to count instances, because its reader
+  is an editor and the document is what they open. Several instances on one
+  document count once. An instance whose chain references no document counts as
+  one unit of its own, so a workflow that runs on no document does not read as
+  idle. The workflow's own page still reports instances, in those words.
+
+  Hovering that count also says how many of those documents have yet to leave the
+  stage their workflow starts from — on a line of its own, so the two facts can be
+  scanned rather than read through, and folded into the first line when the answer
+  is all of them, where a second line would repeat one number. A document counts
+  there while any of its runs still waits at the start, judged against that run's
+  own pinned snapshot, so a run begun under an earlier version answers to where
+  that version started. The count stays in the hint rather than taking a slot on
+  the rule: it is a part of a number the card already shows, meaningless without
+  that total beside it, and no glyph in the set says "waiting at the start".
+
+  The page no longer opens on a project-wide total. The band headings count the
+  workflows, so a total above them stated the same figure twice, and a total of
+  documents invited a comparison against the cards that can never add up — one
+  document running two workflows is one document in a project total and one on
+  each of their cards.
+
+  The engine gains `documentStuckCause`, which classifies an instance as stuck
+  from its persisted document and pinned snapshot alone — no evaluation, no
+  reads, no actor. It answers for the effect- and activity-level causes
+  `diagnoseInstance` reports (`failed-effect`, `failed-activity`,
+  `hung-effect`) and returns `undefined` for the transition-level ones, which
+  need GROQ results. It is sound but incomplete by construction: a cause it
+  reports is real, and the absence of one means only that no cause was provable,
+  never that the instance is healthy. Surfaces flagging on it must not word an
+  unflagged state as an all-clear. `findActivityNode` and `findStageNode`, the
+  tolerant definition tree lookups it uses, are exported alongside it.
+
+  The tool's instance read is held per engine for the session and replayed on the
+  next mount, which changes what the Workflows tab paints while it loads. A first
+  visit now waits for that read before the definitions grid appears, where it used
+  to lay out cards from the catalog and rearrange them once the instances landed —
+  the grid's bands and counts come from the instances, so the cards had no stable
+  shape until both reads were in. The grid waits on the reader's identity for the
+  same reason: which band a card sits in depends on who is looking, and a
+  project-scoped account resolves through the project member directory, so banding
+  before that answer arrived would have moved every card once it did. An account
+  the directory cannot place, or a directory that fails to load, is an answer
+  rather than a wait — the grid paints unbanded and every card reports no assigned
+  work. A later visit inside the same session paints the
+  held read at once and refreshes behind it.
+
+  The form strip's assigned-task count tells those two apart as well, so an account
+  the member directory cannot place no longer leaves a spinner turning in that slot
+  for the rest of the session. It shows no count, which is what it already did for
+  an account with nothing assigned. The hold is not local to the grid: the
+  task rows under "All documents" and "For me", and the active-instance count on a
+  workflow's Definition page, read the same stream, so they too open on held
+  numbers before the fresh read lands. A failed read is never held, and a provider remount mints a new engine and
+  so starts cold.
+
+  **No upgrade action required.** The card additions are automatic, and
+  `documentStuckCause` is a new export that changes no existing verdict —
+  `diagnoseInstance` classifies exactly as before, now sharing one
+  implementation of the document-derivable causes.
+
+  **Docs impact:** Update the Workflows tool guide where it describes the
+  definitions grid, to cover the new card signals, the assigned-work ordering, the
+  document-versus-instance split between the grid and a workflow's own page, and
+  that the tab opens on a held read after the first visit.
+  `docs/reference.md` already carries `documentStuckCause` beside
+  `diagnoseInstance` with its bound stated; the hosted engine reference needs the
+  same entry, so integrators do not read a missing cause as a health check.
+
+- 3fd04f1: **BREAKING:** `ActionSemantic` was a closed union of action decision values; it now also includes signal values and the open `custom.${string}` form. TypeScript consumers that exhaustively map `ActionSemantic` must handle signal and custom values or narrow to the decision subset before upgrading, otherwise their build will fail. Workflow authors can attach advisory signals and validated custom semantics to workflow roots, stages, activities, and actions, and evaluation results expose them at each matching level.
+
+  Existing stored definitions and runtime behavior remain compatible. The Studio plugin continues to render decision faces when decision values are composed with signal or custom semantics, while non-decision values receive the default action face.
+
+  **Docs impact:** Update the definition and evaluation references plus the concepts guide to document level-wide advisory semantics, the signal vocabulary, custom grammar, and action-only decision values.
+
+## 0.28.0
+
+### Minor Changes
+
+- 5050b06: **BREAKING:** Authoring a deployment now types through `WorkflowDeploymentInput` / `WorkflowConfigInput`, which require `expectedMinReaderModel` as the current reader-floor literal. Passing a parsed `WorkflowDeployment` / `WorkflowConfig` (where the floor is optional/unverified) into `defineWorkflowConfig` or `defineWorkflows` is a type error — share the authored deployment object instead of `config.deployments[n]`. The same pin shows up on the blueprint resource: `EditorialWorkflowsResource.deployment` and `parseWorkflowDeployment`'s return type are now `AcknowledgedDeployment` (floor asserted to the current literal), so a hand-constructed provider resource must carry that literal too.
+
+  At runtime, config parse no longer rejects a stale or missing floor on an untargeted deployment. Only deployment-scoped commands assert, and only the selected deployment: definition deploy, `--check` / `--dry-run`, blueprint provision, `start`, `definition delete`, and `definition diff` (the last is a deployment-scoped read). Instance-id commands (`fire-action`, `abort`, `set-stage`, `reset-activity`) deliberately do not assert — they resolve by instance id, not by a declared deployment's acknowledgement — so an unacknowledged floor does not stop those instance commits.
+
+  Upgrade TypeScript configs and blueprint manifests that fed a parsed deployment into those helpers: keep a shared authored object (`satisfies WorkflowDeploymentInput`) for both `defineWorkflowConfig` and `defineWorkflows`, and give any hand-built `EditorialWorkflowsResource` the current floor literal on `deployment`. Existing configs that already acknowledge the current floor keep working at runtime; a stale selected deployment still fails with `ReaderModelAcknowledgementError` (headline + short steps; the CLI renders it through the clean styled-error path).
+
+  **Docs impact:** Update the CLI / blueprint authoring examples and the prerelease reader-floor guidance so they name `WorkflowConfigInput` / `WorkflowDeploymentInput` / `AcknowledgedDeployment`, forbid passing `config.deployments[n]` into `defineWorkflows`, state that instance-id writes are outside the acknowledgement gate, and stop implying whole-config parse-time rejection for commands that never select a deployment.
+
+- a044ba5: Report a Studio start whose auto-advance lost a write race as the finished run
+  it is. Starting a workflow from the Studio while another runtime (a deployed
+  Function, a script) drives the same instance could hand the editor a warning
+  toast — "'…' started but didn't finish", with a raw `unexpected revision ID`
+  mutation error under it — for a run that had in fact completed: the Studio's own
+  auto-advance simply lost the write race to whoever committed the equivalent move
+  first. That toast was indistinguishable from a genuinely stuck workflow. The
+  Studio now confirms the completed start instead of warning about it.
+
+  Narrow by design: only a lost revision race whose run is already complete is
+  reclassified. A conflict that left the run in flight, and any other reason an
+  auto-advance failed, still surface as before.
+
+  `@sanity/workflow-engine` exports `isRevisionConflict`, the predicate that tells
+  a lost optimistic-locking race from a real error, so integrations can classify
+  one without matching on message text. It answers on the error alone, so narrow
+  to a single rev-guarded write before asking — a bare 409 also covers a create-id
+  collision.
+
+  **No upgrade action required.** Engine behaviour is unchanged and the new export
+  is additive.
+
+  **Docs impact:** `isRevisionConflict` is new public engine surface, added to the
+  errors section of `docs/reference.md` alongside the concurrency errors it
+  classifies; mirror that entry wherever published reference material lists the
+  engine's error helpers.
+
+### Patch Changes
+
+- 1e4a5da: When two runtimes both try to create the same stage guard after each observing it absent — for example a deployed Function reacting to instance commits while a script advances the same workflow — the losing create no longer aborts guard deploy. It falls through to the body-reconciling patch the existing-document path already uses, and writes its own resolution of the guard's conditions rather than assuming the two are identical. Concurrent deploys of an already-present guard were already a patch and are unchanged.
+
+  **No upgrade action required.**
+
+  **Docs impact: None** — `docs/reference.md` already documents `deployStageGuards` as an idempotent upsert.
+
 ## 0.27.0
 
 ### Minor Changes

package/DATAMODEL.md

@@ -702,6 +702,113 @@ its base `date` / `datetime`, so no older code path can write it while skipping
 validation — there is no silent bypass to fence, and the kinds leave the floor
 at 0.
 
+### Model 6 — node semantics and field patch operations (reader floor: 4)
+
+#### Semantics at every definition level
+
+The optional non-empty `semantics[]` field now appears on the workflow root,
+stages, and activities as well as actions. Its engine-owned vocabulary adds
+`signal.positive`, `signal.caution`, and `signal.critical` at every level;
+`custom.<meaning>` is an open, grammar-validated namespace at every level.
+Actions retain their action-only `decision.accept` and `decision.decline`
+values. The values remain advisory and change no execution, gating, transition,
+status, history, or instance state. An absent field retains the generic behavior
+of older definitions.
+
+Manifest feature: `node-semantics` (definition, additive, detectable, floor 0).
+
+Would an old reader misread (rule 5)? No. Definition content has no strict
+read-side parse, and an older engine ignores the optional fields and new
+advisory values. Definition documents are immutable after creation, so an older
+writer never rewrites and drops them. The feature itself remains readable by
+model-0 engines; new writers still stamp the unconditional writer minimum of 4.
+This uses the existing `semantics` slot and extends that same word and shape to
+the remaining definition nodes; a sibling property would duplicate the
+advisory-meaning mechanism and violate the definition language's
+self-similarity rules.
+
+#### Field patch operations
+
+The stored definition grammar additively admits `field.inc`, `field.dec`, and
+`field.setIfMissing` action ops. Instances may embed the same definition tree
+in `definitionSnapshot`, and effect-completion use records the new discriminator
+in `history[]` rows' `opType`. Missing discriminators retain the historical op
+vocabulary, so documents written before model 6 need no normalization. A
+`field.setIfMissing` whose target already has a value writes no `opApplied` row:
+persisting a targeted no-op would make older provenance and feed readers report
+a field write that never happened.
+
+Manifest feature: `field-patch-ops` (definition + instance,
+additive, detectable, floor 0).
+
+Would an old reader misread these ops (rule 5)? No. An older engine strictly
+parsing or deploying a definition document rejects the unknown discriminator.
+The instance runtime is different: `definitionSnapshot` is decoded without a
+definition-schema parse, so an older engine can reach `applyOp`; its exhaustive
+switch has no matching arm and the commit aborts when the missing summary is
+used to build the audit row. That is a loud runtime failure rather than silent
+execution with different semantics. Definition documents are create-only,
+instance persists preserve the opaque `definitionSnapshot` string, and history
+readers already treat `opType` as an opaque audit label, so the discriminator
+survives an old writer's round trip. Rule 5 fences silent misinterpretation,
+not loud refusal, therefore this detectable feature contributes floor 0 and the
+writer maximum remains 4. The floor does not protect these definitions from
+older runtimes: upgrade every runtime that can process shared workflow data
+before adopting the new ops.
+
+Why could the existing definition vocabulary not carry the behavior (definition
+language rule 8)? Incrementing requires a read-modify-write primitive, while
+`ValueExpr` deliberately describes context-free reads and has no arithmetic.
+The existing `field.set` cannot atomically derive its value from the current
+number. Conditional initialization also has no existing field-op equivalent:
+an action-level `when` gates every op and effect in the action, while
+`initialValue` runs only when an entry is first resolved and cannot initialize a
+value cleared later by `field.unset`. These additions are new values in the
+existing `ops[].type` slot and reuse the established field target and
+value-expression shapes. Their abbreviated names deliberately mirror
+`@sanity/client`'s patch vocabulary (`setIfMissing`, `inc`, `dec`) as one trio;
+definition authors who know Sanity patches can predict the workflow spellings.
+
+### Model 7 — the `$attributes` condition variable (reader floor: 4)
+
+One additive growth of the condition dialect ships as model 7. It does not
+raise the reader floor; the writer maximum stays 4.
+
+A new caller-bound synthetic variable `$attributes` binds the acting token's
+org-level User Attributes (Enterprise) as a flat key → active-value record —
+the same values lake role filters read via `user::attributes()`, spelled for
+the workflow condition dialect. Soft-gate paths resolve it when a
+caller-bound projection runs (`evaluate` / fireAction filter re-check /
+editField) — project → organization → global-host attributes page with
+`limit=100`, no further pages; warn when the envelope reports `hasMore` —
+parallel to grants on those paths, not on every `resolveAccess`. It is never
+persisted on `Actor` / history, and left unbound (`undefined`) when the fetch
+is an expected absence (401/402/403/404 — non-Enterprise org, missing feature,
+forbidden) so conditions that read it fail closed — the same posture as `$can`
+without grants. Unexpected fetch failures (5xx, network) throw and are not
+cached, so the next soft-gate call retries; ticks and drainers never call the
+endpoint. Legal sites match `$can` (fireAction action filters, activity
+requirements, editable predicates, and those commit re-checks); cascade gates
+and other caller-free sites deploy-reject it.
+
+Manifest feature: `attributes-condition-var` (definition condition dialect,
+additive, unconditional, floor 0).
+
+Would an old reader misread the var (rule 5)? No — an older engine never binds
+`$attributes`, so a GROQ read is null / fail-closed rather than a silent
+misinterpretation of persisted trees. Definitions that mention `$attributes`
+still deploy and evaluate on older engines; gates that depend on it simply
+never pass until the fleet reads model 7. No reader-floor raise.
+
+**Author-predicate shadowing (model ≤6 → 7):** `attributes` joins the reserved
+condition-var names, so a **new** predicate named `attributes` is
+deploy-rejected. A definition already stored under model ≤6 that declared
+`predicates.attributes` is a different story: on a model-7 engine that binds
+the caller bag, `$attributes` in that definition flips from “the author
+predicate” to “the synthetic User Attributes bag” with no redeploy. Likely
+zero real instances; no migration. Authors who hit it rename the predicate
+and redeploy.
+
 ## Pending governed changes
 
 - **`temp.system.guard` → `system.guard`** — the guard doc type's `temp.`