@sanity/workflow-engine-test 0.8.0 → 0.10.0

package/dist/index.d.cts

@@ -1,35 +1,51 @@
+import type { AbortInstanceArgs } from "@sanity/workflow-engine";
 import { ActivityStatus } from "@sanity/workflow-engine";
 import { Actor } from "@sanity/workflow-engine";
+import { CandidateDocument } 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 { DeployDefinitionsArgs } from "@sanity/workflow-engine";
 import { DeployDefinitionsResult } from "@sanity/workflow-engine";
-import { DispatchResult } 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 type { FireActionArgs } from "@sanity/workflow-engine";
 import { GdrUri } from "@sanity/workflow-engine";
 import type { Grant } from "@sanity/workflow-engine";
+import { InitialFieldValue } from "@sanity/workflow-engine";
 import { MutationGuardAction } from "@sanity/workflow-engine";
 import { MutationGuardDoc } from "@sanity/workflow-engine";
 import type { OperationArgs } from "@sanity/workflow-engine";
+import { OperationResult } from "@sanity/workflow-engine";
 import { PendingEffect } from "@sanity/workflow-engine";
+import type { SetStageArgs } from "@sanity/workflow-engine";
 import type { StartInstanceArgs } from "@sanity/workflow-engine";
 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;
 
+/** Options for `action()`. Only `tag` is meaningful to the fake. */
+declare interface ActionOptions {
+  /** Request tag, recorded on the {@link CallRecord} (`null` = explicit suppression). */
+  tag?: string | null;
+}
+
 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.
@@ -51,73 +67,73 @@ export declare type Bench = BenchState &
   EngineWrappers &
   ReadHelpers &
   GuardHelpers &
-  QueryHelpers;
+  QueryHelpers &
+  ComposedHelpers;
 
-declare type BenchCompleteEffectArgs = Omit<
-  CompleteEffectArgs,
-  "client" | "tag" | "workflowResource" | "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,
-  "client" | "tag" | "workflowResource" | "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,
-  "client" | "tag" | "workflowResource" | "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,
-  "client" | "tag" | "workflowResource" | "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,
-  "client" | "tag" | "workflowResource" | "access"
-> & {
-  access?: WorkflowAccess;
-  /** Shortcut for `access.actor`. */
-  actor?: Actor;
-};
+declare type BenchCompleteEffectArgs = BenchArgs<CompleteEffectArgs>;
+
+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;
   /**
@@ -142,14 +158,7 @@ declare interface BenchState {
   advance: (ms: number) => void;
 }
 
-declare type BenchTickArgs = Omit<
-  OperationArgs,
-  "client" | "tag" | "workflowResource" | "access"
-> & {
-  access?: WorkflowAccess;
-  /** Shortcut for `access.actor`. */
-  actor?: Actor;
-};
+declare type BenchTickArgs = BenchArgs<OperationArgs>;
 
 /**
  * One recorded invocation of a client method — the spy layer behind
@@ -167,10 +176,27 @@ declare interface CallRecord {
   result?: unknown;
   /** Thrown or rejected value, set if the call failed. */
   error?: unknown;
+  /** Request tag from the call's options, when one was passed (`null` = explicit suppression). */
+  tag?: string | null;
   projectId: string;
   dataset: string;
 }
 
+/** Helpers composed across the wrapper + read groups at bench assembly. */
+declare interface ComposedHelpers {
+  /**
+   * Complete the pending effect named `effect` — {@link EngineWrappers.completeEffect}
+   * with the `effectKey` looked up by name, throwing loud when no such effect
+   * is pending. The idiomatic way to play an external handler reporting its
+   * result; pass `ops` to write outcome fields in the same commit.
+   */
+  completePendingEffect: (
+    args: Omit<BenchCompleteEffectArgs, "effectKey"> & {
+      effect: string;
+    },
+  ) => Promise<OperationResult>;
+}
+
 /**
  * Create a fresh bench. By default the bench is fully isolated — two
  * `createBench()` calls have no shared state. Pass `client` + `tag`
@@ -178,14 +204,28 @@ declare interface CallRecord {
  */
 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).
@@ -196,28 +236,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.
@@ -247,6 +266,12 @@ export declare interface CreateBenchOptions {
    * start on the wall clock (`advance` / `setNow` can freeze it later).
    */
   now?: 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;
 }
 
 declare interface CurrentUser {
@@ -279,17 +304,44 @@ declare interface DocumentBody {
 
 declare type DocumentValuePermission = "create" | "read" | "update";
 
-/** Engine-call wrappers that inject the bench-owned client + tag + access. */
+/**
+ * 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[];
+  };
+};
+
+/** 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: Omit<DeployDefinitionsArgs, "client" | "tag" | "workflowResource">,
+  deployDefinitions: <T extends WorkflowDefinitionInput<T>>(
+    args: DeployDefinitionsArgs<T>,
   ) => Promise<DeployDefinitionsResult>;
-  startInstance: (args: BenchStartInstanceArgs) => Promise<WorkflowInstance>;
-  fireAction: (args: BenchFireActionArgs) => Promise<DispatchResult>;
-  editField: (args: BenchEditFieldArgs) => Promise<DispatchResult>;
-  completeEffect: (args: BenchCompleteEffectArgs) => Promise<DispatchResult>;
-  tick: (args: BenchTickArgs) => Promise<DispatchResult>;
+  startInstance: (args: BenchStartInstanceArgs) => Promise<OperationResult>;
+  fireAction: (args: BenchFireActionArgs) => Promise<OperationResult>;
+  editField: (args: BenchEditFieldArgs) => Promise<OperationResult>;
+  completeEffect: (args: BenchCompleteEffectArgs) => Promise<OperationResult>;
+  tick: (args: BenchTickArgs) => Promise<OperationResult>;
   evaluate: (args: BenchEvaluateArgs) => Promise<WorkflowEvaluation>;
+  /** 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[]>;
 };
@@ -370,8 +422,12 @@ declare interface FetchOptions {
    * raw response. Ignored when `filterResponse` is not `false`.
    */
   returnQuery?: boolean;
-  /** Accepted for signature parity; not simulated. */
-  tag?: string;
+  /**
+   * Request tag, recorded on the {@link CallRecord} for assertions.
+   * `null` mirrors `@sanity/client`'s explicit-suppression form and is
+   * recorded as-is. No other behavior is simulated.
+   */
+  tag?: string | null;
   /** Accepted for signature parity; not simulated. */
   signal?: AbortSignal;
 }
@@ -382,7 +438,7 @@ declare interface Grant_2 {
 }
 
 declare type GuardHelpers = {
-  /** All deployed `temp.system.guard` docs in the store. */
+  /** All deployed guard docs ({@link MutationGuardDoc}) in the store. */
   listGuards: () => Promise<MutationGuardDoc[]>;
   /**
    * Guards that would deny an arbitrary edit to `documentId` right now (i.e.
@@ -394,15 +450,17 @@ declare type GuardHelpers = {
     as?: Actor,
   ) => Promise<MutationGuardDoc[]>;
   /**
-   * Write to a document through the client's enforced write seam — the bench
+   * Write to a document through the client's guarded write seam — the bench
    * client gates the write against deployed guards (incl. `identity()`) and
-   * throws `MutationGuardDeniedError` on denial, exactly as the lake would.
-   * `as` routes the write through a token-scoped sibling so `identity()`
-   * resolves to that actor.
+   * throws `MutationGuardDeniedError` on denial — the lake's intended
+   * rejection, simulated by the bench. `as` routes the write through a
+   * token-scoped sibling so `identity()` resolves to that actor. A `patch`
+   * ({@link EditDocumentPatch}) is required for edits and rejected for
+   * `action: 'delete'` — the combination is contradictory input.
    */
   editDocument: (opts: {
     documentId: string;
-    patch: Record<string, unknown>;
+    patch?: EditDocumentPatch;
     action?: MutationGuardAction;
     as?: Actor;
   }) => Promise<StoreDocument>;
@@ -424,6 +482,8 @@ declare interface MutationLogEntry {
   projectId: string;
   dataset: string;
   mutations: TxnMutation[];
+  /** Request tag the commit carried, when one was passed (`null` = explicit suppression). */
+  tag?: string | null;
 }
 
 /** The operation recorded per affected document, matching `@sanity/client`. */
@@ -451,8 +511,21 @@ declare interface MutationOptions {
   visibility?: "sync" | "async" | "deferred";
   /** Accepted for signature parity; not simulated. */
   autoGenerateArrayKeys?: boolean;
+  /**
+   * Request tag, recorded on the {@link CallRecord} and the
+   * {@link MutationLogEntry} for assertions. `null` mirrors
+   * `@sanity/client`'s explicit-suppression form and is recorded as-is.
+   * No other behavior is simulated.
+   */
+  tag?: string | null;
+}
+
+/** Options for `PatchHandle.commit()`. Only `tag` is meaningful to the fake. */
+declare interface PatchCommitOptions {
+  /** Request tag, recorded on the mutation log entry (`null` = explicit suppression). */
+  tag?: string | null;
   /** Accepted for signature parity; not simulated. */
-  tag?: string;
+  visibility?: "sync" | "async" | "deferred";
 }
 
 declare interface PatchHandle {
@@ -467,7 +540,7 @@ declare interface PatchHandle {
     items: unknown[],
   ) => PatchHandle;
   ifRevisionId: (rev: string) => PatchHandle;
-  commit: () => Promise<SanityDocument>;
+  commit: (options?: PatchCommitOptions) => Promise<SanityDocument>;
   /** Test-only introspection — not on real Patch */
   toJSON: () => {
     id: string;
@@ -561,9 +634,9 @@ declare type ReadHelpers = {
    * 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.)
+   * Walks `history.spawned` entries on the parent — the durable record
+   * (the workflow-scope registry tracks the same children, keyed for
+   * adoption rather than enumeration).
    *
    * Returns children ordered by `startedAt` ascending.
    */
@@ -598,6 +671,15 @@ declare type ReadHelpers = {
    * non-reactive content forwarder needs. Sorted by `startedAt` ascending.
    */
   instancesForDocument: (document: GdrUri) => 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`, `applicableWhen` passes. All matches, name ascending.
+   */
+  definitionsForDocument: (
+    document: CandidateDocument,
+  ) => Promise<DeployedDefinition[]>;
   /** Snapshot of all documents in the store — for inspecting the world. */
   snapshot: () => readonly StoreDocument[];
 };
@@ -650,6 +732,18 @@ declare interface ReleaseDocument extends SanityDocument {
   publishAt?: string;
 }
 
+/**
+ * A `release.ref` entry pointing at `_.releases.<releaseName>` in the bench's
+ * default resource — what a release-targeting workflow's `release` field
+ * expects at start.
+ */
+export declare function releaseField(
+  releaseName: string,
+  opts?: {
+    name?: string;
+  },
+): InitialFieldValue;
+
 declare interface ReleaseMetadata {
   title?: string;
   description?: string;
@@ -737,6 +831,19 @@ declare type StoreDocument = {
   [key: string]: unknown;
 };
 
+/**
+ * The conventional workflow-scope `subject` doc.ref entry, keyed by a bare
+ * doc id in the bench's default resource. `type` defaults to `'document'`;
+ * pass the subject's schema type when a filter or projection reads it.
+ */
+export declare function subjectField(
+  documentId: string,
+  opts?: {
+    name?: string;
+    type?: string;
+  },
+): InitialFieldValue;
+
 declare interface SystemFields {
   _rev: string;
   _createdAt: string;
@@ -758,22 +865,18 @@ declare interface TestClient {
     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.
+   * Sanity-style HTTP request hook. Present iff the handle has an
+   * acting identity — created with `accessControl`, or bound to a
+   * registered token (`identities` + `token`). 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.
    */
   request?: <T>(opts: {
     url?: string;
     uri?: string;
     signal?: AbortSignal;
-    tag?: string;
+    tag?: string | null;
   }) => Promise<T>;
   create: <T extends SanityDocumentLike>(
     doc: T,
@@ -811,7 +914,10 @@ declare interface TestClient {
    * Returns a synthetic `transactionId`. Multi-action arrays are applied
    * atomically — any failure rolls back the batch.
    */
-  action: (action: Action | Action[]) => Promise<ActionResult>;
+  action: (
+    action: Action | Action[],
+    options?: ActionOptions,
+  ) => Promise<ActionResult>;
   /** Helpers mirroring `@sanity/client`'s `client.releases.*` surface. */
   releases: ReleasesHandle;
   /** Helper for `sanity.action.document.version.create`. */
@@ -825,11 +931,15 @@ declare interface TestClient {
     releaseId: string;
     publishedId: string;
   }) => Promise<ActionResult>;
-  /** Current `(projectId, dataset)` and active perspective. */
+  /**
+   * Current `(projectId, dataset)` and active perspective. `token` is
+   * present iff the handle is bound to a registered identity.
+   */
   config: () => {
     projectId: string;
     dataset: string;
     perspective: Perspective;
+    token?: string;
   };
   /**
    * Return a new client handle pointing at a different `(projectId, dataset)`
@@ -846,8 +956,18 @@ declare interface TestClient {
        * 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.
+       * Mutually exclusive with `token`.
        */
       accessControl: TestClientAccessControl;
+      /**
+       * Bind the sibling to a token registered in the family's identity
+       * registry (`createTestClient({ identities })` / `addIdentity`): its
+       * `/users/me` serves that identity's user, its ACL path serves that
+       * identity's grants, and reads/writes are gated through them — the
+       * token determines identity, exactly like production. Unknown tokens
+       * throw. Mutually exclusive with `accessControl`.
+       */
+      token: string;
     }>,
   ) => TestClient;
   /** Replace the current dataset with the given documents. */
@@ -864,9 +984,21 @@ declare interface TestClient {
    * 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.
+   * committed between the caller's read and write. Mutations that don't
+   * pass `ifRevisionId` are unaffected.
+   *
+   * Reach for this when the code under test reads a document's `_rev` and
+   * commits with `ifRevisionId` internally — so you can't stage the race
+   * by mutating the document first (the code would just re-read the new
+   * revision and its commit would match). The counter is consumed one per
+   * guarded commit, so `count` lets a test drive a recover-after-N-losses
+   * path or exhaust a retry budget, deterministically and without relying
+   * on promise interleaving.
+   *
+   * Note: this forces the conflict *outcome* — it short-circuits the
+   * revision comparison rather than changing the stored `_rev`. The code
+   * under test sees the identical 409 error a real lost race produces; the
+   * stored revision is left untouched.
    */
   simulateConcurrentEdit: (id: string, count?: number) => void;
   /** List `(projectId, dataset)` pairs known in this registry. */
@@ -884,6 +1016,16 @@ declare interface TestClient {
   stub: (name: string, handler: unknown) => void;
   /** The currently-registered stubs, keyed by member name. */
   stubs: () => Record<string, unknown>;
+  /**
+   * Register (or upsert) a token→identity entry in the family's shared
+   * registry. Siblings already bound to `token` resolve lazily, so a
+   * re-registration takes effect on them immediately. Registering an
+   * identity does not bind it — pass `token` at `createTestClient` or
+   * `withConfig({ token })` to act as it.
+   */
+  addIdentity: (token: string, identity: TestClientIdentity) => void;
+  /** Snapshot of the registered token→identity entries. */
+  identities: () => Record<string, TestClientIdentity>;
   /**
    * Every mutation committed through this client's registry, flattened
    * and in order — `create` / `createOrReplace` / `createIfNotExists` /
@@ -928,6 +1070,20 @@ declare interface TestClientAccessControl {
   aclPath?: string;
 }
 
+/**
+ * One entry in the token→identity registry (`createTestClient({ identities })`).
+ * A handle bound to the entry's token behaves exactly like one configured
+ * with `accessControl: { currentUser: user, grants }` — `/users/me` serves
+ * `user`, the default ACL path serves `grants`, and reads/writes are gated
+ * through them.
+ */
+declare interface TestClientIdentity {
+  /** What `/users/me` returns for clients bound to this token. */
+  user: CurrentUser;
+  /** Grants served at the ACL path and enforced on reads/writes. */
+  grants: Grant_2[];
+}
+
 /**
  * In-memory document store backing a TestClient. Closure-scoped — created
  * fresh per test, no global state.
@@ -983,6 +1139,12 @@ declare interface TxnCommitOptions {
   returnFirst?: boolean;
   /** Override the synthetic transaction id (mirrors `client.transaction(undefined, { transactionId })`). */
   transactionId?: string;
+  /**
+   * Request tag, recorded on the mutation log entry for assertions.
+   * `null` mirrors `@sanity/client`'s explicit-suppression form and is
+   * recorded as-is. No other behavior is simulated.
+   */
+  tag?: string | null;
 }
 
 declare type TxnCommitResult =