@sanity/workflow-engine-test 0.9.0 → 0.11.0

package/dist/index.d.ts

@@ -1,36 +1,46 @@
+import type { AbortInstanceArgs } from "@sanity/workflow-engine";
 import { ActivityStatus } from "@sanity/workflow-engine";
 import { Actor } from "@sanity/workflow-engine";
+import { ChildrenArgs } from "@sanity/workflow-engine";
+import { Clock } from "@sanity/workflow-engine";
 import type { CompleteEffectArgs } from "@sanity/workflow-engine";
+import { CreateEngineArgs } from "@sanity/workflow-engine";
+import type { DeclaredExecutionContext } from "@sanity/workflow-engine";
+import { DefinitionsForDocumentArgs } from "@sanity/workflow-engine";
+import type { DeleteDefinitionArgs } from "@sanity/workflow-engine";
+import { DeleteDefinitionResult } from "@sanity/workflow-engine";
 import { DeployDefinitionsArgs } from "@sanity/workflow-engine";
 import { DeployDefinitionsResult } from "@sanity/workflow-engine";
+import { DeployedDefinition } from "@sanity/workflow-engine";
 import type { EditFieldArgs } from "@sanity/workflow-engine";
+import { Engine } from "@sanity/workflow-engine";
 import type { EvaluateArgs } from "@sanity/workflow-engine";
+import { FindPendingEffectsArgs } from "@sanity/workflow-engine";
 import type { FireActionArgs } from "@sanity/workflow-engine";
-import { GdrUri } from "@sanity/workflow-engine";
 import type { Grant } from "@sanity/workflow-engine";
 import { InitialFieldValue } from "@sanity/workflow-engine";
+import { InstanceRefArgs } from "@sanity/workflow-engine";
+import { InstancesForDocumentArgs } from "@sanity/workflow-engine";
+import { InstancesQueryFilter } from "@sanity/workflow-engine";
 import { MutationGuardAction } from "@sanity/workflow-engine";
 import { MutationGuardDoc } from "@sanity/workflow-engine";
 import type { OperationArgs } from "@sanity/workflow-engine";
 import { OperationResult } from "@sanity/workflow-engine";
 import { PendingEffect } from "@sanity/workflow-engine";
+import type { SetStageArgs } from "@sanity/workflow-engine";
 import type { StartInstanceArgs } from "@sanity/workflow-engine";
+import type { TestClient } from "@sanity-labs/client-fake-for-test";
 import type { WorkflowAccess } from "@sanity/workflow-engine";
+import { WorkflowDefinitionInput } from "@sanity/workflow-engine";
 import { WorkflowEvaluation } from "@sanity/workflow-engine";
 import { WorkflowInstance } from "@sanity/workflow-engine";
 import type { WorkflowResource } from "@sanity/workflow-engine";
 
-declare type Action = ReleaseAction | VersionAction;
-
-declare interface ActionResult {
-  transactionId: string;
-}
-
 /**
- * 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.
+ * The bench's default identity — wildcard user + wildcard grants,
+ * registered as the default token on the bench's fake client so the
+ * engine token-resolves it (`/users/me` + the ACL path) exactly like
+ * production.
  *
  * Production code never sees this; pass `createBench({ access })` to
  * test denial paths.
@@ -55,56 +65,73 @@ export declare type Bench = BenchState &
   QueryHelpers &
   ComposedHelpers;
 
-declare type BenchCompleteEffectArgs = Omit<CompleteEffectArgs, "access"> & {
-  access?: WorkflowAccess;
-  /** Shortcut for `access.actor`. */
-  actor?: Actor;
-};
+/** Default engine-scope partition tag for benches that don't pass one. */
+export declare const BENCH_TAG = "bench";
 
-declare type BenchEditFieldArgs = Omit<EditFieldArgs, "access"> & {
-  access?: WorkflowAccess;
-  /** Shortcut for `access.actor`. */
-  actor?: Actor;
-  /** Shortcut for `access.grants`. */
-  grants?: Grant[];
-};
+declare type BenchAbortInstanceArgs = BenchArgs<AbortInstanceArgs>;
 
-declare type BenchEvaluateArgs = Omit<EvaluateArgs, "access"> & {
+/**
+ * A bench verb's args: the engine verb's args plus the bench's per-call
+ * identity shortcuts — the composed pair runs the verb through a
+ * token-scoped sibling client.
+ */
+declare type BenchArgs<T> = T & {
   access?: WorkflowAccess;
   /** Shortcut for `access.actor`. */
   actor?: Actor;
-  /** Shortcut for `access.grants`. */
-  grants?: Grant[];
 };
 
-declare type BenchFireActionArgs = Omit<FireActionArgs, "access"> & {
-  access?: WorkflowAccess;
-  /** Shortcut for `access.actor`. */
-  actor?: Actor;
+/** {@link BenchArgs} for the verbs that also take the `grants` shortcut. */
+declare type BenchArgsWithGrants<T> = BenchArgs<T> & {
   /** Shortcut for `access.grants`. */
   grants?: Grant[];
 };
 
-declare type BenchStartInstanceArgs = Omit<StartInstanceArgs, "access"> & {
-  access?: WorkflowAccess;
-  /** Shortcut for `access.actor`. */
-  actor?: Actor;
-};
+declare type BenchCompleteEffectArgs = BenchArgs<CompleteEffectArgs>;
+
+declare type BenchDeleteDefinitionArgs =
+  BenchArgsWithGrants<DeleteDefinitionArgs>;
+
+declare type BenchEditFieldArgs = BenchArgsWithGrants<EditFieldArgs>;
+
+declare type BenchEvaluateArgs = BenchArgsWithGrants<EvaluateArgs>;
+
+declare type BenchFireActionArgs = BenchArgsWithGrants<FireActionArgs>;
+
+declare type BenchSetStageArgs = BenchArgs<SetStageArgs>;
+
+declare type BenchStartInstanceArgs = BenchArgs<StartInstanceArgs>;
 
 /** 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 engine-scope partition tag every wrapped call runs under. */
+  tag: string;
+  /** The workflow resource every wrapped call targets. */
+  workflowResource: WorkflowResource;
+  /** The declared execution context stamped on every wrapped call's history
+   *  entries (default `{kind: 'test'}`) — inherited by {@link createBenchEngine}. */
+  executionContext: DeclaredExecutionContext;
   /**
-   * The access state (actor + grants) the bench injects as the
-   * `access` override on every wrapped engine call. Defaults to
-   * `ALL_ACCESS`.
+   * The bench's default identity (actor + grants) — registered as the
+   * default token on the fake client. Defaults to `ALL_ACCESS`.
    */
   access: WorkflowAccess;
   /** Convenience: `access.actor`. */
   currentUser: Actor;
   /** Convenience: `access.grants ?? []`. */
   grants: Grant[];
+  /**
+   * A token-bound sibling client acting as `access` — the bench's ONE
+   * identity-registration seam. Registers the pair on the fake client's
+   * family-shared registry (idempotent, cached per identity; omitted
+   * grants default to wildcard) and returns the sibling whose
+   * `/users/me` + ACL path serve it — the engine token-resolves it like
+   * production. Bind it to {@link createBenchEngine} to act as another
+   * user end-to-end; never hand-roll `addIdentity` + `withConfig`.
+   */
+  clientFor: (access: WorkflowAccess) => TestClient;
   /** Add documents to the store after construction. */
   seedDocuments: (documents: StoreDocument[]) => void;
   /**
@@ -117,8 +144,7 @@ declare interface BenchState {
    * Freeze the bench clock at an explicit ISO instant. Every subsequent
    * engine call (`startInstance` / `fireAction` / `tick` / `completeEffect`
    * / `evaluate`) sees this as `$now` and stamps it on history, so
-   * time-based `completeWhen` / `failWhen` / SLA predicates are
-   * deterministic.
+   * time-based `when` triggers and SLA predicates are deterministic.
    */
   setNow: (iso: string) => void;
   /**
@@ -129,31 +155,7 @@ declare interface BenchState {
   advance: (ms: number) => void;
 }
 
-declare type BenchTickArgs = Omit<OperationArgs, "access"> & {
-  access?: WorkflowAccess;
-  /** Shortcut for `access.actor`. */
-  actor?: Actor;
-};
-
-/**
- * One recorded invocation of a client method — the spy layer behind
- * `client.calls()` / `client.callCount()`. `result` holds the resolved
- * value (awaited, for async methods); `error` holds the thrown/rejected
- * value. Builder-returning methods (`patch`, `transaction`) record the
- * builder as `result`; their eventual writes show up in the mutation log.
- */
-declare interface CallRecord {
-  /** Method name; namespace methods are dotted, e.g. `releases.create`. */
-  method: string;
-  /** Arguments as passed (stored by reference, like `vi.fn`). */
-  args: unknown[];
-  /** Resolved/returned value, set once the call settles successfully. */
-  result?: unknown;
-  /** Thrown or rejected value, set if the call failed. */
-  error?: unknown;
-  projectId: string;
-  dataset: string;
-}
+declare type BenchTickArgs = BenchArgs<OperationArgs>;
 
 /** Helpers composed across the wrapper + read groups at bench assembly. */
 declare interface ComposedHelpers {
@@ -177,14 +179,28 @@ declare interface ComposedHelpers {
  */
 export declare function createBench(options?: CreateBenchOptions): Bench;
 
+/**
+ * Build an out-of-band {@link Engine} on a bench's client, inheriting the
+ * bench's tag, workflow resource, and clock (so `setNow` / `advance` govern
+ * the engine's `$now` too). Use this when a test needs an engine of its own —
+ * custom effect handlers, racing two drainers — rather than the wrappers the
+ * bench exposes. `overrides` win over every inherited value.
+ */
+export declare function createBenchEngine(
+  bench: EngineScope & {
+    now: Clock;
+  },
+  overrides?: Partial<CreateEngineArgs>,
+): Engine;
+
 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.
+   * The bench's default identity (actor + grants), registered as the
+   * default token on the fake client — the engine token-resolves it like
+   * production. 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).
@@ -195,28 +211,7 @@ export declare interface CreateBenchOptions {
   /** 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 environment partition. Defaults to `"bench"`. Pass
+   * Engine-scope environment partition. Defaults to {@link BENCH_TAG}. Pass
    * different tags to two benches sharing a `client` to assert partition
    * isolation; pass the same tag to assert visibility through a shared
    * partition.
@@ -246,140 +241,71 @@ export declare interface CreateBenchOptions {
    * start on the wall clock (`advance` / `setNow` can freeze it later).
    */
   now?: string;
-}
-
-declare interface CurrentUser {
-  id: string;
-  name?: string;
-  email?: string;
-  /** @deprecated singular `role` on legacy responses */
-  role?: string;
-  roles?: {
-    name: string;
-    title?: string;
-    description?: string;
-  }[];
+  /**
+   * Declared execution context stamped (with the inferred runtime) on every
+   * history entry the bench's engine calls append. Defaults to
+   * `{ kind: "test" }`; override to exercise provenance rendering.
+   */
+  executionContext?: DeclaredExecutionContext;
 }
 
 /** Default workflow resource for benches that don't pass one. */
 export declare const DEFAULT_WORKFLOW_RESOURCE: WorkflowResource;
 
 /**
- * Document body accepted by `version.create` / `createVersion`. The id
- * is derived from `releaseId + publishedId` so callers may omit `_id`
- * here. `version.replace` requires `_id` since it identifies the doc
- * to replace.
+ * The write {@link GuardHelpers.editDocument} performs. Every arm is a real
+ * distinct client write the guard seam vets under that action — `create` is
+ * deliberately absent because editing addresses an existing document; create
+ * through the client (`bench.client.create` / `clientFor(...).create`), which
+ * the same seam gates as a create.
  */
-declare interface DocumentBody {
-  _id?: string;
-  _type: string;
-  [field: string]: unknown;
-}
+export declare type EditDocumentAction = Exclude<MutationGuardAction, "create">;
 
-declare type DocumentValuePermission = "create" | "read" | "update";
+/**
+ * How {@link GuardHelpers.editDocument} mutates the document. Each present
+ * key becomes one patch op, applied in `set` → `unset` → `insert` order in a
+ * single commit; the shapes mirror the client's patch builder.
+ */
+export declare type EditDocumentPatch = {
+  set?: Record<string, unknown>;
+  unset?: string[];
+  insert?: {
+    position: "before" | "after" | "replace";
+    anchor: string;
+    items: unknown[];
+  };
+};
 
-/** Engine-call wrappers that inject the bench-owned client + tag + access. */
+/** The bench-owned engine call context injected into every wrapped verb. */
+declare type EngineScope = {
+  client: TestClient;
+  tag: string;
+  workflowResource: WorkflowResource;
+  executionContext: DeclaredExecutionContext;
+};
+
+/** Engine-call wrappers that inject the bench-owned client + tag + identity. */
 declare type EngineWrappers = {
-  deployDefinitions: (
-    args: DeployDefinitionsArgs,
+  deployDefinitions: <T extends WorkflowDefinitionInput<T>>(
+    args: DeployDefinitionsArgs<T>,
   ) => Promise<DeployDefinitionsResult>;
+  deleteDefinition: (
+    args: BenchDeleteDefinitionArgs,
+  ) => Promise<DeleteDefinitionResult>;
   startInstance: (args: BenchStartInstanceArgs) => Promise<OperationResult>;
   fireAction: (args: BenchFireActionArgs) => Promise<OperationResult>;
   editField: (args: BenchEditFieldArgs) => Promise<OperationResult>;
   completeEffect: (args: BenchCompleteEffectArgs) => Promise<OperationResult>;
   tick: (args: BenchTickArgs) => Promise<OperationResult>;
   evaluate: (args: BenchEvaluateArgs) => Promise<WorkflowEvaluation>;
+  /** Admin override — bypass filters/transitions and force the stage. */
+  setStage: (args: BenchSetStageArgs) => Promise<OperationResult>;
+  /** Admin override — hard-stop an in-flight instance where it stands. */
+  abortInstance: (args: BenchAbortInstanceArgs) => Promise<OperationResult>;
   guardsForInstance: (instanceId: string) => Promise<MutationGuardDoc[]>;
   guardsForDefinition: (definition: string) => Promise<MutationGuardDoc[]>;
 };
 
-/**
- * A single mutation in the raw array form accepted by `mutate()` — the
- * same shape `@sanity/client` accepts. The inline `patch` form mirrors
- * the real client's keyed patch object.
- */
-declare type FakeMutation =
-  | {
-      create: SanityDocumentLike;
-    }
-  | {
-      createOrReplace: SanityDocumentLike;
-    }
-  | {
-      createIfNotExists: SanityDocumentLike;
-    }
-  | {
-      delete: {
-        id: string;
-      };
-    }
-  | {
-      patch: {
-        id: string;
-        ifRevisionID?: string;
-        set?: Record<string, unknown>;
-        setIfMissing?: Record<string, unknown>;
-        unset?: string[];
-        inc?: Record<string, number>;
-        dec?: Record<string, number>;
-        insert?: {
-          before?: string;
-          after?: string;
-          replace?: string;
-          items: unknown[];
-        };
-      };
-    };
-
-/**
- * Data-plane subset of `@sanity/client`'s surface, with multi-dataset support.
- *
- * One `createTestClient()` call creates a registry of stores keyed by
- * `(projectId, dataset)`. The returned client points at one of them.
- * `withConfig({ projectId, dataset })` returns a new handle into the same
- * registry but pointing at a different store — useful for workflows where
- * definitions live in one dataset and instances live in another.
- *
- * Two separate `createTestClient()` calls have separate registries, so
- * tests stay isolated from each other.
- *
- * Methods not on the real client:
- *
- * - `seed`, `add`, `reset`, `snapshot`, `store` — bulk-load helpers,
- *   scoped to the current dataset.
- * - `simulateConcurrentEdit()` — force the next N revision-guarded writes
- *   to a document to 409, for optimistic-locking retry tests.
- * - `datasets()` — lists known dataset keys in this registry.
- *
- * Methods deliberately omitted:
- *
- * - Project / agent / asset / live / listen APIs.
- */
-declare interface FetchOptions {
-  /** Override the client's configured perspective for this read. */
-  perspective?: Perspective;
-  /**
-   * When `false`, resolve to a {@link RawQueryResponse} (`{ query, ms,
-   * result }`) instead of the bare result — mirrors `@sanity/client`.
-   * Defaults to `true`.
-   */
-  filterResponse?: boolean;
-  /**
-   * With `filterResponse: false`, set to `false` to omit `query` from the
-   * raw response. Ignored when `filterResponse` is not `false`.
-   */
-  returnQuery?: boolean;
-  /** Accepted for signature parity; not simulated. */
-  tag?: string;
-  /** Accepted for signature parity; not simulated. */
-  signal?: AbortSignal;
-}
-
-declare interface Grant_2 {
-  filter: string;
-  permissions: DocumentValuePermission[];
-}
-
 declare type GuardHelpers = {
   /** All deployed guard docs ({@link MutationGuardDoc}) in the store. */
   listGuards: () => Promise<MutationGuardDoc[]>;
@@ -398,119 +324,27 @@ declare type GuardHelpers = {
    * throws `MutationGuardDeniedError` on denial — the lake's intended
    * rejection, simulated by the bench. `as` routes the write through a
    * token-scoped sibling so `identity()` resolves to that actor.
+   *
+   * Each {@link EditDocumentAction} performs that real write, so a guard
+   * scoped to it is genuinely consulted: `update` (default) applies `patch`;
+   * `delete` deletes; `publish` promotes the existing draft
+   * (`drafts.<documentId>`) onto `documentId`; `unpublish` retracts
+   * `documentId` into its draft. `documentId` is always the published id.
+   * A `patch` ({@link EditDocumentPatch}) is required for `update` and
+   * rejected for every other action — the combination is contradictory input.
+   *
+   * Resolves to the post-write document as the DEFAULT identity reads it —
+   * `undefined` after `delete`/`unpublish` (the doc is gone), or when the
+   * default identity cannot read the written doc.
    */
   editDocument: (opts: {
     documentId: string;
-    patch: Record<string, unknown>;
-    action?: MutationGuardAction;
+    patch?: EditDocumentPatch;
+    action?: EditDocumentAction;
     as?: Actor;
-  }) => Promise<StoreDocument>;
+  }) => Promise<StoreDocument | undefined>;
 };
 
-/** Result of a mutation when ids are requested for all affected documents. */
-declare interface MultipleMutationResult {
-  transactionId: string;
-  documentIds: string[];
-  results: {
-    id: string;
-    operation: MutationOperation;
-  }[];
-}
-
-/** Append-only record of one committed transaction (a single mutation is a 1-entry transaction). */
-declare interface MutationLogEntry {
-  transactionId: string;
-  projectId: string;
-  dataset: string;
-  mutations: TxnMutation[];
-}
-
-/** The operation recorded per affected document, matching `@sanity/client`. */
-declare type MutationOperation = "create" | "update" | "delete" | "none";
-
-declare interface MutationOptions {
-  ifRevisionId?: string;
-  /**
-   * Shape the resolved value, mirroring `@sanity/client`:
-   * - default → the mutated document
-   * - `returnDocuments: false` → an id-shaped mutation result
-   *   ({@link SingleMutationResult} / {@link MultipleMutationResult})
-   * - `returnFirst: false` with documents → an array
-   *
-   * The static return type reflects the default (the document); pass a
-   * type argument or cast when requesting an id-shaped result.
-   */
-  returnDocuments?: boolean;
-  returnFirst?: boolean;
-  /** Override the synthetic transaction id used in the result and log. */
-  transactionId?: string;
-  /** When `true`, validate + shape the result but don't persist. */
-  dryRun?: boolean;
-  /** Accepted for signature parity; not simulated. */
-  visibility?: "sync" | "async" | "deferred";
-  /** Accepted for signature parity; not simulated. */
-  autoGenerateArrayKeys?: boolean;
-  /** Accepted for signature parity; not simulated. */
-  tag?: string;
-}
-
-declare interface PatchHandle {
-  set: (props: Record<string, unknown>) => PatchHandle;
-  setIfMissing: (props: Record<string, unknown>) => PatchHandle;
-  unset: (paths: string[]) => PatchHandle;
-  inc: (props: Record<string, number>) => PatchHandle;
-  dec: (props: Record<string, number>) => PatchHandle;
-  insert: (
-    position: "before" | "after" | "replace",
-    anchor: string,
-    items: unknown[],
-  ) => PatchHandle;
-  ifRevisionId: (rev: string) => PatchHandle;
-  commit: () => Promise<SanityDocument>;
-  /** Test-only introspection — not on real Patch */
-  toJSON: () => {
-    id: string;
-    ops: PatchOp[];
-    ifRev?: string;
-  };
-}
-
-/**
- * Patch operations the test client supports.
- *
- * Subset of `@sanity/client`'s PatchOperations. Each entry is one
- * mutation step applied in order at commit time.
- */
-declare type PatchOp =
-  | {
-      kind: "set";
-      props: Record<string, unknown>;
-    }
-  | {
-      kind: "setIfMissing";
-      props: Record<string, unknown>;
-    }
-  | {
-      kind: "unset";
-      paths: string[];
-    }
-  | {
-      kind: "inc";
-      props: Record<string, number>;
-    }
-  | {
-      kind: "dec";
-      props: Record<string, number>;
-    }
-  | {
-      kind: "insert";
-      position: "before" | "after" | "replace";
-      anchor: string;
-      items: unknown[];
-    };
-
-declare type Perspective = "raw" | "published" | "drafts" | string[];
-
 declare type QueryHelpers = {
   /**
    * Run an arbitrary GROQ query through `workflow.query`. The query MUST
@@ -542,34 +376,35 @@ declare type QueryHelpers = {
 };
 
 declare type ReadHelpers = {
-  /** Read the workflow instance by id. Throws if missing. */
-  getInstance: (instanceId: string) => Promise<WorkflowInstance>;
+  /**
+   * The engine's instance point-read: throws typed `InstanceNotFoundError`
+   * when the doc is missing or belongs to another engine's tag partition.
+   */
+  getInstance: (args: InstanceRefArgs) => Promise<WorkflowInstance>;
   /** Current stage name of an instance. */
   currentStage: (instanceId: string) => Promise<string>;
-  /** Pending effects on an instance. */
-  pendingEffects: (instanceId: string) => Promise<PendingEffect[]>;
+  /** Every pending effect on an instance — claimed and unclaimed alike. */
+  listPendingEffects: (args: InstanceRefArgs) => Promise<PendingEffect[]>;
+  /** Pending effects filtered by claim presence and/or effect names. */
+  findPendingEffects: (
+    args: FindPendingEffectsArgs,
+  ) => Promise<PendingEffect[]>;
   /** Status of a single activity on an instance, or undefined if missing. */
   activityStatus: (
     instanceId: string,
     activity: string,
   ) => Promise<ActivityStatus | undefined>;
-  /** The rendered `$effects` map — context entries keyed by `name`,
-   *  completed-effect outputs namespaced under the effect's name. */
-  effectsContextMap: (instanceId: string) => Promise<Record<string, unknown>>;
+  /** The rendered `$context` map — the start-time seed + a parent's spawn
+   *  handoff, keyed by entry `name`. */
+  contextMap: (instanceId: string) => Promise<Record<string, unknown>>;
+  /** The rendered `$effects` map — completed effects' outputs, namespaced
+   *  by effect name. */
+  effectOutputsMap: (instanceId: string) => Promise<Record<string, unknown>>;
   /**
-   * Spawned children of `parentInstanceId`. If `activity` is provided,
-   * only children spawned by that specific activity on the parent.
-   *
-   * Walks `history.spawned` entries on the parent — this is the durable
-   * record. (The per-activity `spawnedInstances` field only lives on the
-   * open StageEntry's activities; history survives transitions.)
-   *
-   * Returns children ordered by `startedAt` ascending.
+   * Spawned children of the instance, optionally restricted to those
+   * spawned by `activity`. Ordered by `startedAt` ascending.
    */
-  children: (
-    parentInstanceId: string,
-    activity?: string,
-  ) => Promise<WorkflowInstance[]>;
+  children: (args: ChildrenArgs) => Promise<WorkflowInstance[]>;
   /**
    * All workflow instances whose `doc.ref` field entry named
    * `entryName` (default `"subject"`) matches the given doc id. Useful
@@ -581,74 +416,37 @@ declare type ReadHelpers = {
     entryName?: string,
   ) => Promise<WorkflowInstance[]>;
   /**
-   * All instances of `workflowName` currently at `stage`. Includes
-   * completed instances (`completedAt != null`) by default; set
-   * `{ openOnly: true }` to filter to in-flight only.
+   * All instances of `definition` currently at `stage`. In-flight only by
+   * default; `includeCompleted: true` widens to completed/aborted instances.
+   * The options derive from the engine's {@link InstancesQueryFilter}, so a
+   * vocabulary drift is a compile error here, not a silently-dropped filter.
    */
-  instancesByStage: (options: {
-    workflowName: string;
-    stage: string;
-    openOnly?: boolean;
-  }) => Promise<WorkflowInstance[]>;
+  instancesByStage: (
+    options: Required<Pick<InstancesQueryFilter, "definition" | "stage">> &
+      Pick<InstancesQueryFilter, "includeCompleted">,
+  ) => Promise<WorkflowInstance[]>;
   /**
    * Every in-flight instance whose reactive watch-set includes `document`
    * (a resource-qualified GDR URI) — the reverse of the forward watch-set.
    * Answers "which instances should this changed doc `tick`?" the way a
    * non-reactive content forwarder needs. Sorted by `startedAt` ascending.
    */
-  instancesForDocument: (document: GdrUri) => Promise<WorkflowInstance[]>;
+  instancesForDocument: (
+    args: InstancesForDocumentArgs,
+  ) => Promise<WorkflowInstance[]>;
+  /**
+   * The startable half of {@link ReadHelpers.instancesForDocument}: the
+   * latest deployed version of every definition applicable to the LOADED
+   * candidate document — startable, a required subject entry accepts its
+   * `_type`, `start.filter` passes. All matches, name ascending.
+   */
+  definitionsForDocument: (
+    args: DefinitionsForDocumentArgs,
+  ) => Promise<DeployedDefinition[]>;
   /** Snapshot of all documents in the store — for inspecting the world. */
   snapshot: () => readonly StoreDocument[];
 };
 
-declare type ReleaseAction =
-  | {
-      actionType: "sanity.action.release.create";
-      releaseId: string;
-      metadata?: Partial<ReleaseMetadata>;
-    }
-  | {
-      actionType: "sanity.action.release.edit";
-      releaseId: string;
-      patch: {
-        set?: Record<string, unknown>;
-        unset?: string[];
-      };
-    }
-  | {
-      actionType: "sanity.action.release.schedule";
-      releaseId: string;
-      publishAt: string;
-    }
-  | {
-      actionType: "sanity.action.release.unschedule";
-      releaseId: string;
-    }
-  | {
-      actionType: "sanity.action.release.publish";
-      releaseId: string;
-    }
-  | {
-      actionType: "sanity.action.release.archive";
-      releaseId: string;
-    }
-  | {
-      actionType: "sanity.action.release.unarchive";
-      releaseId: string;
-    }
-  | {
-      actionType: "sanity.action.release.delete";
-      releaseId: string;
-    };
-
-declare interface ReleaseDocument extends SanityDocument {
-  _type: "system.release";
-  name: string;
-  state: ReleaseState;
-  metadata: ReleaseMetadata;
-  publishAt?: string;
-}
-
 /**
  * A `release.ref` entry pointing at `_.releases.<releaseName>` in the bench's
  * default resource — what a release-targeting workflow's `release` field
@@ -661,86 +459,6 @@ export declare function releaseField(
   },
 ): InitialFieldValue;
 
-declare interface ReleaseMetadata {
-  title?: string;
-  description?: string;
-  releaseType?: ReleaseType;
-  intendedPublishAt?: string;
-}
-
-declare interface ReleasesHandle {
-  create: (params: {
-    releaseId: string;
-    metadata?: Partial<ReleaseMetadata>;
-  }) => Promise<
-    ActionResult & {
-      releaseId: string;
-      metadata: ReleaseMetadata;
-    }
-  >;
-  edit: (params: {
-    releaseId: string;
-    patch: {
-      set?: Record<string, unknown>;
-      unset?: string[];
-    };
-  }) => Promise<ActionResult>;
-  get: (params: { releaseId: string }) => Promise<ReleaseDocument | undefined>;
-  fetchDocuments: (params: { releaseId: string }) => Promise<SanityDocument[]>;
-  schedule: (params: {
-    releaseId: string;
-    publishAt: string;
-  }) => Promise<ActionResult>;
-  unschedule: (params: { releaseId: string }) => Promise<ActionResult>;
-  publish: (params: { releaseId: string }) => Promise<ActionResult>;
-  archive: (params: { releaseId: string }) => Promise<ActionResult>;
-  unarchive: (params: { releaseId: string }) => Promise<ActionResult>;
-  delete: (params: { releaseId: string }) => Promise<ActionResult>;
-}
-
-declare type ReleaseState = "active" | "scheduled" | "published" | "archived";
-
-declare type ReleaseType = "asap" | "scheduled" | "undecided";
-
-/** @public */
-declare interface SanityDocument {
-  _id: string;
-  _type: string;
-  _createdAt: string;
-  _updatedAt: string;
-  _rev: string;
-  [key: string]: unknown;
-}
-
-/**
- * Similar to `SanityDocument` but only requires the `_id` and `_type`
- *
- * @see SanityDocument
- *
- * @public
- */
-declare interface SanityDocumentLike {
-  _id: string;
-  _type: string;
-  _createdAt?: string;
-  _updatedAt?: string;
-  _rev?: string;
-  _system?: {
-    delete?: boolean;
-  };
-  [key: string]: unknown;
-}
-
-/** Result of a mutation when `returnFirst` resolves true and ids are requested. */
-declare interface SingleMutationResult {
-  transactionId: string;
-  documentId: string;
-  results: {
-    id: string;
-    operation: MutationOperation;
-  }[];
-}
-
 /** A document as stored in the bench's fake lake. */
 declare type StoreDocument = {
   _id: string;
@@ -761,312 +479,6 @@ export declare function subjectField(
   },
 ): InitialFieldValue;
 
-declare interface SystemFields {
-  _rev: string;
-  _createdAt: string;
-  _updatedAt: string;
-}
-
-declare interface TestClient {
-  fetch: <T = unknown>(
-    query: string,
-    params?: Record<string, unknown>,
-    options?: FetchOptions,
-  ) => Promise<T>;
-  getDocument: <T = SanityDocument>(
-    id: string,
-    options?: FetchOptions,
-  ) => Promise<T | undefined>;
-  getDocuments: <T = SanityDocument>(
-    ids: string[],
-    options?: FetchOptions,
-  ) => Promise<(T | null)[]>;
-  /**
-   * Sanity-style HTTP request hook. Present iff the client was
-   * created with `accessControl`. The engine's access resolver pokes
-   * `/users/me` and the configured ACL path through this — without it
-   * the engine throws on any verb that needs an actor (which is the
-   * cue for the bench to supply an `access` override).
-   *
-   * Test cases that want to exercise the engine's token-resolution
-   * path should configure `accessControl`; cases that want bench-style
-   * always-allow should leave it off and pass `access` through the
-   * bench.
-   */
-  request?: <T>(opts: {
-    url?: string;
-    uri?: string;
-    signal?: AbortSignal;
-    tag?: string;
-  }) => Promise<T>;
-  create: <T extends SanityDocumentLike>(
-    doc: T,
-    options?: MutationOptions,
-  ) => Promise<T & SystemFields>;
-  createOrReplace: <T extends SanityDocumentLike>(
-    doc: T,
-    options?: MutationOptions,
-  ) => Promise<T & SystemFields>;
-  createIfNotExists: <T extends SanityDocumentLike>(
-    doc: T,
-    options?: MutationOptions,
-  ) => Promise<T & SystemFields>;
-  delete: (
-    id: string,
-    options?: MutationOptions,
-  ) => Promise<{
-    _id: string;
-  } | null>;
-  patch: (documentId: string) => PatchHandle;
-  transaction: () => TransactionHandle;
-  /**
-   * Apply a batch of mutations in the raw array form (or a `patch()` /
-   * `transaction()` builder) — mirrors `@sanity/client`'s `mutate()`.
-   * Atomic: any failure rolls the whole batch back. The resolved shape
-   * follows `options.returnDocuments` / `returnFirst` exactly like the
-   * real client (default → {@link MultipleMutationResult}).
-   */
-  mutate: (
-    operations: FakeMutation[] | PatchHandle | TransactionHandle,
-    options?: TxnCommitOptions,
-  ) => Promise<TxnCommitResult>;
-  /**
-   * Dispatch one or more release / version actions against the store.
-   * Returns a synthetic `transactionId`. Multi-action arrays are applied
-   * atomically — any failure rolls back the batch.
-   */
-  action: (action: Action | Action[]) => Promise<ActionResult>;
-  /** Helpers mirroring `@sanity/client`'s `client.releases.*` surface. */
-  releases: ReleasesHandle;
-  /** Helper for `sanity.action.document.version.create`. */
-  createVersion: (params: {
-    releaseId: string;
-    publishedId: string;
-    document: DocumentBody;
-  }) => Promise<ActionResult>;
-  /** Helper for `sanity.action.document.version.unpublish`. */
-  unpublishVersion: (params: {
-    releaseId: string;
-    publishedId: string;
-  }) => Promise<ActionResult>;
-  /** Current `(projectId, dataset)` and active perspective. */
-  config: () => {
-    projectId: string;
-    dataset: string;
-    perspective: Perspective;
-  };
-  /**
-   * Return a new client handle pointing at a different `(projectId, dataset)`
-   * within the SAME backing registry. Either field can be omitted to keep
-   * the current value. Two clients produced by `withConfig` see each
-   * other's writes if they point at the same `(projectId, dataset)`.
-   */
-  withConfig: (
-    config: Partial<{
-      projectId: string;
-      dataset: string;
-      perspective: Perspective;
-      /**
-       * Rebind the acting identity (and its grants) on a sibling that shares
-       * the same store — the test analogue of a token-scoped client. Lets two
-       * actors write the same dataset, e.g. for `identity()`-based guards.
-       */
-      accessControl: TestClientAccessControl;
-    }>,
-  ) => TestClient;
-  /** Replace the current dataset with the given documents. */
-  seed: (documents: SanityDocumentLike[]) => void;
-  /** Add documents to the current dataset without dropping existing ones. */
-  add: (documents: SanityDocumentLike[]) => void;
-  /** Drop all documents in the current dataset. */
-  reset: () => void;
-  /** Read-only snapshot of all documents in the current dataset. */
-  snapshot: () => readonly SanityDocument[];
-  /** Direct store access for the current dataset. */
-  store: () => TestStore;
-  /**
-   * Simulate `count` concurrent edits to `id` in the current dataset: the
-   * next `count` revision-guarded mutations (those passing `ifRevisionId`)
-   * to that document throw a 409-shaped conflict, as if another client
-   * committed between the caller's read and write. Lets a test exercise
-   * optimistic-locking retry paths deterministically, without timing or
-   * interleaving. Mutations that don't pass `ifRevisionId` are unaffected.
-   */
-  simulateConcurrentEdit: (id: string, count?: number) => void;
-  /** List `(projectId, dataset)` pairs known in this registry. */
-  datasets: () => {
-    projectId: string;
-    dataset: string;
-  }[];
-  /**
-   * Register a handler for a `@sanity/client` member the fake doesn't
-   * implement (e.g. `listen`, `assets`). Accessing that member on the
-   * client then returns the handler instead of throwing the
-   * "not implemented" guard error. Shared across sibling `withConfig`
-   * handles. Stubs fill gaps only — they don't shadow implemented methods.
-   */
-  stub: (name: string, handler: unknown) => void;
-  /** The currently-registered stubs, keyed by member name. */
-  stubs: () => Record<string, unknown>;
-  /**
-   * Every mutation committed through this client's registry, flattened
-   * and in order — `create` / `createOrReplace` / `createIfNotExists` /
-   * `delete` / `patch`, whether issued directly, via `transaction()`, or
-   * via `mutate()`. The spy hook for "assert exactly what writes my code
-   * submitted".
-   */
-  mutations: () => TxnMutation[];
-  /**
-   * Every committed transaction, in order. A direct mutation is recorded
-   * as a one-mutation transaction. Each entry carries its synthetic
-   * `transactionId` and the `(projectId, dataset)` it targeted.
-   */
-  transactions: () => MutationLogEntry[];
-  /** Clear the recorded mutation / transaction log. */
-  clearLog: () => void;
-  /**
-   * Every recorded method call, in order — the spy layer for "was `fetch`
-   * called, how many times, and with what params". Records the
-   * `@sanity/client`-surface methods (`fetch`, `getDocument`, `create`,
-   * `patch`, `mutate`, `releases.*`, …), not the test-only helpers.
-   * Pass a method name to filter (e.g. `calls("fetch")`); namespace
-   * methods are dotted (`calls("releases.create")`). Shared across
-   * `withConfig` siblings.
-   */
-  calls: (method?: string) => CallRecord[];
-  /** Number of recorded calls, optionally filtered by method name. */
-  callCount: (method?: string) => number;
-  /** Clear the recorded call log. */
-  clearCalls: () => void;
-}
-
-declare interface TestClientAccessControl {
-  /** What `client.request({ url: "/users/me" })` returns. */
-  currentUser: CurrentUser;
-  /** What `client.request({ url: aclPath })` returns. */
-  grants: Grant_2[];
-  /**
-   * URL path the engine's access resolver hits to fetch grants.
-   * Defaults to `/projects/<projectId>/datasets/<dataset>/acl`.
-   */
-  aclPath?: string;
-}
-
-/**
- * In-memory document store backing a TestClient. Closure-scoped — created
- * fresh per test, no global state.
- *
- * The shape mirrors what `groq-js` evaluates against: an array of
- * documents. Internally we keep a Map by `_id` for O(1) lookup, and
- * project to an array on each query.
- */
-declare interface TestStore {
-  /** Replace the entire dataset with the given documents. Existing docs are dropped. */
-  seed: (documents: SanityDocumentLike[]) => void;
-  /** Add documents without dropping existing ones. Conflicts (same _id) overwrite. */
-  add: (documents: SanityDocumentLike[]) => void;
-  /** Remove all documents. */
-  reset: () => void;
-  /** All documents as an array, in insertion order. */
-  all: () => SanityDocument[];
-  /** Get one document by _id, or undefined. */
-  get: (id: string) => SanityDocument | undefined;
-  /** Insert a fully-formed document by _id. Replaces if it already exists. */
-  put: (doc: SanityDocument) => void;
-  /** Remove a document by _id. Returns the removed doc or undefined. */
-  remove: (id: string) => SanityDocument | undefined;
-  /** Snapshot of all docs, useful for assertions. */
-  snapshot: () => readonly SanityDocument[];
-}
-
-declare interface TransactionHandle {
-  create: (doc: SanityDocumentLike) => TransactionHandle;
-  createOrReplace: (doc: SanityDocumentLike) => TransactionHandle;
-  createIfNotExists: (doc: SanityDocumentLike) => TransactionHandle;
-  delete: (id: string) => TransactionHandle;
-  /** Accept either a Patch builder (drained at commit) or an inline doc id + ops. */
-  patch: (
-    documentIdOrPatch: string | PatchHandle,
-    ops?: PatchOp[],
-    ifRev?: string,
-  ) => TransactionHandle;
-  commit: (options?: TxnCommitOptions) => Promise<TxnCommitResult>;
-  /** Test-only introspection — not on real Transaction. */
-  toJSON: () => TxnMutation[];
-}
-
-declare interface TxnCommitOptions {
-  /**
-   * Shape the resolved value (mirrors `@sanity/client`):
-   * - default (both unset) → {@link MultipleMutationResult}
-   * - `returnDocuments: true` → the resulting document(s)
-   * - `returnFirst: true` with `returnDocuments` → a single document
-   * - `returnDocuments: false` → an id-shaped mutation result
-   */
-  returnDocuments?: boolean;
-  returnFirst?: boolean;
-  /** Override the synthetic transaction id (mirrors `client.transaction(undefined, { transactionId })`). */
-  transactionId?: string;
-}
-
-declare type TxnCommitResult =
-  | MultipleMutationResult
-  | SingleMutationResult
-  | SanityDocument
-  | SanityDocument[];
-
-/**
- * A transaction collects mutations and applies them atomically at commit
- * time. Mutations are applied in declaration order; if any one fails, the
- * whole transaction throws and no writes land in the store.
- *
- * Subset of `@sanity/client`'s Transaction. Same shape, narrower surface.
- */
-declare type TxnMutation =
-  | {
-      kind: "create";
-      doc: SanityDocumentLike;
-    }
-  | {
-      kind: "createOrReplace";
-      doc: SanityDocumentLike;
-    }
-  | {
-      kind: "createIfNotExists";
-      doc: SanityDocumentLike;
-    }
-  | {
-      kind: "delete";
-      id: string;
-    }
-  | {
-      kind: "patch";
-      documentId: string;
-      ops: PatchOp[];
-      ifRev?: string;
-    };
-
-declare type VersionAction =
-  | {
-      actionType: "sanity.action.document.version.create";
-      publishedId: string;
-      document: DocumentBody;
-      releaseId?: string;
-    }
-  | {
-      actionType: "sanity.action.document.version.replace";
-      document: SanityDocumentLike;
-    }
-  | {
-      actionType: "sanity.action.document.version.discard";
-      versionId: string;
-    }
-  | {
-      actionType: "sanity.action.document.version.unpublish";
-      versionId: string;
-      publishedId: string;
-    };
-
 /**
  * The default grants used when tests don't specify any. A single
  * permissive grant matches every document and confers all permissions.