@sanity/workflow-engine 0.31.0 → 0.33.0

package/CHANGELOG.md

@@ -1,5 +1,328 @@
 # @sanity/workflow-engine
 
+## 0.33.0
+
+### Minor Changes
+
+- 8874c50: **BREAKING:** A `subject`, `doc.ref`, or `doc.refs` field marked `required: true`
+  now requires its selected documents to remain readable after initialization.
+  Previously, the flag checked only that an initial value was supplied. Missing
+  required targets now produce a fault and prevent normal actions, triggered
+  actions, and transitions from advancing, even without an activity requirement
+  reading those targets. Abort and direct edits to editable fields remain
+  available. Optional references fault only when an unmet runtime condition needs
+  their content; completed workflows remain completed.
+
+  `StuckCause` adds `document-missing`. Update exhaustive handlers before upgrading,
+  or their typechecks fail and renderers have no matching branch. Evaluation
+  identifies the affected field and reference in `missingDocuments`, with its title
+  and completed availability evidence; `blockingMissingDocuments` selects the
+  references that prevent progress. The engine checks draft, published, and release
+  representations before distinguishing deletion from inaccessible content or
+  content outside the workflow perspective. Studio, CLI, and MCP use that same
+  result. Failed availability checks report unreadable content and log the cause;
+  optional references still permit unrelated actions. Incomplete reads do not
+  claim deletion, and an existing task fault keeps
+  its recovery controls. The fault clears when the required content becomes
+  readable; this release adds no undo-delete operation and does not automatically
+  abort workflows.
+
+  Upgrade every Workflows runtime sharing affected data, including Studio, CLI,
+  MCP servers, and deployed Functions, before relying on continued required-target
+  availability. Then set the deployment's reviewed `expectedMinReaderModel` to
+  `10` before deploying definitions with required content references. Writers stamp
+  model 10; this feature requires reader model 10, while documents without it keep
+  the floor required by their other features, normally 4, 8, or 9. Existing
+  instances remain readable without a backfill and adopt the rule under upgraded
+  engines. Their stored floor rises on the next full write, so an older runtime
+  can still advance an unstamped existing instance until the fleet is upgraded.
+  See `packages/workflow-engine/DATAMODEL.md` for the complete rollout contract.
+
+  The rendered CLI `show` command evaluates running instances. If evaluation fails,
+  it warns and displays stored state; terminal instances and `show --json` retain
+  their stored-state behavior.
+
+  **Docs impact:** Update field requiredness and initialization guidance, required
+  reference repair examples, the model-10 readers-first rollout, the diagnostics
+  reference for `StuckCause` and `MissingDocument`, CLI `show` and `diagnose`, MCP
+  workflow-state guidance, and the Workflows tool and document-view guides for
+  loading, deletion, permissions, and perspectives.
+
+- 0555271: An effect node can now declare a bounded retry policy the engine enforces on every runtime:
+  `retry: {kind: 'engine', attempts, backoff?: {kind: 'fixed' | 'exponential', delayMs}, expiryMs?}`.
+  The block's `kind` names who runs the policy and `engine` is the only accepted member; authoring may
+  omit it, as with `start.kind`, and `defineWorkflow` fills it in while desugaring, so a stored block
+  without it fails to parse at deploy. `attempts` is the total number of attempts
+  including the first, `backoff` is the wait between two attempts
+  (`delayMs` every time under `fixed`, doubled per attempt already made under `exponential`), and
+  `expiryMs` decides whether a further attempt may start: the engine stops rather than begin a wait
+  that would carry the run past it, so an attempt can go unused. It is not a handler timeout: an
+  attempt already running is never interrupted, so a run can finish after the window and a success
+  then still counts.
+
+  The whole policy runs inside one `drainEffects` call, under one claim whose lease is renewed across
+  each wait, and **every attempt invokes the handler again**. That is a third cause of the
+  at-least-once repetition handlers already tolerate, and no `effectHistory` row sits between two
+  attempts, so derive external-system identifiers from `ctx.effectKey` rather than checking history
+  to deduplicate. Two
+  things stop a run without settling it, both reported in the drain's `lost` bucket. A lease this
+  drainer can no longer renew leaves the entry pending, for a later drain to pick up once the lease
+  lapses. An entry another party completed or cancelled during a backoff is already settled by that
+  party, and the handler is not invoked again.
+  Otherwise the run settles in the single `effectCompleted` row the drain has always written: `failed`
+  with a `detail` naming the attempts used and the last error (`failed after 3 of 3 attempts: gateway
+timeout`), or `done` with a `detail` naming the attempt that succeeded when a later one did. A
+  policy changes no routing rule, since `$effectStatus['<name>'] == 'failed'` routes the instance
+  exactly as a single failure does. It does change which outcome those rules see, because an attempt
+  after the first that succeeds makes the status `done`. Adding a policy to an effect a `'failed'`
+  branch already watches is therefore a behaviour change, not only a latency change. Nothing
+  about an attempt is persisted, so no scheduler is involved and no per-attempt history rows appear.
+  An effect that declares no `retry` is unchanged: its handler's first failure settles it.
+
+  The waits are the engine's only deliberate pause, so `createEngine({sleep})` now takes a `Sleeper`
+  that decides how they are spent. Production omits it and spends real time; a deterministic harness
+  passes one that moves its `clock` forward instead, which is what the engine test bench does, so a
+  paced policy runs in a test without waiting.
+
+  **No upgrade action required** to keep existing definitions working; `sweepStaleClaims` and every
+  history shape are unchanged, and `drainEffects` keeps its signature and result shape. Two things to
+  weigh before adopting it. The
+  waits are real time inside the drain's invocation, so on a Functions host the policy has to fit
+  that function's timeout. Handing the policy to a Durable Functions host's own retry strategy
+  instead is future work in the generated runtime, not part of this contract; today every host waits
+  inside the invocation. And **declaring `retry` raises the definition's reader floor to model 10**:
+  `DATA_MODEL_VERSION` and `DATA_MODEL_MAX_READER` both move to 10, so upgrade every Studio, CLI, MCP
+  server, Function, and other runtime sharing that workflow resource, then raise the reviewed
+  `expectedMinReaderModel` literal to `10`, then deploy. A pre-model-10 reader would ignore the
+  policy and settle the effect on its first failure. Deploy refuses a `retry` definition against an
+  acknowledgement below 10, one whose backoff cannot fit its declared `attempts` inside `expiryMs`,
+  and one whose `expiryMs` or accumulated backoff exceeds **366 days**, since the whole policy runs
+  inside one `drainEffects` invocation and no host offers a single execution longer than a year.
+
+  **Docs impact:** Update the effects concept in the Workflows concepts guide to describe retry as an
+  in-invocation loop and name the per-host cost (the functions timeout, and durables delegation as future work), add `retry`
+  and its one-year span ceiling to the effect-node reference, note the loop in the `drainEffects` protocol entry along with what
+  the `lost` bucket now covers, list the `sleep` option in the `createEngine` reference, and add the retry
+  feature to the crossing-to-model-10 section of the reader-model rollout guide. A cookbook recipe for a bounded
+  external call should show the `retry` node instead of the counter-field retry loop.
+
+- b3b2797: Where the generated unattended runtime hosts a workflow or an effect is declared as one `runtime` block on three authoring nodes: the deployment in `sanity.workflow.ts`, the workflow in `defineWorkflow`, and the effect node. `kind` is `'function'` (a plain Sanity Function), `'durableFunction'` (a durable one), or `'selfHosted'` (a process you run yourself). Each level inherits from the one above, so a workflow that declares no block takes its deployment's kind and an effect takes its workflow's. Omit it everywhere and everything hosts on `'function'`. `kind` is the whole block at the deployment and workflow levels; an effect's `'function'` block also carries the function budget, `timeout` in seconds and `memory` in megabytes, and an effect that declares either gets its own drain function so an expensive handler's budget does not size every other handler's. An unknown kind fails at `defineWorkflow` or `defineWorkflowConfig`, before any deploy runs, naming the three accepted members; a budget on any other kind is rejected there too.
+
+  `@sanity/workflow-blueprint`'s emission plan groups by resolved kind. A `'function'` workflow gets the drain, the heartbeat, and the start watcher it always got. A `'durableFunction'` workflow or effect is listed under `planned.hosting` and emits nothing yet, while the rest of the deployment emits normally, with no error and no whole-deployment refusal. A `'selfHosted'` workflow or effect emits nothing, is skipped by the generated drains, is left out of the generated handler registry, and is reported under `planned.selfHosted`, which names the deadlines that process must tick, the effects it must drain, the parents it must re-evaluate when a child settles, and the autonomous definitions it must start. Two definitions in one deployment that host the same effect name differently fail generation, because one effect name has one handler and one budget. A start watcher is emitted for a durable workflow as well as a function-hosted one, because starting an instance does not depend on the host.
+
+  The block is authoring-only. `defineWorkflow` returns the stored definition plus the `runtime` the generator reads, and the deploy strips it: it never reaches the Content Lake, the stored definition schema rejects it, and two definitions that differ only in a hosting kind fingerprint identically, so changing a kind never mints a definition version. It does change the emitted tree, so regenerate afterwards and delete the function directories the new tree no longer contains.
+
+  **No upgrade action required.** Nothing this release replaces has been published: the deployment `runtime` block and the `@sanity/workflow-blueprint/generate` entry point that exposed the earlier planning helpers both ship for the first time here. Declare a block only where you want to move a workflow or an effect off the default.
+
+  **Docs impact:** Document the `runtime` block once, at all three levels, in the deployment configuration reference beside `tag`, `workflowResource`, and `resourceAliases`: each kind, what the generator emits for it, and the effect-level `timeout` and `memory` units. Add the four hosting shapes (function hosted, durable hosted, self hosted with one workflow kept on functions, and mixed inside one workflow) to the generated-runtime guide, and state there that hosting decides whether a `$now` deadline causes a heartbeat to be emitted rather than which instances an emitted heartbeat ticks. State in the data-model concepts that `runtime` is the authoring-only block tooling reads and the deploy never stores.
+
+- 225e0fb: **BREAKING:** Workflows App SDK and Studio integrations now require `@sanity/sdk` 3.1 or later in the 3.x line, and `@sanity/workflow-sdk` requires the matching `@sanity/sdk-react` 3.1 line when its React entry is used. The previous SDK 2 peer contract is no longer supported. The exported `WorkflowClient`, `TelemetryIntakeClient`, `ProjectUserProfileClient`, and `StudioUserClient` request contracts now pass their target in `url`; the previous `uri` request target is no longer used. The engine's effective client config also accepts the broader `{type: string, id: string}` resource descriptors returned by Sanity client 8.
+
+  Before upgrading Workflows, upgrade `@sanity/sdk` and `@sanity/sdk-react` together to 3.1 or later. Applications that stay on SDK 2 must stay on an earlier Workflows release. If you implement any of the request contracts named above, update it to read the request target from `url` instead of `uri`; otherwise its request-backed reads will fail. Existing `WorkflowClient.config()` implementations need no change when their resource descriptor already has string `type` and `id` fields. No separate CLI upgrade action is required; its definition-sharing and telemetry requests adopt `url` internally.
+
+  Before installing, override SDK 3's `@sanity/mutate` dependency to `0.18.2` in your application's root package-manager configuration, reinstall, and commit the updated lockfile. SDK 3.1.0 allows Mutate 0.18.1, which can leave document reads pending with client 8. For npm, set `overrides["@sanity/sdk"]["@sanity/mutate"]` to `"0.18.2"` in `package.json`. For pnpm, set `overrides['@sanity/sdk@3>@sanity/mutate']` to `0.18.2` in `pnpm-workspace.yaml`. Keep the override until your SDK release requires Mutate 0.18.2 or later. Complete examples and verification steps are in the Installation section of the published `@sanity/workflow-sdk` README.
+
+  Malformed project-member responses now report an inaccessible directory and can recover on a later lookup, instead of being cached as a missing user. No additional upgrade action is required for this correction.
+
+  **Docs impact:** Update the App SDK and Studio integration installation guidance, package compatibility references, and examples to require Sanity App SDK 3.1 and the consumer Mutate override described in the published `@sanity/workflow-sdk` README; update the client API references for `request({url})`, effective resource descriptors, and directory-response failures.
+
+### Patch Changes
+
+- 393ac71: CLI and MCP telemetry now includes `context.surface` (`cli` or `mcp`) and
+  execution mode in each event's `context.environment`. Dashboards can include
+  shell and engine activity while distinguishing it from SDK events marked
+  `sdk`. Existing command trace context is preserved.
+
+  All three surfaces report `production` for `NODE_ENV=production`, and
+  `development` for `development` or `test`. Unset, empty, and unrecognized values
+  default to `production` for CLI and MCP execution mode, and `development` for
+  SDK build mode. SDK environment classification is unchanged. When comparing
+  activity across surfaces, group or filter by surface alongside environment.
+  Environment does not identify a production dataset or deployment; API host,
+  dataset name, and workflow tag do not set it.
+
+  **No upgrade action required.** Existing telemetry consent and opt-out
+  settings still apply. Historical events are unchanged.
+
+  **Docs impact:** Update CLI, MCP, and SDK telemetry guidance to explain surface
+  context, build versus execution mode, the explicit defaults, and how to
+  interpret environment when comparing activity across surfaces.
+
+- 7eb9eca: Correct the API references for field initialization and edits, start requirements,
+  transitions, reference IDs, effect handling, reactive state, member controls,
+  Studio mappings, test helpers, and GROQ condition outcomes. The references state
+  caller constraints and defaults that were missing or incorrect. Package setup
+  guidance identifies the public npm packages and supported deployment command;
+  the MCP validation description distinguishes validation from deployment checks.
+  Runtime behavior and API signatures are unchanged.
+
+  **No upgrade action required.**
+
+  **Docs impact:** After release and reference sync, reconcile the modeling,
+  runtime, reactive UI, Studio, testing, deployment, MCP, and evaluation-insight
+  guides and references with the corrected contracts. Fix affected examples and
+  replace redundant API inventories with verified symbol links while preserving
+  useful teaching and the CLI/MCP reference material not exposed by TypeDoc.
+
+- 2cef086: Internal maintenance consolidates engine action/edit handling and Studio document
+  and workflow title sorting. Action and field-edit calls retain their inputs and
+  results, and document and workflow titles retain their ordering. Action
+  availability, telemetry, and persisted document formats are unchanged.
+
+  **No upgrade action required.**
+
+  **Docs impact: None** because public APIs, configuration, and workflow behavior
+  are unchanged.
+
+- 232f811: Workflows can resolve reviewer attributes from self-hosted studios without
+  sending the attributes request to a global API host that rejects their origin.
+  Actor resolution uses the account-global identity carried by the project user
+  response when available, avoiding an unnecessary global request.
+
+  Custom clients without `withConfig` can also resolve organization attributes
+  when they already serve the engine's required API version.
+
+  **No upgrade action required.** Existing project CORS settings and workflow
+  definitions continue to apply.
+
+  **Docs impact:** Update Workflows prerelease troubleshooting guidance to describe
+  the fix for assignee loading on self-hosted studios and advise upgrading the
+  Workflows packages together. Document the version requirement for custom clients
+  in the engine client reference.
+
+- Updated dependencies [7eb9eca]
+  - @sanity/groq-condition-describe@0.5.1
+
+## 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
@@ -66,7 +66,9 @@ never matches the new type).
 
 - **`modelVersion` — provenance ("conforms-to").** The value of
   `DATA_MODEL_VERSION` at write time: "this document conforms to model N
-  now". Bumps on **every** declared shape change, additive included.
+  now". Advances for **every** declared shape change, additive included,
+  though several changes merged into one unreleased model share its number
+  (rule 9).
   Instances are re-stamped on every full persist (and rollback restore).
   Partial patches deliberately leave the pair alone — they don't normalize
   the shape, so restamping there would lie.
@@ -210,6 +212,13 @@ these principles before the change-process rules below apply.
    definition grammar has no kebab-case values, and no addition introduces
    the first.
 
+One block sits outside the persisted language entirely: `runtime` declares where
+the generated unattended runtime hosts a workflow or an effect, tooling reads it
+at authoring and generation time, and the deploy strips it so nothing reaches the
+Content Lake. One rule decides the category for any new property: it is stored
+if the engine reads it while running, and authoring-only if only tooling reads it
+before deploy.
+
 ## Rules for changing the model
 
 `DATA_MODEL_CHANGES` is the append-only, machine-readable counterpart of the
@@ -234,11 +243,12 @@ retained model-4 baseline.
    log below, and decide — in the same change — whether `DATA_MODEL_VERSION`
    moves **and whether the reader floor moves with it**. Nothing lands
    "incidentally".
-2. **Additive optional fields are allowed** without machinery: bump
-   `DATA_MODEL_VERSION`, leave the reader constants untouched, and
-   declare the tolerant read (what an absent value means on docs written
-   before the field existed) plus why the field survives an old writer's
-   round-trip.
+2. **Additive optional fields are allowed** without machinery: land on the
+   current model per rule 9 — bumping `DATA_MODEL_VERSION` when that model has
+   shipped and joining it when it has not — leave the reader constants
+   untouched, and declare the tolerant read (what an absent value means on
+   docs written before the field existed) plus why the field survives an old
+   writer's round-trip.
 3. **Renames, removals, and semantic changes are not allowed yet.** They
    require versioned upgrade machinery (per-model normalization steps applied
    on read) that does not exist; until it does, the model may only grow
@@ -246,8 +256,9 @@ retained model-4 baseline.
    documents' reader floor — through `DATA_MODEL_MIN_READER` when no reliable
    marker exists — and ships only after the fleet story is written.
 4. **`DATA_MODEL_VERSION` moves when compatibility reasoning changes** — when
-   a reader would need to know which shape it is looking at. A purely
-   internal refactor that provably writes an identical tree does not bump.
+   a reader would need to know which shape it is looking at, and that model has
+   already shipped (rule 9). A purely internal refactor that provably writes an
+   identical tree does not move it.
 5. **Classify by misinterpretation, not parseability.** The snapshot gate
    catches structural drift only. A change can be structurally additive yet
    change the MEANING of existing fields — old readers parse it fine and
@@ -272,6 +283,11 @@ retained model-4 baseline.
    existing slot, value, or variable could carry the behavior. "The existing
    mechanism is illegible or undiscoverable to surfaces" is an argument for
    restructuring that mechanism, not for a sibling property beside it.
+9. **A model number is assigned per release, not per merged change.** A change
+   merged before its model has shipped joins that model's log entry and its
+   ledger instead of opening a new number, so one release carries one model.
+   Reworking a ledger that has not shipped is the one exception to
+   append-only; once a model is released its entry and ledger are frozen.
 
 ## Model log
 
@@ -854,6 +870,204 @@ 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).
+
+### Model 10 — required content-reference availability and bounded effect retry (reader floor: 10)
+
+#### Required content-reference availability
+
+A workflow-scope `subject`, `doc.ref`, or `doc.refs` field marked `required: true`
+requires its selected targets to remain readable in the workflow's perspective
+after initialization. Missing targets produce a derived fault and prevent normal
+actions, triggered actions, and transitions from advancing. Abort and direct
+field repair remain available. Other field kinds retain the input-presence
+contract; optional references retain their authored runtime requirements.
+
+This is an explicitly approved extension of the existing `required` contract.
+It changes interpretation without changing stored field shapes. Existing
+reference values and frozen definition snapshots remain readable without
+normalization or backfill. The behavior applies when the upgraded engine reads
+an existing instance as well as when it starts a new one. The same word and
+shape carry requiredness; no parallel definition property is introduced.
+
+Manifest feature: `required-content-references` (definition + instance,
+reader-floor, detectable, floor 10). The marker is a workflow-scope required
+content-reference declaration, including one in an instance's frozen definition
+snapshot. New writes stamp model 10. Documents without this feature retain the
+floor required by their other features, normally 4, 8, or 9.
+
+Would an old reader misread (rule 5)? Yes. Older engines interpret `required`
+only at initialization and can advance after a required target disappears.
+Upgrade all runtimes sharing affected workflows before relying on this rule,
+then acknowledge reader model 10 before deploying affected definitions. A new
+engine's next full instance write raises the stored floor to 10. Existing
+instances are not backfilled, so until that write the stored floor alone cannot
+prevent an older runtime from advancing them; the readers-first rollout is
+required for those existing workflows too. Unknown fields and frozen snapshots
+survive full persists unchanged, and the floor remains raise-only.
+
+#### Bounded effect retry policy
+
+An effect node may declare `retry: {kind, attempts, backoff?: {kind, delayMs},
+expiryMs?}`. The block's `kind` says who runs the policy, and `engine` is its
+only member: the stored schema requires the discriminator and rejects any
+other value, and an authored block may omit it because desugar fills `engine`
+in, the same shape `start.kind` has. `attempts` is the total number of
+attempts, the first included. `backoff.kind` is `fixed` or `exponential`, and
+`delayMs` is the wait between two attempts: the same every time under `fixed`,
+doubled per attempt already made under `exponential`. `expiryMs` decides
+whether a further attempt may start rather than bounding the run, so an
+attempt already running is never interrupted.
+
+The accepted range is bounded on one side: `expiryMs` and the backoff a policy
+accumulates are each capped at 366 days. The whole policy runs inside one
+`drainEffects` invocation and no host offers a single execution longer than a
+year, so a policy declaring more than that could never run as written wherever
+it ran. The caps weigh declared waits alone, because a handler's
+duration is unknown at deploy; at runtime every elapsed millisecond counts
+against `expiryMs`, handler time included. This
+is a tightening of the accepted values in a new field, not a reshape: no
+previously valid stored tree becomes invalid, because nothing before model 10
+could carry a `retry` block at all. Bounding the span also keeps every deadline
+the engine stamps from it inside the range a timestamp can carry.
+
+The discriminator is there from the start because who runs the policy is the
+one thing about it that will vary, and a later member is then a new value in
+this slot rather than a second mechanism beside it. A `caller` member — the
+engine holding the claim and the expiry ceiling while surfacing each failure
+to whoever called `drainEffects` — is a separate, additive change under its
+own ticket.
+
+This is a definition-tree addition only. The policy runs inside one
+`drainEffects` call: the drain dispatches, waits the declared backoff on a
+failure that has attempts left, renews the claim's lease across the wait, and
+dispatches again, stopping when `attempts` are used up, or rather than start
+a wait that would carry the run past `expiryMs`. Nothing about an attempt is
+persisted, because nothing needs to survive the call — the run is one dispatch
+as far as the instance is concerned, and it ends in the `effectCompleted` row
+the engine already writes.
+That row's `detail` names how the run ended: the attempts used and the last
+error on a failure, or the attempt that succeeded when a later one did. No
+instance field, history row, or vocabulary value is added or changed.
+
+An absent `retry` preserves the model-9 meaning exactly: a failing handler
+completes the effect as failed on its first attempt, and a claim abandoned by
+a dead drainer is redispatched without limit under `effects.leaseMs`. That
+recovery path is also unchanged for an effect that declares a policy — a
+drainer that dies mid-run leaves a lapsed claim, the sweep releases it, and
+the next drain starts a fresh run.
+
+Why the existing vocabulary could not carry this (rule 8). The engine's only
+retry control was `effects.leaseMs`, a runtime construction option and one
+global number for every effect a deployment drains; it cannot say that a
+payout gets five paced attempts and a notification gets one. The definition
+could already express a retry LOOP — a counter field, an incrementing op, and
+transitions reading `$effectStatus` — but that re-enters a stage and queues a
+new effect entry each pass, which is a different thing: it retries the
+workflow step, not the dispatch. This policy governs how one queued entry is
+dispatched, and no existing slot speaks about a dispatch. `retry` is a new
+value in the existing effect node rather than a sibling mechanism: it
+introduces no error type, no ordering rule against an existing gate, and no
+verdict leg. Its failure is the effect-failure outcome that already exists,
+and its routing is the `$effectStatus` variable that already exists.
+
+Would an old reader misread (rule 5)? Yes. A pre-model-10 engine reading a
+definition preserves the unknown `retry` property and ignores it, so a handler
+failure completes the effect on the first attempt: an author who declared five
+attempts silently gets one, and the instance takes its failure branch four
+attempts early. That is a silent wrong outcome rather than a refused read,
+which is exactly what the floor exists for. Instances need no separate
+judgment — the policy writes no instance shape a model-9 reader has not seen.
+
+The marker is an effect node carrying `retry`, detectable in a definition
+document's own tree and in an instance's embedded `definitionSnapshot`. An
+instance derives the floor from its pinned definition, so an instance of a
+policy-bearing definition is held to the same reader as the definition itself.
+Definitions and instances without a `retry` effect retain the floor their
+other features derive, normally model 4, 8 or 9, or model 10 through the
+required-reference feature beside it.
+
+Manifest feature: `effect-retry-policy` (definition + instance, reader-floor,
+detectable, floor 10). The instance document type is listed because an
+instance inherits its pinned definition's floor, not because the policy adds
+an instance shape.
+
 ## Pending governed changes
 
 - **`temp.system.guard` → `system.guard`** — the guard doc type's `temp.`

package/README.md

@@ -4,8 +4,8 @@ Workflow / BPM engine for Sanity content. Define workflows as data, run them as
 instances against a Sanity client, gate transitions on GROQ filters, and queue
 effects for runtimes to drain.
 
-> **Status:** 0.x, internal. Restricted-access package; the API may change
-> between minor versions.
+> **Status:** Pre-1.0 and publicly available on npm. The API may change between
+> minor versions.
 
 ## Installation