@sanity/workflow-engine-test 0.11.0 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # @sanity/workflow-engine-test
 
+## 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,10 +30,10 @@ 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'})

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",
@@ -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,
@@ -365,6 +375,34 @@ 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({
+        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 +414,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 +439,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 +474,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)}`);
@@ -455,4 +507,6 @@ exports.createBenchEngine = createBenchEngine;
 
 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
@@ -281,6 +305,7 @@ declare type EngineScope = {
   client: TestClient;
   tag: string;
   workflowResource: WorkflowResource;
+  resourceClients?: ResourceClientResolver;
   executionContext: DeclaredExecutionContext;
 };
 
@@ -306,6 +331,20 @@ 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: {
+    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[]>;
@@ -358,11 +397,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,
@@ -438,11 +479,19 @@ 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.
+   * `_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 +508,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;

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
@@ -281,6 +305,7 @@ declare type EngineScope = {
   client: TestClient;
   tag: string;
   workflowResource: WorkflowResource;
+  resourceClients?: ResourceClientResolver;
   executionContext: DeclaredExecutionContext;
 };
 
@@ -306,6 +331,20 @@ 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: {
+    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[]>;
@@ -358,11 +397,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,
@@ -438,11 +479,19 @@ 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.
+   * `_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 +508,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;

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, releaseRef, gdrRef, 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"
@@ -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,
@@ -361,6 +373,34 @@ 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({
+        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 +412,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 +437,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 +472,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, releaseField, startedInstanceFixture, subjectField };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity/workflow-engine-test",
-  "version": "0.11.0",
+  "version": "0.12.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.17.0"
   },
   "devDependencies": {
     "@sanity/client": "^7.22.1",