@sanity/workflow-engine 0.31.0 → 0.32.0

package/CHANGELOG.md

@@ -1,5 +1,135 @@
 # @sanity/workflow-engine
 
+## 0.32.0
+
+### Minor Changes
+
+- a8ed312: **BREAKING:** Assignment is now one ordered user-or-role member-list model: a direct user holder shadows every role in the same activity, role-only values route work to a pool, and singular `assignee` fields allow at most one user while retaining any number of roles. The `claim` field and action sugars have been removed from the authoring DSL; authors using them must replace each pair with an `assignee` field, a literal role seed where the work starts in a pool, ordinary field edits for take/release, a guarded `editable` predicate when second-taker exclusion is required, and `$assigned` on holder-only actions. Definitions that still submit `type: 'claim'` now fail validation.
+
+  Upgrade every engine, Studio, CLI, MCP, and adapter runtime sharing a workflow resource before deploying a definition containing a singular `assignee`, then acknowledge reader model 9 on deployment. Existing model-8-and-earlier instances remain readable and keep their object/null singular representation; no stored-document backfill is required. Deploy now rejects project-role references absent from the target project's live role catalog and warns when a referenced role has no current human holder, so the deploying identity must be able to read the project role and member directories.
+
+  Studio assignment matching and holder explanations now follow direct-user shadowing. The CLI adds viewer-scoped assignment list flags and counts, MCP instance listing adds corresponding assignment inputs and counts, and the public waiting `Diagnosis` adds a required `waitingFor` discriminant that distinguishes caller-actionable, manual-but-unavailable, and automation waits without implying that unassigned work is freely actionable.
+
+  `@sanity/workflow-components` now exports `roleMemberCount`, which reports the distinct people who can fulfill any supplied project role using the workflow definition's aliases. Pass the current member directory, required role names, and normalized `roleAliases`; literal members and alias-only fulfillers are deduplicated by account-global user id. No upgrade action is required unless a custom assignment surface wants alias-aware pool sizes.
+
+  **Docs impact:** Update the assignment model and authoring references, the reader-model rollout guide, guarded role-pool and take/release examples, the `@sanity/workflow-components` member-selection reference for `roleMemberCount`, Studio task-holder explanations, CLI instance-list flags, MCP list tool reference, deploy role-validation requirements, and migration guidance from removed claim sugar.
+
+- 2de38fd: **BREAKING:** `createEngine` takes its effect settings as one `effects` group. The top-level `effectHandlers`, `effectLeaseMs`, and `missingHandler` options are removed, with no alias and no deprecation shim, so everyone who builds an engine — a Sanity Function drainer, a hosted runtime, a script, a test — must move them into `effects: {handlers, leaseMs, missingHandler}`. An unmigrated TypeScript call stops compiling. An unmigrated plain-JavaScript call still builds an engine, but one with no handlers and the default `fail` policy, so its first drain throws `MissingHandlerError` instead of dispatching.
+
+  Migrate every construction site: `createEngine({client, workflowResource, tag, effectHandlers: H, effectLeaseMs: L, missingHandler: P})` becomes `createEngine({client, workflowResource, tag, effects: {handlers: H, leaseMs: L, missingHandler: P}})`. The resolved values read back off the engine under the same word, so `engine.effectHandlers` and `engine.missingHandler` become `engine.effects.handlers` and `engine.effects.missingHandler`. Nothing about draining changes: the same `fail` default, the same five-minute default lease, and the same claim, dispatch, and deploy-verification semantics. `@sanity/workflow-engine-test`'s `createBenchEngine(bench, overrides)` forwards `CreateEngineArgs` unchanged, so bench engines move their handler and policy overrides into the same group.
+
+  `@sanity/workflow-studio`'s `useWorkflowEngine` follows the engine: its `effectHandlers` and `missingHandler` props are replaced by one `effects` prop taking the engine's exported `EngineEffectsArgs`, so a Studio-side drainer passes `effects: {handlers, missingHandler}`. Keep that object referentially stable, at module scope or through `useMemo` — the hook memoizes the engine on it, and a new object every render rebuilds the engine every render. The `@sanity/workflow-studio-plugin` `effectHandlers` config key is unchanged; the plugin translates it into the group where it builds the engine.
+
+  **Docs impact:** Update the `createEngine` options reference and the effects concepts page for the new group, the missing-handler and claim-lease reference entries that named the old keys, the `useWorkflowEngine` adapter reference, the Studio plugin README's drain-function example, and every cookbook or runtime example that constructs an engine with handlers; carry the migration into the release notes.
+
+- a2ce4a7: **BREAKING:** Mutation guards now have one public compilation path:
+  `compileGuards` replaces the singular `compileGuard` export and returns every
+  Lake document required for the authored guard. Callers using `compileGuard`
+  must switch to `compileGuards` and persist every returned document; retaining
+  the old call would either fail to compile after upgrade or omit required
+  ID-space siblings. Literal field-seed document IDs now also enforce the Lake's
+  128-character limit and reject double dots; replace an invalid seed with a
+  valid resource-local document ID before upgrading. `MutationContext.action` now admits only the
+  Lake's `create`, `update`, and `delete` operations, and
+  `documentActionDenials` takes their concrete `before` / `after` mutation image
+  instead of a prospective document plus authored lifecycle action. Callers of
+  that helper must construct the same mutation the Lake will evaluate; otherwise
+  their preview can disagree with enforcement. Pure `evaluateFromSnapshot`
+  callers that supply dereference-bearing guards must also pass a
+  `guardDereference` resolver for stored resource reads; the engine and reactive
+  session supply their token-bound client resolver automatically.
+
+  Mutation guards now deploy edit locks against draft IDs and publish or
+  unpublish gates against published IDs using the create, update, and delete
+  operations Content Lake evaluates. A guard combining both action classes
+  emits separate temporary guard documents, preventing either match from leaking
+  into the other ID space. Guard previews bind `document.before` and
+  `document.after`, follow stored resource-local references, continue to
+  understand temporary guards emitted with the older lifecycle-action vocabulary,
+  and reject invalid actions, ID patterns, or predicates before deployment.
+
+  Existing guard definitions keep their authored shape. Definitions whose guards
+  stay within one emitted ID space require no rollout change and retain their
+  existing reader floor. A guard that combines direct create/delete actions,
+  content updates, or publish/unpublish actions across ID spaces is a detectable
+  model-9 feature on both its definition and instances.
+
+  Before deploying such a definition, upgrade every Studio, CLI, MCP server,
+  Function, and other engine runtime sharing its workflow resource, then change
+  that deployment's reviewed `expectedMinReaderModel` literal to `9`. This
+  readers-first order is required because pre-model-9 engines only know the base
+  guard document ID: after a newer engine emits an ID-space sibling, an older
+  engine could otherwise advance or abort the instance, retract only the base,
+  and leave an advisory lock behind. The affected instance commits reader floor
+  9 before split guards deploy, so an old runtime fails explicitly instead of
+  stranding a sibling. Existing affected instances need no data migration; their
+  first model-9 commit raises the floor before it can create a split guard.
+
+  **Docs impact:** Update `docs/reference.md` and the public mutation-guard
+  reference to explain publish and unpublish action translation, predicate
+  document bindings and dereferencing,
+  deploy-time validation errors, and why mixed-ID-space guards emit separate
+  documents. Update the prerelease reader-model rollout guide with the conditional
+  model-9 adoption sequence, including every shared runtime, the
+  `expectedMinReaderModel: 9` change, the old-retractor failure mode, and the fact
+  that unaffected definitions retain their existing floor and require no data
+  migration. Keep the `@sanity/workflow-engine-test` README's draft-ID examples
+  and the root live-parity credential guidance aligned with those contracts.
+
+- 2ddd3d7: **BREAKING:** `WorkflowErrorKind` can now be `concurrent-cascade`, paired with
+  the new exported `ConcurrentCascadeError`, when an automatic cascade exhausts
+  its revision-conflict retry budget. Consumers with exhaustive switches or
+  `Record<WorkflowErrorKind, …>` mappings over the previous union must add the
+  new member before upgrading; otherwise their TypeScript build will fail.
+
+  Automatic cascade hops now recover from concurrent same-instance commits by
+  reloading and re-evaluating state before retrying. Bounded retries for actions,
+  field edits, and effect writes now also classify conflicts only at the parent
+  instance commit, so a later guard or child-settlement 409 surfaces immediately
+  instead of being mislabeled as instance contention. Update exhaustive error
+  handling as described above; workflow definitions and stored instances require
+  no migration.
+
+  **Docs impact:** Add `ConcurrentCascadeError` to the engine error reference and
+  describe automatic cascade conflict recovery.
+
+- 6035672: Every mutating verb's `OperationResult` and `evaluate`'s `WorkflowEvaluation` now carry `nextEvaluationAt`, an optional ISO 8601 instant: the earliest future moment at which the passage of time alone could change what an instance evaluates to. It is the nearest `$now` boundary across every clock-reading condition site in the instance's current stage — transitions, activity filters, requirements, action filters and triggers, and editable-field gates — computed from the instance's current field values and verified by re-evaluating each site at the candidate instant. A runtime that polls on a cron can wait exactly instead (`tick`, read `nextEvaluationAt`, sleep until it, `tick` again), and a live session can re-render on the same instant.
+
+  Read the absence of the field precisely: it is absent for two reasons and no others. Either no clock-reading site the engine can judge there has a boundary — the stage declares none, or none has one the instance's current values pin, since date arithmetic and dataset scans report nothing rather than a guess — or the instance is terminal and will never re-evaluate. A result with `changed: false` still carries it, which is exactly when a scheduler needs it: a tick that moved nothing because the deadline has not arrived yet still reports when it will. What the engine can judge differs between the two surfaces: it derives the operation-side copy caller-free, so an action filter, requirement, or editable predicate combining `$now` with `$actor`, `$assigned`, `$can`, or `$attributes` is unevaluable there and contributes nothing to a verb result. Such a site answers per actor and a verb result carries no actor, so `evaluate` — projected for one — is the surface that answers it; deploy already keeps caller-bound reads out of the cascade gates the engine acts on.
+
+  The instant is a pure function of the evaluated instance state, its definition, and the operation's clock reading. It is never persisted and never derived after a write: a cascading verb derives it from the settled in-memory state before that hop persists, a verb returning the instance unchanged derives it from the state it loaded, and a derivation failure fails the call rather than following a commit that already landed.
+
+  **No upgrade action required.** The field is optional and additive; existing callers, the reactive session, and the Studio and App SDK adapters compile and behave unchanged, and consumers that already return these result types expose the new field without any change of their own.
+
+  **Docs impact:** The repository reference (`docs/reference.md`) is updated in this change; the published documentation is not. Update the published engine reference where it lists the `OperationResult` and `WorkflowEvaluation` shapes and where the verb entries describe what `tick`, `fireAction`, and `evaluate` return, so both shapes name `nextEvaluationAt` and carry the absence rule above, and correct the `createEngine.clock` entry, which says one reading per operation where the engine takes one per pass. Update the published concepts page where it explains that the engine never runs a clock and that a caller must `tick` when a deadline passes, so the scheduling story says how a runtime learns when that is.
+
+- 26dd4e5: Generated API references now include every type used by a public signature and link cross-package symbols to their authoritative package entry. Caller-facing helper contracts such as field mutation operations, engine operation context types, test-bench argument types, member avatar data, MCP client policy, and Studio user clients are now available as named exports where their public APIs already expose those shapes. GROQ condition consumers can import the documented `COMPARISON_OPS` list alongside its `ComparisonOp` type, while the shared cross-package exhaustiveness helper is an unsupported `@internal` export and is omitted from the reference.
+
+  **No upgrade action required.** Existing imports and runtime behavior remain compatible; consumers may adopt the new named type exports instead of reconstructing those shapes locally.
+
+  **Docs impact:** Refresh the generated API references for the affected packages; no conceptual guides, examples, or migration guidance need changes.
+
+- b04580d: **BREAKING:** The in-memory bench now exposes `GuardDeniedError` when Content Lake-style mutation guards reject client writes, replacing the engine-specific `MutationGuardDeniedError` previously thrown by the fake seam. Bench consumers that catch or assert the old class must import `GuardDeniedError` from `@sanity/workflow-engine-test` and match it instead; without this migration, denial assertions will fail even though the write remains rejected.
+
+  Publish and unpublish tests must also express guards in terms of the lake mutations they commit: publish updates or creates the published document and deletes its draft, while unpublish creates the draft and deletes the published document. Replace synthetic `publish` and `unpublish` guard-action expectations with the applicable `create`, `update`, and `delete` actions.
+
+  The engine's `DocumentValuePermission` and `Grant` types now include the lake's `manage` permission so access configurations can represent identities allowed to author system documents. `DOCUMENT_VALUE_PERMISSIONS` is now exported for consumers that need the complete runtime vocabulary.
+
+  The bench also re-exports `WriteAccessDeniedError`, giving access-control denial assertions the same stable package entry point as mutation-guard denial assertions. No upgrade action is required. Consumers may move existing imports of this class from `@sanity-labs/client-fake-for-test` to `@sanity/workflow-engine-test`.
+
+  **Docs impact:** Update the engine authorization API reference for the `manage` permission and `DOCUMENT_VALUE_PERMISSIONS`, plus the engine test-bench guard and access-denial guidance for the re-exported error classes and underlying publish/unpublish mutations.
+
+### Patch Changes
+
+- 2ba0c09: Generated API references keep navigation between public authoring, resource-alias, and observer helpers while no longer presenting private implementation helpers or private-package README targets as broken links.
+
+  **No upgrade action required.** Runtime behavior and public TypeScript contracts are unchanged.
+
+  **Docs impact:** Regenerate the API reference entries for these packages so their corrected TSDoc and README content is visible.
+
+- Updated dependencies [26dd4e5]
+  - @sanity/groq-condition-describe@0.5.0
+
 ## 0.31.0
 
 ### Patch Changes

package/DATAMODEL.md

@@ -6,7 +6,7 @@ The engine owns three standalone document types in the Content Lake:
 | ---------------------------- | -------------------------------------------- | --------------------------------------------------------------------------------------------- |
 | `sanity.workflow.definition` | `planDefinitionDeploy` (`src/api/deploy.ts`) | never — deploys are create-only                                                               |
 | `sanity.workflow.instance`   | `buildInstanceBase` (`src/instance.ts`)      | every persist writes the canonical state via `instanceStateFields` (`src/engine/mutation.ts`) |
-| `temp.system.guard`          | `compileGuard` (`src/core/guards.ts`)        | full-body refresh on stage re-entry; revision-conditional delete on retract                   |
+| `temp.system.guard`          | `compileGuards` (`src/core/guards.ts`)       | full-body refresh on stage re-entry; revision-conditional delete on retract                   |
 
 These field trees are **our contract with every past and future engine
 version reading the same dataset**. This file is where changes to them are
@@ -854,6 +854,84 @@ facet requires acknowledgement 8; a set without it may retain acknowledgement 4.
 instances whose canonical field tree carries a non-empty `roles` list stamp
 floor 8.
 
+### Model 9 — split guard ID spaces and singular assignment member lists (reader floor: 9)
+
+#### Split guard ID spaces
+
+A guard whose actions span more than one emitted ID space produces separate
+temporary guard documents: direct create/delete actions preserve authored IDs,
+content updates lock draft IDs, and publish/unpublish gates target published
+IDs. The split prevents one match from applying every action to every ID, but
+it also means retraction must reconstruct more than the historical base guard
+ID. The definition and instance field trees do not grow; model 9 records the
+new compatibility meaning of the existing guard action list, as required by
+rule 4.
+
+Manifest feature: `split-guard-id-spaces` (definition + instance,
+reader-floor, detectable, floor 9). The stable marker is a guard whose actions
+occupy at least two of the direct, edit, and lifecycle groups. Definitions and
+instances without such a guard retain the floor derived from their other
+features, normally model 4 or model 8.
+
+Would an old reader misread (rule 5)? Yes. A pre-model-9 engine can read the
+unchanged guard definition but only knows the base temporary-guard ID. If it
+advances or aborts an instance after a model-9 engine emitted the sibling
+document, it retracts the base and silently strands the sibling. That stale
+advisory guard can keep an action locked after its stage exited. The instance's
+embedded `definitionSnapshot` makes the feature detectable, so the commit that
+can first deploy split guards stamps floor 9 before deployment; an older engine
+then fails at the instance reader gate, and a concurrent old write loses its
+revision compare-and-swap before it can retract anything. Full persists retain
+the raise-only floor, so a newer engine cannot reopen the old-writer path.
+
+Roll out readers first: upgrade every Studio, CLI, MCP server, Function, and
+other engine runtime sharing the workflow resource, then raise the deployment's
+reviewed `expectedMinReaderModel` literal to 9 before deploying a definition
+with a split guard. Existing definitions and instances are safe to leave in
+place: until a model-9 engine commits an affected instance, no split sibling
+exists; that first commit establishes the floor before deploying one. The guard
+document remains the unstamped foreign Content Lake shape—the compatibility
+marker belongs to the engine-owned definition and instance trees.
+
+The model-9 vocabulary ledger also records `document` beside `guard` and
+`mutation` as a guard-predicate root. This pins the already-authored foreign
+predicate dialect to the evaluator: `document.before` and `document.after`
+must not disappear from a later reader while stored guard predicates still
+reference them.
+
+#### Singular assignment member lists
+
+The singular `assignee` value becomes the same ordered user-or-role member
+list as `assignees`, with one cardinality rule: it admits at most one user
+member while role members do not consume the limit. This lets a singular slot
+retain one or more routing roles while one person holds it. An empty value is
+`[]`; append and remove-where ops apply to the list.
+
+Like plural and composite assignment values, a singular replacement validates
+new members against the current project directory while retaining already
+stored members that have since left it. Taking or releasing routed work must
+not become impossible merely because another retained member is now stale.
+
+Readers permanently accept the model-8-and-earlier object/null representation
+and normalize it to a zero-or-one-element list in memory. Writers partition by
+the frozen definition snapshot's model stamp: instances pinned to definitions
+below model 9 re-encode singular values as object/null for their whole lives,
+while instances pinned to model-9 definitions write lists. A legacy instance
+therefore never mixes representations, and no stored document is backfilled.
+Redeploying is the opt-in migration for future instances; already-running
+instances finish under their pinned definition model.
+
+An older reader would interpret the list as an invalid singular value rather
+than the assignment it represents, so this is a reader-floor change. The
+definition tree gains no property: the existing `assignee` kind is the right
+slot and its persisted value evolves. Definitions that declare that kind and
+their instances require model 9. Definitions without it retain the highest
+floor required by their other features, including the unconditional model-4
+instance floor.
+
+Manifest feature: `singular-assignee-lists` (definition + instance,
+reader-floor, detectable, floor 9).
+
 ## Pending governed changes
 
 - **`temp.system.guard` → `system.guard`** — the guard doc type's `temp.`