@sanity/workflow-studio-plugin 0.20.0 → 0.22.0

package/CHANGELOG.md

@@ -1,5 +1,128 @@
 # @sanity/workflow-studio-plugin
 
+## 0.22.0
+
+### Patch Changes
+
+- Updated dependencies [88ba4ba]
+  - @sanity/workflow-engine@0.22.0
+  - @sanity/workflow-components@0.22.0
+  - @sanity/workflow-diagram@0.22.0
+  - @sanity/workflow-react@0.22.0
+  - @sanity/workflow-studio@0.22.0
+
+## 0.21.0
+
+### Minor Changes
+
+- cdba5dc: The Workflows tool's task list now starts instance bands collapsed in the Overview segment (For me keeps them open; document groups stay open in both), and remembers explicit expand/collapse toggles across sessions — tracked per segment, stored in localStorage namespaced by engine resource with a versioned payload and a least-recently-toggled cap, degrading to session-only in-memory state when storage is unavailable. Untouched bands always follow the current defaults.
+- 9b7e918: **BREAKING:** the `sanity` peer dependency floor rises from `^6` to `^6.3.0` — the doc-link verdict rides preview-store APIs first published in Studio 6.3.0.
+
+  Doc-ref faces resolve the referenced document's actual `_type` through one live session store instead of issuing a query per mounted face: every face reading the same document shares a single verdict pipeline into the Studio preview store, which multiplexes all observation over its one global dataset listener with batched hydration. Verdicts are real-time — a document created, published, or deleted mid-session upgrades or demotes its faces as it happens — and remounts (tab switches, dialog opens, list repaints) paint the last verdict instantly while the pipeline re-syncs. Readability gates the verdict: a representation that exists but is unreadable to the current actor fails open (the face is never demoted to "unavailable"), and a document persisted only as a release version resolves through its version document instead of reading as missing.
+
+  The Workflows tool's orphan detection reads the same live store, so it now agrees with the doc-link faces and with a reloaded tool in real time: deleting a document while the tool is open removes its workflow group from the task views and raises the clean-up banner as it happens, and a restored document re-enters the views the same way. Detection stays conservative — only a confirmed no-representation verdict hides a group; in-flight and unreadable observations report nothing, and a failed one keeps its last confirmed verdict — and the settle flow still re-confirms absence with a fresh lake read before anything irreversible fires.
+
+- 809faca: The Workflows tool now detects workflows whose documents have been deleted. Their groups leave the task views (and the document filter), and a banner names how many there are and offers to clean them up after confirmation — under the hood each workflow is aborted where it stands. Detection is conservative: a group counts as orphaned only when every document it presents targets this Studio's content dataset and a lake probe confirms no representation (published, draft, or release version) exists; foreign refs and failed reads keep the group visible. Settling re-confirms absence at run time — a document restored since detection leaves its workflows running, and a failed recheck settles nothing. The summary toast reports each skipped or failed workflow by name, and the run re-probes detection: failed workflows stay detected by the banner for another pass, while a workflow whose document exists again returns to the task views.
+- 38cb271: The plugin logs a UI-engagement telemetry vocabulary through the host Studio's telemetry store — eleven `Editorial Workflows Studio Plugin` events (the surface-qualified prefix keeps them separable from the engine's `Editorial Workflows` outcome events in downstream queries) complementing the engine's outcome vocabulary: surface views (tool and document view with tab attribution, the activity dialog with source attribution, instance detail keyed by instance), the start-dialog funnel (opened vs submitted per entry point, resumes flagged), auto-start runs (silent vs collect, request count), action-control use attributed to its physical surface and overflow-menu path with the UI-visible success flag, todo toggles attributed to their surface and write seam (tick action vs field edit), form-strip clicks, and applied task filters (category keys and value counts only). Payloads carry enums, counts, flags, and the instance id — never customer-authored strings. Events share the host store's session with the engine events, no-op in hosts without a telemetry provider, and a once-per-mount guard keeps StrictMode double-effects from double-counting views.
+
+  Internally, `StartWorkflowRequest` gains a required `source`, and the start controls, `useFireAction`, and `ActivityDetailDialog` gain surface/source props (none are exported package API). Two reads are deliberately not covered: field-editor opens (the per-kind editors share no open seam; the engine's sampled field-edited event covers actual edits) and the instance-detail entry path (tool list, document-view jump-out, and deep link collapse to one router state).
+
+- 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.
+
+- bcc30fe: **BREAKING:** Every surface emits and matches the account-global user id (`sanityUserId`) — the one identity namespace the engine stores. Studio member records carry `sanityUserId` alongside the project-scoped id; the plugin's member/picker views, `useAssignmentIdentity()`, display resolution, and the new `useSelfActor()` join through it once, so pickers, "for me" matching, and self-authored actor stamps all speak global ids. `@sanity/workflow-sdk` gains `useProjectMembers(projectId)`, loading the configured project's human members as assignment rows whose `id` is the global user id (display from project profiles). `@sanity/workflow-components`' `ProjectMember.id` is documented as the account-global id, and the new `projectMemberRow` builder is the one place member-row semantics live (global id preferred, membership-id fallback) — both integrations delegate to it. "For me" and assignment matching compare global ids: instances stored with project-scoped assignees stop matching until their next engine commit self-heals them.
+
+### Patch Changes
+
+- a5b327d: Adapt Studio assignee controls to the reusable picker's controlled value contract.
+- 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.
+
+- Updated dependencies [d9394e5]
+- Updated dependencies [a5b327d]
+- Updated dependencies [a5b327d]
+- Updated dependencies [92e28bd]
+- Updated dependencies [f4bc057]
+- Updated dependencies [bcc30fe]
+- Updated dependencies [e7392af]
+- Updated dependencies [fa9c796]
+- Updated dependencies [bcc30fe]
+  - @sanity/workflow-engine@0.21.0
+  - @sanity/workflow-components@0.21.0
+  - @sanity/workflow-react@0.21.0
+  - @sanity/workflow-studio@0.21.0
+  - @sanity/workflow-diagram@0.21.0
+
 ## 0.20.0
 
 ### Minor Changes

package/README.md

@@ -102,7 +102,7 @@ import {articleReview} from './workflows/article-review'
 export default defineWorkflowConfig({
   deployments: [
     {
-      expectedMinReaderModel: 2,
+      expectedMinReaderModel: 4,
       name: 'production',
       // The tag namespaces all workflow data — the plugin only sees
       // definitions and instances deployed under the tag it's configured with.
@@ -376,6 +376,14 @@ stack — see Sanity's Functions documentation for stack setup. Concurrent
 runtimes are safe: ticks are idempotent, pending effects carry claims, and
 `missingHandler: 'skip'` keeps runtimes out of each other's effects.
 
+A third function is worth considering: deleting a document does not cascade
+into its workflows, so instances whose documents are gone stay in-flight
+until something settles them. The Workflows tool detects these and offers
+to settle them all, but that needs an editor looking; a document-delete
+function settles them the moment the deletion happens, on the robot token —
+see the cookbook recipe
+[Handle a deleted subject document](https://www.sanity.io/docs/editorial-workflows/cookbook-handle-deleted-subject).
+
 ## Limitations
 
 - **Advisory enforcement.** The plugin's gates and locks are UI; only