@sanity/workflow-engine 0.28.0 → 0.30.0

package/CHANGELOG.md

@@ -1,5 +1,206 @@
 # @sanity/workflow-engine
 
+## 0.30.0
+
+### Minor Changes
+
+- a3a8dc0: The engine gains a list-projection read for instance dashboards. `instancePreviewsQuery` compiles the same filter arms as `instancesQuery` into a `WorkflowInstancePreview` projection — the open stage alone, field lists reduced to identity, date, document-reference, and release-reference kinds, and `claimedEffects`/`failedEffects` facts in place of the unbounded audit trails — kilobytes lighter per row than the full document. `readInstancePreviewDoc` is the matching gate-then-parse funnel (`WorkflowInstancePreviewSchema`/`parseInstancePreviewDocument` underneath), and the internal identity normalizer accepts any host carrying the identity slots, rows included. `InstancesQueryFilter` adds a keyset `before` cursor (requires `limit`) for paging the newest-first order without skipping or repeating rows across pages; both list orders now break `startedAt` ties on `_id`. **No upgrade action required** — existing reads are unchanged apart from the deterministic tie order.
+
+  **Docs impact:** The engine reference's instance-query section documents `instancePreviewsQuery`, `WorkflowInstancePreview`, and the `before` cursor in this release's pass — the Workflows tool ships reading them in the same release.
+
+- a3a8dc0: **BREAKING:** the exported `WorkflowObserver` contract (workflow-react) gains two required members, `fetchInstancePreviews` and `listenInstanceChanges` — a custom observer no longer compiles until it implements both; the shipped SDK and Studio adapters already do, so their consumers need no action.
+
+  The reactive layer gains a progressively-hydrated preview list. `useInstancePreviews` (workflow-react) drains the engine's preview projection page by page until the whole filtered set is held — `drained: true` means counts over it are totals — then keeps every row fresh from ONE shared change listener per engine tag: an event refetches the touched previews alone, so update cost is per commit, never per list size. Page size is caller-supplied. The engine adds `instanceChangesQuery` (the tag partition as a listen filter), and the `WorkflowObserver` contract adds `fetchInstancePreviews` and `listenInstanceChanges`, implemented by the SDK observer (the Studio adapter inherits them). A change-feed failure never silently freezes a list: the SDK observer reconnects with exponential backoff and then emits a `reset` event, on which `useInstancePreviews` re-drains the whole partition — gap-missed additions, edits, and deletions all land.
+
+  **Docs impact:** The reactive-core reference documents `useInstancePreviews` and the observer contract's two new required members in this release's pass — the Workflows tool ships reading them in the same release, and the custom-adapter guidance must name both members beside the BREAKING note.
+
+- 90207dc: **BREAKING:** `assertReaderModelAcknowledgement` now requires `{requiredMinReaderModel, context?}` instead of a context string, and `ReaderModelAcknowledgementError` accepts its optional context through `{context}`. The Blueprint package's `AcknowledgedDeployment` type moves to the engine as `AcknowledgedWorkflowDeployment`; update imports and use that shared name. Assignment-valued fields can now declare a non-empty `roles` list that limits newly written assignees. Existing fields without `roles` stay unconstrained, retain reader floor 4, and continue deploying with `expectedMinReaderModel: 4`; installing this release requires no coordinated rollout or configuration change.
+
+  Before adding `roles`, upgrade every Studio, CLI, MCP server, Function, and other runtime that shares the affected workflow resource, then change that deployment's literal `expectedMinReaderModel` to `8`. MCP deployments pass the same reviewed literal as the optional `expectedMinReaderModel` tool argument. Definitions and instances carrying the facet require reader model 8. User assignees qualify through direct roles or the definition's role aliases, while collective role assignees must literally match one configured role. Studio assignment controls, including manual start, auto-start, and assignees nested in to-do rows, offer only eligible choices while retaining stale current values so editors can remove or replace them. Constrained pickers name the active eligible roles and distinguish an empty eligible set from a search with no matches. Top-level plural and composite edits retain no more occurrences of a stale assignment at each declared assignment location than the previous value contained; removal and reordering therefore work, while an added copy is a new assignment and must qualify. Direct singular replacements and every assignment present in an `updateWhere` fragment remain strict. Each engine verb uses one member-directory snapshot across retries, cascade hops, and spawned children, then the next verb reads current membership.
+
+  Malformed project-member and project-user directory responses now fail loudly instead of treating bad rows or role records as missing users, and actor resolution reports those failures as `inaccessible`, so integrations can distinguish directory failures from absent membership.
+
+  CLI `start` and `definition delete` no longer apply the definition-submission acknowledgement gate; deploy, check, dry-run, definition diff, Blueprint provision, and engine definition APIs still validate the selected definitions' required floor.
+
+  No reader-fleet rollout or deployment-literal change is required for existing definitions that do not use `roles`.
+
+  **Docs impact:** Update the assignment field reference and authoring examples for `roles`, distinguish eligibility from editability, action permission, and literal queue ownership, and add the model-8 conditional adoption sequence to the prerelease rollout guide.
+
+- b0b1550: **BREAKING:** Product-prefixed telemetry events now use `Workflows <event>` instead of `Editorial Workflows <event>`; `EditorialWorkflowsResource` is replaced by `WorkflowsResource`; and `defineWorkflows` now generates `workflows-<deployment name>` resource names instead of `editorial-workflows-<deployment name>`. Telemetry consumers matching the previous literals stop receiving events until updated, TypeScript consumers importing the previous Blueprint interface no longer compile, and an existing Blueprint stack that relies on the generated name treats the new default as a different resource identity.
+
+  Update telemetry dashboards, schemas, alerts, and queries to match the `Workflows` prefix; event suffixes, payloads, and versions are unchanged. Replace Blueprint imports with `WorkflowsResource`. Before deploying an existing Blueprint stack, either pass its recorded resource name explicitly or plan the detach-and-create migration to the new default. Workflows request-tag families and billing classification are unchanged.
+
+  Other user-facing package copy now uses the Workflows product name. No upgrade action is required for consumers that do not match telemetry event names or use the Blueprint package.
+
+  **Docs impact:** Rename the product throughout the public documentation, move the docs section to `/docs/workflows/*` with permanent redirects from every `/docs/editorial-workflows/*` path, and document the telemetry-prefix, `WorkflowsResource`, and Blueprint resource-name migrations in the telemetry reference, Blueprint guide, and release notes.
+
+### Patch Changes
+
+- 210ca63: The API documentation shipped in every package's `.d.ts` files is rewritten to be substantially terser: multi-paragraph doc comments are cut to the facts a consumer needs, and internal narration no longer appears in editor hover text. Runtime behavior, exports, and type signatures are unchanged across the whole package group.
+
+  **No upgrade action required.**
+
+  **Docs impact: None** — the published documentation site is authored separately; only in-editor `.d.ts` hover text changes.
+
+- a3a8dc0: `readInstancePreviewDoc` now takes an untyped lake row. A preview page slot without a string `_id` fails as a shape error named `(unknown id)` instead of being assumed to have an id for the model gate.
+
+  **No upgrade action required.** Callers that already passed `{_id: string}` continue to type-check.
+
+  **Docs impact:** None. The preview-row funnel is unchanged for well-formed rows; only the untyped input is honest.
+
+- Updated dependencies [210ca63]
+  - @sanity/groq-condition-describe@0.4.1
+
+## 0.29.0
+
+### Minor Changes
+
+- f44fc33: Workflow conditions can now read the caller's org-level User Attributes (Enterprise) through the advisory `$attributes` variable — for example `$attributes.department == "politics"` on a fireAction action filter, activity requirement, or editable predicate. Values match what lake role filters read via `user::attributes()`, keyed by attribute name with each active scalar or array value. Soft-gate paths (`evaluate`, fireAction filter re-check, editField) fetch the bag; ticks and drainers do not. Expected absences (401/402/403/404 — non-Enterprise, missing feature, forbidden) leave `$attributes` unbound so conditions that read it fail closed; unexpected fetch failures (5xx, network) throw on those soft-gate paths only and are not cached so the next call retries. An empty successful page binds `{}`. When the Management API envelope reports `hasMore: true`, the engine still binds the partial bag and warns (`nextCursor` makes follow-up pagination a small engine change). Engine checks remain advisory; the Content Lake is still the only enforcement point. `$attributes` is never persisted on `Actor` / history. The MCP authoring guide names the new variable alongside the other caller-bound vars. The test bench accepts an `attributes` bag (construction shortcuts and per-call overrides) the same way it accepts `grants`.
+
+  **No upgrade action required.** Existing definitions are unchanged. Authors who want attribute-gated actions opt in by writing `$attributes` in caller-bound condition sites; cascade gates continue to reject caller-bound vars at deploy.
+
+  **Docs impact:** Update the condition-variables reference (`docs/reference.md` § context-bound variables) and any guide that lists `$actor` / `$can` / `$assigned` so `$attributes` and the Enterprise / fail-closed semantics are named; note the spelling difference vs lake `user::attributes()`.
+
+- 26f25e0: Definition authors and effect runtimes can now use `field.inc`, `field.dec`, and
+  `field.setIfMissing` operations. Arithmetic operations accept an optional
+  numeric value expression that defaults to `1`, validate number-field targets,
+  reject non-finite results, and participate in the same atomic engine commits as
+  existing field operations. A retry is deduplicated only when the caller supplies
+  an idempotency key; the arithmetic operation itself is not idempotent.
+  `field.setIfMissing` targets nullable fields; list fields are always arrays and
+  are rejected. When the target already has a value, `field.setIfMissing` does
+  nothing and writes no `opApplied` history row. Like Sanity Content Lake patches,
+  `field.inc` and `field.dec` require the target to already hold a number: a
+  declared number without an initial value is `null`, so arithmetic rejects without
+  committing. Initialize counters with `field.setIfMissing` set to `0` before
+  incrementing when the value may be absent.
+
+  Persisted-model version 6 adds the three operation discriminators. The change is
+  additive and the reader floor remains 4, so existing definitions and instances
+  require no migration. Before deploying a definition that uses these operations,
+  upgrade every Studio, CLI, MCP server, Function, and other runtime that can
+  process workflow data in the shared environment. The unchanged reader floor
+  does not fence out an older engine, which rejects or aborts when it encounters a
+  new operation rather than executing it with different semantics.
+
+  **Docs impact:** Update the Operations guide and operation reference with all
+  three forms, their defaults and validation, effect-completion availability, the
+  Sanity-compatible `field.setIfMissing(0)` then `field.inc` initialization
+  pattern, the warning that arithmetic never assumes a missing value is zero, and
+  the bounded-retry counting pattern that loops below a fixed total-attempt limit
+  and routes exhausted work to manual recovery. Note that no-op
+  `field.setIfMissing` attempts write no `opApplied` history row, and include the
+  readers-first rollout guidance for model 6 operations.
+
+- 25bd1fb: Each card in the Studio plugin's Workflows tab now carries what the definition
+  is doing, not just its name: how many of its documents have work in flight, when
+  one of them last changed stage, how many hold a task past its due date, and one
+  alert glyph when something is wrong. The card reports live state only — what a
+  workflow runs on and what it says about itself change on a deploy, and that
+  workflow's own Definition page already names both. The
+  grid bands into "Assigned to you" and "Other workflows", so whether the reader
+  has work in a workflow is carried by where its card sits; rows keep the
+  catalog's alphabetical order inside each band. A card wears one alert, and it
+  means a run of that workflow cannot continue without help. The engine's
+  `blocked` readiness hold earns none, because it is an expected transient state
+  and flagging it would mark most cards most of the time; a rejected
+  document-type binding earns none either, because it belongs to the definition
+  rather than to any of its runs and is reported on that workflow's Definition
+  page.
+
+  The age on a card is a STAGE ARRIVAL, not a last-modified stamp. Every engine
+  commit moves an instance's change stamp — an assignment, a date, a drained
+  effect — and a workflow can absorb a great deal of that without advancing, so
+  the arrival is the event a catalog can read as progress. The consequence is
+  deliberate: a busy workflow held inside one stage reads as old, which is the
+  pathology worth seeing. Hovering that age names the move — which document went
+  to which stage, and the exact time — resolving the document's title through the
+  preview store only once the tooltip opens.
+
+  Overdue is the only signal drawn in a tone — caution, where the alert glyph
+  takes critical — and the only one that disappears when it reads zero: it reports
+  that something is wrong rather than how things stand, so a card with nothing
+  late spends no room saying so. A
+  document counts as overdue while an unsettled task on it is past its due date;
+  a finished task's date, however old, is not a debt. Overdue is measured on one
+  shared rule with the todo rows, so a card's count and a row's face can no
+  longer disagree about a single date.
+
+  The grid counts DOCUMENTS where it used to count instances, because its reader
+  is an editor and the document is what they open. Several instances on one
+  document count once. An instance whose chain references no document counts as
+  one unit of its own, so a workflow that runs on no document does not read as
+  idle. The workflow's own page still reports instances, in those words.
+
+  Hovering that count also says how many of those documents have yet to leave the
+  stage their workflow starts from — on a line of its own, so the two facts can be
+  scanned rather than read through, and folded into the first line when the answer
+  is all of them, where a second line would repeat one number. A document counts
+  there while any of its runs still waits at the start, judged against that run's
+  own pinned snapshot, so a run begun under an earlier version answers to where
+  that version started. The count stays in the hint rather than taking a slot on
+  the rule: it is a part of a number the card already shows, meaningless without
+  that total beside it, and no glyph in the set says "waiting at the start".
+
+  The page no longer opens on a project-wide total. The band headings count the
+  workflows, so a total above them stated the same figure twice, and a total of
+  documents invited a comparison against the cards that can never add up — one
+  document running two workflows is one document in a project total and one on
+  each of their cards.
+
+  The engine gains `documentStuckCause`, which classifies an instance as stuck
+  from its persisted document and pinned snapshot alone — no evaluation, no
+  reads, no actor. It answers for the effect- and activity-level causes
+  `diagnoseInstance` reports (`failed-effect`, `failed-activity`,
+  `hung-effect`) and returns `undefined` for the transition-level ones, which
+  need GROQ results. It is sound but incomplete by construction: a cause it
+  reports is real, and the absence of one means only that no cause was provable,
+  never that the instance is healthy. Surfaces flagging on it must not word an
+  unflagged state as an all-clear. `findActivityNode` and `findStageNode`, the
+  tolerant definition tree lookups it uses, are exported alongside it.
+
+  The tool's instance read is held per engine for the session and replayed on the
+  next mount, which changes what the Workflows tab paints while it loads. A first
+  visit now waits for that read before the definitions grid appears, where it used
+  to lay out cards from the catalog and rearrange them once the instances landed —
+  the grid's bands and counts come from the instances, so the cards had no stable
+  shape until both reads were in. The grid waits on the reader's identity for the
+  same reason: which band a card sits in depends on who is looking, and a
+  project-scoped account resolves through the project member directory, so banding
+  before that answer arrived would have moved every card once it did. An account
+  the directory cannot place, or a directory that fails to load, is an answer
+  rather than a wait — the grid paints unbanded and every card reports no assigned
+  work. A later visit inside the same session paints the
+  held read at once and refreshes behind it.
+
+  The form strip's assigned-task count tells those two apart as well, so an account
+  the member directory cannot place no longer leaves a spinner turning in that slot
+  for the rest of the session. It shows no count, which is what it already did for
+  an account with nothing assigned. The hold is not local to the grid: the
+  task rows under "All documents" and "For me", and the active-instance count on a
+  workflow's Definition page, read the same stream, so they too open on held
+  numbers before the fresh read lands. A failed read is never held, and a provider remount mints a new engine and
+  so starts cold.
+
+  **No upgrade action required.** The card additions are automatic, and
+  `documentStuckCause` is a new export that changes no existing verdict —
+  `diagnoseInstance` classifies exactly as before, now sharing one
+  implementation of the document-derivable causes.
+
+  **Docs impact:** Update the Workflows tool guide where it describes the
+  definitions grid, to cover the new card signals, the assigned-work ordering, the
+  document-versus-instance split between the grid and a workflow's own page, and
+  that the tab opens on a held read after the first visit.
+  `docs/reference.md` already carries `documentStuckCause` beside
+  `diagnoseInstance` with its bound stated; the hosted engine reference needs the
+  same entry, so integrators do not read a missing cause as a health check.
+
+- 3fd04f1: **BREAKING:** `ActionSemantic` was a closed union of action decision values; it now also includes signal values and the open `custom.${string}` form. TypeScript consumers that exhaustively map `ActionSemantic` must handle signal and custom values or narrow to the decision subset before upgrading, otherwise their build will fail. Workflow authors can attach advisory signals and validated custom semantics to workflow roots, stages, activities, and actions, and evaluation results expose them at each matching level.
+
+  Existing stored definitions and runtime behavior remain compatible. The Studio plugin continues to render decision faces when decision values are composed with signal or custom semantics, while non-decision values receive the default action face.
+
+  **Docs impact:** Update the definition and evaluation references plus the concepts guide to document level-wide advisory semantics, the signal vocabulary, custom grammar, and action-only decision values.
+
 ## 0.28.0
 
 ### Minor Changes

package/DATAMODEL.md

@@ -72,10 +72,12 @@ never matches the new type).
   the shape, so restamping there would lie.
 - **`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.
+  from compatibility-bearing features present in the canonical stored tree,
+  while retaining the unconditional `DATA_MODEL_MIN_READER` baseline of 4.
+  `DATA_MODEL_MAX_READER` is the maximum floor the current writer can emit.
+  A deployment acknowledges the highest reader model verified
+  for its shared runtimes, and the writer compares it with the submitted
+  definitions' required floor.
 - **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.
@@ -138,13 +140,12 @@ never matches the new type).
   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.**
-  Before any writer that raises `DATA_MODEL_MIN_READER` deploys, every
-  reader in the fleet — customer-deployed Functions foremost — must already
-  run an engine at or above the new floor (the BACKWARD deployment order:
-  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.
+- **Persisting a floor-bearing feature is an availability decision.** Before a
+  definition using that feature deploys, every reader sharing its workflow
+  resource — customer-deployed Functions foremost — must run an engine at or
+  above the feature's floor. Increasing the writer's maximum alone requires no
+  coordinated rollout. 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.** `assertReadableModel`, the parse
   functions, and the error classes are exported from
   `@sanity/workflow-engine`, so every consumer surface composes the same
@@ -224,8 +225,9 @@ floor only when its stable marker is present in the canonical stored tree. An
 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.
+this way. Raising `DATA_MODEL_MAX_READER` expands what the writer may emit; a
+detectable feature raises only documents carrying its stable marker above the
+retained model-4 baseline.
 
 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
@@ -233,16 +235,16 @@ floor.
    moves **and whether the reader floor moves with it**. Nothing lands
    "incidentally".
 2. **Additive optional fields are allowed** without machinery: bump
-   `DATA_MODEL_VERSION`, leave `DATA_MODEL_MIN_READER` untouched, and
+   `DATA_MODEL_VERSION`, leave the reader constants untouched, and
    declare the tolerant read (what an absent value means on docs written
    before the field existed) plus why the field survives an old writer's
    round-trip.
 3. **Renames, removals, and semantic changes are not allowed yet.** They
    require versioned upgrade machinery (per-model normalization steps applied
    on read) that does not exist; until it does, the model may only grow
-   additively. When such a change eventually lands, it raises
-   `DATA_MODEL_MIN_READER` — a declared fence against older readers, shipped
-   only after the fleet story is written.
+   additively. When such a change eventually lands, it raises the affected
+   documents' reader floor — through `DATA_MODEL_MIN_READER` when no reliable
+   marker exists — and ships only after the fleet story is written.
 4. **`DATA_MODEL_VERSION` moves when compatibility reasoning changes** — when
    a reader would need to know which shape it is looking at. A purely
    internal refactor that provably writes an identical tree does not bump.
@@ -251,7 +253,7 @@ floor.
    change the MEANING of existing fields — old readers parse it fine and
    silently misinterpret. That judgment (would an old reader misread, not
    just fail to parse?) is exactly what decides whether
-   `DATA_MODEL_MIN_READER` moves, and no snapshot can make it — each model
+   a feature floor 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
@@ -619,7 +621,7 @@ 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
+baseline (`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,
@@ -702,6 +704,156 @@ its base `date` / `datetime`, so no older code path can write it while skipping
 validation — there is no silent bypass to fence, and the kinds leave the floor
 at 0.
 
+### Model 6 — node semantics and field patch operations
+
+#### Semantics at every definition level
+
+The optional non-empty `semantics[]` field now appears on the workflow root,
+stages, and activities as well as actions. Its engine-owned vocabulary adds
+`signal.positive`, `signal.caution`, and `signal.critical` at every level;
+`custom.<meaning>` is an open, grammar-validated namespace at every level.
+Actions retain their action-only `decision.accept` and `decision.decline`
+values. The values remain advisory and change no execution, gating, transition,
+status, history, or instance state. An absent field retains the generic behavior
+of older definitions.
+
+Manifest feature: `node-semantics` (definition, additive, detectable, floor 0).
+
+Would an old reader misread (rule 5)? No. Definition content has no strict
+read-side parse, and an older engine ignores the optional fields and new
+advisory values. Definition documents are immutable after creation, so an older
+writer never rewrites and drops them. The feature itself remains readable by
+model-0 engines; new writers still stamp the unconditional writer minimum of 4.
+This uses the existing `semantics` slot and extends that same word and shape to
+the remaining definition nodes; a sibling property would duplicate the
+advisory-meaning mechanism and violate the definition language's
+self-similarity rules.
+
+#### Field patch operations
+
+The stored definition grammar additively admits `field.inc`, `field.dec`, and
+`field.setIfMissing` action ops. Instances may embed the same definition tree
+in `definitionSnapshot`, and effect-completion use records the new discriminator
+in `history[]` rows' `opType`. Missing discriminators retain the historical op
+vocabulary, so documents written before model 6 need no normalization. A
+`field.setIfMissing` whose target already has a value writes no `opApplied` row:
+persisting a targeted no-op would make older provenance and feed readers report
+a field write that never happened.
+
+Manifest feature: `field-patch-ops` (definition + instance,
+additive, detectable, floor 0).
+
+Would an old reader misread these ops (rule 5)? No. An older engine strictly
+parsing or deploying a definition document rejects the unknown discriminator.
+The instance runtime is different: `definitionSnapshot` is decoded without a
+definition-schema parse, so an older engine can reach `applyOp`; its exhaustive
+switch has no matching arm and the commit aborts when the missing summary is
+used to build the audit row. That is a loud runtime failure rather than silent
+execution with different semantics. Definition documents are create-only,
+instance persists preserve the opaque `definitionSnapshot` string, and history
+readers already treat `opType` as an opaque audit label, so the discriminator
+survives an old writer's round trip. Rule 5 fences silent misinterpretation,
+not loud refusal, therefore this detectable feature contributes floor 0 and does
+not raise the writer maximum. The floor does not protect these definitions from
+older runtimes: upgrade every runtime that can process shared workflow data
+before adopting the new ops.
+
+Why could the existing definition vocabulary not carry the behavior (definition
+language rule 8)? Incrementing requires a read-modify-write primitive, while
+`ValueExpr` deliberately describes context-free reads and has no arithmetic.
+The existing `field.set` cannot atomically derive its value from the current
+number. Conditional initialization also has no existing field-op equivalent:
+an action-level `when` gates every op and effect in the action, while
+`initialValue` runs only when an entry is first resolved and cannot initialize a
+value cleared later by `field.unset`. These additions are new values in the
+existing `ops[].type` slot and reuse the established field target and
+value-expression shapes. Their abbreviated names deliberately mirror
+`@sanity/client`'s patch vocabulary (`setIfMissing`, `inc`, `dec`) as one trio;
+definition authors who know Sanity patches can predict the workflow spellings.
+
+### Model 7 — the `$attributes` condition variable (reader floor: 4)
+
+One additive growth of the condition dialect ships as model 7. It does not
+raise the reader floor; the writer maximum stays 4.
+
+A new caller-bound synthetic variable `$attributes` binds the acting token's
+org-level User Attributes (Enterprise) as a flat key → active-value record —
+the same values lake role filters read via `user::attributes()`, spelled for
+the workflow condition dialect. Soft-gate paths resolve it when a
+caller-bound projection runs (`evaluate` / fireAction filter re-check /
+editField) — project → organization → global-host attributes page with
+`limit=100`, no further pages; warn when the envelope reports `hasMore` —
+parallel to grants on those paths, not on every `resolveAccess`. It is never
+persisted on `Actor` / history, and left unbound (`undefined`) when the fetch
+is an expected absence (401/402/403/404 — non-Enterprise org, missing feature,
+forbidden) so conditions that read it fail closed — the same posture as `$can`
+without grants. Unexpected fetch failures (5xx, network) throw and are not
+cached, so the next soft-gate call retries; ticks and drainers never call the
+endpoint. Legal sites match `$can` (fireAction action filters, activity
+requirements, editable predicates, and those commit re-checks); cascade gates
+and other caller-free sites deploy-reject it.
+
+Manifest feature: `attributes-condition-var` (definition condition dialect,
+additive, unconditional, floor 0).
+
+Would an old reader misread the var (rule 5)? No — an older engine never binds
+`$attributes`, so a GROQ read is null / fail-closed rather than a silent
+misinterpretation of persisted trees. Definitions that mention `$attributes`
+still deploy and evaluate on older engines; gates that depend on it simply
+never pass until the fleet reads model 7. No reader-floor raise.
+
+**Author-predicate shadowing (model ≤6 → 7):** `attributes` joins the reserved
+condition-var names, so a **new** predicate named `attributes` is
+deploy-rejected. A definition already stored under model ≤6 that declared
+`predicates.attributes` is a different story: on a model-7 engine that binds
+the caller bag, `$attributes` in that definition flips from “the author
+predicate” to “the synthetic User Attributes bag” with no redeploy. Likely
+zero real instances; no migration. Authors who hit it rename the predicate
+and redeploy.
+
+### Model 8 — role-constrained assignment fields (reader floor: 8)
+
+Assignment-valued field shapes may carry a non-empty `roles` list. The facet
+limits newly written user assignees to project members who fulfil at least one
+listed role, including the definition's role aliases. A collective role
+assignee remains ownership rather than capability and is eligible only when
+its literal role is listed. An absent facet preserves the historical
+unconstrained meaning.
+
+Freshly resolved values and singular replacements validate the complete
+assignment. For plural and composite replacements, stale retention is
+count-bounded per declared assignment location: a candidate may retain no more
+occurrences of one assignment identity than the previous value held at that
+location. Array indices are not part of the location, so removal and reordering
+do not make surviving assignments new; an added copy exceeds the previous count
+and must qualify. An `updateWhere` merge validates every assignment location
+present in its incoming fragment strictly, so a fragment must omit rather than
+restate a stale assignment. Each top-level engine verb uses one project-directory
+snapshot across retries, cascade hops, and spawned children; a later verb reads
+a fresh snapshot.
+
+The property is valid on `assignee` and `assignees` wherever field shapes are
+declared: scope fields, nested object/array shapes, and effect outputs. This
+follows the definition language's existing facet vocabulary: as `types` says
+which documents may occupy a reference slot, `roles` says which people or
+collective roles may occupy an assignment slot. The existing vocabulary could
+not carry this behavior because `editable` governs who may mutate a field,
+while action `roles` governs who may act; neither describes eligible field
+values.
+
+Both stamped trees grow the property: definitions persist it on field shapes,
+and instances copy it onto resolved assignment entries so later writes remain
+self-describing. Model-6 and model-7 writers shipped without this behavior. An
+older reader would preserve the unknown property but silently accept an
+assignee the declaration excludes, so the facet is appended at model 8 rather
+than backfilled into either shipped ledger.
+
+Manifest feature: `role-constrained-assignment-fields` (definition + instance,
+reader-floor, detectable, floor 8). A submitted definition set carrying the
+facet requires acknowledgement 8; a set without it may retain acknowledgement 4. Documents without the facet retain the model-4 floor; only definitions and
+instances whose canonical field tree carries a non-empty `roles` list stamp
+floor 8.
+
 ## Pending governed changes
 
 - **`temp.system.guard` → `system.guard`** — the guard doc type's `temp.`