@sanity/workflow-engine 0.20.0 → 0.21.0

package/CHANGELOG.md

@@ -1,5 +1,98 @@
 # @sanity/workflow-engine
 
+## 0.21.0
+
+### Minor Changes
+
+- d9394e5: **BREAKING:** Settle every child created by one spawn commit before the parent reacts to the cohort.
+
+  Parent transitions and triggered actions now observe the complete same-commit cohort instead of intermediate prefixes where later children are still unprimed. Spawn propagation stamps terminal child rows in one parent commit, cascade hops reuse an unchanged drain read, and successful aborts reuse their committed instance for immediate drain and ancestor propagation.
+
+- f4bc057: **BREAKING:** `list_workflow_instances` now returns one page with `has_more` and an optional `next_cursor`; callers that need every match must continue with the cursor. The optional `limit` accepts 1–100 rows and defaults to 25.
+
+  Bound instance and definition list reads with lake-side filtering and consumer-specific projections.
+
+  Document filtering now excludes exited-stage references and includes live unresolved child-workflow references. Definition discovery selects and model-gates only the latest deployed version of each workflow name; historical versions remain stored and available to history-oriented APIs.
+
+  The MCP eval suite now verifies that agents follow list cursors to find a target beyond the first default page, including in persisted Braintrust runs.
+
+  MCP tool telemetry reports a `cursorUsed` boolean so continued list-page adoption is measurable without sending cursor values, arguments, or results.
+
+- bcc30fe: **BREAKING:** One identity namespace inside the engine — every principal id in live state is the account-global user id (`sanityUserId`). The write boundary admits global-namespace ids only (`g…` humans, `p-…` robots verbatim; `e-…` third-party ids normalize to their embedded global form in the persisted output; plain project-scoped ids and unclassifiable forms are rejected with the remediation named). Actor resolution reads `/users/me` on both the workflow resource host and the global host: the global record is the canonical actor id, the resource host supplies roles, and the resource-local principal id rides the in-memory access context to bind `identity()` in guard previews and grant-filter evaluation — so advisory verdicts agree with the lake's own dialect, including per-resource identity for foreign-subject forecasts. Identity-kind guard `metadata` projections deploy in the target dataset's LOCAL spellings (translated through the project member list at deploy/refresh), so attribution predicates work without the author knowing two namespaces exist. Instances written before ids were namespace-classified resolve their live-state ids to global through the project-users directory at the read funnel (all-or-nothing per document, loud when unresolvable) and converge to global spellings on their next commit; `history[]` stays verbatim as audit record. Ships as data model 4 with reader floor 4: pre-classifier engines refuse new instances rather than mis-compare them, and deployment acknowledgements move to `expectedMinReaderModel: 4`. The prefix classifier is public API (`classifyPrincipalId`, `lakePrincipalId`, the `identity()` sentinels) so adapters can share the one namespace rule. **Existing instances written with project-scoped ids may no longer match user-identity queries and list filters until their next engine commit self-heals them; a prerelease deployment with no data worth keeping can reset with `sanity-workflows nuke` and start fresh.** There is no fallback to a project-scoped actor: when the workflow resource host reports a project-scoped principal, resolving the account-global record is required and its failure refuses the call. **Docs impact:** upgrade guidance is canonical in `docs/reader-model-rollout.md` § "Crossing to model 4" — any changelog-derived docs, upgrade notes, or assistant guidance should point there (readers-first sequencing, self-heal semantics, and the `sanity-workflows nuke` reset recommendation for prerelease data).
+- e7392af: Add the `resetActivity` admin verb — reset a failed (or otherwise terminal) activity in an instance's current stage back to `active` (re-run) or `skipped` (bypass), then cascade so a `$allActivitiesDone`-gated exit transition can fire. `workflow.diagnose` now marks its `reset-activity` remediation `available`, and the CLI ships the real `reset-activity <instanceId> <activity> [--skip]` command in place of the stub. Emits the `Editorial Workflows Activity Reset` adoption event on every attempt (`changed: false` on a no-op), matching the `set-stage` and `abort` overrides.
+
+  Writes strictly within the existing model-3 grammar: it reuses the `activityStatusChanged` history variant and the existing activity statuses, so it adds no persisted shape — there is no data-model version bump and no reader-floor change.
+
+- fa9c796: **BREAKING:** Replace the singular `start.allowed` and activity requirement record with ordered, named requirement arrays.
+
+  Start readiness now accepts polymorphic `groq` and `singleSubject` nodes:
+
+  ```ts
+  // Before
+  start: {allowed: '$fields.approved == true'}
+
+  // After
+  start: {
+    requirements: [
+      {type: 'groq', name: 'approved', title: 'Approval required', query: '$fields.approved == true'},
+    ],
+  }
+  ```
+
+  Use `singleSubject` instead of `$subjectHasInFlightInstance` to allow at most one in-flight run of the same definition for a subject. The requirement is definition-scoped and version-blind across deployments:
+
+  ```ts
+  // Before
+  start: {allowed: '!$subjectHasInFlightInstance'}
+
+  // After
+  start: {
+    requirements: [
+      {type: 'singleSubject', name: 'single-subject', description: 'Finish the existing run first.'},
+    ],
+  }
+  ```
+
+  Activity readiness uses the same ordered descriptor model with `groq` nodes:
+
+  ```ts
+  // Before
+  requirements: {
+    approved: 'defined($fields.approval)'
+  }
+
+  // After
+  requirements: [{type: 'groq', name: 'approved', query: 'defined($fields.approval)'}]
+  ```
+
+  Requirement names must be unique within their owning array. Evaluation preserves author order and reports every unmet requirement with its `name` and optional editor-facing `title` and `description`. Fresh standalone starts enforce the requirements after validating inputs. Resuming an unfinished start and parent-owned spawning continue to bypass start requirements.
+
+  `evaluateStart()` now returns ordered `requirements` entries containing each descriptor, outcome, and GROQ insight where applicable. Its singular top-level `insight` is removed. `StartNotAllowedError.insight` is replaced by `StartNotAllowedError.unmetRequirements`. Activity evaluation likewise reports unmet requirement descriptors instead of names alone.
+
+  Rename the public start-requirement analysis helpers and constants:
+
+  ```ts
+  // Before
+  explainStartAllowed(args)
+  unboundAllowedReads(query, fields)
+  START_ALLOWED_VARS
+
+  // After
+  explainStartRequirement(args)
+  unboundRequirementReads(query, fields)
+  START_REQUIREMENT_VARS
+  ```
+
+  `definitionsForDocument({document, subject})` becomes `definitionsForDocument({document})`. Start applicability no longer needs a separately supplied subject. The engine-owned start dataset projection exposes only `definition`, `subject`, and `completedAt`; authors no longer query raw instance storage for deduplication.
+
+  Studio pre-flights both requirement kinds against the live document session, disables starts whose requirements are unmet, and renders the authored description or title with a humanized requirement-name fallback. Controls re-enable on the same mount when a blocking run completes.
+
+  Persisted data model 4 unconditionally raises `minReaderModel` to 4 for new definitions and instances because older readers would ignore readiness arrays and could commit invalid transitions. Upgrade every reader and Function before deploying model-4 writers. Legacy deployed definitions are not normalized; prerelease environments with incompatible definitions may use `sanity-workflows nuke` before redeploying.
+
+### Patch Changes
+
+- 92e28bd: Fix reset telemetry test fixtures to use the current reader model.
+
 ## 0.20.0
 
 ### Minor Changes

package/DATAMODEL.md

@@ -152,6 +152,63 @@ never matches the new type).
   direct reads at gate only (see "Consumer surfaces adopt the gate" above
   for the split and its rationale).
 
+## Definition-language philosophy
+
+The authoring DSL is one language, not a bag of options. The principle of
+least surprise applies to the WHOLE surface, and the test for any addition is
+self-similarity: **someone who knows one part of the DSL should be able to
+guess the rest.** Every change to the definition tree is designed against
+these principles before the change-process rules below apply.
+
+1. **Same concept, same word, same shape — at every level.** The gating
+   vocabulary is the canonical example: `filter` is **existence** (a
+   non-match might as well not exist — hidden, never merely disabled),
+   `requirements` is **readiness** (named readiness gates; an unmet entry
+   keeps the node visible but disabled, with the failing entries named),
+   `when` is **trigger**. A position that needs one of these concepts uses
+   the name and shape the concept has everywhere else; a concept that
+   changes name or shape between levels is a defect in the language, not a
+   local convenience.
+2. **Surfaced things are nodes; mappings are internal.** Anything a person
+   will see — stages, activities, actions, transitions, fields, guards —
+   is an entry in a **polymorphic array of named objects**:
+   `{name, title?, description?, …}`, discriminated by `type` where
+   variants exist, so every surfaced entry can carry its own human copy.
+   Plain records (name → expression) are for internal mappings no surface
+   renders (predicates, effect bindings, role aliases). If an entry can be
+   shown to a person, it is an object in an array; a concept that outgrows
+   a record becomes an array of nodes, never a record of objects. Existence filters need none of this: a filtered-out entry
+   renders nothing, so there is nothing to title — bare condition strings
+   remain correct there.
+3. **New capability is a new value in an existing slot, never a parallel
+   mechanism.** Extend the vocabulary of an existing slot — a new named
+   entry, a new declared value, a new synthetic variable — before adding a
+   sibling property. A proposal arriving with its own error type, its own
+   ordering rule against an existing gate, or its own verdict leg beside an
+   existing mechanism's is the smell that it duplicates that mechanism.
+4. **Legibility comes from structure, not from bespoke props.** When a
+   surface needs to explain a refusal, the fix is named or structured slots
+   whose entries surfaces can address — never a one-off property added so
+   the engine can recognize a single policy. If the existing mechanism is
+   illegible or undiscoverable, restructure that mechanism. Authoring-time
+   discoverability can also live at the library layer — typed, documented
+   helpers that emit canonical expressions — before the model grows any
+   surface for it.
+5. **If the gap is scoping, add a scope, not a mechanism.** A rule that
+   duplicates an existing behavior with different scoping (per-definition
+   vs cross-definition, per-subject vs per-run) is the existing mechanism
+   plus a scoping value or variable, not a new property.
+6. **A persisted name is forever.** The shape ledger is append-only and
+   renames are forbidden (rule 3 below), so the name and shape of a new
+   definition-tree property are merge-blocking review concerns, not
+   bikeshedding. Names describe the check (`requirements`), never promise
+   an outcome the advisory engine cannot deliver (`unique`, `locked`).
+   Value vocabularies follow the established scheme — single lowercase
+   words, camelCase for multiword values (`todoList`, `fieldRead`), dotted
+   namespaces for families (`doc.ref`, `field.set`) — and nothing else: the
+   definition grammar has no kebab-case values, and no addition introduces
+   the first.
+
 ## Rules for changing the model
 
 `DATA_MODEL_CHANGES` is the append-only, machine-readable counterpart of the
@@ -208,6 +265,11 @@ floor.
    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.
+8. **A new definition-tree property justifies itself against the
+   definition-language philosophy above.** The model-log entry states why no
+   existing slot, value, or variable could carry the behavior. "The existing
+   mechanism is illegible or undiscoverable to surfaces" is an argument for
+   restructuring that mechanism, not for a sibling property beside it.
 
 ## Model log
 
@@ -498,6 +560,112 @@ writing, failing closed. A claim without a token (older writer's takeover)
 simply cannot authorise mid-dispatch reports; dispatch and completion are
 unaffected.
 
+### Model 4 — classified principal ids (reader floor: 4)
+
+One namespace change ships as model 4, and it is the first UNCONDITIONAL
+reader-floor raise — model 2's floor-bearing features were detectable,
+fencing only the documents that carried them; this one fences every
+instance the engine writes: **every principal id the engine writes into
+live state is the account-global user id** (`sanityUserId` — the `g…`-prefixed identity
+that is stable across projects and org-level resources). Model 3 was
+released before it landed, so it mints the next version.
+
+The platform has two identity namespace families: project datasets speak
+per-project principal ids (lake `identity()` returns the project user id — a
+different value per project for the same person), while org-level resources
+(Canvas, Media Library) and the global API host speak the account-global id.
+Documents written before this model carry whichever namespace their engine's
+client host happened to resolve — for dataset-anchored workflows, the
+workflow resource project's local ids. The id string itself carries its
+namespace (`g…` global, `p-…` robot, `e-<globalId>` third-party project form,
+`p…` project-scoped, `<anonymous>`/`<system>` sentinels) — the discrimination
+Sanity's own session middleware applies; `src/core/identity.ts` is the one
+classifier.
+
+**What changes.** No field is added, removed, or renamed — the stamped trees
+are shape-identical to model 3. The declared change is the namespace
+semantics of the principal-id VALUES in live state (`Assignee` user items,
+`Actor` stamps in field values, `completedBy`), plus the read/write discipline
+around them:
+
+- **Write boundary** — identity kinds admit global-namespace ids only:
+  `g…` and `p-…` verbatim, `e-…` normalized to its embedded global id in the
+  persisted output; plain project ids and unclassifiable forms are rejected
+  with the remediation named. Every persisted id has passed classification —
+  the `e-…` rewrite is the only spelling change.
+- **Read funnel (the versioned upgrade step)** — the instance point-read
+  resolves legacy project-scoped ids in live state to their global form
+  through the project-users directory (`/projects/<id>/users/<ids>`, the
+  sanctioned namespace bridge), ALL-OR-NOTHING per document: if any id
+  cannot be resolved the document is read as stored (comparisons against
+  those values fail closed, one loud warning). Because every commit persists
+  the in-memory instance wholesale, a resolved document's next commit
+  converges its stored spellings — normalize-on-rewrite IS this change's
+  migration mechanism; there is no separate tooling and no bulk migration.
+- **The anchor-scope invariant** — a bare project-scoped id in stored live
+  state belongs to the workflow resource's own project (the document's home
+  resource). This held by construction for every pre-model-4 writer
+  (assignment surfaces loaded the anchor project's members; the actor
+  resolved against the anchor host), and the read funnel resolves under it.
+- **`history[]` and `effectHistory[]` stay verbatim forever** — append-only
+  audit rows record who-acted-as-written; engine logic never compares
+  history actor identity for decisions (topology and provenance reads only),
+  and display resolves rows through the directory at presentation time.
+
+**Why the floor rises (rule 5).** An older engine reading a model-4 instance
+would not refuse it — it would MIS-COMPARE it: `$assigned` and the baked
+claim gates are raw string equality, so a global-id assignee against an
+older engine's project-scoped actor silently evaluates false (and the
+mirror-image for legacy values under a new actor). Misinterpretation, not
+parse failure — exactly the case the floor exists for. `minReaderModel: 4`
+makes pre-classifier engines refuse the document loudly instead. The writer
+maximum (`DATA_MODEL_MIN_READER`) rises to 4; deployment acknowledgements
+follow the readers-first rollout (`docs/reader-model-rollout.md`).
+
+Manifest feature: `classified-principal-ids` (instance, reader-floor,
+**unconditional** — every instance this engine writes stamps actor identity
+in the global namespace, so no instance persist can leave the floor below 4;
+definitions carry no principal ids and are unaffected).
+
+Round-trip survival: not applicable in the old-writer direction — the floor
+raise means a pre-model-4 writer refuses the document before any write; the
+one legal mixed state is old documents under new readers, which the read
+funnel owns.
+
+#### Model 4 also adds named polymorphic readiness requirements
+
+Readiness becomes an ordered array of named nodes. `start.requirements`
+accepts authored GROQ nodes and the declared `singleSubject` node;
+`activity.requirements` becomes an array of named GROQ nodes. Each node may
+carry editor-facing `title` and `description` metadata. The singular
+`start.allowed` and the activity requirement record are removed.
+
+- **Definition tree** — start and activity readiness use requirement arrays
+  discriminated by `type`; names are unique within their owning array.
+- **Instance definition snapshot** — the same definition tree is pinned into
+  every new instance. Readers normalize legacy activity requirement maps in
+  existing snapshots into named GROQ nodes before evaluation; newly persisted
+  snapshots use only the array form.
+
+Manifest feature: `readiness-requirements` (definition, reader-floor,
+detectable, floor 4).
+
+Model 4 is the default floor after this change, not a compatibility mode for
+legacy deployed definitions. Deploy the model-4 definition set before running
+the new reader; environments that retain incompatible earlier definitions
+should follow the documented destructive reset (`nuke`) rollout path instead
+of expecting those definitions to be normalized on read.
+
+Would an old reader misread the field (rule 5)? Yes. An older engine ignores
+the new arrays and therefore treats gated starts and activities as ready,
+which changes the state-machine decisions it may commit. Missing arrays keep
+their historical meaning (no requirements), but a present array requires a
+model-4 reader. The writer floor is raised unconditionally to 4 because every
+new instance embeds a model-4 definition snapshot and can later be evaluated
+from that snapshot. Definitions are create-only and instance persists retain
+unknown fields, so model-4 data survives round trips; the floor prevents an
+older engine from interpreting it in the first place.
+
 ## Pending governed changes
 
 - **`temp.system.guard` → `system.guard`** — the guard doc type's `temp.`