@sanity/workflow-engine-test 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sanity, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,18 @@
+# @sanity/workflow-engine-test
+
+In-memory test bench (`createBench`) for
+[`@sanity/workflow-engine`](../workflow-engine). Wraps the engine and an
+in-memory Sanity client so workflow tests stay free of client wiring and actor
+boilerplate.
+
+> **Status:** 0.x, internal. Restricted-access package.
+
+## Installation
+
+```bash
+npm install -D @sanity/workflow-engine-test
+```
+
+## License
+
+[MIT](./LICENSE)

package/dist/index.cjs

@@ -0,0 +1,183 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: !0 });
+var workflowEngine = require("@sanity/workflow-engine"), clientFakeForTest = require("@sanity-labs/client-fake-for-test");
+const DEFAULT_WORKFLOW_RESOURCE = {
+  type: "dataset",
+  id: "test.test"
+}, ALL_ACCESS_USER = {
+  kind: "user",
+  id: "bench-user",
+  roles: ["*"]
+}, WILDCARD_GRANTS = [
+  { filter: "true", permissions: ["create", "read", "update"] }
+], ALL_ACCESS = {
+  actor: ALL_ACCESS_USER,
+  grants: WILDCARD_GRANTS
+};
+function resolveBenchClient(options) {
+  if (options.accessControl !== void 0 && options.client !== void 0)
+    throw new Error(
+      "createBench: `accessControl` and `client` are mutually exclusive. Either let the bench build a TestClient configured with the supplied accessControl, or build the client yourself with `createTestClient({ accessControl })` and pass it in."
+    );
+  const client = options.client ?? clientFakeForTest.createTestClient(
+    options.accessControl !== void 0 ? { accessControl: options.accessControl } : {}
+  );
+  return options.documents && client.add(options.documents), client;
+}
+function resolveBenchAccess(options) {
+  return options.access ?? {
+    actor: options.currentUser ?? ALL_ACCESS_USER,
+    grants: options.grants ?? WILDCARD_GRANTS
+  };
+}
+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;
+  return {
+    actor: args.actor ?? access.actor,
+    ...grants !== void 0 ? { grants } : {}
+  };
+}
+function stripAccessShortcuts(args) {
+  const rest = { ...args };
+  return delete rest.access, delete rest.actor, delete rest.grants, rest;
+}
+function createEngineWrappers(scope, access) {
+  const canTokenResolve = "request" in scope.client, withAccess = (args) => ({
+    ...scope,
+    access: accessFor(access, args, canTokenResolve),
+    ...stripAccessShortcuts(args)
+  });
+  return {
+    deployDefinitions: (args) => workflowEngine.workflow.deployDefinitions({ ...scope, ...args }),
+    startInstance: (args) => workflowEngine.workflow.startInstance(withAccess(args)),
+    fireAction: (args) => workflowEngine.workflow.fireAction(withAccess(args)),
+    completeEffect: (args) => workflowEngine.workflow.completeEffect(withAccess(args)),
+    tick: (args) => workflowEngine.workflow.tick(withAccess(args)),
+    evaluate: (args) => workflowEngine.workflow.evaluate(withAccess(args))
+  };
+}
+function createGuardHelpers(client) {
+  const fetchGuards = () => client.fetch('*[_type == "temp.system.guard"]'), guardDocRef = (documentId, before) => ({
+    id: documentId,
+    ...before?._type ? { type: before._type } : {}
+  });
+  return {
+    listGuards: () => client.fetch('*[_type == "temp.system.guard"] | order(_id asc)'),
+    activeGuardsForDocument: async (documentId, as) => {
+      const guards = await fetchGuards(), before = await client.getDocument(documentId), after = { ...before ?? { _id: documentId, _type: "unknown" } };
+      for (const key of Object.keys(after))
+        key.startsWith("_") || (after[key] = { __guardProbe: !0 });
+      return after.__guardProbe = { __guardProbe: !0 }, workflowEngine.denyingGuards({
+        guards,
+        doc: guardDocRef(documentId, before),
+        context: {
+          before: before ?? null,
+          after,
+          action: "update",
+          ...as ? { identity: as.id } : {}
+        }
+      });
+    },
+    editDocument: async (documentId, patch, editOptions) => {
+      const action = editOptions?.action ?? "update", as = editOptions?.as, before = await client.getDocument(documentId), after = action === "delete" ? null : { ...before ?? { _id: documentId, _type: "unknown" }, ...patch }, guards = await fetchGuards(), denied = await workflowEngine.denyingGuards({
+        guards,
+        doc: guardDocRef(documentId, before),
+        context: {
+          before: before ?? null,
+          after,
+          action,
+          ...as ? { identity: as.id } : {}
+        }
+      });
+      if (denied.length > 0)
+        throw new workflowEngine.MutationGuardDeniedError({
+          documentId,
+          action,
+          denied: denied.map((g) => ({ guardId: g._id, ...g.name ? { name: g.name } : {} }))
+        });
+      return await client.patch(documentId).set(patch).commit(), await client.getDocument(documentId);
+    }
+  };
+}
+function createQueryHelpers(scope) {
+  const withParams = (params) => params !== void 0 ? { params } : {};
+  return {
+    query: (groq, params) => workflowEngine.workflow.query({ ...scope, groq, ...withParams(params) }),
+    queryInScope: (instanceId, groq, params) => workflowEngine.workflow.queryInScope({ ...scope, instanceId, groq, ...withParams(params) })
+  };
+}
+function createReadHelpers(scope) {
+  const { client, tags } = scope, intersectsTags = (docTags) => docTags !== void 0 && tags.some((t) => docTags.includes(t)), getInstance = async (instanceId) => {
+    const doc = await client.getDocument(instanceId);
+    if (!doc) throw new Error(`Workflow instance ${instanceId} not found`);
+    if (!intersectsTags(doc.tags))
+      throw new Error(`Workflow instance ${instanceId} not visible to this engine (tag mismatch)`);
+    return doc;
+  };
+  return {
+    getInstance,
+    currentStage: async (instanceId) => (await getInstance(instanceId)).currentStageId,
+    pendingEffects: async (instanceId) => (await getInstance(instanceId)).pendingEffects,
+    taskStatus: async (instanceId, taskId) => {
+      const instance = await getInstance(instanceId);
+      return instance.stages.find(
+        (s) => s.id === instance.currentStageId && s.exitedAt === void 0
+      )?.tasks.find((t) => t.id === taskId)?.status;
+    },
+    effectsContextMap: async (instanceId) => {
+      const instance = await getInstance(instanceId), map = {};
+      for (const entry of instance.effectsContext) map[entry.id] = entry.value;
+      return map;
+    },
+    children: async (parentInstanceId, taskId) => workflowEngine.workflow.children({
+      ...scope,
+      instanceId: parentInstanceId,
+      ...taskId !== void 0 ? { taskId } : {}
+    }),
+    instancesForSubject: async (subjectRef, slotId = "subject") => (
+      // Subjects live on a workflow-scope `state[id == $slot]` doc.ref
+      // slot. Match instances whose slot's value.id equals the supplied
+      // ref. The slot id is conventionally "subject" but workflows may
+      // name it otherwise.
+      client.fetch(
+        `*[_type == "workflow.instance"
+          && state[_type == "workflow.state.doc.ref" && id == $slot][0].value.id == $ref
+          && count(tags[@ in $engineTags]) > 0] | order(startedAt asc)`,
+        { ref: subjectRef, slot: slotId, engineTags: tags }
+      )
+    ),
+    instancesByStage: async (workflowId, stageId, queryOptions) => {
+      const filter = queryOptions?.openOnly ? " && completedAt == null" : "";
+      return client.fetch(
+        `*[_type == "workflow.instance" && workflowId == $wf && currentStageId == $stage && count(tags[@ in $engineTags]) > 0${filter}]
+          | order(startedAt asc)`,
+        { wf: workflowId, stage: stageId, engineTags: tags }
+      );
+    },
+    snapshot: () => client.snapshot()
+  };
+}
+function createBench(options = {}) {
+  const tags = options.tags ?? ["bench"];
+  workflowEngine.validateTags(tags);
+  const workflowResource = options.workflowResource ?? DEFAULT_WORKFLOW_RESOURCE, client = resolveBenchClient(options), scope = { client, tags, workflowResource }, access = resolveBenchAccess(options);
+  return {
+    client,
+    access,
+    currentUser: access.actor,
+    grants: access.grants ?? [],
+    seedDocuments: (documents) => client.add(documents),
+    ...createEngineWrappers(scope, access),
+    ...createReadHelpers(scope),
+    ...createGuardHelpers(client),
+    ...createQueryHelpers(scope)
+  };
+}
+exports.ALL_ACCESS = ALL_ACCESS;
+exports.ALL_ACCESS_USER = ALL_ACCESS_USER;
+exports.DEFAULT_WORKFLOW_RESOURCE = DEFAULT_WORKFLOW_RESOURCE;
+exports.WILDCARD_GRANTS = WILDCARD_GRANTS;
+exports.createBench = createBench;
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","sources":["../src/constants.ts","../src/access.ts","../src/engine-wrappers.ts","../src/guard-helpers.ts","../src/query-helpers.ts","../src/read-helpers.ts","../src/index.ts"],"sourcesContent":["import type {Actor, Grant, WorkflowAccess, WorkflowResource} from '@sanity/workflow-engine'\n\n/** Default workflow resource for benches that don't pass one. */\nexport const DEFAULT_WORKFLOW_RESOURCE: WorkflowResource = {\n  type: 'dataset',\n  id: 'test.test',\n}\n\n/**\n * The default actor used when tests don't specify one. Has the\n * conventional `\"*\"` wildcard role — `Action.roles` checks treat\n * `\"*\"` as matching any required role, and `Task.assignees` of\n * `{kind: \"role\"}` are satisfied by it too. Production code should\n * never see this id.\n */\nexport const ALL_ACCESS_USER: Actor = {\n  kind: 'user',\n  id: 'bench-user',\n  roles: ['*'],\n}\n\n/**\n * The default grants used when tests don't specify any. A single\n * permissive grant matches every document and confers all permissions.\n */\nexport const WILDCARD_GRANTS: Grant[] = [\n  {filter: 'true', permissions: ['create', 'read', 'update']},\n]\n\n/**\n * The bench's default access state — wildcard user + wildcard\n * grants. The bench injects this as the `access` override on every\n * engine call so the underlying TestClient (which has no token, so\n * no `/users/me` resolution path) never needs to do auth resolution.\n *\n * Production code never sees this; pass `createBench({ access })` to\n * test denial paths.\n */\nexport const ALL_ACCESS: WorkflowAccess = {\n  actor: ALL_ACCESS_USER,\n  grants: WILDCARD_GRANTS,\n}\n","import type {TestClient, TestClientAccessControl} from '@sanity-labs/client-fake-for-test'\nimport {createTestClient} from '@sanity-labs/client-fake-for-test'\nimport type {Actor, Grant, WorkflowAccess} from '@sanity/workflow-engine'\n\nimport {ALL_ACCESS_USER, WILDCARD_GRANTS} from './constants.ts'\nimport type {AccessShortcuts, StoreDocument} from './types.ts'\n\n/**\n * Build the TestClient the bench operates against, enforcing the\n * `client` / `accessControl` mutual-exclusion contract: callers either\n * supply their own client or have the bench mint one (optionally wired\n * with lake-side access control), never both.\n */\nexport function resolveBenchClient(options: {\n  client?: TestClient\n  accessControl?: TestClientAccessControl\n  documents?: StoreDocument[]\n}): TestClient {\n  if (options.accessControl !== undefined && options.client !== undefined) {\n    throw new Error(\n      'createBench: `accessControl` and `client` are mutually exclusive. Either let the bench ' +\n        'build a TestClient configured with the supplied accessControl, or build the client ' +\n        'yourself with `createTestClient({ accessControl })` and pass it in.',\n    )\n  }\n  const client =\n    options.client ??\n    createTestClient(\n      options.accessControl !== undefined ? {accessControl: options.accessControl} : {},\n    )\n  if (options.documents) client.add(options.documents)\n  return client\n}\n\n/**\n * Compose the bench-wide access default. Precedence: the canonical\n * `access` shape, then the `currentUser` / `grants` shortcuts, then\n * {@link ALL_ACCESS_USER} + {@link WILDCARD_GRANTS}.\n */\nexport function resolveBenchAccess(options: {\n  access?: WorkflowAccess\n  currentUser?: Actor\n  grants?: Grant[]\n}): WorkflowAccess {\n  return (\n    options.access ?? {\n      actor: options.currentUser ?? ALL_ACCESS_USER,\n      grants: options.grants ?? WILDCARD_GRANTS,\n    }\n  )\n}\n\n/**\n * Resolve the per-call access override against the bench-wide default.\n * A call may tighten or replace access via the canonical `{ access }`\n * field or the `{ actor, grants }` shortcuts.\n *\n * `canTokenResolve` is true when the bench's client was built with\n * `accessControl` — i.e. its `request` hook can resolve grants from\n * the ACL path. In that case an actor-only override (no grants) must\n * NOT inherit the bench's default grants: doing so would gate the\n * per-call actor with the default's (e.g. wildcard) grants instead of\n * that actor's real grants, silently false-greening denial tests. The\n * engine treats verb `access` as `WorkflowAccessOverride`, so the bench\n * hands it `{ actor }` alone and lets the engine token-resolve grants\n * (via the call's `grantsFromPath`) or skip the gate — both faithful to\n * production. Tokenless default benches keep inheriting the default\n * grants, since there is no other source.\n */\nexport function accessFor(\n  access: WorkflowAccess,\n  args: AccessShortcuts,\n  canTokenResolve: boolean,\n): WorkflowAccess {\n  if (args.access !== undefined) return args.access\n  if (args.actor === undefined && args.grants === undefined) return access\n  const inheritedGrants = canTokenResolve ? undefined : access.grants\n  const grants = args.grants ?? inheritedGrants\n  return {\n    actor: args.actor ?? access.actor,\n    ...(grants !== undefined ? {grants} : {}),\n  }\n}\n\n/**\n * Strip the bench-only access shortcut fields before spreading the rest\n * of a call's args into an engine call, so the composed `access` is the\n * single source of truth.\n */\nexport function stripAccessShortcuts<T extends AccessShortcuts>(\n  args: T,\n): Omit<T, 'access' | 'actor' | 'grants'> {\n  const rest = {...args}\n  delete rest.access\n  delete rest.actor\n  delete rest.grants\n  return rest\n}\n","import {\n  workflow,\n  type DeployDefinitionsArgs,\n  type DeployDefinitionsResult,\n  type DispatchResult,\n  type WorkflowAccess,\n  type WorkflowEvaluation,\n  type WorkflowInstance,\n} from '@sanity/workflow-engine'\n\nimport {accessFor, stripAccessShortcuts} from './access.ts'\nimport type {\n  AccessShortcuts,\n  BenchCompleteEffectArgs,\n  BenchEvaluateArgs,\n  BenchFireActionArgs,\n  BenchStartInstanceArgs,\n  BenchTickArgs,\n  EngineScope,\n} from './types.ts'\n\n/** Engine-call wrappers that inject the bench-owned client + tags + access. */\nexport type EngineWrappers = {\n  deployDefinitions: (\n    args: Omit<DeployDefinitionsArgs, 'client' | 'tags' | 'workflowResource'>,\n  ) => Promise<DeployDefinitionsResult>\n  startInstance: (args: BenchStartInstanceArgs) => Promise<WorkflowInstance>\n  fireAction: (args: BenchFireActionArgs) => Promise<DispatchResult>\n  completeEffect: (args: BenchCompleteEffectArgs) => Promise<DispatchResult>\n  tick: (args: BenchTickArgs) => Promise<DispatchResult>\n  evaluate: (args: BenchEvaluateArgs) => Promise<WorkflowEvaluation>\n}\n\n/**\n * Build the engine-call wrappers. Each access-aware wrapper composes the\n * call's `access` from the bench default plus any per-call override, then\n * spreads the remaining args into the engine with the bench-owned scope.\n */\nexport function createEngineWrappers(scope: EngineScope, access: WorkflowAccess): EngineWrappers {\n  // The fake client only exposes an own `request` hook when built with\n  // `accessControl`; that hook is what lets the engine token-resolve\n  // grants from the ACL path. A plain bench client has no such hook.\n  const canTokenResolve = 'request' in scope.client\n  const withAccess = <T extends AccessShortcuts>(args: T) => ({\n    ...scope,\n    access: accessFor(access, args, canTokenResolve),\n    ...stripAccessShortcuts(args),\n  })\n  return {\n    deployDefinitions: (args) => workflow.deployDefinitions({...scope, ...args}),\n    startInstance: (args) => workflow.startInstance(withAccess(args)),\n    fireAction: (args) => workflow.fireAction(withAccess(args)),\n    completeEffect: (args) => workflow.completeEffect(withAccess(args)),\n    tick: (args) => workflow.tick(withAccess(args)),\n    evaluate: (args) => workflow.evaluate(withAccess(args)),\n  }\n}\n","import type {TestClient} from '@sanity-labs/client-fake-for-test'\nimport {\n  denyingGuards,\n  MutationGuardDeniedError,\n  type Actor,\n  type MutationGuardAction,\n  type MutationGuardDoc,\n} from '@sanity/workflow-engine'\n\nimport type {StoreDocument} from './types.ts'\n\nexport type GuardHelpers = {\n  /** All deployed `temp.system.guard` docs in the store. */\n  listGuards: () => Promise<MutationGuardDoc[]>\n\n  /**\n   * Guards that would deny an arbitrary edit to `documentId` right now (i.e.\n   * active locks). Probes by changing every non-system field; a lifted guard\n   * (predicate `\"true\"`) returns nothing.\n   */\n  activeGuardsForDocument: (documentId: string, as?: Actor) => Promise<MutationGuardDoc[]>\n\n  /**\n   * Attempt a guarded write to a document — the bench's stand-in for the lake's\n   * mutation path. Evaluates deployed guards (incl. `identity()` = the actor)\n   * against the before/after image and throws `MutationGuardDeniedError` if any\n   * deny; otherwise applies the patch. OPTIMISTIC — not the lake enforcing.\n   */\n  editDocument: (\n    documentId: string,\n    patch: Record<string, unknown>,\n    options?: {action?: MutationGuardAction; as?: Actor},\n  ) => Promise<StoreDocument>\n}\n\n/**\n * Build the optimistic, bench-enforced lake mutation-guard helpers. These\n * stand in for the lake's mutation path: they evaluate deployed guards\n * against a before/after image rather than the lake enforcing.\n */\nexport function createGuardHelpers(client: TestClient): GuardHelpers {\n  const fetchGuards = () => client.fetch<MutationGuardDoc[]>(`*[_type == \"temp.system.guard\"]`)\n\n  const guardDocRef = (documentId: string, before: StoreDocument | null | undefined) => ({\n    id: documentId,\n    ...(before?._type ? {type: before._type} : {}),\n  })\n\n  return {\n    listGuards: () =>\n      client.fetch<MutationGuardDoc[]>(`*[_type == \"temp.system.guard\"] | order(_id asc)`),\n\n    activeGuardsForDocument: async (documentId, as) => {\n      const guards = await fetchGuards()\n      const before = await client.getDocument<StoreDocument>(documentId)\n      const after: Record<string, unknown> = {...(before ?? {_id: documentId, _type: 'unknown'})}\n      for (const key of Object.keys(after)) {\n        if (!key.startsWith('_')) after[key] = {__guardProbe: true}\n      }\n      after.__guardProbe = {__guardProbe: true}\n      return denyingGuards({\n        guards,\n        doc: guardDocRef(documentId, before),\n        context: {\n          before: before ?? null,\n          after: after as {_id: string; _type: string},\n          action: 'update',\n          ...(as ? {identity: as.id} : {}),\n        },\n      })\n    },\n\n    editDocument: async (documentId, patch, editOptions) => {\n      const action = editOptions?.action ?? 'update'\n      const as = editOptions?.as\n      const before = await client.getDocument<StoreDocument>(documentId)\n      const after =\n        action === 'delete' ? null : {...(before ?? {_id: documentId, _type: 'unknown'}), ...patch}\n      const guards = await fetchGuards()\n      const denied = await denyingGuards({\n        guards,\n        doc: guardDocRef(documentId, before),\n        context: {\n          before: before ?? null,\n          after,\n          action,\n          ...(as ? {identity: as.id} : {}),\n        },\n      })\n      if (denied.length > 0) {\n        throw new MutationGuardDeniedError({\n          documentId,\n          action,\n          denied: denied.map((g) => ({guardId: g._id, ...(g.name ? {name: g.name} : {})})),\n        })\n      }\n      await client.patch(documentId).set(patch).commit()\n      return (await client.getDocument(documentId)) as StoreDocument\n    },\n  }\n}\n","import {workflow} from '@sanity/workflow-engine'\n\nimport type {EngineScope} from './types.ts'\n\nexport type QueryHelpers = {\n  /**\n   * Run an arbitrary GROQ query through `workflow.query`. The query MUST\n   * filter on the auto-injected `$engineTags` param (e.g.\n   * `*[... && count(tags[@ in $engineTags]) > 0]`) or it throws — the\n   * engine refuses to run a query that could read across tenant tags.\n   * Caller is responsible for narrowing the result.\n   */\n  query: <T = unknown>(groq: string, params?: Record<string, unknown>) => Promise<T>\n\n  /**\n   * Snapshot-aware GROQ for `instanceId` — runs against the same\n   * in-memory view the engine's filters see. Reserved params (`$self`,\n   * `$subject`, `$parent`, `$ancestors`, `$now`, `$stage`) auto-bound\n   * in GDR URI form. Use to ask \"what does the engine see for this\n   * workflow?\" — useful for filter debugging, UIs that mirror engine\n   * state, etc.\n   */\n  queryInScope: <T = unknown>(\n    instanceId: string,\n    groq: string,\n    params?: Record<string, unknown>,\n  ) => Promise<T>\n}\n\n/** Build the GROQ passthrough helpers, both tag-scoped via the bench scope. */\nexport function createQueryHelpers(scope: EngineScope): QueryHelpers {\n  const withParams = (params?: Record<string, unknown>) => (params !== undefined ? {params} : {})\n  return {\n    query: <T = unknown>(groq: string, params?: Record<string, unknown>) =>\n      workflow.query<T>({...scope, groq, ...withParams(params)}),\n\n    queryInScope: <T = unknown>(\n      instanceId: string,\n      groq: string,\n      params?: Record<string, unknown>,\n    ) => workflow.queryInScope<T>({...scope, instanceId, groq, ...withParams(params)}),\n  }\n}\n","import {\n  workflow,\n  type EffectsContextEntry,\n  type PendingEffect,\n  type TaskStatus,\n  type WorkflowInstance,\n} from '@sanity/workflow-engine'\n\nimport type {EngineScope, StoreDocument} from './types.ts'\n\nexport type ReadHelpers = {\n  /** Read the workflow instance by id. Throws if missing. */\n  getInstance: (instanceId: string) => Promise<WorkflowInstance>\n\n  /** Current stage id of an instance. */\n  currentStage: (instanceId: string) => Promise<string>\n\n  /** Pending effects on an instance. */\n  pendingEffects: (instanceId: string) => Promise<PendingEffect[]>\n\n  /** Status of a single task on an instance, or undefined if missing. */\n  taskStatus: (instanceId: string, taskId: string) => Promise<TaskStatus | undefined>\n\n  /** EffectsContext entries on an instance, keyed by `key`. */\n  effectsContextMap: (instanceId: string) => Promise<Record<string, EffectsContextEntry['value']>>\n\n  /**\n   * Spawned children of `parentInstanceId`. If `taskId` is provided,\n   * only children spawned by that specific task on the parent.\n   *\n   * Walks `history.spawned` entries on the parent — this is the durable\n   * record. (The per-task `spawnedInstances` field on `stages[id == $stage && !defined(exitedAt)][0].tasks[]`\n   * gets wiped when the parent transitions past the spawning stage,\n   * since `taskStatus` is rebuilt on every transition.)\n   *\n   * Returns children ordered by `startedAt` ascending.\n   */\n  children: (parentInstanceId: string, taskId?: string) => Promise<WorkflowInstance[]>\n\n  /**\n   * All workflow instances whose `workflow.state.doc.ref` slot named\n   * `slotId` (default `\"subject\"`) matches the given doc id. Useful\n   * for \"what workflow is running on this document?\" questions. Pass\n   * `slotId` for workflows whose subject slot uses a different id.\n   */\n  instancesForSubject: (subjectRef: string, slotId?: string) => Promise<WorkflowInstance[]>\n\n  /**\n   * All instances of `workflowId` currently at `stageId`. Includes\n   * completed instances (`completedAt != null`) by default; set\n   * `{ openOnly: true }` to filter to in-flight only.\n   */\n  instancesByStage: (\n    workflowId: string,\n    stageId: string,\n    options?: {openOnly?: boolean},\n  ) => Promise<WorkflowInstance[]>\n\n  /** Snapshot of all documents in the store — for inspecting the world. */\n  snapshot: () => readonly StoreDocument[]\n}\n\n/**\n * Build the read-side DX helpers. {@link ReadHelpers.getInstance} enforces\n * tag-scoped visibility so every derived read (`currentStage`, `taskStatus`,\n * …) inherits the same isolation the engine's filters apply.\n */\nexport function createReadHelpers(scope: EngineScope): ReadHelpers {\n  const {client, tags} = scope\n\n  const intersectsTags = (docTags: string[] | undefined): boolean =>\n    docTags !== undefined && tags.some((t) => docTags.includes(t))\n\n  const getInstance = async (instanceId: string): Promise<WorkflowInstance> => {\n    const doc = await client.getDocument<WorkflowInstance>(instanceId)\n    if (!doc) throw new Error(`Workflow instance ${instanceId} not found`)\n    if (!intersectsTags(doc.tags)) {\n      throw new Error(`Workflow instance ${instanceId} not visible to this engine (tag mismatch)`)\n    }\n    return doc\n  }\n\n  return {\n    getInstance,\n\n    currentStage: async (instanceId) => (await getInstance(instanceId)).currentStageId,\n\n    pendingEffects: async (instanceId) => (await getInstance(instanceId)).pendingEffects,\n\n    taskStatus: async (instanceId, taskId) => {\n      const instance = await getInstance(instanceId)\n      const stage = instance.stages.find(\n        (s) => s.id === instance.currentStageId && s.exitedAt === undefined,\n      )\n      return stage?.tasks.find((t) => t.id === taskId)?.status\n    },\n\n    effectsContextMap: async (instanceId) => {\n      const instance = await getInstance(instanceId)\n      const map: Record<string, EffectsContextEntry['value']> = {}\n      for (const entry of instance.effectsContext) map[entry.id] = entry.value\n      return map\n    },\n\n    children: async (parentInstanceId, taskId) =>\n      workflow.children({\n        ...scope,\n        instanceId: parentInstanceId,\n        ...(taskId !== undefined ? {taskId} : {}),\n      }),\n\n    instancesForSubject: async (subjectRef, slotId = 'subject') =>\n      // Subjects live on a workflow-scope `state[id == $slot]` doc.ref\n      // slot. Match instances whose slot's value.id equals the supplied\n      // ref. The slot id is conventionally \"subject\" but workflows may\n      // name it otherwise.\n      client.fetch<WorkflowInstance[]>(\n        `*[_type == \"workflow.instance\"\n          && state[_type == \"workflow.state.doc.ref\" && id == $slot][0].value.id == $ref\n          && count(tags[@ in $engineTags]) > 0] | order(startedAt asc)`,\n        {ref: subjectRef, slot: slotId, engineTags: tags},\n      ),\n\n    instancesByStage: async (workflowId, stageId, queryOptions) => {\n      const filter = queryOptions?.openOnly ? ' && completedAt == null' : ''\n      return client.fetch<WorkflowInstance[]>(\n        `*[_type == \"workflow.instance\" && workflowId == $wf && currentStageId == $stage && count(tags[@ in $engineTags]) > 0${filter}]\n          | order(startedAt asc)`,\n        {wf: workflowId, stage: stageId, engineTags: tags},\n      )\n    },\n\n    snapshot: () => client.snapshot() as readonly StoreDocument[],\n  }\n}\n","/**\n * The bench — a dry-run test harness wrapping `@sanity-labs/client-fake-for-test`.\n *\n * The bench is the **only** place in the package that fabricates an\n * actor identity. The engine itself requires an explicit `actor` on\n * every call; the bench provides a default `ALL_ACCESS_USER` so tests\n * don't have to thread one manually, and exposes wrapper methods that\n * inject `bench.currentUser` + `bench.grants` for every engine call.\n *\n * ```\n * const bench = createBench();\n * await bench.deployDefinitions({ definitions: [definition] });\n * const inst = await bench.startInstance({ workflowId: \"...\", subject: {...} });\n * await bench.fireAction({ instanceId: inst._id, taskId: \"...\", action: \"...\" });\n * expect(await bench.currentStage(inst._id)).toBe(\"ready\");\n * ```\n *\n * For denial-path tests, pass an explicit `currentUser` and/or `grants`:\n *\n * ```\n * const bench = createBench({\n *   currentUser: { kind: \"user\", id: \"viewer\", roles: [\"viewer\"] },\n *   grants: [{ filter: '_type == \"workflow.instance\"', permissions: [\"read\"] }],\n * });\n * await expect(bench.fireAction({...})).rejects.toBeInstanceOf(ActionDisabledError);\n * ```\n */\n\nimport type {TestClient, TestClientAccessControl} from '@sanity-labs/client-fake-for-test'\nimport {validateTags} from '@sanity/workflow-engine'\nimport type {Actor, Grant, WorkflowAccess, WorkflowResource} from '@sanity/workflow-engine'\n\nimport {resolveBenchAccess, resolveBenchClient} from './access.ts'\nimport {DEFAULT_WORKFLOW_RESOURCE} from './constants.ts'\nimport {createEngineWrappers, type EngineWrappers} from './engine-wrappers.ts'\nimport {createGuardHelpers, type GuardHelpers} from './guard-helpers.ts'\nimport {createQueryHelpers, type QueryHelpers} from './query-helpers.ts'\nimport {createReadHelpers, type ReadHelpers} from './read-helpers.ts'\nimport type {StoreDocument} from './types.ts'\n\nexport {\n  ALL_ACCESS,\n  ALL_ACCESS_USER,\n  DEFAULT_WORKFLOW_RESOURCE,\n  WILDCARD_GRANTS,\n} from './constants.ts'\n\nexport interface CreateBenchOptions {\n  /** Subject documents seeded into the store. */\n  documents?: StoreDocument[]\n  /**\n   * Access state (actor + grants) injected as the engine `access`\n   * override on every wrapped call. Defaults to `ALL_ACCESS` —\n   * wildcard user + wildcard grants. Pass a restrictive value to\n   * test denial paths.\n   *\n   * Mutually exclusive with the `currentUser` / `grants` shortcuts\n   * (which compose into the same shape internally).\n   */\n  access?: WorkflowAccess\n  /** Shortcut for `access.actor`. Composed with `grants`. */\n  currentUser?: Actor\n  /** Shortcut for `access.grants`. Composed with `currentUser`. */\n  grants?: Grant[]\n  /**\n   * Opt-in: simulate Sanity's hard write-gate inside the TestClient.\n   *\n   * When set, the bench's underlying TestClient:\n   *   - Exposes `client.request({ url })` serving `/users/me` + the\n   *     configured ACL path, so the engine can resolve `WorkflowAccess`\n   *     from \"the token\" exactly like production.\n   *   - Rejects writes the grants don't permit with a Sanity-style\n   *     `WriteAccessDeniedError` — the same 403 a real lake would\n   *     return.\n   *\n   * Use this to demonstrate what would happen if the engine's\n   * soft-gate were bypassed (or disagreed with) — the lake is still\n   * authoritative. The bench's `access` field is the engine-side\n   * override; `accessControl` is the lake-side enforcement. They\n   * usually carry the same `actor` + `grants` but can be made to\n   * disagree to test edge cases.\n   *\n   * Mutually exclusive with passing a pre-built `client`.\n   */\n  accessControl?: TestClientAccessControl\n  /**\n   * Engine-scope tags. Defaults to `[\"bench\"]`. Pass disjoint sets to two\n   * benches sharing a `client` to assert multi-tenant isolation; pass an\n   * overlapping set to assert visibility through a shared tag.\n   *\n   * Tags must be ASCII lowercase + digits + dashes, no leading dash,\n   * no dots — validated at construction.\n   */\n  tags?: string[]\n  /**\n   * Shared TestClient. If omitted, the bench creates its own — two\n   * benches without a shared client are completely isolated, regardless\n   * of tags. Pass the same client to two benches to test tag-scoped\n   * visibility across a shared store.\n   */\n  client?: TestClient\n  /**\n   * Workflow resource the bench's engine operates against. Mirrors\n   * `@sanity/client`'s `ClientConfigResource`. Defaults to\n   * `{ type: \"dataset\", id: \"test.test\" }` so all bench-minted GDR\n   * URIs read as `dataset:test:test:<docId>`.\n   */\n  workflowResource?: WorkflowResource\n}\n\n/** Base bench state, distinct from the engine/read/guard/query helper groups. */\ninterface BenchState {\n  /** The fake Sanity client. Passed automatically by bench wrappers. */\n  client: TestClient\n  /**\n   * The access state (actor + grants) the bench injects as the\n   * `access` override on every wrapped engine call. Defaults to\n   * `ALL_ACCESS`.\n   */\n  access: WorkflowAccess\n  /** Convenience: `access.actor`. */\n  currentUser: Actor\n  /** Convenience: `access.grants ?? []`. */\n  grants: Grant[]\n\n  /** Add documents to the store after construction. */\n  seedDocuments: (documents: StoreDocument[]) => void\n}\n\nexport type Bench = BenchState & EngineWrappers & ReadHelpers & GuardHelpers & QueryHelpers\n\n/**\n * Create a fresh bench. By default the bench is fully isolated — two\n * `createBench()` calls have no shared state. Pass `client` + `tags`\n * to two benches to share a store and exercise tag scoping.\n */\nexport function createBench(options: CreateBenchOptions = {}): Bench {\n  const tags = options.tags ?? ['bench']\n  validateTags(tags)\n  const workflowResource = options.workflowResource ?? DEFAULT_WORKFLOW_RESOURCE\n  const client = resolveBenchClient(options)\n  const scope = {client, tags, workflowResource}\n\n  const access = resolveBenchAccess(options)\n\n  return {\n    client,\n    access,\n    currentUser: access.actor,\n    grants: access.grants ?? [],\n\n    seedDocuments: (documents) => client.add(documents),\n\n    ...createEngineWrappers(scope, access),\n    ...createReadHelpers(scope),\n    ...createGuardHelpers(client),\n    ...createQueryHelpers(scope),\n  }\n}\n"],"names":["createTestClient","workflow","denyingGuards","MutationGuardDeniedError","validateTags"],"mappings":"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"}

package/dist/index.d.cts

@@ -0,0 +1,326 @@
+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 { EffectsContextEntry } from "@sanity/workflow-engine";
+import type { EvaluateArgs } from "@sanity/workflow-engine";
+import type { FireActionArgs } from "@sanity/workflow-engine";
+import type { Grant } from "@sanity/workflow-engine";
+import { MutationGuardAction } from "@sanity/workflow-engine";
+import { MutationGuardDoc } from "@sanity/workflow-engine";
+import type { OperationArgs } from "@sanity/workflow-engine";
+import { PendingEffect } from "@sanity/workflow-engine";
+import type { StartInstanceArgs } from "@sanity/workflow-engine";
+import { TaskStatus } from "@sanity/workflow-engine";
+import type { TestClient } from "@sanity-labs/client-fake-for-test";
+import type { TestClientAccessControl } from "@sanity-labs/client-fake-for-test";
+import type { WorkflowAccess } from "@sanity/workflow-engine";
+import { WorkflowEvaluation } from "@sanity/workflow-engine";
+import { WorkflowInstance } from "@sanity/workflow-engine";
+import type { WorkflowResource } from "@sanity/workflow-engine";
+
+/**
+ * The bench's default access state — wildcard user + wildcard
+ * grants. The bench injects this as the `access` override on every
+ * engine call so the underlying TestClient (which has no token, so
+ * no `/users/me` resolution path) never needs to do auth resolution.
+ *
+ * Production code never sees this; pass `createBench({ access })` to
+ * test denial paths.
+ */
+export declare const ALL_ACCESS: WorkflowAccess;
+
+/**
+ * The default actor used when tests don't specify one. Has the
+ * conventional `"*"` wildcard role — `Action.roles` checks treat
+ * `"*"` as matching any required role, and `Task.assignees` of
+ * `{kind: "role"}` are satisfied by it too. Production code should
+ * never see this id.
+ */
+export declare const ALL_ACCESS_USER: Actor;
+
+export declare type Bench = BenchState &
+  EngineWrappers &
+  ReadHelpers &
+  GuardHelpers &
+  QueryHelpers;
+
+declare type BenchCompleteEffectArgs = Omit<
+  CompleteEffectArgs,
+  "client" | "tags" | "workflowResource" | "access"
+> & {
+  access?: WorkflowAccess;
+  /** Shortcut for `access.actor`. */
+  actor?: Actor;
+};
+
+declare type BenchEvaluateArgs = Omit<
+  EvaluateArgs,
+  "client" | "tags" | "workflowResource" | "access"
+> & {
+  access?: WorkflowAccess;
+  /** Shortcut for `access.actor`. */
+  actor?: Actor;
+  /** Shortcut for `access.grants`. */
+  grants?: Grant[];
+};
+
+declare type BenchFireActionArgs = Omit<
+  FireActionArgs,
+  "client" | "tags" | "workflowResource" | "access"
+> & {
+  access?: WorkflowAccess;
+  /** Shortcut for `access.actor`. */
+  actor?: Actor;
+  /** Shortcut for `access.grants`. */
+  grants?: Grant[];
+};
+
+declare type BenchStartInstanceArgs = Omit<
+  StartInstanceArgs,
+  "client" | "tags" | "workflowResource" | "access"
+> & {
+  access?: WorkflowAccess;
+  /** Shortcut for `access.actor`. */
+  actor?: Actor;
+};
+
+/** Base bench state, distinct from the engine/read/guard/query helper groups. */
+declare interface BenchState {
+  /** The fake Sanity client. Passed automatically by bench wrappers. */
+  client: TestClient;
+  /**
+   * The access state (actor + grants) the bench injects as the
+   * `access` override on every wrapped engine call. Defaults to
+   * `ALL_ACCESS`.
+   */
+  access: WorkflowAccess;
+  /** Convenience: `access.actor`. */
+  currentUser: Actor;
+  /** Convenience: `access.grants ?? []`. */
+  grants: Grant[];
+  /** Add documents to the store after construction. */
+  seedDocuments: (documents: StoreDocument[]) => void;
+}
+
+declare type BenchTickArgs = Omit<
+  OperationArgs,
+  "client" | "tags" | "workflowResource" | "access"
+> & {
+  access?: WorkflowAccess;
+  /** Shortcut for `access.actor`. */
+  actor?: Actor;
+};
+
+/**
+ * Create a fresh bench. By default the bench is fully isolated — two
+ * `createBench()` calls have no shared state. Pass `client` + `tags`
+ * to two benches to share a store and exercise tag scoping.
+ */
+export declare function createBench(options?: CreateBenchOptions): Bench;
+
+export declare interface CreateBenchOptions {
+  /** Subject documents seeded into the store. */
+  documents?: StoreDocument[];
+  /**
+   * Access state (actor + grants) injected as the engine `access`
+   * override on every wrapped call. Defaults to `ALL_ACCESS` —
+   * wildcard user + wildcard grants. Pass a restrictive value to
+   * test denial paths.
+   *
+   * Mutually exclusive with the `currentUser` / `grants` shortcuts
+   * (which compose into the same shape internally).
+   */
+  access?: WorkflowAccess;
+  /** Shortcut for `access.actor`. Composed with `grants`. */
+  currentUser?: Actor;
+  /** Shortcut for `access.grants`. Composed with `currentUser`. */
+  grants?: Grant[];
+  /**
+   * Opt-in: simulate Sanity's hard write-gate inside the TestClient.
+   *
+   * When set, the bench's underlying TestClient:
+   *   - Exposes `client.request({ url })` serving `/users/me` + the
+   *     configured ACL path, so the engine can resolve `WorkflowAccess`
+   *     from "the token" exactly like production.
+   *   - Rejects writes the grants don't permit with a Sanity-style
+   *     `WriteAccessDeniedError` — the same 403 a real lake would
+   *     return.
+   *
+   * Use this to demonstrate what would happen if the engine's
+   * soft-gate were bypassed (or disagreed with) — the lake is still
+   * authoritative. The bench's `access` field is the engine-side
+   * override; `accessControl` is the lake-side enforcement. They
+   * usually carry the same `actor` + `grants` but can be made to
+   * disagree to test edge cases.
+   *
+   * Mutually exclusive with passing a pre-built `client`.
+   */
+  accessControl?: TestClientAccessControl;
+  /**
+   * Engine-scope tags. Defaults to `["bench"]`. Pass disjoint sets to two
+   * benches sharing a `client` to assert multi-tenant isolation; pass an
+   * overlapping set to assert visibility through a shared tag.
+   *
+   * Tags must be ASCII lowercase + digits + dashes, no leading dash,
+   * no dots — validated at construction.
+   */
+  tags?: string[];
+  /**
+   * Shared TestClient. If omitted, the bench creates its own — two
+   * benches without a shared client are completely isolated, regardless
+   * of tags. Pass the same client to two benches to test tag-scoped
+   * visibility across a shared store.
+   */
+  client?: TestClient;
+  /**
+   * Workflow resource the bench's engine operates against. Mirrors
+   * `@sanity/client`'s `ClientConfigResource`. Defaults to
+   * `{ type: "dataset", id: "test.test" }` so all bench-minted GDR
+   * URIs read as `dataset:test:test:<docId>`.
+   */
+  workflowResource?: WorkflowResource;
+}
+
+/** Default workflow resource for benches that don't pass one. */
+export declare const DEFAULT_WORKFLOW_RESOURCE: WorkflowResource;
+
+/** Engine-call wrappers that inject the bench-owned client + tags + access. */
+declare type EngineWrappers = {
+  deployDefinitions: (
+    args: Omit<DeployDefinitionsArgs, "client" | "tags" | "workflowResource">,
+  ) => Promise<DeployDefinitionsResult>;
+  startInstance: (args: BenchStartInstanceArgs) => Promise<WorkflowInstance>;
+  fireAction: (args: BenchFireActionArgs) => Promise<DispatchResult>;
+  completeEffect: (args: BenchCompleteEffectArgs) => Promise<DispatchResult>;
+  tick: (args: BenchTickArgs) => Promise<DispatchResult>;
+  evaluate: (args: BenchEvaluateArgs) => Promise<WorkflowEvaluation>;
+};
+
+declare type GuardHelpers = {
+  /** All deployed `temp.system.guard` docs 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.
+   */
+  activeGuardsForDocument: (
+    documentId: string,
+    as?: Actor,
+  ) => Promise<MutationGuardDoc[]>;
+  /**
+   * Attempt a guarded write to a document — the bench's stand-in for the lake's
+   * mutation path. Evaluates deployed guards (incl. `identity()` = the actor)
+   * against the before/after image and throws `MutationGuardDeniedError` if any
+   * deny; otherwise applies the patch. OPTIMISTIC — not the lake enforcing.
+   */
+  editDocument: (
+    documentId: string,
+    patch: Record<string, unknown>,
+    options?: {
+      action?: MutationGuardAction;
+      as?: Actor;
+    },
+  ) => Promise<StoreDocument>;
+};
+
+declare type QueryHelpers = {
+  /**
+   * Run an arbitrary GROQ query through `workflow.query`. The query MUST
+   * filter on the auto-injected `$engineTags` param (e.g.
+   * `*[... && count(tags[@ in $engineTags]) > 0]`) or it throws — the
+   * engine refuses to run a query that could read across tenant tags.
+   * Caller is responsible for narrowing the result.
+   */
+  query: <T = unknown>(
+    groq: string,
+    params?: Record<string, unknown>,
+  ) => 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.
+   */
+  queryInScope: <T = unknown>(
+    instanceId: string,
+    groq: string,
+    params?: Record<string, unknown>,
+  ) => Promise<T>;
+};
+
+declare type ReadHelpers = {
+  /** Read the workflow instance by id. Throws if missing. */
+  getInstance: (instanceId: string) => Promise<WorkflowInstance>;
+  /** Current stage id of an instance. */
+  currentStage: (instanceId: string) => Promise<string>;
+  /** Pending effects on an instance. */
+  pendingEffects: (instanceId: string) => Promise<PendingEffect[]>;
+  /** Status of a single task on an instance, or undefined if missing. */
+  taskStatus: (
+    instanceId: string,
+    taskId: string,
+  ) => Promise<TaskStatus | undefined>;
+  /** EffectsContext entries on an instance, keyed by `key`. */
+  effectsContextMap: (
+    instanceId: string,
+  ) => Promise<Record<string, EffectsContextEntry["value"]>>;
+  /**
+   * Spawned children of `parentInstanceId`. If `taskId` is provided,
+   * only children spawned by that specific task on the parent.
+   *
+   * Walks `history.spawned` entries on the parent — this is the durable
+   * record. (The per-task `spawnedInstances` field on `stages[id == $stage && !defined(exitedAt)][0].tasks[]`
+   * gets wiped when the parent transitions past the spawning stage,
+   * since `taskStatus` is rebuilt on every transition.)
+   *
+   * Returns children ordered by `startedAt` ascending.
+   */
+  children: (
+    parentInstanceId: string,
+    taskId?: string,
+  ) => Promise<WorkflowInstance[]>;
+  /**
+   * All workflow instances whose `workflow.state.doc.ref` slot named
+   * `slotId` (default `"subject"`) matches the given doc id. Useful
+   * for "what workflow is running on this document?" questions. Pass
+   * `slotId` for workflows whose subject slot uses a different id.
+   */
+  instancesForSubject: (
+    subjectRef: string,
+    slotId?: string,
+  ) => Promise<WorkflowInstance[]>;
+  /**
+   * All instances of `workflowId` currently at `stageId`. Includes
+   * completed instances (`completedAt != null`) by default; set
+   * `{ openOnly: true }` to filter to in-flight only.
+   */
+  instancesByStage: (
+    workflowId: string,
+    stageId: string,
+    options?: {
+      openOnly?: boolean;
+    },
+  ) => Promise<WorkflowInstance[]>;
+  /** Snapshot of all documents in the store — for inspecting the world. */
+  snapshot: () => readonly StoreDocument[];
+};
+
+/** A document as stored in the bench's fake lake. */
+declare type StoreDocument = {
+  _id: string;
+  _type: string;
+  [key: string]: unknown;
+};
+
+/**
+ * The default grants used when tests don't specify any. A single
+ * permissive grant matches every document and confers all permissions.
+ */
+export declare const WILDCARD_GRANTS: Grant[];
+
+export {};

package/dist/index.d.ts

@@ -0,0 +1,326 @@
+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 { EffectsContextEntry } from "@sanity/workflow-engine";
+import type { EvaluateArgs } from "@sanity/workflow-engine";
+import type { FireActionArgs } from "@sanity/workflow-engine";
+import type { Grant } from "@sanity/workflow-engine";
+import { MutationGuardAction } from "@sanity/workflow-engine";
+import { MutationGuardDoc } from "@sanity/workflow-engine";
+import type { OperationArgs } from "@sanity/workflow-engine";
+import { PendingEffect } from "@sanity/workflow-engine";
+import type { StartInstanceArgs } from "@sanity/workflow-engine";
+import { TaskStatus } from "@sanity/workflow-engine";
+import type { TestClient } from "@sanity-labs/client-fake-for-test";
+import type { TestClientAccessControl } from "@sanity-labs/client-fake-for-test";
+import type { WorkflowAccess } from "@sanity/workflow-engine";
+import { WorkflowEvaluation } from "@sanity/workflow-engine";
+import { WorkflowInstance } from "@sanity/workflow-engine";
+import type { WorkflowResource } from "@sanity/workflow-engine";
+
+/**
+ * The bench's default access state — wildcard user + wildcard
+ * grants. The bench injects this as the `access` override on every
+ * engine call so the underlying TestClient (which has no token, so
+ * no `/users/me` resolution path) never needs to do auth resolution.
+ *
+ * Production code never sees this; pass `createBench({ access })` to
+ * test denial paths.
+ */
+export declare const ALL_ACCESS: WorkflowAccess;
+
+/**
+ * The default actor used when tests don't specify one. Has the
+ * conventional `"*"` wildcard role — `Action.roles` checks treat
+ * `"*"` as matching any required role, and `Task.assignees` of
+ * `{kind: "role"}` are satisfied by it too. Production code should
+ * never see this id.
+ */
+export declare const ALL_ACCESS_USER: Actor;
+
+export declare type Bench = BenchState &
+  EngineWrappers &
+  ReadHelpers &
+  GuardHelpers &
+  QueryHelpers;
+
+declare type BenchCompleteEffectArgs = Omit<
+  CompleteEffectArgs,
+  "client" | "tags" | "workflowResource" | "access"
+> & {
+  access?: WorkflowAccess;
+  /** Shortcut for `access.actor`. */
+  actor?: Actor;
+};
+
+declare type BenchEvaluateArgs = Omit<
+  EvaluateArgs,
+  "client" | "tags" | "workflowResource" | "access"
+> & {
+  access?: WorkflowAccess;
+  /** Shortcut for `access.actor`. */
+  actor?: Actor;
+  /** Shortcut for `access.grants`. */
+  grants?: Grant[];
+};
+
+declare type BenchFireActionArgs = Omit<
+  FireActionArgs,
+  "client" | "tags" | "workflowResource" | "access"
+> & {
+  access?: WorkflowAccess;
+  /** Shortcut for `access.actor`. */
+  actor?: Actor;
+  /** Shortcut for `access.grants`. */
+  grants?: Grant[];
+};
+
+declare type BenchStartInstanceArgs = Omit<
+  StartInstanceArgs,
+  "client" | "tags" | "workflowResource" | "access"
+> & {
+  access?: WorkflowAccess;
+  /** Shortcut for `access.actor`. */
+  actor?: Actor;
+};
+
+/** Base bench state, distinct from the engine/read/guard/query helper groups. */
+declare interface BenchState {
+  /** The fake Sanity client. Passed automatically by bench wrappers. */
+  client: TestClient;
+  /**
+   * The access state (actor + grants) the bench injects as the
+   * `access` override on every wrapped engine call. Defaults to
+   * `ALL_ACCESS`.
+   */
+  access: WorkflowAccess;
+  /** Convenience: `access.actor`. */
+  currentUser: Actor;
+  /** Convenience: `access.grants ?? []`. */
+  grants: Grant[];
+  /** Add documents to the store after construction. */
+  seedDocuments: (documents: StoreDocument[]) => void;
+}
+
+declare type BenchTickArgs = Omit<
+  OperationArgs,
+  "client" | "tags" | "workflowResource" | "access"
+> & {
+  access?: WorkflowAccess;
+  /** Shortcut for `access.actor`. */
+  actor?: Actor;
+};
+
+/**
+ * Create a fresh bench. By default the bench is fully isolated — two
+ * `createBench()` calls have no shared state. Pass `client` + `tags`
+ * to two benches to share a store and exercise tag scoping.
+ */
+export declare function createBench(options?: CreateBenchOptions): Bench;
+
+export declare interface CreateBenchOptions {
+  /** Subject documents seeded into the store. */
+  documents?: StoreDocument[];
+  /**
+   * Access state (actor + grants) injected as the engine `access`
+   * override on every wrapped call. Defaults to `ALL_ACCESS` —
+   * wildcard user + wildcard grants. Pass a restrictive value to
+   * test denial paths.
+   *
+   * Mutually exclusive with the `currentUser` / `grants` shortcuts
+   * (which compose into the same shape internally).
+   */
+  access?: WorkflowAccess;
+  /** Shortcut for `access.actor`. Composed with `grants`. */
+  currentUser?: Actor;
+  /** Shortcut for `access.grants`. Composed with `currentUser`. */
+  grants?: Grant[];
+  /**
+   * Opt-in: simulate Sanity's hard write-gate inside the TestClient.
+   *
+   * When set, the bench's underlying TestClient:
+   *   - Exposes `client.request({ url })` serving `/users/me` + the
+   *     configured ACL path, so the engine can resolve `WorkflowAccess`
+   *     from "the token" exactly like production.
+   *   - Rejects writes the grants don't permit with a Sanity-style
+   *     `WriteAccessDeniedError` — the same 403 a real lake would
+   *     return.
+   *
+   * Use this to demonstrate what would happen if the engine's
+   * soft-gate were bypassed (or disagreed with) — the lake is still
+   * authoritative. The bench's `access` field is the engine-side
+   * override; `accessControl` is the lake-side enforcement. They
+   * usually carry the same `actor` + `grants` but can be made to
+   * disagree to test edge cases.
+   *
+   * Mutually exclusive with passing a pre-built `client`.
+   */
+  accessControl?: TestClientAccessControl;
+  /**
+   * Engine-scope tags. Defaults to `["bench"]`. Pass disjoint sets to two
+   * benches sharing a `client` to assert multi-tenant isolation; pass an
+   * overlapping set to assert visibility through a shared tag.
+   *
+   * Tags must be ASCII lowercase + digits + dashes, no leading dash,
+   * no dots — validated at construction.
+   */
+  tags?: string[];
+  /**
+   * Shared TestClient. If omitted, the bench creates its own — two
+   * benches without a shared client are completely isolated, regardless
+   * of tags. Pass the same client to two benches to test tag-scoped
+   * visibility across a shared store.
+   */
+  client?: TestClient;
+  /**
+   * Workflow resource the bench's engine operates against. Mirrors
+   * `@sanity/client`'s `ClientConfigResource`. Defaults to
+   * `{ type: "dataset", id: "test.test" }` so all bench-minted GDR
+   * URIs read as `dataset:test:test:<docId>`.
+   */
+  workflowResource?: WorkflowResource;
+}
+
+/** Default workflow resource for benches that don't pass one. */
+export declare const DEFAULT_WORKFLOW_RESOURCE: WorkflowResource;
+
+/** Engine-call wrappers that inject the bench-owned client + tags + access. */
+declare type EngineWrappers = {
+  deployDefinitions: (
+    args: Omit<DeployDefinitionsArgs, "client" | "tags" | "workflowResource">,
+  ) => Promise<DeployDefinitionsResult>;
+  startInstance: (args: BenchStartInstanceArgs) => Promise<WorkflowInstance>;
+  fireAction: (args: BenchFireActionArgs) => Promise<DispatchResult>;
+  completeEffect: (args: BenchCompleteEffectArgs) => Promise<DispatchResult>;
+  tick: (args: BenchTickArgs) => Promise<DispatchResult>;
+  evaluate: (args: BenchEvaluateArgs) => Promise<WorkflowEvaluation>;
+};
+
+declare type GuardHelpers = {
+  /** All deployed `temp.system.guard` docs 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.
+   */
+  activeGuardsForDocument: (
+    documentId: string,
+    as?: Actor,
+  ) => Promise<MutationGuardDoc[]>;
+  /**
+   * Attempt a guarded write to a document — the bench's stand-in for the lake's
+   * mutation path. Evaluates deployed guards (incl. `identity()` = the actor)
+   * against the before/after image and throws `MutationGuardDeniedError` if any
+   * deny; otherwise applies the patch. OPTIMISTIC — not the lake enforcing.
+   */
+  editDocument: (
+    documentId: string,
+    patch: Record<string, unknown>,
+    options?: {
+      action?: MutationGuardAction;
+      as?: Actor;
+    },
+  ) => Promise<StoreDocument>;
+};
+
+declare type QueryHelpers = {
+  /**
+   * Run an arbitrary GROQ query through `workflow.query`. The query MUST
+   * filter on the auto-injected `$engineTags` param (e.g.
+   * `*[... && count(tags[@ in $engineTags]) > 0]`) or it throws — the
+   * engine refuses to run a query that could read across tenant tags.
+   * Caller is responsible for narrowing the result.
+   */
+  query: <T = unknown>(
+    groq: string,
+    params?: Record<string, unknown>,
+  ) => 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.
+   */
+  queryInScope: <T = unknown>(
+    instanceId: string,
+    groq: string,
+    params?: Record<string, unknown>,
+  ) => Promise<T>;
+};
+
+declare type ReadHelpers = {
+  /** Read the workflow instance by id. Throws if missing. */
+  getInstance: (instanceId: string) => Promise<WorkflowInstance>;
+  /** Current stage id of an instance. */
+  currentStage: (instanceId: string) => Promise<string>;
+  /** Pending effects on an instance. */
+  pendingEffects: (instanceId: string) => Promise<PendingEffect[]>;
+  /** Status of a single task on an instance, or undefined if missing. */
+  taskStatus: (
+    instanceId: string,
+    taskId: string,
+  ) => Promise<TaskStatus | undefined>;
+  /** EffectsContext entries on an instance, keyed by `key`. */
+  effectsContextMap: (
+    instanceId: string,
+  ) => Promise<Record<string, EffectsContextEntry["value"]>>;
+  /**
+   * Spawned children of `parentInstanceId`. If `taskId` is provided,
+   * only children spawned by that specific task on the parent.
+   *
+   * Walks `history.spawned` entries on the parent — this is the durable
+   * record. (The per-task `spawnedInstances` field on `stages[id == $stage && !defined(exitedAt)][0].tasks[]`
+   * gets wiped when the parent transitions past the spawning stage,
+   * since `taskStatus` is rebuilt on every transition.)
+   *
+   * Returns children ordered by `startedAt` ascending.
+   */
+  children: (
+    parentInstanceId: string,
+    taskId?: string,
+  ) => Promise<WorkflowInstance[]>;
+  /**
+   * All workflow instances whose `workflow.state.doc.ref` slot named
+   * `slotId` (default `"subject"`) matches the given doc id. Useful
+   * for "what workflow is running on this document?" questions. Pass
+   * `slotId` for workflows whose subject slot uses a different id.
+   */
+  instancesForSubject: (
+    subjectRef: string,
+    slotId?: string,
+  ) => Promise<WorkflowInstance[]>;
+  /**
+   * All instances of `workflowId` currently at `stageId`. Includes
+   * completed instances (`completedAt != null`) by default; set
+   * `{ openOnly: true }` to filter to in-flight only.
+   */
+  instancesByStage: (
+    workflowId: string,
+    stageId: string,
+    options?: {
+      openOnly?: boolean;
+    },
+  ) => Promise<WorkflowInstance[]>;
+  /** Snapshot of all documents in the store — for inspecting the world. */
+  snapshot: () => readonly StoreDocument[];
+};
+
+/** A document as stored in the bench's fake lake. */
+declare type StoreDocument = {
+  _id: string;
+  _type: string;
+  [key: string]: unknown;
+};
+
+/**
+ * The default grants used when tests don't specify any. A single
+ * permissive grant matches every document and confers all permissions.
+ */
+export declare const WILDCARD_GRANTS: Grant[];
+
+export {};

package/dist/index.js

@@ -0,0 +1,184 @@
+import { workflow, denyingGuards, MutationGuardDeniedError, validateTags } from "@sanity/workflow-engine";
+import { createTestClient } from "@sanity-labs/client-fake-for-test";
+const DEFAULT_WORKFLOW_RESOURCE = {
+  type: "dataset",
+  id: "test.test"
+}, ALL_ACCESS_USER = {
+  kind: "user",
+  id: "bench-user",
+  roles: ["*"]
+}, WILDCARD_GRANTS = [
+  { filter: "true", permissions: ["create", "read", "update"] }
+], ALL_ACCESS = {
+  actor: ALL_ACCESS_USER,
+  grants: WILDCARD_GRANTS
+};
+function resolveBenchClient(options) {
+  if (options.accessControl !== void 0 && options.client !== void 0)
+    throw new Error(
+      "createBench: `accessControl` and `client` are mutually exclusive. Either let the bench build a TestClient configured with the supplied accessControl, or build the client yourself with `createTestClient({ accessControl })` and pass it in."
+    );
+  const client = options.client ?? createTestClient(
+    options.accessControl !== void 0 ? { accessControl: options.accessControl } : {}
+  );
+  return options.documents && client.add(options.documents), client;
+}
+function resolveBenchAccess(options) {
+  return options.access ?? {
+    actor: options.currentUser ?? ALL_ACCESS_USER,
+    grants: options.grants ?? WILDCARD_GRANTS
+  };
+}
+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;
+  return {
+    actor: args.actor ?? access.actor,
+    ...grants !== void 0 ? { grants } : {}
+  };
+}
+function stripAccessShortcuts(args) {
+  const rest = { ...args };
+  return delete rest.access, delete rest.actor, delete rest.grants, rest;
+}
+function createEngineWrappers(scope, access) {
+  const canTokenResolve = "request" in scope.client, withAccess = (args) => ({
+    ...scope,
+    access: accessFor(access, args, canTokenResolve),
+    ...stripAccessShortcuts(args)
+  });
+  return {
+    deployDefinitions: (args) => workflow.deployDefinitions({ ...scope, ...args }),
+    startInstance: (args) => workflow.startInstance(withAccess(args)),
+    fireAction: (args) => workflow.fireAction(withAccess(args)),
+    completeEffect: (args) => workflow.completeEffect(withAccess(args)),
+    tick: (args) => workflow.tick(withAccess(args)),
+    evaluate: (args) => workflow.evaluate(withAccess(args))
+  };
+}
+function createGuardHelpers(client) {
+  const fetchGuards = () => client.fetch('*[_type == "temp.system.guard"]'), guardDocRef = (documentId, before) => ({
+    id: documentId,
+    ...before?._type ? { type: before._type } : {}
+  });
+  return {
+    listGuards: () => client.fetch('*[_type == "temp.system.guard"] | order(_id asc)'),
+    activeGuardsForDocument: async (documentId, as) => {
+      const guards = await fetchGuards(), before = await client.getDocument(documentId), after = { ...before ?? { _id: documentId, _type: "unknown" } };
+      for (const key of Object.keys(after))
+        key.startsWith("_") || (after[key] = { __guardProbe: !0 });
+      return after.__guardProbe = { __guardProbe: !0 }, denyingGuards({
+        guards,
+        doc: guardDocRef(documentId, before),
+        context: {
+          before: before ?? null,
+          after,
+          action: "update",
+          ...as ? { identity: as.id } : {}
+        }
+      });
+    },
+    editDocument: async (documentId, patch, editOptions) => {
+      const action = editOptions?.action ?? "update", as = editOptions?.as, before = await client.getDocument(documentId), after = action === "delete" ? null : { ...before ?? { _id: documentId, _type: "unknown" }, ...patch }, guards = await fetchGuards(), denied = await denyingGuards({
+        guards,
+        doc: guardDocRef(documentId, before),
+        context: {
+          before: before ?? null,
+          after,
+          action,
+          ...as ? { identity: as.id } : {}
+        }
+      });
+      if (denied.length > 0)
+        throw new MutationGuardDeniedError({
+          documentId,
+          action,
+          denied: denied.map((g) => ({ guardId: g._id, ...g.name ? { name: g.name } : {} }))
+        });
+      return await client.patch(documentId).set(patch).commit(), await client.getDocument(documentId);
+    }
+  };
+}
+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) })
+  };
+}
+function createReadHelpers(scope) {
+  const { client, tags } = scope, intersectsTags = (docTags) => docTags !== void 0 && tags.some((t) => docTags.includes(t)), getInstance = async (instanceId) => {
+    const doc = await client.getDocument(instanceId);
+    if (!doc) throw new Error(`Workflow instance ${instanceId} not found`);
+    if (!intersectsTags(doc.tags))
+      throw new Error(`Workflow instance ${instanceId} not visible to this engine (tag mismatch)`);
+    return doc;
+  };
+  return {
+    getInstance,
+    currentStage: async (instanceId) => (await getInstance(instanceId)).currentStageId,
+    pendingEffects: async (instanceId) => (await getInstance(instanceId)).pendingEffects,
+    taskStatus: async (instanceId, taskId) => {
+      const instance = await getInstance(instanceId);
+      return instance.stages.find(
+        (s) => s.id === instance.currentStageId && s.exitedAt === void 0
+      )?.tasks.find((t) => t.id === taskId)?.status;
+    },
+    effectsContextMap: async (instanceId) => {
+      const instance = await getInstance(instanceId), map = {};
+      for (const entry of instance.effectsContext) map[entry.id] = entry.value;
+      return map;
+    },
+    children: async (parentInstanceId, taskId) => workflow.children({
+      ...scope,
+      instanceId: parentInstanceId,
+      ...taskId !== void 0 ? { taskId } : {}
+    }),
+    instancesForSubject: async (subjectRef, slotId = "subject") => (
+      // Subjects live on a workflow-scope `state[id == $slot]` doc.ref
+      // slot. Match instances whose slot's value.id equals the supplied
+      // ref. The slot id is conventionally "subject" but workflows may
+      // name it otherwise.
+      client.fetch(
+        `*[_type == "workflow.instance"
+          && state[_type == "workflow.state.doc.ref" && id == $slot][0].value.id == $ref
+          && count(tags[@ in $engineTags]) > 0] | order(startedAt asc)`,
+        { ref: subjectRef, slot: slotId, engineTags: tags }
+      )
+    ),
+    instancesByStage: async (workflowId, stageId, queryOptions) => {
+      const filter = queryOptions?.openOnly ? " && completedAt == null" : "";
+      return client.fetch(
+        `*[_type == "workflow.instance" && workflowId == $wf && currentStageId == $stage && count(tags[@ in $engineTags]) > 0${filter}]
+          | order(startedAt asc)`,
+        { wf: workflowId, stage: stageId, engineTags: tags }
+      );
+    },
+    snapshot: () => client.snapshot()
+  };
+}
+function createBench(options = {}) {
+  const tags = options.tags ?? ["bench"];
+  validateTags(tags);
+  const workflowResource = options.workflowResource ?? DEFAULT_WORKFLOW_RESOURCE, client = resolveBenchClient(options), scope = { client, tags, workflowResource }, access = resolveBenchAccess(options);
+  return {
+    client,
+    access,
+    currentUser: access.actor,
+    grants: access.grants ?? [],
+    seedDocuments: (documents) => client.add(documents),
+    ...createEngineWrappers(scope, access),
+    ...createReadHelpers(scope),
+    ...createGuardHelpers(client),
+    ...createQueryHelpers(scope)
+  };
+}
+export {
+  ALL_ACCESS,
+  ALL_ACCESS_USER,
+  DEFAULT_WORKFLOW_RESOURCE,
+  WILDCARD_GRANTS,
+  createBench
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../src/constants.ts","../src/access.ts","../src/engine-wrappers.ts","../src/guard-helpers.ts","../src/query-helpers.ts","../src/read-helpers.ts","../src/index.ts"],"sourcesContent":["import type {Actor, Grant, WorkflowAccess, WorkflowResource} from '@sanity/workflow-engine'\n\n/** Default workflow resource for benches that don't pass one. */\nexport const DEFAULT_WORKFLOW_RESOURCE: WorkflowResource = {\n  type: 'dataset',\n  id: 'test.test',\n}\n\n/**\n * The default actor used when tests don't specify one. Has the\n * conventional `\"*\"` wildcard role — `Action.roles` checks treat\n * `\"*\"` as matching any required role, and `Task.assignees` of\n * `{kind: \"role\"}` are satisfied by it too. Production code should\n * never see this id.\n */\nexport const ALL_ACCESS_USER: Actor = {\n  kind: 'user',\n  id: 'bench-user',\n  roles: ['*'],\n}\n\n/**\n * The default grants used when tests don't specify any. A single\n * permissive grant matches every document and confers all permissions.\n */\nexport const WILDCARD_GRANTS: Grant[] = [\n  {filter: 'true', permissions: ['create', 'read', 'update']},\n]\n\n/**\n * The bench's default access state — wildcard user + wildcard\n * grants. The bench injects this as the `access` override on every\n * engine call so the underlying TestClient (which has no token, so\n * no `/users/me` resolution path) never needs to do auth resolution.\n *\n * Production code never sees this; pass `createBench({ access })` to\n * test denial paths.\n */\nexport const ALL_ACCESS: WorkflowAccess = {\n  actor: ALL_ACCESS_USER,\n  grants: WILDCARD_GRANTS,\n}\n","import type {TestClient, TestClientAccessControl} from '@sanity-labs/client-fake-for-test'\nimport {createTestClient} from '@sanity-labs/client-fake-for-test'\nimport type {Actor, Grant, WorkflowAccess} from '@sanity/workflow-engine'\n\nimport {ALL_ACCESS_USER, WILDCARD_GRANTS} from './constants.ts'\nimport type {AccessShortcuts, StoreDocument} from './types.ts'\n\n/**\n * Build the TestClient the bench operates against, enforcing the\n * `client` / `accessControl` mutual-exclusion contract: callers either\n * supply their own client or have the bench mint one (optionally wired\n * with lake-side access control), never both.\n */\nexport function resolveBenchClient(options: {\n  client?: TestClient\n  accessControl?: TestClientAccessControl\n  documents?: StoreDocument[]\n}): TestClient {\n  if (options.accessControl !== undefined && options.client !== undefined) {\n    throw new Error(\n      'createBench: `accessControl` and `client` are mutually exclusive. Either let the bench ' +\n        'build a TestClient configured with the supplied accessControl, or build the client ' +\n        'yourself with `createTestClient({ accessControl })` and pass it in.',\n    )\n  }\n  const client =\n    options.client ??\n    createTestClient(\n      options.accessControl !== undefined ? {accessControl: options.accessControl} : {},\n    )\n  if (options.documents) client.add(options.documents)\n  return client\n}\n\n/**\n * Compose the bench-wide access default. Precedence: the canonical\n * `access` shape, then the `currentUser` / `grants` shortcuts, then\n * {@link ALL_ACCESS_USER} + {@link WILDCARD_GRANTS}.\n */\nexport function resolveBenchAccess(options: {\n  access?: WorkflowAccess\n  currentUser?: Actor\n  grants?: Grant[]\n}): WorkflowAccess {\n  return (\n    options.access ?? {\n      actor: options.currentUser ?? ALL_ACCESS_USER,\n      grants: options.grants ?? WILDCARD_GRANTS,\n    }\n  )\n}\n\n/**\n * Resolve the per-call access override against the bench-wide default.\n * A call may tighten or replace access via the canonical `{ access }`\n * field or the `{ actor, grants }` shortcuts.\n *\n * `canTokenResolve` is true when the bench's client was built with\n * `accessControl` — i.e. its `request` hook can resolve grants from\n * the ACL path. In that case an actor-only override (no grants) must\n * NOT inherit the bench's default grants: doing so would gate the\n * per-call actor with the default's (e.g. wildcard) grants instead of\n * that actor's real grants, silently false-greening denial tests. The\n * engine treats verb `access` as `WorkflowAccessOverride`, so the bench\n * hands it `{ actor }` alone and lets the engine token-resolve grants\n * (via the call's `grantsFromPath`) or skip the gate — both faithful to\n * production. Tokenless default benches keep inheriting the default\n * grants, since there is no other source.\n */\nexport function accessFor(\n  access: WorkflowAccess,\n  args: AccessShortcuts,\n  canTokenResolve: boolean,\n): WorkflowAccess {\n  if (args.access !== undefined) return args.access\n  if (args.actor === undefined && args.grants === undefined) return access\n  const inheritedGrants = canTokenResolve ? undefined : access.grants\n  const grants = args.grants ?? inheritedGrants\n  return {\n    actor: args.actor ?? access.actor,\n    ...(grants !== undefined ? {grants} : {}),\n  }\n}\n\n/**\n * Strip the bench-only access shortcut fields before spreading the rest\n * of a call's args into an engine call, so the composed `access` is the\n * single source of truth.\n */\nexport function stripAccessShortcuts<T extends AccessShortcuts>(\n  args: T,\n): Omit<T, 'access' | 'actor' | 'grants'> {\n  const rest = {...args}\n  delete rest.access\n  delete rest.actor\n  delete rest.grants\n  return rest\n}\n","import {\n  workflow,\n  type DeployDefinitionsArgs,\n  type DeployDefinitionsResult,\n  type DispatchResult,\n  type WorkflowAccess,\n  type WorkflowEvaluation,\n  type WorkflowInstance,\n} from '@sanity/workflow-engine'\n\nimport {accessFor, stripAccessShortcuts} from './access.ts'\nimport type {\n  AccessShortcuts,\n  BenchCompleteEffectArgs,\n  BenchEvaluateArgs,\n  BenchFireActionArgs,\n  BenchStartInstanceArgs,\n  BenchTickArgs,\n  EngineScope,\n} from './types.ts'\n\n/** Engine-call wrappers that inject the bench-owned client + tags + access. */\nexport type EngineWrappers = {\n  deployDefinitions: (\n    args: Omit<DeployDefinitionsArgs, 'client' | 'tags' | 'workflowResource'>,\n  ) => Promise<DeployDefinitionsResult>\n  startInstance: (args: BenchStartInstanceArgs) => Promise<WorkflowInstance>\n  fireAction: (args: BenchFireActionArgs) => Promise<DispatchResult>\n  completeEffect: (args: BenchCompleteEffectArgs) => Promise<DispatchResult>\n  tick: (args: BenchTickArgs) => Promise<DispatchResult>\n  evaluate: (args: BenchEvaluateArgs) => Promise<WorkflowEvaluation>\n}\n\n/**\n * Build the engine-call wrappers. Each access-aware wrapper composes the\n * call's `access` from the bench default plus any per-call override, then\n * spreads the remaining args into the engine with the bench-owned scope.\n */\nexport function createEngineWrappers(scope: EngineScope, access: WorkflowAccess): EngineWrappers {\n  // The fake client only exposes an own `request` hook when built with\n  // `accessControl`; that hook is what lets the engine token-resolve\n  // grants from the ACL path. A plain bench client has no such hook.\n  const canTokenResolve = 'request' in scope.client\n  const withAccess = <T extends AccessShortcuts>(args: T) => ({\n    ...scope,\n    access: accessFor(access, args, canTokenResolve),\n    ...stripAccessShortcuts(args),\n  })\n  return {\n    deployDefinitions: (args) => workflow.deployDefinitions({...scope, ...args}),\n    startInstance: (args) => workflow.startInstance(withAccess(args)),\n    fireAction: (args) => workflow.fireAction(withAccess(args)),\n    completeEffect: (args) => workflow.completeEffect(withAccess(args)),\n    tick: (args) => workflow.tick(withAccess(args)),\n    evaluate: (args) => workflow.evaluate(withAccess(args)),\n  }\n}\n","import type {TestClient} from '@sanity-labs/client-fake-for-test'\nimport {\n  denyingGuards,\n  MutationGuardDeniedError,\n  type Actor,\n  type MutationGuardAction,\n  type MutationGuardDoc,\n} from '@sanity/workflow-engine'\n\nimport type {StoreDocument} from './types.ts'\n\nexport type GuardHelpers = {\n  /** All deployed `temp.system.guard` docs in the store. */\n  listGuards: () => Promise<MutationGuardDoc[]>\n\n  /**\n   * Guards that would deny an arbitrary edit to `documentId` right now (i.e.\n   * active locks). Probes by changing every non-system field; a lifted guard\n   * (predicate `\"true\"`) returns nothing.\n   */\n  activeGuardsForDocument: (documentId: string, as?: Actor) => Promise<MutationGuardDoc[]>\n\n  /**\n   * Attempt a guarded write to a document — the bench's stand-in for the lake's\n   * mutation path. Evaluates deployed guards (incl. `identity()` = the actor)\n   * against the before/after image and throws `MutationGuardDeniedError` if any\n   * deny; otherwise applies the patch. OPTIMISTIC — not the lake enforcing.\n   */\n  editDocument: (\n    documentId: string,\n    patch: Record<string, unknown>,\n    options?: {action?: MutationGuardAction; as?: Actor},\n  ) => Promise<StoreDocument>\n}\n\n/**\n * Build the optimistic, bench-enforced lake mutation-guard helpers. These\n * stand in for the lake's mutation path: they evaluate deployed guards\n * against a before/after image rather than the lake enforcing.\n */\nexport function createGuardHelpers(client: TestClient): GuardHelpers {\n  const fetchGuards = () => client.fetch<MutationGuardDoc[]>(`*[_type == \"temp.system.guard\"]`)\n\n  const guardDocRef = (documentId: string, before: StoreDocument | null | undefined) => ({\n    id: documentId,\n    ...(before?._type ? {type: before._type} : {}),\n  })\n\n  return {\n    listGuards: () =>\n      client.fetch<MutationGuardDoc[]>(`*[_type == \"temp.system.guard\"] | order(_id asc)`),\n\n    activeGuardsForDocument: async (documentId, as) => {\n      const guards = await fetchGuards()\n      const before = await client.getDocument<StoreDocument>(documentId)\n      const after: Record<string, unknown> = {...(before ?? {_id: documentId, _type: 'unknown'})}\n      for (const key of Object.keys(after)) {\n        if (!key.startsWith('_')) after[key] = {__guardProbe: true}\n      }\n      after.__guardProbe = {__guardProbe: true}\n      return denyingGuards({\n        guards,\n        doc: guardDocRef(documentId, before),\n        context: {\n          before: before ?? null,\n          after: after as {_id: string; _type: string},\n          action: 'update',\n          ...(as ? {identity: as.id} : {}),\n        },\n      })\n    },\n\n    editDocument: async (documentId, patch, editOptions) => {\n      const action = editOptions?.action ?? 'update'\n      const as = editOptions?.as\n      const before = await client.getDocument<StoreDocument>(documentId)\n      const after =\n        action === 'delete' ? null : {...(before ?? {_id: documentId, _type: 'unknown'}), ...patch}\n      const guards = await fetchGuards()\n      const denied = await denyingGuards({\n        guards,\n        doc: guardDocRef(documentId, before),\n        context: {\n          before: before ?? null,\n          after,\n          action,\n          ...(as ? {identity: as.id} : {}),\n        },\n      })\n      if (denied.length > 0) {\n        throw new MutationGuardDeniedError({\n          documentId,\n          action,\n          denied: denied.map((g) => ({guardId: g._id, ...(g.name ? {name: g.name} : {})})),\n        })\n      }\n      await client.patch(documentId).set(patch).commit()\n      return (await client.getDocument(documentId)) as StoreDocument\n    },\n  }\n}\n","import {workflow} from '@sanity/workflow-engine'\n\nimport type {EngineScope} from './types.ts'\n\nexport type QueryHelpers = {\n  /**\n   * Run an arbitrary GROQ query through `workflow.query`. The query MUST\n   * filter on the auto-injected `$engineTags` param (e.g.\n   * `*[... && count(tags[@ in $engineTags]) > 0]`) or it throws — the\n   * engine refuses to run a query that could read across tenant tags.\n   * Caller is responsible for narrowing the result.\n   */\n  query: <T = unknown>(groq: string, params?: Record<string, unknown>) => Promise<T>\n\n  /**\n   * Snapshot-aware GROQ for `instanceId` — runs against the same\n   * in-memory view the engine's filters see. Reserved params (`$self`,\n   * `$subject`, `$parent`, `$ancestors`, `$now`, `$stage`) auto-bound\n   * in GDR URI form. Use to ask \"what does the engine see for this\n   * workflow?\" — useful for filter debugging, UIs that mirror engine\n   * state, etc.\n   */\n  queryInScope: <T = unknown>(\n    instanceId: string,\n    groq: string,\n    params?: Record<string, unknown>,\n  ) => Promise<T>\n}\n\n/** Build the GROQ passthrough helpers, both tag-scoped via the bench scope. */\nexport function createQueryHelpers(scope: EngineScope): QueryHelpers {\n  const withParams = (params?: Record<string, unknown>) => (params !== undefined ? {params} : {})\n  return {\n    query: <T = unknown>(groq: string, params?: Record<string, unknown>) =>\n      workflow.query<T>({...scope, groq, ...withParams(params)}),\n\n    queryInScope: <T = unknown>(\n      instanceId: string,\n      groq: string,\n      params?: Record<string, unknown>,\n    ) => workflow.queryInScope<T>({...scope, instanceId, groq, ...withParams(params)}),\n  }\n}\n","import {\n  workflow,\n  type EffectsContextEntry,\n  type PendingEffect,\n  type TaskStatus,\n  type WorkflowInstance,\n} from '@sanity/workflow-engine'\n\nimport type {EngineScope, StoreDocument} from './types.ts'\n\nexport type ReadHelpers = {\n  /** Read the workflow instance by id. Throws if missing. */\n  getInstance: (instanceId: string) => Promise<WorkflowInstance>\n\n  /** Current stage id of an instance. */\n  currentStage: (instanceId: string) => Promise<string>\n\n  /** Pending effects on an instance. */\n  pendingEffects: (instanceId: string) => Promise<PendingEffect[]>\n\n  /** Status of a single task on an instance, or undefined if missing. */\n  taskStatus: (instanceId: string, taskId: string) => Promise<TaskStatus | undefined>\n\n  /** EffectsContext entries on an instance, keyed by `key`. */\n  effectsContextMap: (instanceId: string) => Promise<Record<string, EffectsContextEntry['value']>>\n\n  /**\n   * Spawned children of `parentInstanceId`. If `taskId` is provided,\n   * only children spawned by that specific task on the parent.\n   *\n   * Walks `history.spawned` entries on the parent — this is the durable\n   * record. (The per-task `spawnedInstances` field on `stages[id == $stage && !defined(exitedAt)][0].tasks[]`\n   * gets wiped when the parent transitions past the spawning stage,\n   * since `taskStatus` is rebuilt on every transition.)\n   *\n   * Returns children ordered by `startedAt` ascending.\n   */\n  children: (parentInstanceId: string, taskId?: string) => Promise<WorkflowInstance[]>\n\n  /**\n   * All workflow instances whose `workflow.state.doc.ref` slot named\n   * `slotId` (default `\"subject\"`) matches the given doc id. Useful\n   * for \"what workflow is running on this document?\" questions. Pass\n   * `slotId` for workflows whose subject slot uses a different id.\n   */\n  instancesForSubject: (subjectRef: string, slotId?: string) => Promise<WorkflowInstance[]>\n\n  /**\n   * All instances of `workflowId` currently at `stageId`. Includes\n   * completed instances (`completedAt != null`) by default; set\n   * `{ openOnly: true }` to filter to in-flight only.\n   */\n  instancesByStage: (\n    workflowId: string,\n    stageId: string,\n    options?: {openOnly?: boolean},\n  ) => Promise<WorkflowInstance[]>\n\n  /** Snapshot of all documents in the store — for inspecting the world. */\n  snapshot: () => readonly StoreDocument[]\n}\n\n/**\n * Build the read-side DX helpers. {@link ReadHelpers.getInstance} enforces\n * tag-scoped visibility so every derived read (`currentStage`, `taskStatus`,\n * …) inherits the same isolation the engine's filters apply.\n */\nexport function createReadHelpers(scope: EngineScope): ReadHelpers {\n  const {client, tags} = scope\n\n  const intersectsTags = (docTags: string[] | undefined): boolean =>\n    docTags !== undefined && tags.some((t) => docTags.includes(t))\n\n  const getInstance = async (instanceId: string): Promise<WorkflowInstance> => {\n    const doc = await client.getDocument<WorkflowInstance>(instanceId)\n    if (!doc) throw new Error(`Workflow instance ${instanceId} not found`)\n    if (!intersectsTags(doc.tags)) {\n      throw new Error(`Workflow instance ${instanceId} not visible to this engine (tag mismatch)`)\n    }\n    return doc\n  }\n\n  return {\n    getInstance,\n\n    currentStage: async (instanceId) => (await getInstance(instanceId)).currentStageId,\n\n    pendingEffects: async (instanceId) => (await getInstance(instanceId)).pendingEffects,\n\n    taskStatus: async (instanceId, taskId) => {\n      const instance = await getInstance(instanceId)\n      const stage = instance.stages.find(\n        (s) => s.id === instance.currentStageId && s.exitedAt === undefined,\n      )\n      return stage?.tasks.find((t) => t.id === taskId)?.status\n    },\n\n    effectsContextMap: async (instanceId) => {\n      const instance = await getInstance(instanceId)\n      const map: Record<string, EffectsContextEntry['value']> = {}\n      for (const entry of instance.effectsContext) map[entry.id] = entry.value\n      return map\n    },\n\n    children: async (parentInstanceId, taskId) =>\n      workflow.children({\n        ...scope,\n        instanceId: parentInstanceId,\n        ...(taskId !== undefined ? {taskId} : {}),\n      }),\n\n    instancesForSubject: async (subjectRef, slotId = 'subject') =>\n      // Subjects live on a workflow-scope `state[id == $slot]` doc.ref\n      // slot. Match instances whose slot's value.id equals the supplied\n      // ref. The slot id is conventionally \"subject\" but workflows may\n      // name it otherwise.\n      client.fetch<WorkflowInstance[]>(\n        `*[_type == \"workflow.instance\"\n          && state[_type == \"workflow.state.doc.ref\" && id == $slot][0].value.id == $ref\n          && count(tags[@ in $engineTags]) > 0] | order(startedAt asc)`,\n        {ref: subjectRef, slot: slotId, engineTags: tags},\n      ),\n\n    instancesByStage: async (workflowId, stageId, queryOptions) => {\n      const filter = queryOptions?.openOnly ? ' && completedAt == null' : ''\n      return client.fetch<WorkflowInstance[]>(\n        `*[_type == \"workflow.instance\" && workflowId == $wf && currentStageId == $stage && count(tags[@ in $engineTags]) > 0${filter}]\n          | order(startedAt asc)`,\n        {wf: workflowId, stage: stageId, engineTags: tags},\n      )\n    },\n\n    snapshot: () => client.snapshot() as readonly StoreDocument[],\n  }\n}\n","/**\n * The bench — a dry-run test harness wrapping `@sanity-labs/client-fake-for-test`.\n *\n * The bench is the **only** place in the package that fabricates an\n * actor identity. The engine itself requires an explicit `actor` on\n * every call; the bench provides a default `ALL_ACCESS_USER` so tests\n * don't have to thread one manually, and exposes wrapper methods that\n * inject `bench.currentUser` + `bench.grants` for every engine call.\n *\n * ```\n * const bench = createBench();\n * await bench.deployDefinitions({ definitions: [definition] });\n * const inst = await bench.startInstance({ workflowId: \"...\", subject: {...} });\n * await bench.fireAction({ instanceId: inst._id, taskId: \"...\", action: \"...\" });\n * expect(await bench.currentStage(inst._id)).toBe(\"ready\");\n * ```\n *\n * For denial-path tests, pass an explicit `currentUser` and/or `grants`:\n *\n * ```\n * const bench = createBench({\n *   currentUser: { kind: \"user\", id: \"viewer\", roles: [\"viewer\"] },\n *   grants: [{ filter: '_type == \"workflow.instance\"', permissions: [\"read\"] }],\n * });\n * await expect(bench.fireAction({...})).rejects.toBeInstanceOf(ActionDisabledError);\n * ```\n */\n\nimport type {TestClient, TestClientAccessControl} from '@sanity-labs/client-fake-for-test'\nimport {validateTags} from '@sanity/workflow-engine'\nimport type {Actor, Grant, WorkflowAccess, WorkflowResource} from '@sanity/workflow-engine'\n\nimport {resolveBenchAccess, resolveBenchClient} from './access.ts'\nimport {DEFAULT_WORKFLOW_RESOURCE} from './constants.ts'\nimport {createEngineWrappers, type EngineWrappers} from './engine-wrappers.ts'\nimport {createGuardHelpers, type GuardHelpers} from './guard-helpers.ts'\nimport {createQueryHelpers, type QueryHelpers} from './query-helpers.ts'\nimport {createReadHelpers, type ReadHelpers} from './read-helpers.ts'\nimport type {StoreDocument} from './types.ts'\n\nexport {\n  ALL_ACCESS,\n  ALL_ACCESS_USER,\n  DEFAULT_WORKFLOW_RESOURCE,\n  WILDCARD_GRANTS,\n} from './constants.ts'\n\nexport interface CreateBenchOptions {\n  /** Subject documents seeded into the store. */\n  documents?: StoreDocument[]\n  /**\n   * Access state (actor + grants) injected as the engine `access`\n   * override on every wrapped call. Defaults to `ALL_ACCESS` —\n   * wildcard user + wildcard grants. Pass a restrictive value to\n   * test denial paths.\n   *\n   * Mutually exclusive with the `currentUser` / `grants` shortcuts\n   * (which compose into the same shape internally).\n   */\n  access?: WorkflowAccess\n  /** Shortcut for `access.actor`. Composed with `grants`. */\n  currentUser?: Actor\n  /** Shortcut for `access.grants`. Composed with `currentUser`. */\n  grants?: Grant[]\n  /**\n   * Opt-in: simulate Sanity's hard write-gate inside the TestClient.\n   *\n   * When set, the bench's underlying TestClient:\n   *   - Exposes `client.request({ url })` serving `/users/me` + the\n   *     configured ACL path, so the engine can resolve `WorkflowAccess`\n   *     from \"the token\" exactly like production.\n   *   - Rejects writes the grants don't permit with a Sanity-style\n   *     `WriteAccessDeniedError` — the same 403 a real lake would\n   *     return.\n   *\n   * Use this to demonstrate what would happen if the engine's\n   * soft-gate were bypassed (or disagreed with) — the lake is still\n   * authoritative. The bench's `access` field is the engine-side\n   * override; `accessControl` is the lake-side enforcement. They\n   * usually carry the same `actor` + `grants` but can be made to\n   * disagree to test edge cases.\n   *\n   * Mutually exclusive with passing a pre-built `client`.\n   */\n  accessControl?: TestClientAccessControl\n  /**\n   * Engine-scope tags. Defaults to `[\"bench\"]`. Pass disjoint sets to two\n   * benches sharing a `client` to assert multi-tenant isolation; pass an\n   * overlapping set to assert visibility through a shared tag.\n   *\n   * Tags must be ASCII lowercase + digits + dashes, no leading dash,\n   * no dots — validated at construction.\n   */\n  tags?: string[]\n  /**\n   * Shared TestClient. If omitted, the bench creates its own — two\n   * benches without a shared client are completely isolated, regardless\n   * of tags. Pass the same client to two benches to test tag-scoped\n   * visibility across a shared store.\n   */\n  client?: TestClient\n  /**\n   * Workflow resource the bench's engine operates against. Mirrors\n   * `@sanity/client`'s `ClientConfigResource`. Defaults to\n   * `{ type: \"dataset\", id: \"test.test\" }` so all bench-minted GDR\n   * URIs read as `dataset:test:test:<docId>`.\n   */\n  workflowResource?: WorkflowResource\n}\n\n/** Base bench state, distinct from the engine/read/guard/query helper groups. */\ninterface BenchState {\n  /** The fake Sanity client. Passed automatically by bench wrappers. */\n  client: TestClient\n  /**\n   * The access state (actor + grants) the bench injects as the\n   * `access` override on every wrapped engine call. Defaults to\n   * `ALL_ACCESS`.\n   */\n  access: WorkflowAccess\n  /** Convenience: `access.actor`. */\n  currentUser: Actor\n  /** Convenience: `access.grants ?? []`. */\n  grants: Grant[]\n\n  /** Add documents to the store after construction. */\n  seedDocuments: (documents: StoreDocument[]) => void\n}\n\nexport type Bench = BenchState & EngineWrappers & ReadHelpers & GuardHelpers & QueryHelpers\n\n/**\n * Create a fresh bench. By default the bench is fully isolated — two\n * `createBench()` calls have no shared state. Pass `client` + `tags`\n * to two benches to share a store and exercise tag scoping.\n */\nexport function createBench(options: CreateBenchOptions = {}): Bench {\n  const tags = options.tags ?? ['bench']\n  validateTags(tags)\n  const workflowResource = options.workflowResource ?? DEFAULT_WORKFLOW_RESOURCE\n  const client = resolveBenchClient(options)\n  const scope = {client, tags, workflowResource}\n\n  const access = resolveBenchAccess(options)\n\n  return {\n    client,\n    access,\n    currentUser: access.actor,\n    grants: access.grants ?? [],\n\n    seedDocuments: (documents) => client.add(documents),\n\n    ...createEngineWrappers(scope, access),\n    ...createReadHelpers(scope),\n    ...createGuardHelpers(client),\n    ...createQueryHelpers(scope),\n  }\n}\n"],"names":[],"mappings":";;AAGO,MAAM,4BAA8C;AAAA,EACzD,MAAM;AAAA,EACN,IAAI;AACN,GASa,kBAAyB;AAAA,EACpC,MAAM;AAAA,EACN,IAAI;AAAA,EACJ,OAAO,CAAC,GAAG;AACb,GAMa,kBAA2B;AAAA,EACtC,EAAC,QAAQ,QAAQ,aAAa,CAAC,UAAU,QAAQ,QAAQ,EAAA;AAC3D,GAWa,aAA6B;AAAA,EACxC,OAAO;AAAA,EACP,QAAQ;AACV;AC5BO,SAAS,mBAAmB,SAIpB;AACb,MAAI,QAAQ,kBAAkB,UAAa,QAAQ,WAAW;AAC5D,UAAM,IAAI;AAAA,MACR;AAAA,IAAA;AAKJ,QAAM,SACJ,QAAQ,UACR;AAAA,IACE,QAAQ,kBAAkB,SAAY,EAAC,eAAe,QAAQ,kBAAiB,CAAA;AAAA,EAAC;AAEpF,SAAI,QAAQ,aAAW,OAAO,IAAI,QAAQ,SAAS,GAC5C;AACT;AAOO,SAAS,mBAAmB,SAIhB;AACjB,SACE,QAAQ,UAAU;AAAA,IAChB,OAAO,QAAQ,eAAe;AAAA,IAC9B,QAAQ,QAAQ,UAAU;AAAA,EAAA;AAGhC;AAmBO,SAAS,UACd,QACA,MACA,iBACgB;AAChB,MAAI,KAAK,WAAW,OAAW,QAAO,KAAK;AAC3C,MAAI,KAAK,UAAU,UAAa,KAAK,WAAW,OAAW,QAAO;AAClE,QAAM,kBAAkB,kBAAkB,SAAY,OAAO,QACvD,SAAS,KAAK,UAAU;AAC9B,SAAO;AAAA,IACL,OAAO,KAAK,SAAS,OAAO;AAAA,IAC5B,GAAI,WAAW,SAAY,EAAC,WAAU,CAAA;AAAA,EAAC;AAE3C;AAOO,SAAS,qBACd,MACwC;AACxC,QAAM,OAAO,EAAC,GAAG,KAAA;AACjB,SAAA,OAAO,KAAK,QACZ,OAAO,KAAK,OACZ,OAAO,KAAK,QACL;AACT;AC3DO,SAAS,qBAAqB,OAAoB,QAAwC;AAI/F,QAAM,kBAAkB,aAAa,MAAM,QACrC,aAAa,CAA4B,UAAa;AAAA,IAC1D,GAAG;AAAA,IACH,QAAQ,UAAU,QAAQ,MAAM,eAAe;AAAA,IAC/C,GAAG,qBAAqB,IAAI;AAAA,EAAA;AAE9B,SAAO;AAAA,IACL,mBAAmB,CAAC,SAAS,SAAS,kBAAkB,EAAC,GAAG,OAAO,GAAG,MAAK;AAAA,IAC3E,eAAe,CAAC,SAAS,SAAS,cAAc,WAAW,IAAI,CAAC;AAAA,IAChE,YAAY,CAAC,SAAS,SAAS,WAAW,WAAW,IAAI,CAAC;AAAA,IAC1D,gBAAgB,CAAC,SAAS,SAAS,eAAe,WAAW,IAAI,CAAC;AAAA,IAClE,MAAM,CAAC,SAAS,SAAS,KAAK,WAAW,IAAI,CAAC;AAAA,IAC9C,UAAU,CAAC,SAAS,SAAS,SAAS,WAAW,IAAI,CAAC;AAAA,EAAA;AAE1D;AChBO,SAAS,mBAAmB,QAAkC;AACnE,QAAM,cAAc,MAAM,OAAO,MAA0B,iCAAiC,GAEtF,cAAc,CAAC,YAAoB,YAA8C;AAAA,IACrF,IAAI;AAAA,IACJ,GAAI,QAAQ,QAAQ,EAAC,MAAM,OAAO,MAAA,IAAS,CAAA;AAAA,EAAC;AAG9C,SAAO;AAAA,IACL,YAAY,MACV,OAAO,MAA0B,kDAAkD;AAAA,IAErF,yBAAyB,OAAO,YAAY,OAAO;AACjD,YAAM,SAAS,MAAM,YAAA,GACf,SAAS,MAAM,OAAO,YAA2B,UAAU,GAC3D,QAAiC,EAAC,GAAI,UAAU,EAAC,KAAK,YAAY,OAAO,YAAS;AACxF,iBAAW,OAAO,OAAO,KAAK,KAAK;AAC5B,YAAI,WAAW,GAAG,MAAG,MAAM,GAAG,IAAI,EAAC,cAAc;AAExD,aAAA,MAAM,eAAe,EAAC,cAAc,GAAA,GAC7B,cAAc;AAAA,QACnB;AAAA,QACA,KAAK,YAAY,YAAY,MAAM;AAAA,QACnC,SAAS;AAAA,UACP,QAAQ,UAAU;AAAA,UAClB;AAAA,UACA,QAAQ;AAAA,UACR,GAAI,KAAK,EAAC,UAAU,GAAG,GAAA,IAAM,CAAA;AAAA,QAAC;AAAA,MAChC,CACD;AAAA,IACH;AAAA,IAEA,cAAc,OAAO,YAAY,OAAO,gBAAgB;AACtD,YAAM,SAAS,aAAa,UAAU,UAChC,KAAK,aAAa,IAClB,SAAS,MAAM,OAAO,YAA2B,UAAU,GAC3D,QACJ,WAAW,WAAW,OAAO,EAAC,GAAI,UAAU,EAAC,KAAK,YAAY,OAAO,aAAa,GAAG,MAAA,GACjF,SAAS,MAAM,YAAA,GACf,SAAS,MAAM,cAAc;AAAA,QACjC;AAAA,QACA,KAAK,YAAY,YAAY,MAAM;AAAA,QACnC,SAAS;AAAA,UACP,QAAQ,UAAU;AAAA,UAClB;AAAA,UACA;AAAA,UACA,GAAI,KAAK,EAAC,UAAU,GAAG,GAAA,IAAM,CAAA;AAAA,QAAC;AAAA,MAChC,CACD;AACD,UAAI,OAAO,SAAS;AAClB,cAAM,IAAI,yBAAyB;AAAA,UACjC;AAAA,UACA;AAAA,UACA,QAAQ,OAAO,IAAI,CAAC,OAAO,EAAC,SAAS,EAAE,KAAK,GAAI,EAAE,OAAO,EAAC,MAAM,EAAE,SAAQ,CAAA,IAAK;AAAA,QAAA,CAChF;AAEH,aAAA,MAAM,OAAO,MAAM,UAAU,EAAE,IAAI,KAAK,EAAE,OAAA,GAClC,MAAM,OAAO,YAAY,UAAU;AAAA,IAC7C;AAAA,EAAA;AAEJ;ACtEO,SAAS,mBAAmB,OAAkC;AACnE,QAAM,aAAa,CAAC,WAAsC,WAAW,SAAY,EAAC,OAAA,IAAU,CAAA;AAC5F,SAAO;AAAA,IACL,OAAO,CAAc,MAAc,WACjC,SAAS,MAAS,EAAC,GAAG,OAAO,MAAM,GAAG,WAAW,MAAM,GAAE;AAAA,IAE3D,cAAc,CACZ,YACA,MACA,WACG,SAAS,aAAgB,EAAC,GAAG,OAAO,YAAY,MAAM,GAAG,WAAW,MAAM,GAAE;AAAA,EAAA;AAErF;ACyBO,SAAS,kBAAkB,OAAiC;AACjE,QAAM,EAAC,QAAQ,SAAQ,OAEjB,iBAAiB,CAAC,YACtB,YAAY,UAAa,KAAK,KAAK,CAAC,MAAM,QAAQ,SAAS,CAAC,CAAC,GAEzD,cAAc,OAAO,eAAkD;AAC3E,UAAM,MAAM,MAAM,OAAO,YAA8B,UAAU;AACjE,QAAI,CAAC,IAAK,OAAM,IAAI,MAAM,qBAAqB,UAAU,YAAY;AACrE,QAAI,CAAC,eAAe,IAAI,IAAI;AAC1B,YAAM,IAAI,MAAM,qBAAqB,UAAU,4CAA4C;AAE7F,WAAO;AAAA,EACT;AAEA,SAAO;AAAA,IACL;AAAA,IAEA,cAAc,OAAO,gBAAgB,MAAM,YAAY,UAAU,GAAG;AAAA,IAEpE,gBAAgB,OAAO,gBAAgB,MAAM,YAAY,UAAU,GAAG;AAAA,IAEtE,YAAY,OAAO,YAAY,WAAW;AACxC,YAAM,WAAW,MAAM,YAAY,UAAU;AAI7C,aAHc,SAAS,OAAO;AAAA,QAC5B,CAAC,MAAM,EAAE,OAAO,SAAS,kBAAkB,EAAE,aAAa;AAAA,MAAA,GAE9C,MAAM,KAAK,CAAC,MAAM,EAAE,OAAO,MAAM,GAAG;AAAA,IACpD;AAAA,IAEA,mBAAmB,OAAO,eAAe;AACvC,YAAM,WAAW,MAAM,YAAY,UAAU,GACvC,MAAoD,CAAA;AAC1D,iBAAW,SAAS,SAAS,oBAAoB,MAAM,EAAE,IAAI,MAAM;AACnE,aAAO;AAAA,IACT;AAAA,IAEA,UAAU,OAAO,kBAAkB,WACjC,SAAS,SAAS;AAAA,MAChB,GAAG;AAAA,MACH,YAAY;AAAA,MACZ,GAAI,WAAW,SAAY,EAAC,WAAU,CAAA;AAAA,IAAC,CACxC;AAAA,IAEH,qBAAqB,OAAO,YAAY,SAAS;AAAA;AAAA;AAAA;AAAA;AAAA,MAK/C,OAAO;AAAA,QACL;AAAA;AAAA;AAAA,QAGA,EAAC,KAAK,YAAY,MAAM,QAAQ,YAAY,KAAA;AAAA,MAAI;AAAA;AAAA,IAGpD,kBAAkB,OAAO,YAAY,SAAS,iBAAiB;AAC7D,YAAM,SAAS,cAAc,WAAW,4BAA4B;AACpE,aAAO,OAAO;AAAA,QACZ,uHAAuH,MAAM;AAAA;AAAA,QAE7H,EAAC,IAAI,YAAY,OAAO,SAAS,YAAY,KAAA;AAAA,MAAI;AAAA,IAErD;AAAA,IAEA,UAAU,MAAM,OAAO,SAAA;AAAA,EAAS;AAEpC;ACEO,SAAS,YAAY,UAA8B,IAAW;AACnE,QAAM,OAAO,QAAQ,QAAQ,CAAC,OAAO;AACrC,eAAa,IAAI;AACjB,QAAM,mBAAmB,QAAQ,oBAAoB,2BAC/C,SAAS,mBAAmB,OAAO,GACnC,QAAQ,EAAC,QAAQ,MAAM,iBAAA,GAEvB,SAAS,mBAAmB,OAAO;AAEzC,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA,aAAa,OAAO;AAAA,IACpB,QAAQ,OAAO,UAAU,CAAA;AAAA,IAEzB,eAAe,CAAC,cAAc,OAAO,IAAI,SAAS;AAAA,IAElD,GAAG,qBAAqB,OAAO,MAAM;AAAA,IACrC,GAAG,kBAAkB,KAAK;AAAA,IAC1B,GAAG,mBAAmB,MAAM;AAAA,IAC5B,GAAG,mBAAmB,KAAK;AAAA,EAAA;AAE/B;"}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@sanity/workflow-engine-test",
+  "version": "0.0.0",
+  "description": "In-memory test bench (createBench) for @sanity/workflow-engine.",
+  "keywords": [
+    "sanity",
+    "sanity-io",
+    "test-bench",
+    "testing",
+    "workflow",
+    "workflows"
+  ],
+  "homepage": "https://github.com/sanity-io/workflows/tree/main/packages/workflow-engine-test#readme",
+  "bugs": {
+    "url": "https://github.com/sanity-io/workflows/issues"
+  },
+  "license": "MIT",
+  "author": "Sanity.io <hello@sanity.io>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sanity-io/workflows.git",
+    "directory": "packages/workflow-engine-test"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "dependencies": {
+    "@sanity-labs/client-fake-for-test": "^0.3.0",
+    "@sanity/workflow-engine": "0.0.0"
+  },
+  "devDependencies": {
+    "@sanity/pkg-utils": "^10.5.2",
+    "vitest": "^4.1.8"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "pkg-utils build --clean",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  }
+}