@sanity/workflow-engine 0.15.0 → 0.17.0

package/CHANGELOG.md

@@ -1,5 +1,84 @@
 # @sanity/workflow-engine
 
+## 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
+
+- 11e2d6f: Export `DEFAULT_TRANSITION_WHEN` — the trigger a transition desugars to when the author declares none — so consumers describing transition triggers can recognize the default's spelling instead of copying the literal.
+- 7510fd5: Delivery-surface helpers and an honest remediation contract. The start-surface boundary is now engine-owned and shared: `buildInitialFields` (typing caller-supplied start values against a workflow's declared field entries) and `startRefusal` (the spawn-only refusal message), both previously private to the CLI. Also exported: `documentPrefilter` and `inFlightFilter` (the instance-list document and in-flight arms, for list builders that compose their own conditions) and `parseDefinitionInput` (the deploy boundary's envelope-strip + stored-form parse). The `drain-effects` remediation verb is now flagged `available: true` — the engine's `drainEffects` verb ships, so a hung-effect diagnosis names a fix the consumer can actually run instead of describing it as not yet callable.
+- 79c54db: Reactive session reads now match the engine's own reads.
+  - The session feeder projects every observed doc onto its watch ref's identity the way the lake's perspective reads do: the published-form id becomes `_id` (Studio/SDK stores resolve drafts and release versions under `drafts.*`/`versions.*` ids, which keyed the session's overlay and snapshot where no transition `when` condition or `$fields.<docref>` deref ever looks — an editor's uncommitted draft could not satisfy a condition the engine's `tick()` would read as satisfied), and a draft/version's stored id rides along as `_originalId`, so conditions like `_originalId in path("versions.**")` read what the engine's own hydration returns. The projection is an engine export (`projectToWatchRef`), one encoding beside `contentDraftFallback`/`contentDocQuery`, and it is strict: only the exact representations a store may legitimately resolve under the instance's perspective are accepted — anything else (another doc's dotted id under a version prefix, a version from an unbound release, a draft the perspective makes invisible) fails loudly instead of being fed under the watched identity.
+  - Watches whose perspective makes drafts invisible to the engine no longer fall back to the draft. The engine hydrates a `[release]` stack as version-over-published (and `'published'`/`'raw'` scalars as published/raw) with drafts invisible; the Studio adapter resolved `version ?? draft ?? published` and the SDK's per-doc store has the same fallback built in. The Studio adapter now skips the draft arm unless the effective perspective names `'drafts'`, and the SDK adapter observes such refs through the query store under the instance's exact perspective stack. The SDK's query-store route reads committed state (live), so local uncommitted edits to a release version doc no longer feed the session there — Studio keeps its optimistic `editState` reads. New engine helpers `contentDraftFallback` and `contentDocQuery` are the single encoding of the rule, shared with the engine's own hydration.
+  - `useWorkflowSession` resets its surfaced `evaluation` to `undefined` on an `instanceId` swap, as the contract promises, instead of leaving the previous instance's projection visible until the new instance first evaluates.
+
+- 6a46db1: **BREAKING:** the definition root's `applicableWhen` moved to `start.filter`, inside a new `start` block — `{kind?: 'interactive' | 'autonomous', filter?: GROQ}` — describing how standalone runs begin. No alias, no dual-read: definitions authored with `applicableWhen` fail the strict parse until rewritten.
+  - `start.kind` classifies who initiates a run — a person from a start surface (`'interactive'`, the default; `startKindOf(def)` is the one reading rule) or a system reacting to a document (`'autonomous'`, hidden from human start pickers). Classification only: `startInstance` stays one verb and one code path for every caller and kind — an interactive start of an autonomous workflow is legal. Deploy invariants: a spawn-only (`lifecycle: 'child'`) definition may not declare `start`; an `'autonomous'` kind requires every required input entry to be subject-style (`doc.ref`/`doc.refs` — the shared `isSubjectEntry` rule); a `start.filter` may read only declared **input-sourced** entries via `$fields` (a typo or a query/literal entry is a silent never-pass); and a root-reading filter (`_type == …`, `@`, or a `^` escaping a scan) requires a subject entry, since a read surface with no subject never binds a root.
+  - `start.filter` is a **read-side visibility rule, not a gate** — `startInstance` never evaluates it and never throws on it; it starts whenever the caller supplies the required inputs. The filter decides what appears in / is chosen from Start lists: `definitionsForDocument`/applicability and the Studio start control evaluate it in a widened, named start-filter context (`START_FILTER_VARS`) — the candidate document as root, `$tag`/`$definition`/`$now`/`$fields` bound (`$fields` = the caller's input entries as GDR envelopes, so `$fields.<entry>.id` is the GDR URI), and `*[...]` = the workflow resource's dataset. Filters that never scan keep the cheap pure evaluation (`analyzeCondition(...).readsDataset` decides); scanning filters evaluate over a fetched slice of EVERY instance in the tag (completed included — `*` carries no hidden predicate; filters qualify in-flight themselves with `!defined(completedAt)`), so a filter can bound what surfaces (WIP limits, one-run-per-subject). Absent bindings evaluate GROQ-null and fail closed.
+
+- 35b9b85: Commit/recovery hardening and a locale-independent content fingerprint:
+  - `completeEffect` now commits under the engine's shared optimistic-locking retry, like every other claim-protocol write: a lost revision race reloads and re-commits the same reported outcome instead of escaping as a raw 409 — which discarded the handler's outputs and re-dispatched the effect after lease expiry, running the external side effect twice. Exhausting every attempt throws the new `ConcurrentCompleteEffectError` (kind `concurrent-complete-effect`).
+  - A retried `abortInstance` of an already-terminal instance now propagates to ancestors unconditionally, matching the condemned-children drain: a crash between the terminal commit and the ancestor walk no longer wedges the parent's subworkflow gate on a child that already died.
+  - `hashDefinitionContent` and the model-shape canonicaliser sort object keys by UTF-16 code unit instead of the locale-dependent `localeCompare`, so identical definitions fingerprint identically on every machine. A definition whose key ordering differed under the deploying machine's locale hashes differently once — the next redeploy of such content mints one new version instead of reading as unchanged.
+
+- e5f5b77: **BREAKING:** actions become the only payload mechanism — every op, effect, and spawn in the system lives on an action; structure never does.
+  - Actions gain `when` (cascade-fired trigger: the engine fires it the moment it's true, at most once per stage visit, level-triggered; never fireAction-able) and `spawn` (the subworkflow block, unlocking caller-triggered and conditional spawn). Fires-on-entry is spelled `when: 'true'`.
+  - Deleted from the model: `activation`, activity-level `ops`/`effects`/`subworkflows`, `completeWhen`/`failWhen`, `kind`, and transition `ops`/`effects`. Transitions are pure edges `{name, when, to}` (the condition key renamed from `filter` — trigger semantics). `target` survives as the off-system marker; `kind` is now always derived, plus a new derived executor classification (autonomous / interactive / off-system / hybrid) on activity evaluations.
+  - Activities are `active` from stage entry (no `pending` status, no activation moment, no machine-step implicit); a new deploy invariant requires every activity to have a reachable path to a terminal status.
+  - A cascade hop is ONE transaction: the current stage's triggered actions run to in-memory fixpoint, then transition selection, then a single CAS commit; chain hops stay separate commits. The per-visit `firedActions` ledger on the activity entry re-arms on re-entry (a stage resets on re-entry). The cascading token executes triggered actions; `roles` on a triggered action pins which identities may execute it (an incapable token leaves it armed).
+  - The context bag split: `$effects` now carries completed effects' outputs ONLY (derived from `effectHistory`), and the new `$context` carries the `startInstance` seed plus a parent's `spawn.context` handoff (the persisted `effectsContext` field renamed `context`; `startInstance`'s seed arg renamed accordingly). `$effectStatus` is unchanged.
+  - Spawn registry rows key per (activity entry, spawning action), so two spawn actions on one activity can never cross-adopt each other's children.
+  - `fireAction` rejects a `when` action (`cascade-fired` verdict); evaluation projects triggered actions as narratable (`triggered: true` + `whenInsight`), never as buttons.
+
+### Patch Changes
+
+- 01e8042: Fix `fieldRead` values landing in `doc.ref`-kinded slots: a bare (no-path) read of a `doc.ref` source now preserves the stored reference instead of handing over the dereferenced document wherever the result feeds a `doc.ref`-kinded slot — a `doc.ref` entry's `initialValue` seed (the mirror pattern no longer fails `startInstance` with `FieldValueShapeError`), a `field.set` op targeting a `doc.ref` entry, a `field.append` op item landing in a `doc.refs` entry, and `doc.ref` sub-fields reached through an object-expression op value (`field.set` object entries, `field.append` rows, `field.updateWhere` merges — sub-values resolve against the entry's declared sub-field shapes). Identity preservation applies only to bare reads into `doc.ref`-kinded slots; every other surface (conditions, effect bindings, guard metadata, path-carrying reads, undeclared object-expression keys) keeps the doc-centric dereference.
+- 01e8042: Close the unvalidated `field.updateWhere` write path. The merged rows now pass the same shape gate as `field.set` / `field.append` — a wrong-kinded merge value for a declared row sub-field throws `FieldValueShapeError` and aborts the commit instead of persisting silently. An `updateWhere` may only target an `array` entry (the one kind whose rows carry declared sub-fields): a definition-carried op against any other kind is rejected at define/deploy time, and the op applier enforces the same gate for the boundaries deploy never sees (effect-completion ops, definition/instance divergence) — previously a merge into a `doc.refs` entry spread the merge value's fields (for a bare `fieldRead` of a `doc.ref`, the whole dereferenced document) into the stored GDR rows with no error. A merge may also never write the reserved row keys `_key` / `_type` — row identity and bookkeeping are engine-stamped, and a merge would restamp every matched row with the same literal; statically-named keys are rejected at define/deploy, and the applier re-checks the resolved merge. `field.removeWhere` is unchanged and keeps accepting every array-valued kind, `doc.refs` included — dropping rows needs no row shape.
+- Updated dependencies [7510fd5]
+  - @sanity/groq-condition-describe@0.2.0
+
 ## 0.15.0
 
 ### Minor Changes

package/DATAMODEL.md

@@ -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
@@ -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).
@@ -113,11 +146,12 @@ 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
 
@@ -166,13 +200,123 @@ rules, not folklore:
   — always read as changed, so the first redeploy after upgrade mints a
   fresh version.
 
-### Model 1 — stamping introduced (reader floor: 0)
+### Model 1 — stamping introduced; actions-only payload model (reader 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"). No other shape change. The floor is 0: any
-engine ever released reads model-1 documents fine, and model-0 documents
-keep reading exactly as before.
+contract — see "The stamp pair"). The floor is 0: model-0 documents keep
+reading exactly as before, and every engine from the amendment below onward
+reads model-1 documents fine (the amendment's sanction — no readers or
+writers existed outside this repo — is what made the pre-amendment window
+irrelevant).
+
+**Amended in place before any consumer existed** (a sanctioned exception to
+rule 3 — model 1 had no readers or writers outside this repo when the
+reshape landed, so the freeze point moved rather than minting a model 2):
+actions became the only payload mechanism, and the persisted trees reshaped
+accordingly. One caveat was weighed and accepted when the exception was
+confirmed: released engines predating the amendment stamp model 1 while
+writing the pre-amendment shapes, so documents they wrote pass the stamp
+gate and then fail ungoverned (a raw shape error, not
+`ModelVersionAheadError`). Those documents are declared disposable — every
+dataset holding them is a this-repo test dataset and must be reset before a
+post-amendment engine touches it. Nothing migrates them.
+
+Definition tree (the stored authoring model):
+
+- Activities carry no payload: `activation`, `ops`, `effects`,
+  `completeWhen`, `failWhen`, `subworkflows`, and `kind` are gone from the
+  activity tree. `target` survives as the off-system marker.
+- Actions gained `when` (a cascade-fired trigger condition), `spawn` (the
+  subworkflow block formerly on the activity), and `roles` (stored verbatim
+  only on cascade-fired actions — the execute pin; fireAction actions still
+  fold roles into `filter` at desugar).
+- Transitions are pure edges: `{name, when, to}` plus presentation —
+  `filter` renamed to `when`, `ops`/`effects` gone.
+
+Instance tree:
+
+- `effectsContext` renamed to `context` (entry `_type`s
+  `effectsContext.<kind>` → `context.<kind>`); it now holds ONLY the
+  start-time seed and a parent's spawn handoff. Completed effects' outputs
+  live solely on `effectHistory[].outputs` (the `$effects` read derives from
+  there).
+- `ActivityEntry` statuses lost `pending` (entries are `active` from stage
+  entry, or `skipped`) and gained `firedActions: string[]` — the per-visit
+  ledger of cascade-fired actions.
+- `SubworkflowEntry` gained required `action` (the spawning action's name;
+  rows key per activity + action).
+- History: the `activityActivated` variant is gone; `actionFired` gained
+  `triggered?: true`; `opApplied` lost its `transition` origin key;
+  `EffectOrigin.kind` is only ever `'action'`.
+
+**Pre-adoption model-1 amendment: moved `applicableWhen` to `start.filter`,
+added `start.kind` — a deliberate freeze bypass; no external consumers
+exist.** Same sanction as the amendment above (rule 3 untouched, the freeze
+point moves, no model 2 minted). The definition root gained an optional
+`start` block: `kind` (`'interactive' | 'autonomous'`, stored explicitly —
+desugar fills the default; the block itself stays absent on definitions that
+never declared one, and an absent block reads as interactive with no filter)
+and `filter` — the former `applicableWhen`, re-scoped from a pure
+candidate-doc predicate to the start-filter context (`$tag` / `$definition` /
+`$now` / `$fields` bound, `*[...]` reading the workflow dataset; the
+`startFilterVars` vocabulary joins the ledger). `start.filter` is a READ-SIDE
+visibility rule — evaluated by `definitionsForDocument`/applicability and the
+Studio start control to decide what appears in Start lists; `startInstance`
+never reads it and never throws on it. An earlier iteration of this amendment
+added a `startFilterOverridden` instance-history variant (paired with a
+throwing start-time gate and an `overrideStartFilter` verb arg); that gate was
+removed before any consumer existed, so this same in-place amendment ALSO
+removed the `startFilterOverridden` variant — no gate, no override, nothing to
+audit. The instance tree is back to its pre-amendment history variants.
+Would an old reader misread (rule 5)? No reader exists outside this repo —
+which is the sanction; post-amendment engines read pre-amendment model-1
+definitions fine (no `start` block ⇒ the defaults above). The released-engine
+caveat above covers this amendment identically: definitions a released engine
+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.
 
 ## Pending governed changes