@sanity/workflow-engine-test 0.10.0 → 0.11.0

package/dist/index.d.ts

@@ -1,21 +1,27 @@
 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 { 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";
@@ -23,24 +29,13 @@ 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;
-
-/** 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 identity — wildcard user + wildcard grants,
  * registered as the default token on the bench's fake client so the
@@ -94,6 +89,9 @@ declare type BenchArgsWithGrants<T> = BenchArgs<T> & {
 
 declare type BenchCompleteEffectArgs = BenchArgs<CompleteEffectArgs>;
 
+declare type BenchDeleteDefinitionArgs =
+  BenchArgsWithGrants<DeleteDefinitionArgs>;
+
 declare type BenchEditFieldArgs = BenchArgsWithGrants<EditFieldArgs>;
 
 declare type BenchEvaluateArgs = BenchArgsWithGrants<EvaluateArgs>;
@@ -146,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;
   /**
@@ -160,28 +157,6 @@ declare interface BenchState {
 
 declare type BenchTickArgs = BenchArgs<OperationArgs>;
 
-/**
- * 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;
-  /** 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 {
   /**
@@ -274,35 +249,17 @@ export declare interface CreateBenchOptions {
   executionContext?: DeclaredExecutionContext;
 }
 
-declare interface CurrentUser {
-  id: string;
-  name?: string;
-  email?: string;
-  /** @deprecated singular `role` on legacy responses */
-  role?: string;
-  roles?: {
-    name: string;
-    title?: string;
-    description?: string;
-  }[];
-}
-
 /** 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;
-}
-
-declare type DocumentValuePermission = "create" | "read" | "update";
+export declare type EditDocumentAction = Exclude<MutationGuardAction, "create">;
 
 /**
  * How {@link GuardHelpers.editDocument} mutates the document. Each present
@@ -332,6 +289,9 @@ declare type EngineWrappers = {
   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>;
@@ -346,97 +306,6 @@ declare type EngineWrappers = {
   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;
-  /**
-   * 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;
-}
-
-declare interface Grant_2 {
-  filter: string;
-  permissions: DocumentValuePermission[];
-}
-
 declare type GuardHelpers = {
   /** All deployed guard docs ({@link MutationGuardDoc}) in the store. */
   listGuards: () => Promise<MutationGuardDoc[]>;
@@ -454,137 +323,28 @@ declare type GuardHelpers = {
    * client gates the write against deployed guards (incl. `identity()`) and
    * 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.
+   * 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?: EditDocumentPatch;
-    action?: MutationGuardAction;
+    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[];
-  /** Request tag the commit carried, when one was passed (`null` = explicit suppression). */
-  tag?: string | null;
-}
-
-/** 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;
-  /**
-   * 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. */
-  visibility?: "sync" | "async" | "deferred";
-}
-
-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: (options?: PatchCommitOptions) => 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
@@ -616,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 — the durable record
-   * (the workflow-scope registry tracks the same children, keyed for
-   * adoption rather than enumeration).
-   *
-   * 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
@@ -655,83 +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`, `applicableWhen` passes. All matches, name ascending.
+   * `_type`, `start.filter` passes. All matches, name ascending.
    */
   definitionsForDocument: (
-    document: CandidateDocument,
+    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
@@ -744,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;
@@ -844,367 +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 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 | null;
-  }) => 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[],
-    options?: ActionOptions,
-  ) => 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. `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)`
-   * 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.
-       * 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. */
-  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. 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. */
-  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>;
-  /**
-   * 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` /
-   * `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;
-}
-
-/**
- * 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.
- *
- * 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;
-  /**
-   * 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 =
-  | 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.