@sanity/workflow-engine 0.16.0 → 0.18.0

package/CHANGELOG.md

@@ -1,5 +1,92 @@
 # @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
+
+- f9389e5: **BREAKING:** the evaluation nodes gain a required causal-autonomy slot — `WorkflowEvaluation.autonomy` (`WorkflowAutonomy`), `StageEvaluation.autonomy` (`StageAutonomy`), `ActivityEvaluation.autonomy` (`AutonomyAnswer`). Code that constructs evaluation shapes by hand (test fixtures, adapters) must now supply them; reading consumers are unaffected.
+
+  Causal autonomy analysis: `deriveWorkflowAutonomy(definition, {children?})` answers "will this activity complete without a caller, and if not, what is it waiting on?" by static dataflow over the stored definition, instance-free. Each gate's reads are classified by their producers — writer actions (caller- vs cascade-fired, followed transitively), `input` seeds, the edit seam, effect completions (autonomous given the host's drain), spawned children (recursed when a `children` map resolves them), lake content reads, `$now` — and rolled up per activity, stage, and workflow as `completesWithoutCaller: 'yes' | 'no' | 'conditional'` plus structured `waitsOn` entries. A cascade-fired action's `roles` execute pin counts as a dependency: the runtime holds a pinned trigger armed until a capable token cascades, so a pinned automation reports `conditional` with an `execute-pin` wait naming the roles. This is the causal refinement of the mechanical `ExecutorClassification`: an all-`when` activity whose triggers only read caller-written fields classifies `autonomous` but answers `no` here, naming the caller action it waits on (role pin recovered from the desugared membership filter). Advisory like every insight — a narratable answer, never a gate.
+
+  Narration joins the insight render surface: `describeAutonomyWait(wait, ctx)` phrases one wait, `narrateAutonomyWaits(waits, ctx)` phrases and de-duplicates a list, `autonomySummary(autonomy, ctx)` gives the workflow-level line ("this workflow runs itself except at …"). `stageAutonomyOf(autonomy, stageName)` / `activityAutonomyOf(stageAutonomy, activityName)` are the total rollup lookups (throw on a miss), and the engine root now also re-exports `atomReadsDataset` alongside the rest of the `@sanity/groq-condition-describe` surface.
+
+- c3eed2e: Export `entryDocRefs` — the canonical `doc.ref`/`doc.refs` GDR extraction over field entries (with its untrusted-lake-data narrowing) — and add `limit` to `InstancesQueryFilter`: a capped read returns the NEWEST rows (`startedAt desc`, sliced), so bounded consumers stop streaming unbounded datasets.
+- 092a0d4: **BREAKING:** runtime-supplied refs written into field state are gated on the deployment's declared resource surface.
+  - A `doc.ref` / `doc.refs` / `release.ref` value a caller or effect handler supplies — start `initialFields` input, an action's param-sourced op values, `editField` values, effect-completion ops — must target a declared resource: the `workflowResource` itself or a resource the `resourceClients` resolver serves. An off-surface ref throws the new `RefResourceUndeclaredError` and the commit aborts, instead of writing cleanly and failing later when something dereferences it. The check is advisory like every engine check; stored documents are unchanged.
+  - Definition-authored refs are exempt: literal `initialValue` seeds, `type: 'query'` texts, spawn `with` projections, and op values that bind no action param were validated (and alias-expanded) at deploy, so they materialize into field state without re-checking.
+  - Resource aliases stay a deploy-time abstraction: `deployDefinitions({definitions, resourceAliases?})` expands every `@<alias>:` reference to its physical GDR before fingerprinting, and nothing alias-shaped survives past deploy — the runtime holds no alias map, and an alias-shaped ref supplied to a runtime verb is rejected as malformed like any other non-GDR string.
+  - `createBench` takes `serveResources` (dataset siblings served — and thereby declared — straight from the bench's own store) plus a raw `resourceClients` resolver for anything beyond same-store siblings. The engine also exports `sameResource` alongside the existing GDR helpers.
+  - The CLI wires no `resourceClients`, so refs supplied at runtime through it (`start --field`, `fire-action` ref params) admit the workflow resource only.
+
+- 5a1a9fe: **BREAKING:** engine reads of persisted documents now parse instead of cast — a malformed `sanity.workflow.instance` or guard document fails the read with a `PersistedDocShapeError` naming the document and the offending fields, where it previously flowed through typed casts and corrupted behavior downstream. Reads that silently tolerated corruption now fail hard: `children` throws on a malformed spawn ref in history (previously skipped the row), and the reactive session rejects malformed self-doc pushes and guard updates with the typed error.
+
+  Runtime valibot schemas are the single source of truth for each persisted doc shape: `WorkflowInstanceSchema` and `MutationGuardDocSchema` (the definition already had one), pinned field-by-field to the hand-written types so drift is a compile error. The parses are tolerant of unknown keys at every level (the data-model round-trip rule) and of unknown future `history[]` variants, and exact on everything the engine interprets. New exports: `parseInstanceDocument`, `parseGuardDocument`, `readInstanceDoc` (model gate + parse composed), `PersistedDocShapeError`, the two schemas, and `schemaTreeShape` (the declared field tree of a schema — what the model-surface ledger now pins for the instance and guard doc types).
+
+- e3a7ba2: **BREAKING:** a supplied `instanceId` is now `startInstance`'s idempotency key. When the id already exists under the engine's tag for the same start, the call RESUMES the outstanding prime/cascade commits — the retry path for a start that failed after its create landed — instead of failing on the `_id` collision. Reusing an id for a different start (definition or explicit version mismatch), or for an unfinished start that was aborted, throws `ContractViolationError`. The mid-sequence failures are typed and carry the retry id: a prime failure after the create committed throws the new `StartNotPrimedError` (a failed but resumable start — the message names the id to retry with), and a first-cascade failure after a successful prime throws the new `StartNotSettledError` (carrying the primed instance when re-readable) — the run exists by then and must not be reported as a failed start; `WorkflowStateDivergedError` still passes through unwrapped. For standalone (`startInstance`) starts the `Editorial Workflows Instance Started` telemetry event fires once the instance is primed (started = created + primed) rather than after the first cascade settles; spawned children keep emitting after they fully settle. New exports: `isUnprimed` (classifies a created-but-unprimed instance — an unfinished, resumable start) and `instanceDocId` (mint an id to hold across start attempts).
+- 30fed9e: **BREAKING:** deploy now rejects a set of authoring shapes that previously deployed clean and failed silently at runtime. Already-deployed definitions keep running — the rejections fire on `defineWorkflow` and (re)deploy only:
+  - A `$row` read at any condition site that doesn't bind it (only a spawn `with` projection and a where-op `where` do) is rejected — a bare `$row` in a transition `when`, activity `filter`, predicate, effect binding, `spawn.forEach`, or `spawn.context` evaluated as GROQ null and could wedge transition selection.
+  - `spawn.forEach` is deploy-checked against the workflow-scope `$fields` window it actually evaluates with — a forEach reading a stage/activity field previously passed deploy and resolved null at spawn time, spawning nothing.
+  - The workflow `name` and every guard `name` must match the lake-id-segment grammar (`^[a-z0-9][a-z0-9-]*$`) — both interpolate into deployed document ids. Previously-deployable uppercase, underscore, and dotted names are now rejected: a dot collides with the id's own `.` separator, and looser spellings failed the whole deploy batch (or, for guards, the stage-entry commit) with an opaque lake 400.
+  - Static `$fields.<name>.<path>` reads inside condition, forEach, and `start.allowed` GROQ are checked against the entry's declared value shape, the reference envelopes included — a `release.ref` read of `._id` (the envelope key is `id`) silently inverted a fan-out match. Reads resolve to the innermost shadowing entry; windows spanning several possible contexts reject a pathed read only when it fits none of the same-named declarations, so a shape valid in any possible context is never a false rejection. In `start.allowed`, references bind as their raw envelopes — a singular `doc.ref` included, since nothing hydrates at the gate or the pre-flight — so content-field reads are rejected there.
+
+  The `content-release` example's spawn `forEach` now matches on the release envelope's `id` key (it read `._id`, which is not an envelope key, so reviews spawned for articles NOT in the release), and the guard `predicate` TSDoc spells out the polarity: strictly-`true` ALLOWS, anything else DENIES.
+
+- 1321ba5: **BREAKING:** `start.filter` splits into visibility + permission. `filter` is now browse-time-pure — candidate document as root, `$tag`/`$definition`/`$now`, dataset scans — and any `$fields` read in it is deploy-rejected (inputs don't exist at browse time; the unbound-`$fields` evaluation let permission-style filters pass vacuously). The new `start.allowed` is the permission predicate — same context vars plus `$fields` (the caller's `initialFields` as GDR envelopes), never a candidate root — and `startInstance` enforces it: declaring the expression is the opt-in, a false or GROQ-null verdict throws the new `StartNotAllowedError` (kind `start-not-allowed`, `ConditionInsight` attached), no override arg. New reads: the `evaluateStart` verb pre-flights the gates (`StartEvaluation`: `allowed`/`outcome`/`insight`/`unboundReads`/`missingRequired`) — bindability-aware: a predicate reading a not-yet-supplied entry reports `'unevaluable'` with the entries named in `unboundReads`, never the collapsed verdict GROQ equality gives on a missing operand (at the gate absence is final, so `startInstance` evaluates it as-is). `explainStartAllowed` + `startFieldsParam` + `unboundAllowedReads` are the underlying primitives. API renames: `StartFilterScope` is now `StartScope` and no longer carries `fields` (the `$fields` map is `explainStartAllowed`'s own argument); `START_ALLOWED_VARS` joins the condition-scope inventory. For definitions already deployed with a `$fields`-reading `filter`, the read is GROQ null on every surface (nothing binds `$fields` there anymore) and the rule is inert — whether the filter then hides the definition (`defined()`-style reads fail closed) or surfaces it vacuously (`count(...) == 0`-style rules match nothing) depends on its shape; redeploy rejects it until the expression moves to `allowed`.
+
+### Patch Changes
+
+- d0c62ea: A store echo buffered during a session commit that fails read validation no longer throws from the commit's settle path — which could replace a successful commit's result (or shadow its real error). The failure is deferred to the next `update` call, the seam consumers already treat as the validation surface, after that call's own docs are processed.
+- df4bd80: Docs: an unbound start-context binding or dangling `$fields` condition read evaluates to GROQ null per read — whether the expression then fails closed or passes vacuously depends on where the null lands, so blanket "fails closed" / "silently never passes" claims are corrected to the per-shape truth across the start-context TSDoc, the deploy-rejection messages (now "silently misevaluates"), and the reference doc. The condition-evaluation module header in `groq-condition-describe` states the same per-read truth ("'unevaluable' only where the null lands as the final result"). A test now pins the genuinely-null-result unevaluable case (an ordered comparison against a missing attribute — total `==` equality can only produce a definite false). No evaluation behavior change.
+- e683875: The evaluation projection derives every condition scope from the same rendered-scope assembly the engine's commit paths use (`renderConditionScope` in the pure core), so projection/commit parity holds by construction. Previously the projection bound workflow-scope `$fields` only, while the cascade merged the open stage's field overlay — a transition trigger routing on a stage-scope field (the idiomatic "route on state an action wrote") routed in the cascade but misreported `whenSatisfied`/`unevaluable` in `evaluate`, and the author's predicates pre-evaluated over the narrower scope. Activity `filter` insights and cascade-fired action gates are now also explained caller-free in their activity context — the scope stage entry actually binds — and `queryInScope` binds that same caller-free scope (the open stage's overlay plus the pre-evaluated `$<predicate>` booleans).
+- a8ace4d: TSDoc: `WorkflowTransaction.delete` now names both of its consumers — engine-side `deleteDefinition` housekeeping, and the CLI's `nuke` reset outside the engine — instead of claiming `deleteDefinition` is the sole one.
+- Updated dependencies [f9389e5]
+- Updated dependencies [df4bd80]
+  - @sanity/groq-condition-describe@0.3.0
+
 ## 0.16.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
@@ -16,14 +16,22 @@ declared; the model-surface gates keep undeclared drift red:
   file per `DATA_MODEL_VERSION`, **append-only**: only the current version's
   file is ever regenerated (`vitest -u` on the gate test), so past model
   shapes stay checked in verbatim — the historical corpus future upgrade
-  machinery tests against. It pins the field trees of every doc
-  type built through the real constructors, plus the stored grammar's
-  vocabulary (every enum's values, every variant discriminator), so a value
-  rename is as red as a key rename.
+  machinery tests against. The instance and guard shapes are **declared**
+  trees, derived from each doc type's runtime schema
+  (`WorkflowInstanceSchema` / `MutationGuardDocSchema` via
+  `schemaTreeShape`) — the schema is the single source of truth for the
+  stored shape, and a declared tree pins optional fields no fixture
+  reaches. The definition document and the persist write-set stay
+  **concrete** trees built through the real constructors (the deploy plan's
+  envelope and the persist field-set are constructor facts). The ledger also
+  pins the stored grammar's vocabulary (every enum's values, every variant
+  discriminator), so a value rename is as red as a key rename.
 - **Coverage tests** (`src/__tests__/model-surface.test.ts`) walk the stored
   definition schema and fail when any declared key, discriminator, or
   instantiable enum value stops appearing in the canonical document — the
-  grammar cannot grow past the fixture silently.
+  grammar cannot grow past the fixture silently. Parse gates keep the
+  schemas and the constructors in lockstep: the canonical constructor-built
+  instance and guard must parse cleanly through their doc schemas.
 - **The lifecycle ledger** (`model-shapes/model-<N>.lifecycle.json` in
   `workflow-engine-test`) drives real instances through the verbs —
   including the recovery paths (expired-lease sweep, loop-back re-entry
@@ -32,13 +40,9 @@ declared; the model-surface gates keep undeclared drift red:
   `SubworkflowEntry` rows, pending effects (claim included), effect
   history, the idempotency ledger, and ALL `HistoryEntry` variants (the
   accounting is compile-checked against the union, so a new variant fails
-  the build until the scenarios produce it).
-
-Residual review responsibility: each ledger entry pins one shape per
-variant (the scenario's first), so an _optional_ key that only appears on
-some entries of an already-covered variant — or a conditionally-written
-field no fixture or scenario reaches — still needs a reviewer to demand a
-ledger-visible sample. Fixture width is part of reviewing a model change.
+  the build until the scenarios produce it). Every verb-driven document
+  must ALSO parse cleanly through the instance schema — a verb writing a
+  tree the read boundary would reject fails here, not in production.
 
 This is **not** definition-content versioning: `version` / `pinnedVersion` /
 `contentHash` track what an author deployed; the model stamp tracks the shape
@@ -47,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".
@@ -65,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.
@@ -79,19 +83,48 @@ never matches the new type).
   every stamp `0..N`. There is no supported-version floor for _old_ docs;
   introducing one is a deliberate future mechanism, never a side effect of
   a shape change.
-- **Fail hard on `minReaderModel` ahead — and only that.** Every engine read
-  of a stamped doc type (definition, instance) passes through
-  `assertReadableModel` — point reads, list queries, the drained-children
-  projection, snapshot hydration's raw reads. A floor ahead of the engine's
-  `DATA_MODEL_VERSION` throws
-  `ModelVersionAheadError` ("upgrade `@sanity/workflow-engine`") instead of
-  silently misreading a shape this engine predates. Deliberately wholesale:
-  one such document in a read's scope fails the whole read (a listing, a
-  verdict computation) rather than degrading silently. Two structural
-  exceptions: existence-only probes (no shape is interpreted), and lake-side
-  GROQ filters, which evaluate persisted fields server-side before any
-  client gate can run — their safety rests entirely on rule 3's
+- **Fail hard on `minReaderModel` ahead.** Every engine read of a stamped
+  doc type (definition, instance) passes through `assertReadableModel` —
+  point reads, list queries, the drained-children projection, snapshot
+  hydration's raw reads. A floor ahead of the engine's `DATA_MODEL_VERSION`
+  throws `ModelVersionAheadError` ("upgrade `@sanity/workflow-engine`")
+  instead of silently misreading a shape this engine predates. Deliberately
+  wholesale: one such document in a read's scope fails the whole read (a
+  listing, a verdict computation) rather than degrading silently. Two
+  structural exceptions: existence-only probes (no shape is interpreted),
+  and lake-side GROQ filters, which evaluate persisted fields server-side
+  before any client gate can run — their safety rests entirely on rule 3's
   additive-only constraint.
+- **Parse, don't cast — the shape gate behind the model gate.** After the
+  floor check, every engine read of an instance document parses it through
+  the runtime schema (`parseInstanceDocument`; `readInstanceDoc` composes
+  gate + parse), and every guard read parses through
+  `parseGuardDocument` — a malformed tree throws `PersistedDocShapeError`
+  naming the document and the offending fields, instead of corrupting
+  behavior downstream. The parse is TOLERANT where governance requires it:
+  unknown keys pass at every level (the round-trip rule), and `history[]`
+  admits unknown future variants (audit rows an engine only appends and
+  filters by known `_type`s). It is EXACT on everything the engine
+  interprets — statuses, discriminators, refs, timestamps — which makes
+  vocabulary growth inside a known persisted shape a **breaking** change
+  under rule 5 (a validating old reader rejects the new value): widen the
+  fleet's readers before any writer emits it, or raise the floor. The
+  definition document deliberately has no read-side content parse: deploys
+  are create-only and the content is strictly parsed at that sole write
+  boundary; a read-side strict parse would wrongly reject additive
+  newer-model definitions.
+- **Consumer surfaces adopt the gate at their own direct reads.** The
+  reactive studio/sdk adapters validate every engine-owned stream at the
+  observer boundary (gate + parse, surfaced as an explicit invalid/
+  model-ahead session state instead of a throw); the CLI's direct reads, and
+  the MCP tools and Studio-plugin reads that interpret rows from the
+  deliberately-ungated `engine.query` escape hatch, apply
+  `assertReadableModel` per document — list projections carry the stamp
+  pair so projected rows gate too. Those surfaces are deliberately
+  gate-only (no shape parse): projections structurally can't shape-parse,
+  and the CLI's full-doc readers are INSPECTION surfaces — an operator must
+  be able to open the very document being investigated, so a corrupt doc
+  renders best-effort there instead of refusing.
 - **Old writers restamp down — the round-trip rule.** An older engine
   persisting a newer-but-compatible instance stamps its own `modelVersion`
   (honest conforms-to; the stamp oscillates in mixed fleets, harmlessly).
@@ -100,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.**
@@ -113,14 +145,31 @@ never matches the new type).
   upgrade consumers before producers). And like every engine-side check the
   floor is advisory — it gates our own clients; the Content Lake stays the
   sole enforcement point.
-- **The gate ships from the engine.** Consumer surfaces that read these docs
-  without routing through the engine (the CLI's direct reads, MCP query
-  projections, the reactive studio/sdk adapters) adopt `assertReadableModel`
-  with the parse-don't-cast follow-up; until then they render newer-model
-  docs unchecked.
+- **The gate ships from the engine.** `assertReadableModel`, the parse
+  functions, and the error classes are exported from
+  `@sanity/workflow-engine`, so every consumer surface composes the same
+  primitives — the reactive adapters at gate + parse, the CLI/MCP/plugin
+  direct reads at gate only (see "Consumer surfaces adopt the gate" above
+  for the split and its rationale).
 
 ## 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`
@@ -147,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
 
@@ -168,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
@@ -243,6 +307,144 @@ wrote with `applicableWhen` stamp model 1 and then fail the strict parse
 ungoverned — same disposition, those datasets are this-repo test data and are
 reset, not migrated.
 
+**Pre-adoption model-1 amendment: split `start.filter` into visibility +
+permission — the definition root's `start` block gained `allowed`, and
+`filter` tightened to browse-time-pure.** Same sanction as the amendments
+above (rule 3 untouched, the freeze point moves, no model 2 minted; the
+stored definition parse is strict, so even an additive `start` key would
+fence out released readers — the sanction is what makes that acceptable).
+The two keys answer different questions with different evaluation contexts:
+
+- `filter` — visibility: "should a start surface offer this workflow for
+  this document?" Browse-time-pure — candidate document as root,
+  `$tag`/`$definition`/`$now` bound (`startFilterVars` in the ledger shrank
+  accordingly), `*[...]` reading the workflow dataset — and any `$fields`
+  read is deploy-rejected with a pointer to `allowed`: `$fields` cannot
+  exist before inputs do, and an unbound `$fields` made permission-style
+  filters pass vacuously (GROQ null matches no row, so a
+  `count(...) == 0` dedupe rule surfaced a definition despite an open run).
+  Evaluated by `definitionsForDocument`/applicability and start controls,
+  exactly as before; `startInstance` still never reads it.
+- `allowed` — permission: "given these concrete inputs, may a run start
+  now?" (dedupe, WIP limits, overlap rules). Same context vars plus
+  `$fields` (the caller's `initialFields` as GDR envelopes —
+  `startAllowedVars` joins the ledger vocabulary), never a candidate root
+  (deploy-rejected; the subject rides `$fields.<entry>.id`). `startInstance`
+  ENFORCES it: declaring the expression is the opt-in, false or GROQ null
+  throws `StartNotAllowedError` (kind `start-not-allowed`), no override arg.
+  The `evaluateStart` verb pre-flights the same verdict as an
+  insight-carrying read. Advisory under races like every engine-side check —
+  the Content Lake stays the only enforcement point.
+
+Would an old reader misread (rule 5)? No reader exists outside this repo —
+the sanction. A post-amendment engine reads pre-amendment model-1
+definitions fine: an absent `allowed` means no permission gate, and a
+pre-amendment `$fields`-reading `filter` still evaluates with the read as
+GROQ null (no surface binds `$fields` there anymore) — the rule is inert,
+and whether the filter hides the definition (`defined()`-style reads fail
+closed) or surfaces it vacuously (the count-dedupe shape above) depends on
+its shape. Redeploying one fails validation until the expression moves to
+`allowed`.
+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)