@sanity/workflow-engine-test 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -0,0 +1,494 @@
+# @sanity/workflow-engine-test
+
+## 0.10.0
+
+### Minor Changes
+
+- 65c7b0f: **BREAKING:** `bench.editDocument` now takes a `{set?, unset?, insert?}` patch spec instead of a set-only object — rewrite `patch: {title: 'x'}` as `patch: {set: {title: 'x'}}`. All three op kinds ride the same guarded as-actor write seam in a single commit, so `!defined(...)` predicates and array appends are now testable without bypassing `identity()` routing. A non-delete edit whose patch carries no ops throws, and `action: 'delete'` rejects a patch outright — contradictory input fails loud instead of being dropped.
+
+  New bench surface:
+  - `bench.setStage(args)` and `bench.abortInstance(args)` — the two instance-admin verbs join the wrapped set, injecting the bench access default and the bench clock like every other wrapper (previously callers rebuilt an engine by hand and time-based predicates evaluated at wall-clock).
+  - `createBenchEngine(bench, overrides?)` is now exported: builds an out-of-band engine that inherits the bench's client, tag, workflow resource, and clock; `overrides` win.
+  - The bench exposes its `tag` and `workflowResource`, and the default tag ships as the `BENCH_TAG` constant.
+
+- d192d68: Definitions can now declare which documents they're for, and consumers can discover the right workflow to surface or start — no more hand-maintained per-consumer mapping tables.
+  - `types?: string[]` on `doc.ref` / `doc.refs` field entries — the engine's `reference.to`. Absent accepts any type; declaring it on any other kind is a define-time error, as is an empty list or a literal seed whose GDR `type` isn't listed.
+  - Optional definition-level `applicableWhen` — GROQ evaluated against a candidate document (the doc is the root; no `$` vars are bound, no lake) for value-level routing like `"_type == 'article' && articleType == 'finance'"`. Deploy validation rejects a parse error, any `$var` read, and any `*` dataset scan — each would make the predicate silently wrong at runtime.
+  - Discovery is a pure derivation over deployed definitions: startable ∧ a required subject entry accepts the doc's `_type` ∧ `applicableWhen` passes (a GROQ-null result fails closed; a malformed predicate fails LOUD, naming its definition). Exposed as `applicableDefinitions` / `isDefinitionApplicable` / `acceptsDocumentType`, and as the `definitionsForDocument` verb (namespace + `Engine`) — the startable half of `instancesForDocument`. It takes the LOADED candidate document, considers only the latest deployed version per name, and surfaces ALL matches with no engine ranking. Advisory like every engine-side check.
+  - Every hard write door honours `types`: `startInstance` initialFields, the spawn `with` handoff, and `editField` / `field.set` / `field.append` ops (resolved ref entries persist their declared `types`, like `object`/`array` persist `fields`/`of`, so instances stay self-describing). A violation fails hard — API-contract validation, the same tier as a missing required field. The spawn error names the projection footgun when (and only when) it applies: a projected bare id / `_ref` canonicalises with the generic type `"document"`, so a typed child entry needs `{"id": _id, "type": _type}` projected. A query-sourced entry's mismatching lake result is discarded with an audit row, like every other query-shape mismatch.
+  - Bench: `definitionsForDocument(document)` read helper.
+
+- d6e92ed: Now published with public npm access (previously restricted) — installable without `@sanity` org membership.
+
+### Patch Changes
+
+- 9f5a40f: Multi-resource bench coverage now proves the engine's auto-derived sibling routing: a subject in a foreign dataset is readable with no `resourceClients`, and a resolver miss reads the derived sibling for the target resource instead of falling back to the workflow client.
+- 2511bb5: The `releaseField` fixture builds its `release.ref` envelope through the engine's `releaseRef` constructor, and test expectations track the engine's reworded `instancesQuery` document-filter error.
+- 6bbf3ca: **BREAKING:** effect delivery reliability — claim leases with a stale-claim sweeper, and caller-supplied idempotency keys that are actually honored.
+
+  Claim leases (`drainEffects` / `sweepStaleClaims`):
+  - Every claim `drainEffects` stamps now carries `leaseExpiresAt` (engine-configurable via `createEngine({effectLeaseMs})`, default 5 minutes). A claim whose lease lapsed no longer protects its entry — the claimer is presumed dead, so a drainer dying between claim and complete no longer wedges the entry forever (previously the only recovery was aborting the whole instance). A claim persisted before leases existed counts as already expired, keeping exactly those stuck entries recoverable. There is deliberately no attempt counter on the claim: the retry count is the `effectClaimReleased` history rows for the entry's `_key` (plus the live claim), and a stored field would drift from that trail.
+  - `drainEffects` takes expired claims over in the same CAS write that stamps its own claim, recording an `effectClaimReleased` history row (new `HistoryEntry` variant) with the abandoned claim embedded for audit. The `ifRevisionId` guard is the sweeper election — concurrent recoverers race safely.
+  - New standalone `sweepStaleClaims({client, tag, instanceId})` export: force-release expired claims WITHOUT dispatching, for ops/admin housekeeping. Deliberately not an `Engine` verb (same category as the guard-lifecycle helpers) — a drain already self-recovers via takeover. Returns the released entries; the next drain redispatches them.
+  - `DrainEffectsResult` gains a required `lost` bucket: entries this drainer dispatched whose completion lost to another party (e.g. a takeover finishing first). Previously that race crashed the drain with `EffectNotFoundError` mid-loop.
+  - `EffectHandler`'s TSDoc now states the delivery contract explicitly: **at-least-once — a handler MAY double-run** (crash between dispatch and completion, or a slow dispatch outliving its lease). Check `effectHistory[]` for the run's `ctx.effectKey` before irreversible work, and derive external-system identifiers from `ctx.effectKey` so the receiving system can dedupe.
+  - `drainEffects`/`sweepStaleClaims` read the engine clock for claim/lease stamps, so lease timing is deterministic under `createEngine({clock})` (previously drain stamped wall-clock unconditionally).
+
+  Caller idempotency keys (previously a declared-but-dead arg):
+  - The commit-owning verbs — `fireAction`, `editField`, `completeEffect`, `setStage`, `abortInstance` — now honor `idempotencyKey`. The first commit records the key on a new `processedRequests[]` instance ledger **in the same CAS write as the operation**, and a blind retry replays instead of double-applying (or, for a completed effect, throwing `EffectNotFoundError`): the op is not re-applied, but the cascade still runs to convergence — repairing the exact crash window a keyed retry exists for (died between the original's commit and its cascade) — so `changed` is `false` unless that cascade moved the instance. The check runs before the verbs' soft gates, so a replay can't die on a gate its own original commit closed (a resolved activity, a moved stage).
+  - Ledger rows expire after `idempotencyTtlMs` (engine-scope config, default 24h) and are pruned lazily by later keyed commits; instances whose callers pass no keys never grow the ledger. Reusing a live key on a different verb throws `ContractViolationError`.
+  - The moved arg is the breaking part: `idempotencyKey` now lives on `DedupableOperationArgs` (which the five verbs' args extend) instead of `OperationArgs`, so `tick` — which owns no commit and is naturally idempotent — no longer accepts the previously-ignored field.
+
+- adf32f7: **BREAKING:** the `createBench({accessControl})` option is removed — it is subsumed by the identity registry (the identity's grants both render `$can` and gate the fake lake's writes, so identity and enforcement can't disagree), and a supplied `client` is rebound to the bench's default token identity. The bench expresses identities as registered tokens on its fake client: `createBench({currentUser, grants})` registers the default token, per-call `actor:`/`grants:` shortcuts mint cached token-scoped sibling clients, and the engine token-resolves every identity from `/users/me` + the ACL path exactly like production — token and actor can no longer disagree. The bench API is unchanged for tests using the shortcuts. New surface: `bench.clientFor({actor, grants?})` exposes the identity directory directly — the one registration seam for acting as another user (bind its sibling to `createBenchEngine`); omitted grants default to wildcard. New `createBench({executionContext})` passthrough (default `{kind: 'test'}`) for provenance assertions.
+- 23cf131: Internal test fixture only (nothing published changes): `multiResourceHarness` accepts two new options — `contentAccessControl` gives the content resource an identity-serving, grant-gated client whose ACL path serves the supplied grants; `wfGrants` swaps the grants on the harness's existing token-bound wf identity (the identity itself stays `{id: 'test'}`).
+- 6c21009: Regression tests pinning documented contracts: a guard `match.idPatterns` glob supports multiple `*`s and matches the whole id (anchored — no substring leak), `$can` binds in activity `requirements.*` and in `editable` predicates (unmet under read-only grants, met under update grants), and deploying a guard whose `idRefs` resolve to documents in different resources fails loudly with the single-resource error instead of picking one.
+- dc64968: Published tarballs no longer include sourcemaps (whose `sourcesContent` embedded the complete TypeScript source) or inline code comments in the compiled JS — license markers and bundler annotations (`/*@__PURE__*/`-style tree-shaking hints) are preserved. Types and TSDoc in `.d.ts` files ship unchanged, and the tarballs shrink accordingly (workflow-engine: ~3× smaller). Each tarball now ships its `CHANGELOG.md`, so release notes reach consumers who can install the package but cannot see the repository.
+- d192d68: **BREAKING:** subworkflow lifecycle is now owned by a workflow-scope registry (`instance.subworkflows`) instead of stage-entry bookkeeping. A child instance is a workflow-level fact; its record now lives (and survives) at workflow scope.
+  - Re-entering a spawning stage **adopts** live children whose `forEach` rows are rediscovered instead of spawning a duplicate cohort. Rows that vanished from discovery follow the block's new `onExit` policy — `'detach'` (default) lets the child run to completion outside the gate, `'abort'` kills it. Stage exit applies the same policy to the live cohort.
+  - `forEach` rows must carry an identity for adopt-matching: `_key` ?? `_id` for object rows (mint a `_key` in the projection for synthetic rows), the value itself for scalar rows. An identity-less or duplicate-identity row fails the spawn with a teaching error.
+  - `abortInstance` now cascades: every live descendant is aborted recursively. An owed abort is recorded ON the child's registry row (`abortPending: {at, reason}` — crash-safe, and kept afterwards as the audit of why); the cascade drains condemned rows, and a condemned row is never adopted into a fresh cohort.
+  - `$subworkflows` is now an **always-bound** condition var over ALL registry rows, faceted by `activity` / `definition` / `rowKey` / `status` (`'active' | 'done' | 'aborted'`), with `current` marking the open stage entry's cohort and `stage` the child's current stage — usable in transition filters, requirements, and any stage's gates. The implicit spawn gate scopes itself to the current cohort and settles on not-active (an aborted child releases it); authored gates that assumed spawn-scoped rows must now facet (`$subworkflows[activity == "…" && current && …]`).
+  - Live children join the parent's watch-set and snapshot with raw reads, so conditions over child state re-evaluate as children move; a terminal child's state is frozen onto its registry row and its document leaves the watch-set.
+  - Child completion propagates through the registry: a detached child (spawning stage exited, parent moved on) still stamps its row and re-cascades the parent; a terminal parent takes the stamp and history record without being reopened; a propagation with no matching registry row records a loud `subworkflowOrphaned` history entry instead of silently dropping.
+  - A parent may complete with live detached children — legal, and `diagnose` now reports `liveChildren` on terminal states so consumers can surface it.
+  - Removed: `ActivityEntry.spawnedInstances` — the registry replaces it. Instances persisted before the registry have an empty registry, so a spawning activity that was waiting on in-flight children resolves immediately on its next cascade (the cohort gate is vacuously settled) and those children's completions no longer propagate — each is recorded as a `subworkflowOrphaned` history entry on the parent when it terminates. Let in-flight fan-outs finish before upgrading, or expect to re-drive affected parents manually.
+
+- Updated dependencies [4ca17bb]
+- Updated dependencies [5143707]
+- Updated dependencies [0709ab1]
+- Updated dependencies [6bbf3ca]
+- Updated dependencies [9f5a40f]
+- Updated dependencies [d192d68]
+- Updated dependencies [6c21009]
+- Updated dependencies [109f900]
+- Updated dependencies [109f900]
+- Updated dependencies [444b0e6]
+- Updated dependencies [2511bb5]
+- Updated dependencies [d4fd8e6]
+- Updated dependencies [30ed0e8]
+- Updated dependencies [2834704]
+- Updated dependencies [2511bb5]
+- Updated dependencies [2511bb5]
+- Updated dependencies [2511bb5]
+- Updated dependencies [4607d59]
+- Updated dependencies [52f6024]
+- Updated dependencies [a8f1cb9]
+- Updated dependencies [adf32f7]
+- Updated dependencies [5cb0850]
+- Updated dependencies [70a136c]
+- Updated dependencies [91540de]
+- Updated dependencies [8455fbb]
+- Updated dependencies [325c2d1]
+- Updated dependencies [d6e92ed]
+- Updated dependencies [6c21009]
+- Updated dependencies [7ffdc77]
+- Updated dependencies [325c2d1]
+- Updated dependencies [7ffdc77]
+- Updated dependencies [ced40e4]
+- Updated dependencies [9b1b40d]
+- Updated dependencies [8c319b2]
+- Updated dependencies [dc64968]
+- Updated dependencies [23cf131]
+- Updated dependencies [d192d68]
+- Updated dependencies [15337f1]
+- Updated dependencies [2d1a8e1]
+- Updated dependencies [12cdbd6]
+- Updated dependencies [437b544]
+- Updated dependencies [ced40e4]
+  - @sanity/workflow-engine@0.15.0
+
+## 0.9.0
+
+### Minor Changes
+
+- 7a655bd: The bench grows the fixture helpers every consumer was hand-rolling: `subjectField(documentId, {name?, type?})` and `releaseField(releaseName, {name?})` build initial-field entries for the bench's default resource (derived via the engine's GDR constructors, not restated URI strings), and `bench.completePendingEffect({instanceId, effect, ...})` completes a pending effect looked up by name — the idiomatic way to play an external handler reporting its result — throwing loud when no such effect is pending.
+- 5c69928: **BREAKING:** runtime API coherence pass — one result shape, one session noun, nameable engine args.
+  - `DispatchResult` → `OperationResult`, and its `fired` flag → `changed` with one meaning honored by every verb: this call changed the instance's workflow state (`false` = successful no-op — an idempotent re-fire, a tick that wrote nothing, a `setStage` already at the target, an abort of an already-terminal instance; failures still throw). `tick` derives it from the instance revision, so a persisted activity-gate flip that didn't unlock a transition still reports `changed: true`. `abortInstance` documents its always-`0` cascade (a terminal instance doesn't cascade; ancestor propagation reports on the ancestors).
+  - `startInstance` now returns `OperationResult` instead of a bare `WorkflowInstance` — its cascade is finally observable. Reach the instance via `result.instance`.
+  - Engine argument types are exported and nameable: the exported `*Args` shapes are now exactly what `Engine` methods take, and the raw `workflow.*` namespace takes `<Verb>Args & EngineScopeArgs` (the new exported scope type: `client` / `tag` / `workflowResource` / `resourceClients`). New named args for the read/housekeeping verbs: `InstanceRefArgs`, `ChildrenArgs`, `GuardsForDefinitionArgs`, `InstancesForDocumentArgs`, `QueryArgs`, `QueryInScopeArgs`, `FindPendingEffectsArgs`, `DrainEffectsArgs`, `SessionArgs`. `EvaluateArgs` is likewise scope-free now.
+  - Verb-surface parity between `Engine` and `workflow.*` is exact and documented: `Engine.evaluateInstance` → `Engine.evaluate` (matching `workflow.evaluate`); engine-only members (`session`, `subscriptionDocumentsForInstance`, `drainEffects`, `verifyDeployedDefinitions`) and the namespace-only `workflow.permissions` are called out as deliberate.
+  - One noun for the reactive session handle: `engine.instance(doc, opts?)` → `engine.session({instance, access?, grantsFromPath?})` (args object — no positional outlier), still returning `InstanceSession`; workflow-react's `WorkflowInstanceController` → `WorkflowSession`; the studio/sdk hooks `useWorkflowInstance` → `useWorkflowSession`. "Instance" now always means the document.
+  - Test bench mirrors the engine: `bench.startInstance` returns `OperationResult`, and the `Bench*Args` types are the engine-bound shapes minus `access`.
+  - CLI reports follow the rename: the report objects for `fire-action` / `move-stage` / `abort` (and `fire-action`'s `--json` payload) now say `changed` instead of `fired`.
+
+- 6ee9068: **BREAKING:** the bench's default `ALL_ACCESS_USER` actor is `kind: 'person'` (was `'user'`), following the engine's actor-kind rename — tests asserting on recorded actor kinds must follow.
+
+### Patch Changes
+
+- d9c8179: Drop the remaining "POC" branding from the guard docs and single-source the persisted guard doc type. Doc comments reference the type via `GUARD_DOC_TYPE` instead of hardcoding the literal, tests build guard ids and `_type` assertions with the exported `GUARD_DOC_TYPE` / `lakeGuardId`, and a contract-pin test pins the persisted wire literals so the eventual stored-type rename is a deliberate act. The `GUARD_DOC_TYPE` doc also notes that the cutover rename is a breaking type change for already-persisted guard docs.
+- 0a7979a: Reconcile the guard enforcement story across the public surface. The packages previously asserted both that "the lake enforces guards" and that "enforcement is optimistic — the lake does not enforce `temp.system.guard`". Only the second is true: the lake does not evaluate the guard doc type yet (it is the placeholder for the lake's forthcoming guard primitive), so deployed guards deny optimistically engine-side on every plan and the lake ACL is the only hard gate. Every TSDoc block and README now tells that one story, with `GUARD_DOC_TYPE` as the canonical anchor; the bench's write rejection is described as a simulation of the intended lake contract, not a reproduction of current production behavior.
+- 113a796: README: the shared-store sample passes the shipped `tag` argument to `createBench` instead of the renamed-away `tags`.
+- Updated dependencies [a0443c4]
+- Updated dependencies [a0443c4]
+- Updated dependencies [ad9b6f6]
+- Updated dependencies [83d5924]
+- Updated dependencies [7a655bd]
+- Updated dependencies [d9c8179]
+- Updated dependencies [0a7979a]
+- Updated dependencies [df00bbb]
+- Updated dependencies [5c69928]
+- Updated dependencies [2f081a3]
+- Updated dependencies [df00bbb]
+- Updated dependencies [113a796]
+- Updated dependencies [df00bbb]
+- Updated dependencies [2829643]
+- Updated dependencies [6ee9068]
+- Updated dependencies [2829643]
+- Updated dependencies [a0443c4]
+  - @sanity/workflow-engine@0.14.0
+
+## 0.8.0
+
+### Minor Changes
+
+- 5bbc3f0: **BREAKING:** `Bench` methods (and exported test helpers) that took 3+ positional parameters now take a single named options object — e.g. `bench.editDocument({documentId, patch})`, `bench.instancesByStage({workflowName, stage})`, `bench.queryInScope({instanceId, groq})`. Behavior is unchanged — only the calling convention; update call sites to pass a single object.
+- 6e51913: Add resource aliases so a definition can reference content portably across deploys. A definition addresses content through a named alias — `@content:<id>` — instead of a hardcoded physical GDR. `deployDefinitions` accepts a `resourceAliases` map binding each alias to a physical `WorkflowResource` (`ResourceAliases`, the sibling of role aliases), and expands every `@<alias>:` reference to its bound physical GDR at deploy: the deployed definition holds only physical references, so no alias and no runtime resolver survive past deploy. Switching environments is just deploying the same source with a different map.
+
+  Expansion runs in the shared deploy planner, before the content fingerprint, so `deployDefinitions` and `definition diff` always fingerprint the same physical content (they can't drift), and rebinding an alias and redeploying the same source surfaces as changed content — a new version — never a silent shift in what the workflow reads. Deploy fails closed when a definition references an alias the deploy doesn't bind, or when a standalone reference expands to a malformed GDR. Expansion is a structural walk that rewrites references in GROQ and literal ref values only, never in `title`/`description` prose. Bare ids and physical GDRs are unchanged, so single-resource setups need no `resourceAliases`. The test bench accepts `resourceAliases` on `deployDefinitions`.
+
+### Patch Changes
+
+- Updated dependencies [416d4c9]
+- Updated dependencies [4dfe72a]
+- Updated dependencies [5bbc3f0]
+- Updated dependencies [0bf7503]
+- Updated dependencies [6e51913]
+- Updated dependencies [3229f41]
+  - @sanity/workflow-engine@0.13.0
+
+## 0.7.0
+
+### Minor Changes
+
+- 9519c76: **BREAKING:** Rename the structural `Task` node in the workflow DSL to `Activity`. The node holds multiple Actions, its own scoped Fields, and a status lifecycle — it is not atomic, so in process-modelling terms it is an _Activity_ (BPMN: Activity is the umbrella for work, Task the atomic kind). This frees the word "task" so it never appears in the model — "Tasks" is now purely a product/UI worklist view, not a model entity.
+
+  `Action` (the actor-fired command) is unchanged.
+
+  The rename cascades across the whole surface:
+  - Authoring: `defineTask` → `defineActivity`; the `tasks:` array on a stage → `activities:`; `Task`/`AuthoringTask` types → `Activity`/`AuthoringActivity`.
+  - Classification: `TASK_KINDS` → `ACTIVITY_KINDS`, `TaskKind` → `ActivityKind`, `deriveTaskKind`/`taskKind` → `deriveActivityKind`/`activityKind` (kind values `user`/`service`/`script`/`manual`/`receive` are unchanged). The shipped "task kinds" surface is retitled "Activity kinds".
+  - Status: `TASK_STATUSES`/`TaskStatus` → `ACTIVITY_STATUSES`/`ActivityStatus` (and the terminal-status counterparts); status _values_ are unchanged.
+  - Predicate sentinels: `$tasks` → `$activities`, `$allTasksDone` → `$allActivitiesDone`, `$anyTaskFailed` → `$anyActivityFailed`, `$requiredTasksDone` → `$requiredActivitiesDone`, `$task` → `$activity`. Authored GROQ filters referencing the old names must be updated.
+  - Persisted/wire format: the `'task'` field scope value → `'activity'`, history entry types (`taskActivated`/`taskStatusChanged` → `activityActivated`/`activityStatusChanged`), and engine result/diagnostic codes (`failed-task` → `failed-activity`, `task-not-active` → `activity-not-active`, `reset-task` → `reset-activity`, etc.).
+  - `workflow-react`: the `fireAction` argument `{task}` → `{activity}`.
+
+  Nothing referencing "task" remains in the model. This is a deliberate pre-customer breaking change to land the correct, permanent vocabulary.
+
+- 9233cd3: Add `engine.instancesForDocument({document})` — the reverse of the watch-set, finding every in-flight instance whose evaluation depends on a given document. The forward watch-set (`subscriptionDocumentsForInstance` / `collectWatchRefs`) answers "which docs does this instance watch"; this answers "which instances watch this doc", which a non-reactive, content-change-driven runtime (a Sanity Function, an Inngest/durable worker) needs to know which instances a changed document should `tick`. It mirrors the forward method's name (`subscriptionDocumentsForInstance` ↔ `instancesForDocument`) and sits alongside the existing `instancesForSubject` / `instancesByStage` read helpers.
+
+  It matches the same ref set the forward watch-set uses — the instance itself, its ancestors, and the docs named by `doc.ref` / `doc.refs` / `release.ref` field entries on the workflow scope **and the current stage** — via the new pure `instanceWatchesDocument(instance, document)` helper, which derives from `collectWatchRefs`, so forward and reverse stay in lockstep (the same way `hydrateSnapshot`'s load-set does). A coarse GROQ prefilter narrows candidates server-side; the shared matcher does the exact, open-stage-only narrowing. The subject is matched by its full, resource-qualified GDR URI, so a cross-dataset doc never matches a same-id doc in another resource. The test bench gains a matching `bench.instancesForDocument(document)` read helper.
+
+  This replaces the hand-rolled, incomplete GROQ a content forwarder would otherwise write (which misses stage-scope refs, `release.ref`, and ancestors).
+
+### Patch Changes
+
+- Updated dependencies [5b10863]
+- Updated dependencies [ae1434e]
+- Updated dependencies [d850aef]
+- Updated dependencies [9519c76]
+- Updated dependencies [9233cd3]
+- Updated dependencies [3ea4953]
+- Updated dependencies [e5a862a]
+  - @sanity/workflow-engine@0.12.0
+
+## 0.6.1
+
+### Patch Changes
+
+- Updated dependencies [3b8f3de]
+  - @sanity/workflow-engine@0.11.0
+
+## 0.6.0
+
+### Minor Changes
+
+- fae3553: **BREAKING:** Rename the domain concept **state → fields** across the whole API and persisted data model.
+
+  "State" was too easily conflated with "stage". The typed, valued data attached to workflows, stages, and tasks is now called **fields** — clearer, and aligned with Sanity schemas: the fields on a workflow, stage, and task can have typed values. This is a clean break (no migration, no back-compat); already-deployed definitions and instances must be redeployed/recreated.
+
+  **Authoring DSL**
+  - `defineState(...)` → `defineField(...)`
+  - The `state: [...]` array on a workflow / stage / task → `fields: [...]`
+  - The `$state.<name>` GROQ scope token → `$fields.<name>`
+  - A `claim` action's `state:` reference → `field:`
+  - A `stateRead` source → `fieldRead`; its `state:` (entry name) → `field:`
+  - Op targets address the entry by `field:` instead of `state:`
+
+  **Persisted / wire format**
+  - Op type strings `state.set` / `state.unset` / `state.append` / `state.updateWhere` / `state.removeWhere` → `field.*`
+  - The stored `state[]` array on instances, stage entries, and task entries → `fields[]`
+  - `startInstance({ initialState })` → `startInstance({ initialFields })`
+
+  **Types & functions** (engine)
+
+  `StateEntry`→`FieldEntry`, `AuthoringStateEntry`→`AuthoringFieldEntry`, `ResolvedStateEntry`→`ResolvedFieldEntry`, `InitialStateValue`→`InitialFieldValue`, `StateKind`→`FieldKind`, `StateValueMap`→`FieldValueMap`, `StateScope`→`FieldScope`, `StoredStateRef`→`StoredFieldRef`, `STATE_SLOT_DISPLAY`→`FIELD_SLOT_DISPLAY`, `EditStateArgs`→`EditFieldArgs`, `EditStateTarget`→`EditFieldTarget`, `EditStateDeniedError`→`EditFieldDeniedError`, `ConcurrentEditStateError`→`ConcurrentEditFieldError`, `RequiredStateNotProvidedError`→`RequiredFieldNotProvidedError`, and the `editState` verb → `editField`.
+
+  Unchanged: runtime/lifecycle instance "state" (stage moves, `WorkflowStateDivergedError`, the projected instance snapshot), the `field`/`fields` JSON-matching primitives in `updateWhere`/`removeWhere` predicates and object Sources, and the Content Lake release `state`.
+
+### Patch Changes
+
+- Updated dependencies [fae3553]
+  - @sanity/workflow-engine@0.10.0
+
+## 0.5.0
+
+### Minor Changes
+
+- 2e4c980: Add a generic edit seam for declared-editable workflow state.
+
+  State slots can now declare `editable` (default off) and be written directly
+  through one `editState` verb — reassign, reschedule, claim-by-hand, append to a
+  log — instead of a bespoke action per field.
+  - `editable` on a state slot — default off. _Who_ may edit is expressed with
+    the gating actions already have, not a new permission concept: `true` (anyone
+    in the slot's scope window), a **role list** (the same `action.roles` sugar —
+    it desugars to the identical `count($actor.roles[@ in [...]]) > 0` membership
+    predicate), or a raw GROQ predicate (checked like `action.filter`). A stage
+    may TIGHTEN a slot via an `editable` override map — the override is ANDed with
+    the slot's baseline, so it can only narrow, never open a closed slot.
+  - `editState` engine verb (and `engine.editState` / `instanceSession.editState`):
+    gates on the slot's editability and scope window, applies the edit as a
+    `state.*` op (so provenance + history are stamped by the op path), refreshes
+    the stage's guards, then cascades — an edit to a value a transition reads can
+    move the instance. Advisory like every engine gate; the lake ACL + guards are
+    the only hard locks.
+  - Scope is the editable window: a workflow slot is editable while the instance
+    is live, a stage slot while its stage is current, a task slot while its task
+    is active.
+  - The projection gains `editableSlots`: each declared-editable slot in scope
+    with this actor's edit verdict and the current value's provenance (`setBy` /
+    `setAt`, read off `opApplied` history — no denormalised copy). `EditDisabledReason`
+    and `EditStateDeniedError` mirror the action verdict surface.
+  - `@sanity/workflow-react`'s controller exposes `editState`, threaded through
+    the Studio and App SDK adapters.
+
+### Patch Changes
+
+- fd6b866: Add role aliasing to the authoring DSL: a definition-level `roleAliases` map
+  ("can be fulfilled by"). It's an authoring convenience — the same capability is
+  often carried by different role names depending on how a project deploys its
+  Content Lake roles, so rather than enumerate every equivalent role inline in
+  each `roles` gate (or fork the definition per deployment), declare once which
+  other roles fulfill it. Each key is a role a gate or `assignees` entry names;
+  its value lists the roles that also satisfy it. The reserved `"*"` key lists
+  roles that fulfill any gate (e.g. `{ "*": ["administrator"] }` for a
+  deployment's broad role).
+
+  The map expands the **required** side — never the actor's roles — and is applied
+  in both places roles are matched: the `roles` gate bakes the expanded membership
+  into its desugared GROQ at define time, and `$assigned` resolves the assignee's
+  role through the map at runtime. Expansion is one level (non-transitive).
+
+  This also corrects the misleading `Actor."*"` documentation: an actor's `roles`
+  are matched by literal membership only — there is no actor-side wildcard — with
+  the definition's `roleAliases` as the sole mechanism for widening, so the
+  advisory gate can never grant access the actor was not actually given. Like
+  every engine gate it is advisory; the registrant owns keeping the map true to
+  the deployment's real Content Lake ACLs.
+
+- Updated dependencies [2e4c980]
+- Updated dependencies [fd6b866]
+  - @sanity/workflow-engine@0.9.0
+
+## 0.4.2
+
+### Patch Changes
+
+- Updated dependencies [c298ee2]
+- Updated dependencies [8131dd5]
+- Updated dependencies [8bf467e]
+  - @sanity/workflow-engine@0.8.0
+
+## 0.4.1
+
+### Patch Changes
+
+- Updated dependencies [ef927bc]
+- Updated dependencies [32f5e64]
+- Updated dependencies [df7582f]
+- Updated dependencies [ed4174c]
+- Updated dependencies [129258c]
+  - @sanity/workflow-engine@0.7.0
+
+## 0.4.0
+
+### Minor Changes
+
+- c6d1762: Model the engine tag as a single environment partition: `tags: string[]` becomes `tag: string`.
+
+  The array + set-intersection matching was over-modelled — an engine operates against exactly one environment (test vs prod) at a time. `createEngine`, the raw `workflow.*` args (`DeployDefinitionsArgs`, `StartInstanceArgs`, `OperationArgs`, `EvaluateArgs`, `DeleteDefinitionArgs`), and the stored `workflow.definition` / `workflow.instance` documents now carry a single `tag`. Reads filter by equality (`tag == $tag`) instead of intersection, and `workflow.query` requires a `$tag` filter rather than `$engineTags`. Consumer-authored `type: "query"` state entries that referenced the `$engineTags` scope param now receive `$tag` (a single string) instead. `validateTags` is replaced by `validateTag`, and `canonicalTag` is removed (the tag is the ID prefix directly).
+
+  The `tag` is **required** — there is no default. The engine enforces nothing, so the partition is the only thing keeping reads and writes off the wrong environment; an engine must not guess. `createEngine` requires it, and the CLI (`WORKFLOW_TAG` / `--tag`) and MCP server (`WORKFLOW_TAG`) both fail at startup when it's absent.
+
+  The test bench's `createBench({ tags })` option becomes `createBench({ tag })`.
+
+### Patch Changes
+
+- Updated dependencies [c6d1762]
+  - @sanity/workflow-engine@0.6.0
+
+## 0.3.1
+
+### Patch Changes
+
+- Updated dependencies [dbc4afa]
+- Updated dependencies [e2a6d5d]
+- Updated dependencies [aa87a1c]
+  - @sanity/workflow-engine@0.5.0
+
+## 0.3.0
+
+### Minor Changes
+
+- fcf938a: Rebuild the authoring DSL and stored model around generic primitives plus
+  define-time sugar. Breaking across the board:
+  - **Name identity everywhere.** `name` replaces `id`/`workflowId` on
+    definitions, stages, tasks, actions, transitions, state entries, and
+    effects; instances carry `definition` + `currentStage` by name. The API
+    boundary follows: `startInstance({definition})`,
+    `guardsForDefinition({definition})`, `children({task})`, deploy results
+    carry `definition`, and guard provenance is `sourceDefinition` /
+    `sourceStage`. The pre-rebuild "slot" vocabulary is gone — state values
+    validate as state entries (`StateValueShapeError` with `entryType` /
+    `entryName`). Bare
+    in-array `type` discriminators replace namespaced `_type` kinds
+    (`doc.ref`, `assignees`, `state.set`, …). Engine-owned lake doc types are
+    `sanity.workflow.definition` / `sanity.workflow.instance`.
+  - **Two-layer schemas.** Authoring shapes (primitives + sugar) desugar at
+    define-time into the stored definition: the claim pair, the `audit` op
+    (stamped append), `roles`/`status` field sugar, lexical scope resolution
+    for op targets, and the default `$allTasksDone` transition filter.
+    State-entry names and predicate keys must be GROQ-safe identifiers (they
+    are referenced as `$state.<name>` / `$<name>` in conditions). Deploy
+    invariants reject duplicate names (stages, tasks, actions, transitions,
+    state entries per scope, guards across the definition, effects), unknown
+    targets, reserved-var shadowing, predicate cross-references and
+    caller-scoped vars in predicates, `$can` outside action filters, and
+    malformed guard reads.
+  - **Ops are the only mutation vocabulary.** `state.set` / `state.unset` /
+    `state.append` / `state.updateWhere` / `state.removeWhere` /
+    `status.set`, with `{scope, state}` targets resolved at deploy and
+    `status.set` as the single task-resolution mechanism (stamps completion +
+    history).
+  - **Lifecycle payloads.** Tasks own activation (`activation: 'auto' |
+'manual'`, machine-step auto-resolution, `completeWhen`/`failWhen`,
+    `subworkflows` fan-out with `$subworkflows` completion gates and parent
+    `context` handoff); transitions own exit/arrival (always-filtered,
+    first-truthy wins, carry ops + effects); terminal stages are structural
+    (no transitions).
+  - **One gate mechanism.** Conditions are GROQ over the rendered scope
+    (`$self`, `$state`, `$actor`, `$assigned`, `$can`, `$effects`, `$tasks`,
+    `$subworkflows`, `$now`, …) with author predicates pre-bound as boolean
+    params. Everything engine-side is advisory; hard enforcement is the lake
+    ACL plus guards (`temp.system.guard` docs with `metadata` projections and
+    name-derived ids).
+  - **Effects registry.** Effects are `{name, bindings, input}` with
+    GROQ-string bindings over the rendered scope; completed-effect `outputs`
+    land in `effectsContext` namespaced under the effect's name and read as
+    `$effects['<effect name>'].<output>`.
+
+  The test bench mirrors the new surface (`task` instead of `taskId`,
+  name-keyed reads, `effectsContextMap` returning the rendered `$effects`
+  map).
+
+- 6c4e0a0: Add `guardsForDefinition` — find every guard a workflow deployed without needing a live instance. Guard docs are stamped with the version-less workflowId, so it spans the datasources statically named across all deployed versions: the workflow resource, plus any resource a guard idRef names statically (a hardcoded GDR literal, directly or via a `stateRead` of a slot whose source is a literal GDR). Guards whose resource is only known per-instance (a `subject`/`init`-sourced slot) are not reachable this way — `guardsForInstance` covers those. Exposed on the engine (`engine.guardsForDefinition({workflowId})`) and the bench (`bench.guardsForDefinition(workflowId)`), reusing the existing `GUARD_DOC_TYPE` + provenance fields.
+
+### Patch Changes
+
+- 12e23b0: New shared primitives so consumers and tests build the engine's shapes exactly the way the engine does:
+  - `datasetResourceParts(id)` — the one parser for `<projectId>.<dataset>` resource ids (`gdrFromResource` and the React adapters' routing both delegate to it; malformed ids now fail on empty parts too).
+  - `subscriptionDocument(ref)` — build one `SubscriptionDocument` from a `GlobalDocumentReference`, the same construction `subscriptionDocumentsForInstance` uses.
+  - `MutationGuardDeniedError.fromGuards({documentId, action, guards})` — the one mapping from denying guard docs to the structured `denied` payload, used by the engine's pre-flight and the test bench's write seam.
+
+- Updated dependencies [4b5f59a]
+- Updated dependencies [fcf938a]
+- Updated dependencies [6c4e0a0]
+- Updated dependencies [12e23b0]
+- Updated dependencies [12e23b0]
+  - @sanity/workflow-engine@0.4.0
+
+## 0.2.1
+
+### Patch Changes
+
+- 0c6ccde: Compose the engine's shared `WORKFLOW_INSTANCE_TYPE` constant and `tagScopeFilter()` predicate in the test bench's read helpers (`instancesForSubject`, `instancesByStage`) instead of hand-writing the `"workflow.instance"` type literal and the `count(tags[@ in $engineTags]) > 0` tag-scope predicate.
+- Updated dependencies [41ddd80]
+- Updated dependencies [0c6ccde]
+  - @sanity/workflow-engine@0.3.0
+
+## 0.2.0
+
+### Minor Changes
+
+- 2b800a8: Enforce lake mutation guards at the client write seam. The bench-minted `TestClient` is now wired with `@sanity-labs/client-fake-for-test@^0.4.0`'s `mutationGuard` hook, backed by the engine's `denyingGuards` — so **every** write through the bench client is gated against deployed guards (incl. the engine's own content writes), exactly where the real lake enforces, not just in `bench.editDocument`. `editDocument` now writes through the client; its `{as}` actor routes through a token-scoped `withConfig({ accessControl })` sibling so `identity()` resolves correctly. Guard evaluation stays in `@sanity/workflow-engine` (one code path); the client only provides the seam.
+- ce6960d: Guard provenance + housekeeping queries.
+  - Mutation guard docs now carry explicit `sourceInstanceId` / `sourceDefinitionId` / `sourceStageId` provenance fields, so the engine can find its guards for coherency refresh and housekeeping without parsing them out of `_id`.
+  - New `engine.guardsForInstance({instanceId})` returns every guard an instance registered, unioned across the resource the instance lives in and the resource of each `doc.ref`/`doc.refs` GDR it holds in state (same "if it's in the workflow, we pull it in" scope as snapshot hydration).
+  - New exported `guardsForInstance` / `guardsForResource` helpers and a centralized `GUARD_DOC_TYPE` constant (single rename point for the eventual `temp.` prefix drop).
+  - The bench exposes `guardsForInstance`; its `listGuards` now delegates to `guardsForResource`.
+
+- 0432670: Injectable clock for deterministic time. The engine now threads a single
+  `Clock` (`() => string`, default wall-clock) through each verb-driven
+  operation, taking one reading per operation so `$now` in filters, the `now`
+  op-source, and the timestamps the engine stamps (history `at`, `completedAt`,
+  `enteredAt`, `lastChangedAt`, queued/ran effect stamps, query-slot `resolvedAt`)
+  all share one instant. Production passes nothing and is unchanged. The clock is
+  injected ONCE — via `createEngine({ clock })`, or the test bench's `setNow` /
+  `advance` — not as a per-verb option; the raw `workflow.*` verbs accept it only
+  through an internal seam, keeping the public `*Args` interfaces free of it. The
+  external effect drainer (`drainEffects`) is out of scope and still uses
+  wall-clock. The pure
+  core (`buildParams`, `resolveSource`) now takes `now` as a value rather than
+  reading wall-clock itself, restoring `core/`'s "no `new Date()`" contract.
+  `Clock` and `wallClock` are exported from the package root.
+
+  The bench (`@sanity/workflow-engine-test`) exposes the knob: `bench.setNow(iso)`
+  freezes time, `bench.advance(ms)` moves it forward, `bench.now()` reads it, and
+  `createBench({ now })` starts frozen. The clock is threaded into every wrapped
+  verb, so a time-based `completeWhen` / `failWhen` / SLA predicate fires by
+  advancing the clock and ticking — without mutating the subject document.
+
+  Also removes the never-implemented `dueAt` hint field from `TaskEntry`: nothing
+  ever wrote or read it, so it carried no behaviour. Re-add it with a real
+  implementation if a cron-indexing fast-path is built later.
+
+### Patch Changes
+
+- a4f6d81: Bump `@sanity-labs/client-fake-for-test` to 0.5.0 for its new
+  `simulateConcurrentEdit` helper, which the bench surfaces (via `bench.client`)
+  to drive optimistic-locking races deterministically — used by the concurrent
+  `fireAction` coverage.
+- 95d7a31: Add a GROQ parity gate that pins the bench's `groq-js` evaluation against a real
+  Content Lake. A shared corpus of representative query shapes — filters, nested
+  array traversal, aggregations, computed projections, `in`-sets, reference
+  matches, and dereferences — runs in CI in-memory (`groq-parity.test.ts`), and an
+  on-demand `test:parity:live` script replays the identical cases against a live
+  dataset to catch evaluator drift. The live gate is excluded from the default
+  `vitest run` and skips itself without `SANITY_*` creds.
+- Updated dependencies [d04cbea]
+- Updated dependencies [870188e]
+- Updated dependencies [a4f6d81]
+- Updated dependencies [eff2a77]
+- Updated dependencies [ce6960d]
+- Updated dependencies [dff88ff]
+- Updated dependencies [782272a]
+- Updated dependencies [2b800a8]
+- Updated dependencies [0432670]
+- Updated dependencies [53a0598]
+- Updated dependencies [c2ad7a9]
+  - @sanity/workflow-engine@0.2.0
+
+## 0.1.0
+
+### Minor Changes
+
+- 43d6b81: Initial release.
+  - **`@sanity/workflow-engine`** — a workflow / BPM engine for Sanity content. Define workflows as data (stages, tasks, actions, guards, effects), run them as instances against a Sanity client, gate transitions on GROQ predicates, and queue side effects for runtimes to drain. Multi-tenant via engine-scope tags; ships a typed authoring surface under `@sanity/workflow-engine/define`.
+  - **`@sanity/workflow-engine-test`** — an in-memory `createBench` harness for exercising workflows against the engine without a live Sanity client (deploy definitions, start instances, fire actions, assert state).
+
+### Patch Changes
+
+- Updated dependencies [43d6b81]
+- Updated dependencies [127be08]
+- Updated dependencies [bf62213]
+  - @sanity/workflow-engine@0.1.0

package/README.md

@@ -13,6 +13,57 @@ boilerplate.
 npm install -D @sanity/workflow-engine-test
 ```
 
+## The bench
+
+`createBench()` builds an isolated bench: the real engine, a fake in-memory
+Sanity client, an all-access default actor, and a bench-owned clock. Every
+wrapped verb injects the bench's client, tag, workflow resource, access
+default, and clock, so a test reads as the workflow it exercises:
+
+- **Runtime verbs** — `deployDefinitions`, `startInstance`, `fireAction`,
+  `editField`, `completeEffect` (and `completePendingEffect`, addressed by
+  effect name), `tick`, `evaluate`.
+- **Instance-admin overrides** — `setStage`, `abortInstance`. Same injection,
+  so a forced move into a deadline-gated stage evaluates `$now` at bench time,
+  not wall-clock.
+- **Reads and probes** — `getInstance`, `currentStage`, `activityStatus`,
+  `pendingEffects`, `children`, `instancesForSubject`, `instancesByStage`,
+  `instancesForDocument`, `query`, plus the guard helpers below.
+
+```ts
+const bench = createBench({now: '2026-01-01T00:00:00Z'})
+await bench.deployDefinitions({definitions: [reviewWorkflow]})
+
+const {instance} = await bench.startInstance({
+  definition: 'review-workflow',
+  initialFields: [subjectField('article-1')],
+})
+await bench.fireAction({instanceId: instance._id, activity: 'review', action: 'approve'})
+expect(await bench.currentStage(instance._id)).toBe('approved')
+
+// Admin overrides ride the same defaults:
+await bench.abortInstance({instanceId: instance._id, reason: 'hard stop'})
+```
+
+`subjectField(docId)` and `releaseField(name)` build the runtime
+initial-field entries for the bench's default resource, so tests never
+hand-roll GDR URI strings. For denial paths, pass a restrictive
+`currentUser` / `grants` (or a full `access`) at construction, or override
+per call with the `actor` shortcut / an explicit `access`.
+
+**Time is bench-owned.** `createBench({now})` starts frozen; `setNow` /
+`advance` move it. Every wrapped verb evaluates `$now` and stamps history at
+bench time, so deadline predicates are tested by advancing the clock and
+ticking — never by waiting.
+
+## Out-of-band engines
+
+Some tests need an engine of their own — custom effect handlers, racing two
+drainers, a `deleteDefinition` call. `createBenchEngine(bench, overrides?)`
+builds one on the bench's client, inheriting its tag, workflow resource, and
+clock (`overrides` win). The bench exposes `tag` and `workflowResource` for
+raw `workflow.*` calls, and the default tag ships as the `BENCH_TAG` constant.
+
 ## Mutation guards
 
 A workflow stage can deploy **mutation guards** — `temp.system.guard` documents
@@ -26,10 +77,10 @@ once the lake enforces them. There are two distinct things you test, and the
 bench gives you a helper for each:
 
 - **Write-time rejection (simulated)** — `bench.editDocument({documentId, patch})`
-  writes through the bench client, and a write a deployed guard denies throws
-  `MutationGuardDeniedError` — the rejection the lake is designed to apply to
-  _any_ client once guard enforcement ships; the bench reproduces it on the
-  client it mints.
+  writes through the bench client (`patch` is a `{set?, unset?, insert?}` spec),
+  and a write a deployed guard denies throws `MutationGuardDeniedError` — the
+  rejection the lake is designed to apply to _any_ client once guard
+  enforcement ships; the bench reproduces it on the client it mints.
 - **Read-time preflight** — `bench.activeGuardsForDocument(id)` answers "_would_
   a write be denied right now?" _without_ writing. This is the check a UI uses
   to disable a button or show a lock ahead of time. It's a pure read over the
@@ -46,9 +97,9 @@ const bench = createBench({documents: [{_id: 'doc-1', _type: 'article', body: 'b
 const active = await bench.activeGuardsForDocument('doc-1')
 
 // Rejection: a guard-violating write throws (bench-simulated lake contract).
-await expect(bench.editDocument({documentId: 'doc-1', patch: {body: 'edited'}})).rejects.toThrow(
-  MutationGuardDeniedError,
-)
+await expect(
+  bench.editDocument({documentId: 'doc-1', patch: {set: {body: 'edited'}}}),
+).rejects.toThrow(MutationGuardDeniedError)
 ```
 
 > To share one store across benches with the write seam intact, pass another