@sanity/workflow-engine-test 0.7.0 → 0.9.0

package/dist/index.d.cts

@@ -3,15 +3,16 @@ import { Actor } from "@sanity/workflow-engine";
 import type { CompleteEffectArgs } from "@sanity/workflow-engine";
 import { DeployDefinitionsArgs } from "@sanity/workflow-engine";
 import { DeployDefinitionsResult } from "@sanity/workflow-engine";
-import { DispatchResult } from "@sanity/workflow-engine";
 import type { EditFieldArgs } from "@sanity/workflow-engine";
 import type { EvaluateArgs } from "@sanity/workflow-engine";
 import type { FireActionArgs } from "@sanity/workflow-engine";
 import { GdrUri } from "@sanity/workflow-engine";
 import type { Grant } from "@sanity/workflow-engine";
+import { InitialFieldValue } from "@sanity/workflow-engine";
 import { MutationGuardAction } from "@sanity/workflow-engine";
 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 { StartInstanceArgs } from "@sanity/workflow-engine";
 import type { WorkflowAccess } from "@sanity/workflow-engine";
@@ -51,21 +52,16 @@ export declare type Bench = BenchState &
   EngineWrappers &
   ReadHelpers &
   GuardHelpers &
-  QueryHelpers;
+  QueryHelpers &
+  ComposedHelpers;
 
-declare type BenchCompleteEffectArgs = Omit<
-  CompleteEffectArgs,
-  "client" | "tag" | "workflowResource" | "access"
-> & {
+declare type BenchCompleteEffectArgs = Omit<CompleteEffectArgs, "access"> & {
   access?: WorkflowAccess;
   /** Shortcut for `access.actor`. */
   actor?: Actor;
 };
 
-declare type BenchEditFieldArgs = Omit<
-  EditFieldArgs,
-  "client" | "tag" | "workflowResource" | "access"
-> & {
+declare type BenchEditFieldArgs = Omit<EditFieldArgs, "access"> & {
   access?: WorkflowAccess;
   /** Shortcut for `access.actor`. */
   actor?: Actor;
@@ -73,10 +69,7 @@ declare type BenchEditFieldArgs = Omit<
   grants?: Grant[];
 };
 
-declare type BenchEvaluateArgs = Omit<
-  EvaluateArgs,
-  "client" | "tag" | "workflowResource" | "access"
-> & {
+declare type BenchEvaluateArgs = Omit<EvaluateArgs, "access"> & {
   access?: WorkflowAccess;
   /** Shortcut for `access.actor`. */
   actor?: Actor;
@@ -84,10 +77,7 @@ declare type BenchEvaluateArgs = Omit<
   grants?: Grant[];
 };
 
-declare type BenchFireActionArgs = Omit<
-  FireActionArgs,
-  "client" | "tag" | "workflowResource" | "access"
-> & {
+declare type BenchFireActionArgs = Omit<FireActionArgs, "access"> & {
   access?: WorkflowAccess;
   /** Shortcut for `access.actor`. */
   actor?: Actor;
@@ -95,10 +85,7 @@ declare type BenchFireActionArgs = Omit<
   grants?: Grant[];
 };
 
-declare type BenchStartInstanceArgs = Omit<
-  StartInstanceArgs,
-  "client" | "tag" | "workflowResource" | "access"
-> & {
+declare type BenchStartInstanceArgs = Omit<StartInstanceArgs, "access"> & {
   access?: WorkflowAccess;
   /** Shortcut for `access.actor`. */
   actor?: Actor;
@@ -142,10 +129,7 @@ declare interface BenchState {
   advance: (ms: number) => void;
 }
 
-declare type BenchTickArgs = Omit<
-  OperationArgs,
-  "client" | "tag" | "workflowResource" | "access"
-> & {
+declare type BenchTickArgs = Omit<OperationArgs, "access"> & {
   access?: WorkflowAccess;
   /** Shortcut for `access.actor`. */
   actor?: Actor;
@@ -171,6 +155,21 @@ declare interface CallRecord {
   dataset: string;
 }
 
+/** Helpers composed across the wrapper + read groups at bench assembly. */
+declare interface ComposedHelpers {
+  /**
+   * Complete the pending effect named `effect` — {@link EngineWrappers.completeEffect}
+   * with the `effectKey` looked up by name, throwing loud when no such effect
+   * is pending. The idiomatic way to play an external handler reporting its
+   * result; pass `ops` to write outcome fields in the same commit.
+   */
+  completePendingEffect: (
+    args: Omit<BenchCompleteEffectArgs, "effectKey"> & {
+      effect: string;
+    },
+  ) => Promise<OperationResult>;
+}
+
 /**
  * Create a fresh bench. By default the bench is fully isolated — two
  * `createBench()` calls have no shared state. Pass `client` + `tag`
@@ -282,13 +281,13 @@ declare type DocumentValuePermission = "create" | "read" | "update";
 /** Engine-call wrappers that inject the bench-owned client + tag + access. */
 declare type EngineWrappers = {
   deployDefinitions: (
-    args: Omit<DeployDefinitionsArgs, "client" | "tag" | "workflowResource">,
+    args: DeployDefinitionsArgs,
   ) => Promise<DeployDefinitionsResult>;
-  startInstance: (args: BenchStartInstanceArgs) => Promise<WorkflowInstance>;
-  fireAction: (args: BenchFireActionArgs) => Promise<DispatchResult>;
-  editField: (args: BenchEditFieldArgs) => Promise<DispatchResult>;
-  completeEffect: (args: BenchCompleteEffectArgs) => Promise<DispatchResult>;
-  tick: (args: BenchTickArgs) => Promise<DispatchResult>;
+  startInstance: (args: BenchStartInstanceArgs) => Promise<OperationResult>;
+  fireAction: (args: BenchFireActionArgs) => Promise<OperationResult>;
+  editField: (args: BenchEditFieldArgs) => Promise<OperationResult>;
+  completeEffect: (args: BenchCompleteEffectArgs) => Promise<OperationResult>;
+  tick: (args: BenchTickArgs) => Promise<OperationResult>;
   evaluate: (args: BenchEvaluateArgs) => Promise<WorkflowEvaluation>;
   guardsForInstance: (instanceId: string) => Promise<MutationGuardDoc[]>;
   guardsForDefinition: (definition: string) => Promise<MutationGuardDoc[]>;
@@ -382,7 +381,7 @@ declare interface Grant_2 {
 }
 
 declare type GuardHelpers = {
-  /** All deployed `temp.system.guard` docs in the store. */
+  /** 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.
@@ -394,20 +393,18 @@ declare type GuardHelpers = {
     as?: Actor,
   ) => Promise<MutationGuardDoc[]>;
   /**
-   * Write to a document through the client's enforced write seam — the bench
+   * Write to a document through the client's guarded write seam — the bench
    * client gates the write against deployed guards (incl. `identity()`) and
-   * throws `MutationGuardDeniedError` on denial, exactly as the lake would.
-   * `as` routes the write through a token-scoped sibling so `identity()`
-   * resolves to that actor.
+   * throws `MutationGuardDeniedError` on denial — the lake's intended
+   * rejection, simulated by the bench. `as` routes the write through a
+   * token-scoped sibling so `identity()` resolves to that actor.
    */
-  editDocument: (
-    documentId: string,
-    patch: Record<string, unknown>,
-    options?: {
-      action?: MutationGuardAction;
-      as?: Actor;
-    },
-  ) => Promise<StoreDocument>;
+  editDocument: (opts: {
+    documentId: string;
+    patch: Record<string, unknown>;
+    action?: MutationGuardAction;
+    as?: Actor;
+  }) => Promise<StoreDocument>;
 };
 
 /** Result of a mutation when ids are requested for all affected documents. */
@@ -533,11 +530,15 @@ declare type QueryHelpers = {
    * workflow?" — useful for filter debugging, UIs that mirror engine
    * state, etc.
    */
-  queryInScope: <T = unknown>(
-    instanceId: string,
-    groq: string,
-    params?: Record<string, unknown>,
-  ) => Promise<T>;
+  queryInScope: <T = unknown>({
+    instanceId,
+    groq,
+    params,
+  }: {
+    instanceId: string;
+    groq: string;
+    params?: Record<string, unknown>;
+  }) => Promise<T>;
 };
 
 declare type ReadHelpers = {
@@ -584,13 +585,11 @@ declare type ReadHelpers = {
    * completed instances (`completedAt != null`) by default; set
    * `{ openOnly: true }` to filter to in-flight only.
    */
-  instancesByStage: (
-    workflowName: string,
-    stage: string,
-    options?: {
-      openOnly?: boolean;
-    },
-  ) => Promise<WorkflowInstance[]>;
+  instancesByStage: (options: {
+    workflowName: string;
+    stage: string;
+    openOnly?: boolean;
+  }) => Promise<WorkflowInstance[]>;
   /**
    * Every in-flight instance whose reactive watch-set includes `document`
    * (a resource-qualified GDR URI) — the reverse of the forward watch-set.
@@ -650,6 +649,18 @@ declare interface ReleaseDocument extends SanityDocument {
   publishAt?: string;
 }
 
+/**
+ * A `release.ref` entry pointing at `_.releases.<releaseName>` in the bench's
+ * default resource — what a release-targeting workflow's `release` field
+ * expects at start.
+ */
+export declare function releaseField(
+  releaseName: string,
+  opts?: {
+    name?: string;
+  },
+): InitialFieldValue;
+
 declare interface ReleaseMetadata {
   title?: string;
   description?: string;
@@ -737,6 +748,19 @@ declare type StoreDocument = {
   [key: string]: unknown;
 };
 
+/**
+ * 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.
+ */
+export declare function subjectField(
+  documentId: string,
+  opts?: {
+    name?: string;
+    type?: string;
+  },
+): InitialFieldValue;
+
 declare interface SystemFields {
   _rev: string;
   _createdAt: string;

package/dist/index.d.ts

@@ -3,15 +3,16 @@ import { Actor } from "@sanity/workflow-engine";
 import type { CompleteEffectArgs } from "@sanity/workflow-engine";
 import { DeployDefinitionsArgs } from "@sanity/workflow-engine";
 import { DeployDefinitionsResult } from "@sanity/workflow-engine";
-import { DispatchResult } from "@sanity/workflow-engine";
 import type { EditFieldArgs } from "@sanity/workflow-engine";
 import type { EvaluateArgs } from "@sanity/workflow-engine";
 import type { FireActionArgs } from "@sanity/workflow-engine";
 import { GdrUri } from "@sanity/workflow-engine";
 import type { Grant } from "@sanity/workflow-engine";
+import { InitialFieldValue } from "@sanity/workflow-engine";
 import { MutationGuardAction } from "@sanity/workflow-engine";
 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 { StartInstanceArgs } from "@sanity/workflow-engine";
 import type { WorkflowAccess } from "@sanity/workflow-engine";
@@ -51,21 +52,16 @@ export declare type Bench = BenchState &
   EngineWrappers &
   ReadHelpers &
   GuardHelpers &
-  QueryHelpers;
+  QueryHelpers &
+  ComposedHelpers;
 
-declare type BenchCompleteEffectArgs = Omit<
-  CompleteEffectArgs,
-  "client" | "tag" | "workflowResource" | "access"
-> & {
+declare type BenchCompleteEffectArgs = Omit<CompleteEffectArgs, "access"> & {
   access?: WorkflowAccess;
   /** Shortcut for `access.actor`. */
   actor?: Actor;
 };
 
-declare type BenchEditFieldArgs = Omit<
-  EditFieldArgs,
-  "client" | "tag" | "workflowResource" | "access"
-> & {
+declare type BenchEditFieldArgs = Omit<EditFieldArgs, "access"> & {
   access?: WorkflowAccess;
   /** Shortcut for `access.actor`. */
   actor?: Actor;
@@ -73,10 +69,7 @@ declare type BenchEditFieldArgs = Omit<
   grants?: Grant[];
 };
 
-declare type BenchEvaluateArgs = Omit<
-  EvaluateArgs,
-  "client" | "tag" | "workflowResource" | "access"
-> & {
+declare type BenchEvaluateArgs = Omit<EvaluateArgs, "access"> & {
   access?: WorkflowAccess;
   /** Shortcut for `access.actor`. */
   actor?: Actor;
@@ -84,10 +77,7 @@ declare type BenchEvaluateArgs = Omit<
   grants?: Grant[];
 };
 
-declare type BenchFireActionArgs = Omit<
-  FireActionArgs,
-  "client" | "tag" | "workflowResource" | "access"
-> & {
+declare type BenchFireActionArgs = Omit<FireActionArgs, "access"> & {
   access?: WorkflowAccess;
   /** Shortcut for `access.actor`. */
   actor?: Actor;
@@ -95,10 +85,7 @@ declare type BenchFireActionArgs = Omit<
   grants?: Grant[];
 };
 
-declare type BenchStartInstanceArgs = Omit<
-  StartInstanceArgs,
-  "client" | "tag" | "workflowResource" | "access"
-> & {
+declare type BenchStartInstanceArgs = Omit<StartInstanceArgs, "access"> & {
   access?: WorkflowAccess;
   /** Shortcut for `access.actor`. */
   actor?: Actor;
@@ -142,10 +129,7 @@ declare interface BenchState {
   advance: (ms: number) => void;
 }
 
-declare type BenchTickArgs = Omit<
-  OperationArgs,
-  "client" | "tag" | "workflowResource" | "access"
-> & {
+declare type BenchTickArgs = Omit<OperationArgs, "access"> & {
   access?: WorkflowAccess;
   /** Shortcut for `access.actor`. */
   actor?: Actor;
@@ -171,6 +155,21 @@ declare interface CallRecord {
   dataset: string;
 }
 
+/** Helpers composed across the wrapper + read groups at bench assembly. */
+declare interface ComposedHelpers {
+  /**
+   * Complete the pending effect named `effect` — {@link EngineWrappers.completeEffect}
+   * with the `effectKey` looked up by name, throwing loud when no such effect
+   * is pending. The idiomatic way to play an external handler reporting its
+   * result; pass `ops` to write outcome fields in the same commit.
+   */
+  completePendingEffect: (
+    args: Omit<BenchCompleteEffectArgs, "effectKey"> & {
+      effect: string;
+    },
+  ) => Promise<OperationResult>;
+}
+
 /**
  * Create a fresh bench. By default the bench is fully isolated — two
  * `createBench()` calls have no shared state. Pass `client` + `tag`
@@ -282,13 +281,13 @@ declare type DocumentValuePermission = "create" | "read" | "update";
 /** Engine-call wrappers that inject the bench-owned client + tag + access. */
 declare type EngineWrappers = {
   deployDefinitions: (
-    args: Omit<DeployDefinitionsArgs, "client" | "tag" | "workflowResource">,
+    args: DeployDefinitionsArgs,
   ) => Promise<DeployDefinitionsResult>;
-  startInstance: (args: BenchStartInstanceArgs) => Promise<WorkflowInstance>;
-  fireAction: (args: BenchFireActionArgs) => Promise<DispatchResult>;
-  editField: (args: BenchEditFieldArgs) => Promise<DispatchResult>;
-  completeEffect: (args: BenchCompleteEffectArgs) => Promise<DispatchResult>;
-  tick: (args: BenchTickArgs) => Promise<DispatchResult>;
+  startInstance: (args: BenchStartInstanceArgs) => Promise<OperationResult>;
+  fireAction: (args: BenchFireActionArgs) => Promise<OperationResult>;
+  editField: (args: BenchEditFieldArgs) => Promise<OperationResult>;
+  completeEffect: (args: BenchCompleteEffectArgs) => Promise<OperationResult>;
+  tick: (args: BenchTickArgs) => Promise<OperationResult>;
   evaluate: (args: BenchEvaluateArgs) => Promise<WorkflowEvaluation>;
   guardsForInstance: (instanceId: string) => Promise<MutationGuardDoc[]>;
   guardsForDefinition: (definition: string) => Promise<MutationGuardDoc[]>;
@@ -382,7 +381,7 @@ declare interface Grant_2 {
 }
 
 declare type GuardHelpers = {
-  /** All deployed `temp.system.guard` docs in the store. */
+  /** 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.
@@ -394,20 +393,18 @@ declare type GuardHelpers = {
     as?: Actor,
   ) => Promise<MutationGuardDoc[]>;
   /**
-   * Write to a document through the client's enforced write seam — the bench
+   * Write to a document through the client's guarded write seam — the bench
    * client gates the write against deployed guards (incl. `identity()`) and
-   * throws `MutationGuardDeniedError` on denial, exactly as the lake would.
-   * `as` routes the write through a token-scoped sibling so `identity()`
-   * resolves to that actor.
+   * throws `MutationGuardDeniedError` on denial — the lake's intended
+   * rejection, simulated by the bench. `as` routes the write through a
+   * token-scoped sibling so `identity()` resolves to that actor.
    */
-  editDocument: (
-    documentId: string,
-    patch: Record<string, unknown>,
-    options?: {
-      action?: MutationGuardAction;
-      as?: Actor;
-    },
-  ) => Promise<StoreDocument>;
+  editDocument: (opts: {
+    documentId: string;
+    patch: Record<string, unknown>;
+    action?: MutationGuardAction;
+    as?: Actor;
+  }) => Promise<StoreDocument>;
 };
 
 /** Result of a mutation when ids are requested for all affected documents. */
@@ -533,11 +530,15 @@ declare type QueryHelpers = {
    * workflow?" — useful for filter debugging, UIs that mirror engine
    * state, etc.
    */
-  queryInScope: <T = unknown>(
-    instanceId: string,
-    groq: string,
-    params?: Record<string, unknown>,
-  ) => Promise<T>;
+  queryInScope: <T = unknown>({
+    instanceId,
+    groq,
+    params,
+  }: {
+    instanceId: string;
+    groq: string;
+    params?: Record<string, unknown>;
+  }) => Promise<T>;
 };
 
 declare type ReadHelpers = {
@@ -584,13 +585,11 @@ declare type ReadHelpers = {
    * completed instances (`completedAt != null`) by default; set
    * `{ openOnly: true }` to filter to in-flight only.
    */
-  instancesByStage: (
-    workflowName: string,
-    stage: string,
-    options?: {
-      openOnly?: boolean;
-    },
-  ) => Promise<WorkflowInstance[]>;
+  instancesByStage: (options: {
+    workflowName: string;
+    stage: string;
+    openOnly?: boolean;
+  }) => Promise<WorkflowInstance[]>;
   /**
    * Every in-flight instance whose reactive watch-set includes `document`
    * (a resource-qualified GDR URI) — the reverse of the forward watch-set.
@@ -650,6 +649,18 @@ declare interface ReleaseDocument extends SanityDocument {
   publishAt?: string;
 }
 
+/**
+ * A `release.ref` entry pointing at `_.releases.<releaseName>` in the bench's
+ * default resource — what a release-targeting workflow's `release` field
+ * expects at start.
+ */
+export declare function releaseField(
+  releaseName: string,
+  opts?: {
+    name?: string;
+  },
+): InitialFieldValue;
+
 declare interface ReleaseMetadata {
   title?: string;
   description?: string;
@@ -737,6 +748,19 @@ declare type StoreDocument = {
   [key: string]: unknown;
 };
 
+/**
+ * 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.
+ */
+export declare function subjectField(
+  documentId: string,
+  opts?: {
+    name?: string;
+    type?: string;
+  },
+): InitialFieldValue;
+
 declare interface SystemFields {
   _rev: string;
   _createdAt: string;

package/dist/index.js

@@ -1,4 +1,4 @@
-import { guardsForResource, denyingGuards, MutationGuardDeniedError, workflow, WORKFLOW_INSTANCE_TYPE, tagScopeFilter, effectsContextMap, validateTag } from "@sanity/workflow-engine";
+import { guardsForResource, denyingGuards, MutationGuardDeniedError, workflow, instancesQuery, WORKFLOW_INSTANCE_TYPE, tagScopeFilter, effectsContextMap, gdrFromResource, gdrRef, validateTag } from "@sanity/workflow-engine";
 import require$$0 from "tty";
 import require$$1 from "util";
 function escapeRegExp(string2) {
@@ -5010,7 +5010,7 @@ const DEFAULT_WORKFLOW_RESOURCE = {
   type: "dataset",
   id: "test.test"
 }, ALL_ACCESS_USER = {
-  kind: "user",
+  kind: "person",
   id: "bench-user",
   roles: ["*"]
 }, WILDCARD_GRANTS = [
@@ -5069,7 +5069,11 @@ function resolveBenchAccess(options) {
     grants: options.grants ?? WILDCARD_GRANTS
   };
 }
-function accessFor(access, args, canTokenResolve) {
+function accessFor({
+  access,
+  args,
+  canTokenResolve
+}) {
   if (args.access !== void 0) return args.access;
   if (args.actor === void 0 && args.grants === void 0) return access;
   const inheritedGrants = canTokenResolve ? void 0 : access.grants, grants = args.grants ?? inheritedGrants;
@@ -5082,10 +5086,14 @@ function stripAccessShortcuts(args) {
   const rest = { ...args };
   return delete rest.access, delete rest.actor, delete rest.grants, rest;
 }
-function createEngineWrappers(scope, access, clock) {
+function createEngineWrappers({
+  scope,
+  access,
+  clock
+}) {
   const canTokenResolve = "request" in scope.client, withAccess = (args) => ({
     ...scope,
-    access: accessFor(access, args, canTokenResolve),
+    access: accessFor({ access, args, canTokenResolve }),
     clock,
     ...stripAccessShortcuts(args)
   });
@@ -5117,8 +5125,8 @@ function createGuardHelpers(client) {
         ...as ? { identity: as.id } : {}
       });
     },
-    editDocument: async (documentId, patch, editOptions) => {
-      const action = editOptions?.action ?? "update", as = editOptions?.as, writer = as ? client.withConfig({
+    editDocument: async ({ documentId, patch, action: editAction, as }) => {
+      const action = editAction ?? "update", writer = as ? client.withConfig({
         accessControl: { currentUser: { id: as.id }, grants: WILDCARD_GRANTS }
       }) : client;
       return action === "delete" ? await writer.delete(documentId) : await writer.patch(documentId).set(patch).commit(), await client.getDocument(documentId);
@@ -5129,7 +5137,11 @@ function createQueryHelpers(scope) {
   const withParams = (params) => params !== void 0 ? { params } : {};
   return {
     query: (groq, params) => workflow.query({ ...scope, groq, ...withParams(params) }),
-    queryInScope: (instanceId, groq, params) => workflow.queryInScope({ ...scope, instanceId, groq, ...withParams(params) })
+    queryInScope: ({
+      instanceId,
+      groq,
+      params
+    }) => workflow.queryInScope({ ...scope, instanceId, groq, ...withParams(params) })
   };
 }
 function createReadHelpers(scope) {
@@ -5168,24 +5180,49 @@ function createReadHelpers(scope) {
         { ref: subjectRef, entry: entryName, tag }
       )
     ),
-    instancesByStage: async (workflowName, stage, queryOptions) => {
-      const filter = queryOptions?.openOnly ? " && completedAt == null" : "";
-      return client.fetch(
-        `*[_type == "${WORKFLOW_INSTANCE_TYPE}" && definition == $wf && currentStage == $stage && ${tagScopeFilter()}${filter}]
-          | order(startedAt asc)`,
-        { wf: workflowName, stage, tag }
-      );
+    instancesByStage: async ({ workflowName, stage, openOnly }) => {
+      const { query, params } = instancesQuery({
+        tag,
+        filter: { definition: workflowName, stage, includeCompleted: !openOnly }
+      });
+      return client.fetch(query, params);
     },
     instancesForDocument: async (document2) => workflow.instancesForDocument({ ...scope, document: document2 }),
     snapshot: () => client.snapshot()
   };
 }
+function subjectField(documentId, opts) {
+  return {
+    type: "doc.ref",
+    name: opts?.name ?? "subject",
+    value: gdrRef({
+      res: DEFAULT_WORKFLOW_RESOURCE,
+      documentId,
+      type: opts?.type ?? "document"
+    })
+  };
+}
+function releaseField(releaseName, opts) {
+  return {
+    type: "release.ref",
+    name: opts?.name ?? "release",
+    value: {
+      id: gdrFromResource(DEFAULT_WORKFLOW_RESOURCE, `_.releases.${releaseName}`),
+      type: "system.release",
+      releaseName
+    }
+  };
+}
 function createBench(options = {}) {
   const tag = options.tag ?? "bench";
   validateTag(tag);
-  const workflowResource = options.workflowResource ?? DEFAULT_WORKFLOW_RESOURCE, client = resolveBenchClient(options), scope = { client, tag, workflowResource }, access = resolveBenchAccess(options);
+  const workflowResource = options.workflowResource ?? DEFAULT_WORKFLOW_RESOURCE, client = resolveBenchClient(options), scope = {
+    client,
+    tag,
+    workflowResource
+  }, access = resolveBenchAccess(options);
   let frozenNow = options.now !== void 0 ? assertIsoInstant(options.now) : void 0;
-  const clock = () => frozenNow ?? (/* @__PURE__ */ new Date()).toISOString();
+  const clock = () => frozenNow ?? (/* @__PURE__ */ new Date()).toISOString(), engine = createEngineWrappers({ scope, access, clock }), reads = createReadHelpers(scope);
   return {
     client,
     access,
@@ -5201,10 +5238,16 @@ function createBench(options = {}) {
         throw new Error(`bench.advance: ms must be a finite number, got ${ms2}`);
       frozenNow = new Date(Date.parse(frozenNow ?? (/* @__PURE__ */ new Date()).toISOString()) + ms2).toISOString();
     },
-    ...createEngineWrappers(scope, access, clock),
-    ...createReadHelpers(scope),
+    ...engine,
+    ...reads,
     ...createGuardHelpers(client),
-    ...createQueryHelpers(scope)
+    ...createQueryHelpers(scope),
+    completePendingEffect: async ({ effect, ...rest }) => {
+      const match = (await reads.pendingEffects(rest.instanceId)).find((e) => e.name === effect);
+      if (match === void 0)
+        throw new Error(`completePendingEffect: no pending effect named "${effect}"`);
+      return engine.completeEffect({ ...rest, effectKey: match._key });
+    }
   };
 }
 function assertIsoInstant(iso) {
@@ -5218,6 +5261,8 @@ export {
   ALL_ACCESS_USER,
   DEFAULT_WORKFLOW_RESOURCE,
   WILDCARD_GRANTS,
-  createBench
+  createBench,
+  releaseField,
+  subjectField
 };
 //# sourceMappingURL=index.js.map