@sanity/workflow-engine 0.17.0 → 0.18.0

package/CHANGELOG.md

@@ -1,5 +1,49 @@
 # @sanity/workflow-engine
 
+## 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,103 @@ 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.
+
 ## 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)