@sanity/workflow-engine-test 0.11.0 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,70 @@
 # @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
+
+- 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: New `startedInstanceFixture(bench)` — a real, minimal started instance built through the bench's actual verbs, for consumers that need a persisted-shape-valid instance document without caring about its workflow (hand-crafted instance stubs do not pass the engine's read parse).
+- 1321ba5: The bench exposes `evaluateStart` — the engine's pre-flight of `startInstance`'s gates (the `start.allowed` verdict with its insight, plus the still-missing required inputs), delegating to the verb with the bench clock so `$now` reads the frozen instant.
+
+### Patch Changes
+
+- e683875: The bench `queryInScope` doc now describes the scope the engine actually binds: the caller-free rendered scope (every always-bound condition var, `$fields` with the open stage's overlay merged, `$assigned` at its caller-free `false`, and the author's pre-evaluated `$<predicate>` booleans) — the previous enumeration listed a `$subject` param that was never bound.
+- Updated dependencies [f9389e5]
+- Updated dependencies [d0c62ea]
+- Updated dependencies [c3eed2e]
+- Updated dependencies [df4bd80]
+- Updated dependencies [092a0d4]
+- Updated dependencies [5a1a9fe]
+- Updated dependencies [e3a7ba2]
+- Updated dependencies [30fed9e]
+- Updated dependencies [1321ba5]
+- Updated dependencies [e683875]
+- Updated dependencies [a8ace4d]
+  - @sanity/workflow-engine@0.17.0
+
 ## 0.11.0
 
 ### Minor Changes

package/README.md

@@ -18,7 +18,9 @@ npm install -D @sanity/workflow-engine-test
 `createBench()` builds an isolated bench: the real engine, a fake in-memory
 Sanity client, an all-access default actor, and a bench-owned clock. Every
 wrapped verb injects the bench's client, tag, workflow resource, access
-default, and clock, so a test reads as the workflow it exercises:
+default, clock, and cross-resource resolver (`serveResources` sugar for
+same-store dataset siblings, raw `resourceClients` for anything else), so a
+test reads as the workflow it exercises:
 
 - **Runtime verbs** — `deployDefinitions`, `deleteDefinition`, `startInstance`,
   `fireAction`, `editField`, `completeEffect` (and `completePendingEffect`,
@@ -28,14 +30,14 @@ default, and clock, so a test reads as the workflow it exercises:
   not wall-clock.
 - **Reads and probes** — `getInstance`, `currentStage`, `activityStatus`,
   `listPendingEffects`, `findPendingEffects`, `children`, `instancesForSubject`,
-  `instancesByStage`, `instancesForDocument`, `definitionsForDocument`, `query`,
-  plus the guard helpers below. Helpers sharing an engine verb's name take the
-  engine's own args objects and throw its typed errors — bench reads and engine
-  reads cannot drift.
+  `instancesByStage`, `instancesForDocument`, `definitionsForDocument`,
+  `evaluateStart`, `query`, plus the guard helpers below. Helpers sharing an
+  engine verb's name take the engine's own args objects and throw its typed
+  errors — bench reads and engine reads cannot drift.
 
 ```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',
@@ -70,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

@@ -4,7 +4,7 @@ Object.defineProperty(exports, "__esModule", {
     value: !0
 });
 
-var workflowEngine = require("@sanity/workflow-engine"), clientFakeForTest = require("@sanity-labs/client-fake-for-test");
+var workflowEngine = require("@sanity/workflow-engine"), clientFakeForTest = require("@sanity-labs/client-fake-for-test"), define = require("@sanity/workflow-engine/define");
 
 const DEFAULT_WORKFLOW_RESOURCE = {
     type: "dataset",
@@ -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
@@ -327,6 +327,13 @@ function createReadHelpers(scope) {
                 clock: clock
             } : {}
         }),
+        evaluateStart: args => workflowEngine.workflow.evaluateStart({
+            ...engineScope,
+            ...args,
+            ...clock !== void 0 ? {
+                clock: clock
+            } : {}
+        }),
         snapshot: () => client.snapshot()
     };
 }
@@ -335,6 +342,9 @@ function createBenchEngine(bench, overrides = {}) {
     return workflowEngine.createEngine({
         client: bench.client,
         workflowResource: bench.workflowResource,
+        ...bench.resourceClients !== void 0 ? {
+            resourceClients: bench.resourceClients
+        } : {},
         tag: bench.tag,
         clock: bench.now,
         executionContext: bench.executionContext,
@@ -344,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,
@@ -354,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",
@@ -365,6 +387,35 @@ function releaseField(releaseName, opts) {
     };
 }
 
+async function startedInstanceFixture(bench, opts) {
+    const flow = define.defineWorkflow({
+        name: "fixture-flow",
+        title: "Fixture flow",
+        initialStage: "review",
+        stages: [ {
+            name: "review",
+            transitions: [ {
+                name: "go",
+                to: "done",
+                when: "false"
+            } ]
+        }, {
+            name: "done"
+        } ]
+    });
+    await bench.deployDefinitions({
+        expectedMinReaderModel: 2,
+        definitions: [ flow ]
+    });
+    const {instance: instance} = await bench.startInstance({
+        definition: flow.name,
+        ...opts?.instanceId !== void 0 ? {
+            instanceId: opts.instanceId
+        } : {}
+    });
+    return instance;
+}
+
 function createBench(options = {}) {
     const tag = options.tag ?? BENCH_TAG;
     workflowEngine.validateTag(tag);
@@ -376,10 +427,16 @@ function createBench(options = {}) {
             documents: options.documents
         } : {},
         defaultAccess: access
-    }), identities = createIdentityDirectory(client), scope = {
+    }), identities = createIdentityDirectory(client), resourceClients = benchResourceClients({
+        client: client,
+        options: options
+    }), scope = {
         client: client,
         tag: tag,
         workflowResource: workflowResource,
+        ...resourceClients !== void 0 ? {
+            resourceClients: resourceClients
+        } : {},
         executionContext: options.executionContext ?? {
             kind: workflowEngine.EXECUTION_KINDS.test
         }
@@ -395,10 +452,7 @@ function createBench(options = {}) {
         clock: clock
     });
     return {
-        client: client,
-        tag: tag,
-        workflowResource: workflowResource,
-        executionContext: scope.executionContext,
+        ...scope,
         access: access,
         currentUser: access.actor,
         grants: access.grants ?? [],
@@ -433,6 +487,17 @@ function createBench(options = {}) {
     };
 }
 
+function benchResourceClients(args) {
+    const {client: client} = args, {serveResources: serveResources, resourceClients: resourceClients} = args.options;
+    if (serveResources === void 0 || serveResources.length === 0) return resourceClients;
+    const nonDataset = serveResources.find(served => served.type !== "dataset");
+    if (nonDataset !== void 0) throw new Error(`createBench: serveResources can only serve dataset siblings of the bench store — got ${nonDataset.type} "${nonDataset.id}". Pass resourceClients for other resource types.`);
+    return parsed => {
+        const target = workflowEngine.resourceFromParsed(parsed);
+        return serveResources.some(served => workflowEngine.sameResource(served, target)) ? client.withConfig(workflowEngine.datasetResourceParts(target.id)) : resourceClients?.(parsed);
+    };
+}
+
 function assertIsoInstant(iso) {
     const ms = Date.parse(iso);
     if (Number.isNaN(ms)) throw new Error(`bench clock: expected an ISO-8601 instant, got ${JSON.stringify(iso)}`);
@@ -453,6 +518,10 @@ exports.createBench = createBench;
 
 exports.createBenchEngine = createBenchEngine;
 
+exports.docRefField = docRefField;
+
 exports.releaseField = releaseField;
 
+exports.startedInstanceFixture = startedInstanceFixture;
+
 exports.subjectField = subjectField;

package/dist/index.d.cts

@@ -15,6 +15,7 @@ import { DeployedDefinition } from "@sanity/workflow-engine";
 import type { EditFieldArgs } from "@sanity/workflow-engine";
 import { Engine } from "@sanity/workflow-engine";
 import type { EvaluateArgs } from "@sanity/workflow-engine";
+import { EvaluateStartArgs } from "@sanity/workflow-engine";
 import { FindPendingEffectsArgs } from "@sanity/workflow-engine";
 import type { FireActionArgs } from "@sanity/workflow-engine";
 import type { Grant } from "@sanity/workflow-engine";
@@ -27,10 +28,13 @@ import { MutationGuardDoc } from "@sanity/workflow-engine";
 import type { OperationArgs } from "@sanity/workflow-engine";
 import { OperationResult } from "@sanity/workflow-engine";
 import { PendingEffect } from "@sanity/workflow-engine";
+import type { ResourceClientResolver } from "@sanity/workflow-engine";
 import type { SetStageArgs } from "@sanity/workflow-engine";
+import { StartEvaluation } from "@sanity/workflow-engine";
 import type { StartInstanceArgs } from "@sanity/workflow-engine";
 import type { TestClient } from "@sanity-labs/client-fake-for-test";
 import type { WorkflowAccess } from "@sanity/workflow-engine";
+import { WorkflowDefinition } from "@sanity/workflow-engine";
 import { WorkflowDefinitionInput } from "@sanity/workflow-engine";
 import { WorkflowEvaluation } from "@sanity/workflow-engine";
 import { WorkflowInstance } from "@sanity/workflow-engine";
@@ -110,6 +114,9 @@ declare interface BenchState {
   tag: string;
   /** The workflow resource every wrapped call targets. */
   workflowResource: WorkflowResource;
+  /** The cross-resource read routing every wrapped call carries, when the
+   *  bench declared any — see {@link CreateBenchOptions.resourceClients}. */
+  resourceClients?: ResourceClientResolver;
   /** The declared execution context stamped on every wrapped call's history
    *  entries (default `{kind: 'test'}`) — inherited by {@link createBenchEngine}. */
   executionContext: DeclaredExecutionContext;
@@ -234,6 +241,23 @@ export declare interface CreateBenchOptions {
    * URIs read as `dataset:test:test:<docId>`.
    */
   workflowResource?: WorkflowResource;
+  /**
+   * Sibling datasets the bench serves (and thereby declares) from its own
+   * store — the common cross-resource case. Each listed resource routes to
+   * a `withConfig`-derived handle over the bench's store, so reads reach it
+   * and runtime-supplied refs into it are admitted. Only `dataset`
+   * resources can be siblings of the bench's store; anything else needs
+   * {@link CreateBenchOptions.resourceClients}.
+   */
+  serveResources?: WorkflowResource[];
+  /**
+   * Cross-resource read routing for the bench engine scope — a served
+   * resource is also part of the declared surface for written refs. The
+   * escape hatch for resolver logic beyond same-store siblings; prefer
+   * {@link CreateBenchOptions.serveResources}, which is consulted first
+   * when both are given. Omit for single-resource benches.
+   */
+  resourceClients?: ResourceClientResolver;
   /**
    * Freeze the bench clock at this ISO instant from construction, so
    * `$now` and every engine timestamp are deterministic. Equivalent to
@@ -252,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
@@ -281,6 +318,7 @@ declare type EngineScope = {
   client: TestClient;
   tag: string;
   workflowResource: WorkflowResource;
+  resourceClients?: ResourceClientResolver;
   executionContext: DeclaredExecutionContext;
 };
 
@@ -306,13 +344,28 @@ declare type EngineWrappers = {
   guardsForDefinition: (definition: string) => Promise<MutationGuardDoc[]>;
 };
 
+/** The slice of a bench {@link startedInstanceFixture} drives — structural,
+ *  so the fixture module needs no import of the bench itself. */
+declare interface FixtureBench {
+  deployDefinitions: (args: {
+    expectedMinReaderModel: 2;
+    definitions: WorkflowDefinition[];
+  }) => Promise<unknown>;
+  startInstance: (args: {
+    definition: string;
+    instanceId?: string;
+  }) => Promise<{
+    instance: WorkflowInstance;
+  }>;
+}
+
 declare type GuardHelpers = {
   /** All deployed guard docs ({@link MutationGuardDoc}) in the store. */
   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,
@@ -358,11 +411,13 @@ declare type QueryHelpers = {
   ) => Promise<T>;
   /**
    * Snapshot-aware GROQ for `instanceId` — runs against the same
-   * in-memory view the engine's filters see. Reserved params (`$self`,
-   * `$subject`, `$parent`, `$ancestors`, `$now`, `$stage`) auto-bound
-   * in GDR URI form. Use to ask "what does the engine see for this
-   * workflow?" — useful for filter debugging, UIs that mirror engine
-   * state, etc.
+   * in-memory view the engine's filters see, with the caller-free
+   * rendered scope auto-bound: every always-bound condition var,
+   * `$fields` with the open stage's overlay merged, `$assigned` at its
+   * caller-free `false`, and the author's pre-evaluated `$<predicate>`
+   * booleans, ids in GDR URI form. Use to ask "what does the engine see
+   * for this workflow?" — useful for filter debugging, UIs that mirror
+   * engine state, etc.
    */
   queryInScope: <T = unknown>({
     instanceId,
@@ -406,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,
@@ -437,12 +492,20 @@ 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
-   * `_type`, `start.filter` passes. All matches, name ascending.
+   * candidate document — startable, the `subject`-kind entry accepts its
+   * `_type`, `start.filter` (browse-time-pure) passes. All matches, name
+   * ascending.
    */
   definitionsForDocument: (
     args: DefinitionsForDocumentArgs,
   ) => Promise<DeployedDefinition[]>;
+  /**
+   * Pre-flight `startInstance`'s gates for a definition + candidate
+   * `initialFields`: the `start.allowed` verdict (with its insight) plus the
+   * still-missing required inputs — the read a start surface renders before
+   * committing.
+   */
+  evaluateStart: (args: EvaluateStartArgs) => Promise<StartEvaluation>;
   /** Snapshot of all documents in the store — for inspecting the world. */
   snapshot: () => readonly StoreDocument[];
 };
@@ -459,6 +522,20 @@ export declare function releaseField(
   },
 ): InitialFieldValue;
 
+/**
+ * A REAL, minimal started instance — deployed and started through the bench's
+ * actual verbs, parked forever on its first stage. The fixture for consumers
+ * (adapter tests, validation tests) that need a persisted-shape-valid
+ * instance document without caring about its workflow: hand-crafted instance
+ * stubs do not pass the engine's read parse.
+ */
+export declare function startedInstanceFixture(
+  bench: FixtureBench,
+  opts?: {
+    instanceId?: string;
+  },
+): Promise<WorkflowInstance>;
+
 /** A document as stored in the bench's fake lake. */
 declare type StoreDocument = {
   _id: string;
@@ -467,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

@@ -15,6 +15,7 @@ import { DeployedDefinition } from "@sanity/workflow-engine";
 import type { EditFieldArgs } from "@sanity/workflow-engine";
 import { Engine } from "@sanity/workflow-engine";
 import type { EvaluateArgs } from "@sanity/workflow-engine";
+import { EvaluateStartArgs } from "@sanity/workflow-engine";
 import { FindPendingEffectsArgs } from "@sanity/workflow-engine";
 import type { FireActionArgs } from "@sanity/workflow-engine";
 import type { Grant } from "@sanity/workflow-engine";
@@ -27,10 +28,13 @@ import { MutationGuardDoc } from "@sanity/workflow-engine";
 import type { OperationArgs } from "@sanity/workflow-engine";
 import { OperationResult } from "@sanity/workflow-engine";
 import { PendingEffect } from "@sanity/workflow-engine";
+import type { ResourceClientResolver } from "@sanity/workflow-engine";
 import type { SetStageArgs } from "@sanity/workflow-engine";
+import { StartEvaluation } from "@sanity/workflow-engine";
 import type { StartInstanceArgs } from "@sanity/workflow-engine";
 import type { TestClient } from "@sanity-labs/client-fake-for-test";
 import type { WorkflowAccess } from "@sanity/workflow-engine";
+import { WorkflowDefinition } from "@sanity/workflow-engine";
 import { WorkflowDefinitionInput } from "@sanity/workflow-engine";
 import { WorkflowEvaluation } from "@sanity/workflow-engine";
 import { WorkflowInstance } from "@sanity/workflow-engine";
@@ -110,6 +114,9 @@ declare interface BenchState {
   tag: string;
   /** The workflow resource every wrapped call targets. */
   workflowResource: WorkflowResource;
+  /** The cross-resource read routing every wrapped call carries, when the
+   *  bench declared any — see {@link CreateBenchOptions.resourceClients}. */
+  resourceClients?: ResourceClientResolver;
   /** The declared execution context stamped on every wrapped call's history
    *  entries (default `{kind: 'test'}`) — inherited by {@link createBenchEngine}. */
   executionContext: DeclaredExecutionContext;
@@ -234,6 +241,23 @@ export declare interface CreateBenchOptions {
    * URIs read as `dataset:test:test:<docId>`.
    */
   workflowResource?: WorkflowResource;
+  /**
+   * Sibling datasets the bench serves (and thereby declares) from its own
+   * store — the common cross-resource case. Each listed resource routes to
+   * a `withConfig`-derived handle over the bench's store, so reads reach it
+   * and runtime-supplied refs into it are admitted. Only `dataset`
+   * resources can be siblings of the bench's store; anything else needs
+   * {@link CreateBenchOptions.resourceClients}.
+   */
+  serveResources?: WorkflowResource[];
+  /**
+   * Cross-resource read routing for the bench engine scope — a served
+   * resource is also part of the declared surface for written refs. The
+   * escape hatch for resolver logic beyond same-store siblings; prefer
+   * {@link CreateBenchOptions.serveResources}, which is consulted first
+   * when both are given. Omit for single-resource benches.
+   */
+  resourceClients?: ResourceClientResolver;
   /**
    * Freeze the bench clock at this ISO instant from construction, so
    * `$now` and every engine timestamp are deterministic. Equivalent to
@@ -252,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
@@ -281,6 +318,7 @@ declare type EngineScope = {
   client: TestClient;
   tag: string;
   workflowResource: WorkflowResource;
+  resourceClients?: ResourceClientResolver;
   executionContext: DeclaredExecutionContext;
 };
 
@@ -306,13 +344,28 @@ declare type EngineWrappers = {
   guardsForDefinition: (definition: string) => Promise<MutationGuardDoc[]>;
 };
 
+/** The slice of a bench {@link startedInstanceFixture} drives — structural,
+ *  so the fixture module needs no import of the bench itself. */
+declare interface FixtureBench {
+  deployDefinitions: (args: {
+    expectedMinReaderModel: 2;
+    definitions: WorkflowDefinition[];
+  }) => Promise<unknown>;
+  startInstance: (args: {
+    definition: string;
+    instanceId?: string;
+  }) => Promise<{
+    instance: WorkflowInstance;
+  }>;
+}
+
 declare type GuardHelpers = {
   /** All deployed guard docs ({@link MutationGuardDoc}) in the store. */
   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,
@@ -358,11 +411,13 @@ declare type QueryHelpers = {
   ) => Promise<T>;
   /**
    * Snapshot-aware GROQ for `instanceId` — runs against the same
-   * in-memory view the engine's filters see. Reserved params (`$self`,
-   * `$subject`, `$parent`, `$ancestors`, `$now`, `$stage`) auto-bound
-   * in GDR URI form. Use to ask "what does the engine see for this
-   * workflow?" — useful for filter debugging, UIs that mirror engine
-   * state, etc.
+   * in-memory view the engine's filters see, with the caller-free
+   * rendered scope auto-bound: every always-bound condition var,
+   * `$fields` with the open stage's overlay merged, `$assigned` at its
+   * caller-free `false`, and the author's pre-evaluated `$<predicate>`
+   * booleans, ids in GDR URI form. Use to ask "what does the engine see
+   * for this workflow?" — useful for filter debugging, UIs that mirror
+   * engine state, etc.
    */
   queryInScope: <T = unknown>({
     instanceId,
@@ -406,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,
@@ -437,12 +492,20 @@ 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
-   * `_type`, `start.filter` passes. All matches, name ascending.
+   * candidate document — startable, the `subject`-kind entry accepts its
+   * `_type`, `start.filter` (browse-time-pure) passes. All matches, name
+   * ascending.
    */
   definitionsForDocument: (
     args: DefinitionsForDocumentArgs,
   ) => Promise<DeployedDefinition[]>;
+  /**
+   * Pre-flight `startInstance`'s gates for a definition + candidate
+   * `initialFields`: the `start.allowed` verdict (with its insight) plus the
+   * still-missing required inputs — the read a start surface renders before
+   * committing.
+   */
+  evaluateStart: (args: EvaluateStartArgs) => Promise<StartEvaluation>;
   /** Snapshot of all documents in the store — for inspecting the world. */
   snapshot: () => readonly StoreDocument[];
 };
@@ -459,6 +522,20 @@ export declare function releaseField(
   },
 ): InitialFieldValue;
 
+/**
+ * A REAL, minimal started instance — deployed and started through the bench's
+ * actual verbs, parked forever on its first stage. The fixture for consumers
+ * (adapter tests, validation tests) that need a persisted-shape-valid
+ * instance document without caring about its workflow: hand-crafted instance
+ * stubs do not pass the engine's read parse.
+ */
+export declare function startedInstanceFixture(
+  bench: FixtureBench,
+  opts?: {
+    instanceId?: string;
+  },
+): Promise<WorkflowInstance>;
+
 /** A document as stored in the bench's fake lake. */
 declare type StoreDocument = {
   _id: string;
@@ -467,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,7 +1,9 @@
-import { guardsForResource, denyingGuards, MutationGuardDeniedError, workflow, instancesQuery, WORKFLOW_INSTANCE_TYPE, tagScopeFilter, effectOutputsMap, contextMap, createEngine, releaseRef, gdrRef, validateTag, EXECUTION_KINDS } 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";
 
+import { defineWorkflow } from "@sanity/workflow-engine/define";
+
 const DEFAULT_WORKFLOW_RESOURCE = {
     type: "dataset",
     id: "test.test"
@@ -300,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
@@ -323,6 +325,13 @@ function createReadHelpers(scope) {
                 clock: clock
             } : {}
         }),
+        evaluateStart: args => workflow.evaluateStart({
+            ...engineScope,
+            ...args,
+            ...clock !== void 0 ? {
+                clock: clock
+            } : {}
+        }),
         snapshot: () => client.snapshot()
     };
 }
@@ -331,6 +340,9 @@ function createBenchEngine(bench, overrides = {}) {
     return createEngine({
         client: bench.client,
         workflowResource: bench.workflowResource,
+        ...bench.resourceClients !== void 0 ? {
+            resourceClients: bench.resourceClients
+        } : {},
         tag: bench.tag,
         clock: bench.now,
         executionContext: bench.executionContext,
@@ -340,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,
@@ -350,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",
@@ -361,6 +385,35 @@ function releaseField(releaseName, opts) {
     };
 }
 
+async function startedInstanceFixture(bench, opts) {
+    const flow = defineWorkflow({
+        name: "fixture-flow",
+        title: "Fixture flow",
+        initialStage: "review",
+        stages: [ {
+            name: "review",
+            transitions: [ {
+                name: "go",
+                to: "done",
+                when: "false"
+            } ]
+        }, {
+            name: "done"
+        } ]
+    });
+    await bench.deployDefinitions({
+        expectedMinReaderModel: 2,
+        definitions: [ flow ]
+    });
+    const {instance: instance} = await bench.startInstance({
+        definition: flow.name,
+        ...opts?.instanceId !== void 0 ? {
+            instanceId: opts.instanceId
+        } : {}
+    });
+    return instance;
+}
+
 function createBench(options = {}) {
     const tag = options.tag ?? BENCH_TAG;
     validateTag(tag);
@@ -372,10 +425,16 @@ function createBench(options = {}) {
             documents: options.documents
         } : {},
         defaultAccess: access
-    }), identities = createIdentityDirectory(client), scope = {
+    }), identities = createIdentityDirectory(client), resourceClients = benchResourceClients({
+        client: client,
+        options: options
+    }), scope = {
         client: client,
         tag: tag,
         workflowResource: workflowResource,
+        ...resourceClients !== void 0 ? {
+            resourceClients: resourceClients
+        } : {},
         executionContext: options.executionContext ?? {
             kind: EXECUTION_KINDS.test
         }
@@ -391,10 +450,7 @@ function createBench(options = {}) {
         clock: clock
     });
     return {
-        client: client,
-        tag: tag,
-        workflowResource: workflowResource,
-        executionContext: scope.executionContext,
+        ...scope,
         access: access,
         currentUser: access.actor,
         grants: access.grants ?? [],
@@ -429,10 +485,21 @@ function createBench(options = {}) {
     };
 }
 
+function benchResourceClients(args) {
+    const {client: client} = args, {serveResources: serveResources, resourceClients: resourceClients} = args.options;
+    if (serveResources === void 0 || serveResources.length === 0) return resourceClients;
+    const nonDataset = serveResources.find(served => served.type !== "dataset");
+    if (nonDataset !== void 0) throw new Error(`createBench: serveResources can only serve dataset siblings of the bench store — got ${nonDataset.type} "${nonDataset.id}". Pass resourceClients for other resource types.`);
+    return parsed => {
+        const target = resourceFromParsed(parsed);
+        return serveResources.some(served => sameResource(served, target)) ? client.withConfig(datasetResourceParts(target.id)) : resourceClients?.(parsed);
+    };
+}
+
 function assertIsoInstant(iso) {
     const ms = Date.parse(iso);
     if (Number.isNaN(ms)) throw new Error(`bench clock: expected an ISO-8601 instant, got ${JSON.stringify(iso)}`);
     return new Date(ms).toISOString();
 }
 
-export { ALL_ACCESS, ALL_ACCESS_USER, BENCH_TAG, DEFAULT_WORKFLOW_RESOURCE, WILDCARD_GRANTS, createBench, createBenchEngine, releaseField, 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.11.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.16.0"
+    "@sanity/workflow-engine": "0.18.0"
   },
   "devDependencies": {
     "@sanity/client": "^7.22.1",