@sanity/workflow-engine 0.16.0 → 0.17.0

package/CHANGELOG.md

@@ -1,5 +1,48 @@
 # @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

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
 
@@ -243,6 +277,47 @@ 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
 
 - **`temp.system.guard` → `system.guard`** — the guard doc type's `temp.`