@sanity/workflow-engine 0.17.0 → 0.19.0

package/CHANGELOG.md

@@ -1,5 +1,58 @@
 # @sanity/workflow-engine
 
+## 0.19.0
+
+### Minor Changes
+
+- 24b11dd: Effect handlers can report intermediate field state mid-dispatch. The handler context gains `ctx.commitOps({ops, idempotencyKey})` — field ops only, validated like completion ops, executed through the new `workflow.commitEffectOps` verb as a standard engine commit (gate, history, idempotency ledger, compare-and-swap persist, guard refresh, cascade) — and `ctx.setProgress(field, value)`, sugar that coalesces pending absolute sets per field. Calls enqueue synchronously into a bounded per-dispatch queue (depth 32, 200 commits per dispatch) that serializes commits in call order; overflow throws synchronously at the call site, and settlement drains the queue before completion so an un-awaited failed report still fails the effect. Pending-effect claims now carry a `claimToken` minted on every claim and takeover: a report from an expired, released, or superseded dispatch is rejected before writing (`StaleEffectClaimError`), and a successful report renews the claim's lease. Completion semantics are unchanged and remain claim-blind first-writer-wins. Each report emits the sampled `Editorial Workflows Effect State Reported` telemetry event (adoption signal, max one per minute). Persisted-model note: the claim token rides persisted model 3 additively (see `DATAMODEL.md`).
+- 2005ab7: Action evaluations carry a `firing` consequence (`FiringConsequence` `{exitsStage, transition?}`): what firing the action would do to the flow right now, computed by replaying the fire in memory through the same machinery a real commit runs — ops, the triggered fixpoint, then transition selection — against the projection's state. The answer is total for the current state and conditional on the commit landing; it is omitted where the replay can't be faithful (caller params, a spawn's dataset-driven fan-out in the hop, a terminal instance, a stage visit whose entries have diverged from the pinned definition) and on cascade-fired actions. Advisory, like every derived verdict. Wrong-shape `field.updateWhere` aborts (a merge resolving to a non-object; a resolved merge carrying reserved row keys) now throw the typed `FieldValueShapeError` on the commit path, joining the other wrong-shape write aborts.
+- 24b11dd: Add the `progress` field kind: an elevated `number` carrying application-defined 0–100 completion, so Studio and SDK surfaces can identify and elevate it without guessing which number field means "how far along". Every non-null value must be finite and within 0–100 inclusive (fractions allowed), enforced by one value schema at every write boundary — declaration seeds, start values, edits, ops, nested sub-fields, and effect outputs. Choice lists are rejected on the kind at authoring time. Mints persisted model 3 additively (see `DATAMODEL.md`).
+- 59b40fd: **BREAKING:** a deployment's `name` is now its identity in `defineWorkflowConfig`: enforced unique across the config and constrained to the same grammar as `tag` (lowercase letters, digits, dashes — free text like "My cool workflow" is rejected). Tags may now repeat across deployments; the enforced storage invariant is instead the `(workflowResource, tag)` pair — two deployments sharing both are rejected with each entry named, since they would write into the same partition and fight over definition versions.
+
+## 0.18.0
+
+### Minor Changes
+
+- 3af2ca0: Derive each persisted definition and instance reader floor from the model features it actually contains. Export the append-only data-model change manifest and feature diagnostics so compatible model-2 documents remain readable by older engines while typed choice lists still fail closed.
+- 7276702: Insight phrases resolve effect titles and drop the "settled" jargon. `$effectStatus` requirement phrases and autonomy effect waits now render the effect's declared `title` — an untitled effect keeps its registry name as-is — and the requirement verbs are plain outcomes: "must have succeeded" / "must have failed" / "must have finished". The `requirement.effect-*` and `autonomy-wait.effect` phrase params carry both `effect` (the registry name) and the resolved `title`, so consumers restyling by phrase id needn't re-derive either.
+- 58f8211: Export `expandResourceAliases`, `refsOf`, and the `LogicalRef` type from the package root. Deploy-adjacent tooling can now run the alias expansion as an eager validation (fail-closed on unbound `@<handle>:` references before any write) and walk a definition's spawn references without re-implementing the walk.
+- 00c089d: **BREAKING:** Require every definition deployment and workflow deployment configuration to state an `expectedMinReaderModel` literal that exactly matches the installed engine's writer capability.
+
+  Deploy and definition-diff paths now reject missing or stale acknowledgements before client access or telemetry, with a structured error and readers-first rollout guidance.
+
+- cd03973: **BREAKING:** Reject initial workflow field values that cannot be consumed and expose structured preflight issues.
+
+  Calls that supplied unknown, wrong-kind, non-input, non-workflow-scope, or duplicate initial field rows previously succeeded while discarding those rows. They now fail before creating an instance with structured remediation details.
+
+  Deploy also rejects `spawn.with` keys that the resolved child definition cannot consume because the workflow field is missing or is not input-sourced. `SpawnContractsInvalidError` exposes every rejected parent/child row for machine-readable remediation.
+
+- d26cc1a: Add the engine-owned Actor resolution contract with client-backed resolution for server, CLI, and MCP runtimes; add native Studio and App SDK project-user integrations; and migrate the Studio plugin member picker to the shared directory.
+- 9126299: **BREAKING:** Delete persisted stage guard documents when their stage exits, and remove the lifted-record `GUARD_LIFTED_PREDICATE` and `isGuardLifted` exports.
+
+  Guard deletion now uses the observed document revision so stale exit reconciliation cannot delete a guard reactivated by a newer stage visit. Reactive guard streams contain only active persisted guards.
+
+- 72018af: Add an extensible action semantics array with decision.accept and decision.decline as the initial engine-owned vocabulary.
+- 5cd8ffd: **BREAKING:** Effect handlers now receive each host's concrete Sanity client unchanged, preserving its complete runtime and type surface. Handler traffic is no longer automatically tagged as `workflow.effect` or pinned to the engine API version; handlers own that configuration.
+- b82bda4: **BREAKING:** `startInstance` rejects any `initialFields` row that would not land on an input-sourced declared entry — an undeclared name, a kind mismatch, or an entry that seeds itself (query/literal/fieldRead/working memory) — with `InitialFieldsInvalidError`. Previously such rows were silently ignored and the instance started without the caller's value.
+- 55a54b3: **BREAKING:** the subject is now a first-class field kind, and the subject-entry rule keys on it.
+
+  New `subject` field kind: an elevated single `doc.ref` (same GDR value, validation, and `types` facet) that names THE document a workflow is about. Deploy enforces its placement — workflow scope only, at most one per workflow, never a nested sub-field. A subject entry dereferences in conditions, joins the reactive watch-set, routes spawn discovery, and canonicalises query/spawn refs exactly like a `doc.ref`. The persisted data model grows the value additively (`DATA_MODEL_VERSION` is now 2). The subject kind itself does not raise the reader floor — model 2's floor of 2 comes from the typed-choice-list change shipping alongside; see `DATAMODEL.md`.
+
+  The breaking half: `isSubjectEntry`, applicability (`acceptsDocumentType` / `definitionsForDocument` / document pickers), the autonomous-start deploy invariant, and the root-reading `start.filter` check now identify the subject by the `subject` kind — a required `doc.ref` / `doc.refs` input no longer counts. A deployed definition using that convention still parses and runs, but stops surfacing from document pickers (and stops satisfying the autonomous/root-read invariants on redeploy) until it declares a `subject` entry.
+
+  New exports: `isSingleDocRefKind` (single-GDR kinds — `doc.ref` and `subject`), `isSingleDocRefEntry` (its resolved-entry narrowing), and `refKindAcceptsTypes` (the kinds carrying the accepted-target `types` facet).
+
+- b82bda4: Add the opt-in `$subjectHasInFlightInstance` start variable for composing subject-exclusive visibility and permission rules.
+- 4490442: Add inclusive validation.min/max bounds for workflow string, text, and number declarations, with Studio input constraints and MCP authoring guidance.
+- 1540dce: **BREAKING:** Definitions and instances written by this release require a model-2 engine reader; upgrade every reader before deploying its writers.
+
+  Workflow fields, nested field shapes, effect outputs, and action parameters can declare typed scalar choices with `options.list`. The engine validates authored lists and rejects runtime values outside them, Studio renders one shared select control and displays each selected choice by its title, and the MCP authoring guide explains the syntax.
+
+### Patch Changes
+
+- 239d9f6: Fix action operation values to follow the intended lexical lookup order by reading fields on their current activity before the stage and workflow, including writes made earlier in the same transaction.
+- 71cd58e: Explain that effect-completion field operations require an explicit workflow or stage target scope when validation rejects a missing scope, and document the requirement on `EffectHandler`.
+
 ## 0.17.0
 
 ### Minor 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; predicate lift on retract                                |
+| `temp.system.guard`          | `compileGuard` (`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
@@ -51,7 +51,8 @@ of the documents the engine itself writes.
 ## The stamp pair
 
 The two doc types whose format the engine owns outright — definition and
-instance — carry two numbers (`MODEL_STAMP` in `src/core/model-version.ts`).
+instance — carry two numbers (built together by `modelStampFor` in
+`src/core/model-version.ts`).
 Provenance and compatibility are deliberately separate, because consumers
 sharing a dataset upgrade months apart (Functions lag Studios lag CLIs) and
 "newer" must not mean "incompatible".
@@ -69,13 +70,12 @@ never matches the new type).
   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.
-- **`minReaderModel` — the reader floor.** The value of
-  `DATA_MODEL_MIN_READER` at write time: the oldest engine model that can
-  safely _interpret_ this document. An **additive** change leaves the floor
-  untouched — older engines keep reading and writing newer docs, so
-  mixed-version fleets interoperate. Only a **breaking** change raises it,
-  and raising it is a declared decision to fence out older readers (fleet
-  must upgrade readers before such writers deploy).
+- **`minReaderModel` — the document's reader floor.** The oldest engine model
+  that can safely _interpret this particular document_. Writers derive it
+  from compatibility-bearing features present in the canonical stored tree.
+  `DATA_MODEL_MIN_READER` is the maximum floor the current writer can emit,
+  not a value stamped on every document. Additive features contribute floor
+  0; only an incompatible feature fences older readers out of that document.
 - **Missing stamp = model 0** (floor 0) — the document was last written
   before the stamp existed. A `modelVersion` with no `minReaderModel` is
   malformed foreign data and gates conservatively: the stamp is the floor.
@@ -133,10 +133,9 @@ never matches the new type).
   round-trip**. That is a load-bearing invariant: an additive change whose
   fields would NOT survive an old writer's round-trip is not additive — it
   is breaking, and must raise the floor.
-- **The floor is raise-only.** A rewrite writes
-  `max(stored minReaderModel, own DATA_MODEL_MIN_READER)` — it never lowers
-  or drops the stored floor, because the preserved unknown fields of a newer
-  model may still require it. (The failure mode this fences off is
+- **The floor is raise-only.** A rewrite writes `max(stored minReaderModel, floor derived from the complete post-state)` — it never lowers or drops the
+  stored floor, because preserved unknown fields or a historical semantic
+  requirement may still require it. (The failure mode this fences off is
   documented across the industry: a rewriter that drops the compatibility
   gate it doesn't understand silently reopens the door the floor closed.)
 - **Raising the floor is an availability decision, sequenced readers-first.**
@@ -155,6 +154,22 @@ never matches the new type).
 
 ## Rules for changing the model
 
+`DATA_MODEL_CHANGES` is the append-only, machine-readable counterpart of the
+model log. Every independently reasoned persisted-model feature records a
+stable id, introduction model, affected document types, compatibility class,
+reader floor, and summary. The manifest drives writer-side floor derivation
+and diagnostics; this prose log remains authoritative for the reasoning,
+absent-value behavior, and old-writer round-trip proof.
+
+Feature applicability is explicit. A **detectable** feature contributes its
+floor only when its stable marker is present in the canonical stored tree. An
+**unconditional semantic requirement** applies to every newly written document
+of its declared type when no reliable marker exists. Readers trust the
+persisted floor; they do not recompute features they may be too old to know.
+Every reader-floor increase is represented as a manifest feature and classified
+this way; raising the package maximum never by itself raises every document's
+floor.
+
 1. **Any change to a persisted field tree is a model change** and must be
    declared: update the model-surface snapshot, add an entry to the model
    log below, and decide — in the same change — whether `DATA_MODEL_VERSION`
@@ -181,6 +196,18 @@ never matches the new type).
    just fail to parse?) is exactly what decides whether
    `DATA_MODEL_MIN_READER` moves, and no snapshot can make it — each model
    log entry states it explicitly.
+6. **Manifest and prose move together.** Every structural model change adds a
+   manifest entry and matching model-log declaration. The ledger snapshots
+   the stored grammar and manifest. A semantic-only implementation change may
+   have no observable schema delta; review must still classify and log any
+   change to how persisted values are interpreted.
+7. **The PR compatibility callout is mandatory and explicit.** Near the top of
+   the PR body, state the writer's `modelVersion`, name every feature introduced
+   or changed by the PR that contributes a `minReaderModel`, and state the floor
+   for documents where those features are absent. Say plainly whether model-0
+   readers still work for those documents. Give the rollout order and scope:
+   readers-first before any writer can persist a floor-bearing feature, not a
+   misleading fleet-wide minimum when floor derivation is document-specific.
 
 ## Model log
 
@@ -202,6 +229,9 @@ rules, not folklore:
 
 ### Model 1 — stamping introduced; actions-only payload model (reader floor: 0)
 
+Manifest feature: `governed-model-stamps` (definition + instance, additive,
+floor 0).
+
 The `modelVersion` + `minReaderModel` pair is stamped on the definition and
 instance doc types; the guard doc deliberately carries none (foreign lake
 contract — see "The stamp pair"). The floor is 0: model-0 documents keep
@@ -318,6 +348,156 @@ its shape. Redeploying one fails validation until the expression moves to
 The released-engine caveat above covers this amendment identically: those
 datasets are this-repo test data and are reset, not migrated.
 
+### Model 2 — subject fields, scalar constraints, and action semantics (reader floor: 2)
+
+Four additive growths — a new field kind and three optional facets — ship
+together as model 2.
+
+**The `subject` field kind.** An elevated single `doc.ref` (same GDR value
+shape and validation, the `types` facet included) that names THE document a
+workflow is about — workflow scope only, at most one, both deploy-enforced.
+Both stamped trees grow the value:
+
+- **Definition tree** — `fields[].type` admits `'subject'`, and a `subject`
+  entry may carry `types` like `doc.ref` / `doc.refs`.
+- **Instance tree** — resolved `fields[]` entries admit `_type: 'subject'`
+  (the same arm shape as `doc.ref`, optional `types` included).
+
+Manifest feature: `subject-field-kind` (definition + instance, additive,
+detectable, floor 0).
+
+Would an old reader misread the kind (rule 5)? No — it refuses loudly, never
+silently: the definition document has no read-side content parse, and a
+model-1 engine that loaded a subject-carrying **instance** would fail the
+shape gate (the strict `fields[]` variant rejects the unknown discriminator
+with `PersistedDocShapeError`) before interpreting anything — under the
+document-specific floor derived below only fences it when another floor-bearing
+feature (a choice list or scalar bounds) is also present. The subject kind
+itself leaves the floor at 0.
+
+One evaluation-semantics reconciliation rides the same change, declared
+here under rule 5's judgment: the subject-entry rule (applicability's type
+matching, the autonomous-start invariant, the root-read deploy check) now
+keys on the `subject` kind, where it previously classified any required
+`doc.ref` / `doc.refs` input as the subject. A stored pre-subject
+definition still parses and runs everywhere, but no longer surfaces in
+document pickers until redeployed with a `subject` entry — a deliberate
+refuse-to-guess, not a misread.
+
+**Typed scalar choice lists.** Definition value declarations and resolved
+instance field entries gained an optional `options.list[]` tree. Each item
+carries a display `title` and a typed scalar `value`; an absent `options`
+retains the unconstrained behavior of every model-0/model-1 declaration and
+instance entry.
+
+Manifest feature: `typed-scalar-choice-lists` (definition + instance,
+reader-floor, detectable, floor 2).
+
+The field tree grows additively, and an absent `options` keeps every older
+document's meaning unchanged. A document carrying `options.list` nevertheless
+requires reader floor 2: an older engine would interpret the declaration as
+unconstrained and could commit a value outside the list. That is semantic
+misinterpretation, not a presentation downgrade. Writers of model 2 must
+therefore deploy only after every engine reader has upgraded to model 2; the
+floor makes an older reader fail explicitly instead of silently bypassing
+the declaration. A model-2 definition or instance without a choice list retains
+the floor derived from its other features (often 0). Resolved entries carry the
+same optional tree so field writes remain self-validating. Full persists derive
+from the complete post-state and preserve any higher stored floor.
+
+**Action semantics.** Ordinary stored definition actions gained an optional
+`semantics[]` bag whose initial closed vocabulary is `decision.accept` and
+`decision.decline`. The values express advisory workflow meaning shared by
+consumers; they change no execution, gate, transition, status, history, or
+instance state. An absent `semantics` retains the generic behavior of every
+older definition.
+
+Manifest feature: `action-semantics` (definition, additive, detectable, floor
+0).
+
+Would an old reader misread (rule 5)? No. Definition content has no strict
+read-side parse, and an engine predating the facet ignores the unknown optional
+key, treating the action as generic. That loses advisory information but does
+not change workflow execution. Definition documents are immutable after create,
+so an old writer never rewrites and drops the array. The feature therefore
+leaves the reader floor unchanged.
+
+**Inclusive scalar bounds.** Workflow value declarations gained an optional
+`validation` tree with finite `min` / `max` bounds. On `string` and `text`
+declarations the bounds constrain character length and must be non-negative
+integers; on `number` declarations they constrain the numeric value.
+
+The same tree is available on action params, top-level fields, and nested field
+shapes. Resolved instance field entries carry it so every later field write
+validates against the declaration that created the instance. Definitions and
+instances that omit `validation` retain their unconstrained behavior.
+
+Manifest feature: `inclusive-scalar-bounds` (definition + instance,
+reader-floor, detectable, floor 2).
+
+The shape growth is additive, but a document carrying `validation` requires
+reader floor 2. An older engine would preserve the unknown tree while
+interpreting the value as unconstrained, and could therefore commit an
+out-of-range value. That is semantic misinterpretation under rule 5, so older
+readers must fail at the model gate. A model-2 definition or instance without
+scalar bounds retains the floor derived from its other features (often 0).
+Spread-based mutation copies preserve `validation` across every full persist;
+the derived floor prevents older writers from reaching constrained model-2
+instances.
+
+### Model 3 — the `progress` field kind + effect claim tokens (reader floor: 2)
+
+Two additive growths ship together as model 3 — model 2 was released (npm
+`@sanity/workflow-engine@0.18.0`) before either landed, so they mint the next
+version rather than amending a shipped one. Neither raises the reader floor;
+the writer maximum stays 2.
+
+**The `progress` field kind.** An elevated `number` (same stored numeric
+value) carrying application-defined 0–100 completion, so surfaces can
+identify and elevate it without guessing which number field means "how far
+along". Every non-null value is finite and within 0–100 inclusive (fractions
+allowed), enforced at every write boundary by the kind's one value schema.
+Model 2's `validation` tree composes with it as NARROWING only: each declared
+bound must itself sit within 0–100, gated at authoring. Both stamped trees
+grow the value:
+
+- **Definition tree** — `fields[].type` (and nested `FieldShape.type`)
+  admits `'progress'`.
+- **Instance tree** — resolved `fields[]` entries admit `_type: 'progress'`
+  (the same arm shape as `number`).
+
+Manifest feature: `progress-field-kind` (definition + instance, additive,
+detectable, floor 0).
+
+Would an old reader misread the kind (rule 5)? No — the same loud refusal as
+the `subject` kind: an older engine (model 2 and below) that loaded a
+progress-carrying instance fails the strict `fields[]` variant with
+`PersistedDocShapeError` before interpreting anything, and cannot deploy or
+evaluate a progress-declaring definition. No older code path can write a
+progress field while skipping its bound, so there is no silent bypass to
+fence — the kind leaves the floor at 0.
+
+**Effect claim tokens.** `pendingEffects[].claim` grows an optional
+`claimToken` — an opaque identifier minted fresh on every claim and
+takeover. It is the exact-claim identity a mid-dispatch state report
+(`commitEffectOps`) must present: `effectKey` cannot serve because a lease
+takeover keeps the same key. A successful report also renews the claim's
+`leaseExpiresAt` in the same commit.
+
+Manifest feature: `effect-claim-tokens` (instance, additive, detectable,
+floor 0).
+
+Tolerant read: an older engine's claim parse admits unknown keys, so the
+token rides through untouched and means nothing to it — older claim
+semantics (presence + lease) are unchanged. Round-trip survival: full
+persists derive from the complete loaded post-state, so an older writer
+carries the token along; the claim-REPLACING writes (takeover, sweep
+release, completion drain) discard it deliberately, which is the token's
+own lifecycle — a report presenting a discarded token is rejected before
+writing, failing closed. A claim without a token (older writer's takeover)
+simply cannot authorise mid-dispatch reports; dispatch and completion are
+unaffected.
+
 ## Pending governed changes
 
 - **`temp.system.guard` → `system.guard`** — the guard doc type's `temp.`

package/README.md

@@ -43,6 +43,29 @@ different at each — read it by where it sits:
 4. **Resolved runtime values** — `fields` on a workflow instance document: the
    declared entries with their current values, written by ops and edits.
 
+## Resolving actors to current project users
+
+An `Actor` stores durable provenance, not mutable profile data. CLI, MCP, and
+server consumers resolve through the client already bound to their engine:
+
+```ts
+const result = await engine.resolveActor({actor: effect.actor, projectId})
+
+if (result.status === 'resolved') {
+  await notify(result.user)
+}
+```
+
+The package also exports `resolveClientActor(client, {actor, projectId})` for
+code that has a plain `WorkflowClient` but no constructed engine. UI adapters
+implement `ProjectUserDirectory<User>` with their native user type and pass it
+to `resolveActor(directory, actor)`.
+
+The result distinguishes `resolved`, `missing`, `inaccessible`, and
+`not-person`. Agent and system actor IDs are never sent to a project-user API.
+An integration may also provide centralized `findByEmail`; consumers should
+not page and scan a project directory independently.
+
 ## License
 
 [MIT](./LICENSE)