@sanity/workflow-engine-test 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # @sanity/workflow-engine-test
 
+## 0.13.0
+
+### Minor Changes
+
+- 00c089d: **BREAKING:** Require every definition deployment and workflow deployment configuration to state an `expectedMinReaderModel` literal that exactly matches the installed engine's writer capability.
+
+  Deploy and definition-diff paths now reject missing or stale acknowledgements before client access or telemetry, with a structured error and readers-first rollout guidance.
+
+- 55a54b3: Surfaces understand the new `subject` field kind. Studio plugin: the start dialog's default subject seed lands on a definition's `subject`-kind entry whatever it is named (the doc.ref-named-`subject` convention stays the fallback), subject entries get the document picker / read-only face / state-panel preview / document pill, and mapping validation checks the subject entry's `types` facet. MCP: the subject lookup behind title enrichment prefers the `subject`-kind entry and keeps the name convention as fallback; the authoring guide teaches the kind. Test bench — **BREAKING:** `subjectField` now builds a `subject`-KIND entry value (matching its name and the engine's subject rule); a definition declaring the doc.ref convention needs the new `docRefField(documentId, {name})` instead. `instancesForSubject` matches both single-ref kinds.
+
+### Patch Changes
+
+- 71cd58e: Explain that effect-completion field operations require an explicit workflow or stage target scope when validation rejects a missing scope, and document the requirement on `EffectHandler`.
+- 9126299: **BREAKING:** Delete persisted stage guard documents when their stage exits, and remove the lifted-record `GUARD_LIFTED_PREDICATE` and `isGuardLifted` exports.
+
+  Guard deletion now uses the observed document revision so stale exit reconciliation cannot delete a guard reactivated by a newer stage visit. Reactive guard streams contain only active persisted guards.
+
+- Updated dependencies [239d9f6]
+- Updated dependencies [3af2ca0]
+- Updated dependencies [7276702]
+- Updated dependencies [58f8211]
+- Updated dependencies [00c089d]
+- Updated dependencies [71cd58e]
+- Updated dependencies [cd03973]
+- Updated dependencies [d26cc1a]
+- Updated dependencies [9126299]
+- Updated dependencies [72018af]
+- Updated dependencies [5cd8ffd]
+- Updated dependencies [b82bda4]
+- Updated dependencies [55a54b3]
+- Updated dependencies [b82bda4]
+- Updated dependencies [4490442]
+- Updated dependencies [1540dce]
+  - @sanity/workflow-engine@0.18.0
+
 ## 0.12.0
 
 ### Minor Changes

package/README.md

@@ -37,7 +37,7 @@ test reads as the workflow it exercises:
 
 ```ts
 const bench = createBench({now: '2026-01-01T00:00:00Z'})
-await bench.deployDefinitions({definitions: [reviewWorkflow]})
+await bench.deployDefinitions({expectedMinReaderModel: 2, definitions: [reviewWorkflow]})
 
 const {instance} = await bench.startInstance({
   definition: 'review-workflow',
@@ -72,7 +72,7 @@ raw `workflow.*` calls, and the default tag ships as the `BENCH_TAG` constant.
 ## Mutation guards
 
 A workflow stage can deploy **mutation guards** — `temp.system.guard` documents
-that lock the documents it governs while the stage is active, and lift when it
+that lock the documents it governs while the stage is active, and are deleted when it
 exits. The lake does not enforce this doc type yet: in production, guard
 enforcement is the engine's own **optimistic** evaluation (advisory verdicts
 and engine-side write denials), and the lake ACL is the only hard boundary.

package/dist/index.cjs

@@ -304,7 +304,7 @@ function createReadHelpers(scope) {
             ...engineScope,
             ...args
         }),
-        instancesForSubject: async (subjectRef, entryName = "subject") => client.fetch(`*[_type == "${workflowEngine.WORKFLOW_INSTANCE_TYPE}"\n          && fields[_type == "doc.ref" && name == $entry][0].value.id == $ref\n          && ${workflowEngine.tagScopeFilter()}] | order(startedAt asc)`, {
+        instancesForSubject: async (subjectRef, entryName = "subject") => client.fetch(`*[_type == "${workflowEngine.WORKFLOW_INSTANCE_TYPE}"\n          && fields[_type in ["doc.ref", "subject"] && name == $entry][0].value.id == $ref\n          && ${workflowEngine.tagScopeFilter()}] | order(startedAt asc)`, {
             ref: subjectRef,
             entry: entryName,
             tag: tag
@@ -354,7 +354,7 @@ function createBenchEngine(bench, overrides = {}) {
 
 function subjectField(documentId, opts) {
     return {
-        type: "doc.ref",
+        type: "subject",
         name: opts?.name ?? "subject",
         value: workflowEngine.gdrRef({
             res: DEFAULT_WORKFLOW_RESOURCE,
@@ -364,6 +364,18 @@ function subjectField(documentId, opts) {
     };
 }
 
+function docRefField(documentId, opts) {
+    return {
+        type: "doc.ref",
+        name: opts.name,
+        value: workflowEngine.gdrRef({
+            res: DEFAULT_WORKFLOW_RESOURCE,
+            documentId: documentId,
+            type: opts.type ?? "document"
+        })
+    };
+}
+
 function releaseField(releaseName, opts) {
     return {
         type: "release.ref",
@@ -392,6 +404,7 @@ async function startedInstanceFixture(bench, opts) {
         } ]
     });
     await bench.deployDefinitions({
+        expectedMinReaderModel: 2,
         definitions: [ flow ]
     });
     const {instance: instance} = await bench.startInstance({
@@ -505,6 +518,8 @@ exports.createBench = createBench;
 
 exports.createBenchEngine = createBenchEngine;
 
+exports.docRefField = docRefField;
+
 exports.releaseField = releaseField;
 
 exports.startedInstanceFixture = startedInstanceFixture;

package/dist/index.d.cts

@@ -276,6 +276,19 @@ export declare interface CreateBenchOptions {
 /** Default workflow resource for benches that don't pass one. */
 export declare const DEFAULT_WORKFLOW_RESOURCE: WorkflowResource;
 
+/**
+ * A plain `doc.ref` entry value in the bench's default resource — for
+ * document-reference inputs that are NOT the workflow's subject (the
+ * `subject` kind is what marks THE subject; see {@link subjectField}).
+ */
+export declare function docRefField(
+  documentId: string,
+  opts: {
+    name: string;
+    type?: string;
+  },
+): InitialFieldValue;
+
 /**
  * The write {@link GuardHelpers.editDocument} performs. Every arm is a real
  * distinct client write the guard seam vets under that action — `create` is
@@ -335,6 +348,7 @@ declare type EngineWrappers = {
  *  so the fixture module needs no import of the bench itself. */
 declare interface FixtureBench {
   deployDefinitions: (args: {
+    expectedMinReaderModel: 2;
     definitions: WorkflowDefinition[];
   }) => Promise<unknown>;
   startInstance: (args: {
@@ -350,8 +364,8 @@ declare type GuardHelpers = {
   listGuards: () => Promise<MutationGuardDoc[]>;
   /**
    * Guards that would deny an arbitrary edit to `documentId` right now (i.e.
-   * active locks). Probes by changing every non-system field; a lifted guard
-   * (predicate `"true"`) returns nothing.
+   * active locks). Probes by changing every non-system field; a guard whose
+   * predicate is `"true"` returns nothing.
    */
   activeGuardsForDocument: (
     documentId: string,
@@ -447,10 +461,10 @@ declare type ReadHelpers = {
    */
   children: (args: ChildrenArgs) => Promise<WorkflowInstance[]>;
   /**
-   * All workflow instances whose `doc.ref` field entry named
-   * `entryName` (default `"subject"`) matches the given doc id. Useful
-   * for "what workflow is running on this document?" questions. Pass
-   * `entryName` for workflows whose subject entry uses a different name.
+   * All workflow instances whose single-ref field entry (`subject` kind or
+   * `doc.ref`) named `entryName` (default `"subject"`) matches the given doc
+   * id. Useful for "what workflow is running on this document?" questions.
+   * Pass `entryName` for workflows whose subject entry uses a different name.
    */
   instancesForSubject: (
     subjectRef: string,
@@ -478,7 +492,7 @@ declare type ReadHelpers = {
   /**
    * The startable half of {@link ReadHelpers.instancesForDocument}: the
    * latest deployed version of every definition applicable to the LOADED
-   * candidate document — startable, a required subject entry accepts its
+   * candidate document — startable, the `subject`-kind entry accepts its
    * `_type`, `start.filter` (browse-time-pure) passes. All matches, name
    * ascending.
    */
@@ -530,9 +544,12 @@ declare type StoreDocument = {
 };
 
 /**
- * The conventional workflow-scope `subject` doc.ref entry, keyed by a bare
- * doc id in the bench's default resource. `type` defaults to `'document'`;
- * pass the subject's schema type when a filter or projection reads it.
+ * A workflow-scope `subject`-KIND entry value, keyed by a bare doc id in the
+ * bench's default resource — what a definition declaring the first-class
+ * `subject` kind expects at start (applicability and document pickers key on
+ * that kind). `type` defaults to `'document'`; pass the subject's schema
+ * type when a filter or projection reads it. For a plain `doc.ref` input,
+ * use {@link docRefField}.
  */
 export declare function subjectField(
   documentId: string,

package/dist/index.d.ts

@@ -276,6 +276,19 @@ export declare interface CreateBenchOptions {
 /** Default workflow resource for benches that don't pass one. */
 export declare const DEFAULT_WORKFLOW_RESOURCE: WorkflowResource;
 
+/**
+ * A plain `doc.ref` entry value in the bench's default resource — for
+ * document-reference inputs that are NOT the workflow's subject (the
+ * `subject` kind is what marks THE subject; see {@link subjectField}).
+ */
+export declare function docRefField(
+  documentId: string,
+  opts: {
+    name: string;
+    type?: string;
+  },
+): InitialFieldValue;
+
 /**
  * The write {@link GuardHelpers.editDocument} performs. Every arm is a real
  * distinct client write the guard seam vets under that action — `create` is
@@ -335,6 +348,7 @@ declare type EngineWrappers = {
  *  so the fixture module needs no import of the bench itself. */
 declare interface FixtureBench {
   deployDefinitions: (args: {
+    expectedMinReaderModel: 2;
     definitions: WorkflowDefinition[];
   }) => Promise<unknown>;
   startInstance: (args: {
@@ -350,8 +364,8 @@ declare type GuardHelpers = {
   listGuards: () => Promise<MutationGuardDoc[]>;
   /**
    * Guards that would deny an arbitrary edit to `documentId` right now (i.e.
-   * active locks). Probes by changing every non-system field; a lifted guard
-   * (predicate `"true"`) returns nothing.
+   * active locks). Probes by changing every non-system field; a guard whose
+   * predicate is `"true"` returns nothing.
    */
   activeGuardsForDocument: (
     documentId: string,
@@ -447,10 +461,10 @@ declare type ReadHelpers = {
    */
   children: (args: ChildrenArgs) => Promise<WorkflowInstance[]>;
   /**
-   * All workflow instances whose `doc.ref` field entry named
-   * `entryName` (default `"subject"`) matches the given doc id. Useful
-   * for "what workflow is running on this document?" questions. Pass
-   * `entryName` for workflows whose subject entry uses a different name.
+   * All workflow instances whose single-ref field entry (`subject` kind or
+   * `doc.ref`) named `entryName` (default `"subject"`) matches the given doc
+   * id. Useful for "what workflow is running on this document?" questions.
+   * Pass `entryName` for workflows whose subject entry uses a different name.
    */
   instancesForSubject: (
     subjectRef: string,
@@ -478,7 +492,7 @@ declare type ReadHelpers = {
   /**
    * The startable half of {@link ReadHelpers.instancesForDocument}: the
    * latest deployed version of every definition applicable to the LOADED
-   * candidate document — startable, a required subject entry accepts its
+   * candidate document — startable, the `subject`-kind entry accepts its
    * `_type`, `start.filter` (browse-time-pure) passes. All matches, name
    * ascending.
    */
@@ -530,9 +544,12 @@ declare type StoreDocument = {
 };
 
 /**
- * The conventional workflow-scope `subject` doc.ref entry, keyed by a bare
- * doc id in the bench's default resource. `type` defaults to `'document'`;
- * pass the subject's schema type when a filter or projection reads it.
+ * A workflow-scope `subject`-KIND entry value, keyed by a bare doc id in the
+ * bench's default resource — what a definition declaring the first-class
+ * `subject` kind expects at start (applicability and document pickers key on
+ * that kind). `type` defaults to `'document'`; pass the subject's schema
+ * type when a filter or projection reads it. For a plain `doc.ref` input,
+ * use {@link docRefField}.
  */
 export declare function subjectField(
   documentId: string,

package/dist/index.js

@@ -1,4 +1,4 @@
-import { guardsForResource, denyingGuards, MutationGuardDeniedError, workflow, instancesQuery, WORKFLOW_INSTANCE_TYPE, tagScopeFilter, effectOutputsMap, contextMap, createEngine, releaseRef, gdrRef, validateTag, EXECUTION_KINDS, resourceFromParsed, sameResource, datasetResourceParts } from "@sanity/workflow-engine";
+import { guardsForResource, denyingGuards, MutationGuardDeniedError, workflow, instancesQuery, WORKFLOW_INSTANCE_TYPE, tagScopeFilter, effectOutputsMap, contextMap, createEngine, gdrRef, releaseRef, validateTag, EXECUTION_KINDS, resourceFromParsed, sameResource, datasetResourceParts } from "@sanity/workflow-engine";
 
 import { createTestClient, defaultAclPath, isDraftId, isVersionId } from "@sanity-labs/client-fake-for-test";
 
@@ -302,7 +302,7 @@ function createReadHelpers(scope) {
             ...engineScope,
             ...args
         }),
-        instancesForSubject: async (subjectRef, entryName = "subject") => client.fetch(`*[_type == "${WORKFLOW_INSTANCE_TYPE}"\n          && fields[_type == "doc.ref" && name == $entry][0].value.id == $ref\n          && ${tagScopeFilter()}] | order(startedAt asc)`, {
+        instancesForSubject: async (subjectRef, entryName = "subject") => client.fetch(`*[_type == "${WORKFLOW_INSTANCE_TYPE}"\n          && fields[_type in ["doc.ref", "subject"] && name == $entry][0].value.id == $ref\n          && ${tagScopeFilter()}] | order(startedAt asc)`, {
             ref: subjectRef,
             entry: entryName,
             tag: tag
@@ -352,7 +352,7 @@ function createBenchEngine(bench, overrides = {}) {
 
 function subjectField(documentId, opts) {
     return {
-        type: "doc.ref",
+        type: "subject",
         name: opts?.name ?? "subject",
         value: gdrRef({
             res: DEFAULT_WORKFLOW_RESOURCE,
@@ -362,6 +362,18 @@ function subjectField(documentId, opts) {
     };
 }
 
+function docRefField(documentId, opts) {
+    return {
+        type: "doc.ref",
+        name: opts.name,
+        value: gdrRef({
+            res: DEFAULT_WORKFLOW_RESOURCE,
+            documentId: documentId,
+            type: opts.type ?? "document"
+        })
+    };
+}
+
 function releaseField(releaseName, opts) {
     return {
         type: "release.ref",
@@ -390,6 +402,7 @@ async function startedInstanceFixture(bench, opts) {
         } ]
     });
     await bench.deployDefinitions({
+        expectedMinReaderModel: 2,
         definitions: [ flow ]
     });
     const {instance: instance} = await bench.startInstance({
@@ -489,4 +502,4 @@ function assertIsoInstant(iso) {
     return new Date(ms).toISOString();
 }
 
-export { ALL_ACCESS, ALL_ACCESS_USER, BENCH_TAG, DEFAULT_WORKFLOW_RESOURCE, WILDCARD_GRANTS, createBench, createBenchEngine, releaseField, startedInstanceFixture, subjectField };
+export { ALL_ACCESS, ALL_ACCESS_USER, BENCH_TAG, DEFAULT_WORKFLOW_RESOURCE, WILDCARD_GRANTS, createBench, createBenchEngine, docRefField, releaseField, startedInstanceFixture, subjectField };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity/workflow-engine-test",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "In-memory test bench (createBench) for @sanity/workflow-engine.",
   "keywords": [
     "sanity",
@@ -43,7 +43,7 @@
   },
   "dependencies": {
     "@sanity-labs/client-fake-for-test": "^0.8.0",
-    "@sanity/workflow-engine": "0.17.0"
+    "@sanity/workflow-engine": "0.18.0"
   },
   "devDependencies": {
     "@sanity/client": "^7.22.1",