@sanity/workflow-engine 0.19.0 → 0.20.0

package/dist/index.d.ts

@@ -203,7 +203,7 @@ declare const ActionParamSchema: v.SchemaWithPipe<
             "doc.refs",
             "json",
           ],
-          `Invalid option: expected one of ${string}`
+          string
         >;
         readonly name: v.SchemaWithPipe<
           readonly [
@@ -747,10 +747,7 @@ declare type AuthoringFieldRef = v.InferOutput<typeof AuthoringFieldRefSchema>;
 declare const AuthoringFieldRefSchema: v.StrictObjectSchema<
   {
     readonly scope: v.OptionalSchema<
-      v.PicklistSchema<
-        readonly ["workflow", "stage", "activity"],
-        `Invalid option: expected one of ${string}`
-      >,
+      v.PicklistSchema<readonly ["workflow", "stage", "activity"], string>,
       undefined
     >;
     readonly field: v.SchemaWithPipe<
@@ -916,7 +913,7 @@ declare const AuthoringGuardSchema: v.StrictObjectSchema<
             v.ArraySchema<
               v.PicklistSchema<
                 readonly ["create", "update", "delete", "publish", "unpublish"],
-                `Invalid option: expected one of ${string}`
+                string
               >,
               undefined
             >,
@@ -1091,7 +1088,7 @@ declare const AuthoringManualTargetSchema: v.VariantSchema<
                 readonly scope: v.OptionalSchema<
                   v.PicklistSchema<
                     readonly ["workflow", "stage", "activity"],
-                    `Invalid option: expected one of ${string}`
+                    string
                   >,
                   undefined
                 >;
@@ -1127,7 +1124,7 @@ declare const AuthoringOpSchema: v.VariantSchema<
             readonly scope: v.OptionalSchema<
               v.PicklistSchema<
                 readonly ["workflow", "stage", "activity"],
-                `Invalid option: expected one of ${string}`
+                string
               >,
               undefined
             >;
@@ -1152,7 +1149,7 @@ declare const AuthoringOpSchema: v.VariantSchema<
             readonly scope: v.OptionalSchema<
               v.PicklistSchema<
                 readonly ["workflow", "stage", "activity"],
-                `Invalid option: expected one of ${string}`
+                string
               >,
               undefined
             >;
@@ -1176,7 +1173,7 @@ declare const AuthoringOpSchema: v.VariantSchema<
             readonly scope: v.OptionalSchema<
               v.PicklistSchema<
                 readonly ["workflow", "stage", "activity"],
-                `Invalid option: expected one of ${string}`
+                string
               >,
               undefined
             >;
@@ -1201,7 +1198,7 @@ declare const AuthoringOpSchema: v.VariantSchema<
             readonly scope: v.OptionalSchema<
               v.PicklistSchema<
                 readonly ["workflow", "stage", "activity"],
-                `Invalid option: expected one of ${string}`
+                string
               >,
               undefined
             >;
@@ -1232,7 +1229,7 @@ declare const AuthoringOpSchema: v.VariantSchema<
             readonly scope: v.OptionalSchema<
               v.PicklistSchema<
                 readonly ["workflow", "stage", "activity"],
-                `Invalid option: expected one of ${string}`
+                string
               >,
               undefined
             >;
@@ -1268,7 +1265,7 @@ declare const AuthoringOpSchema: v.VariantSchema<
         >;
         readonly status: v.PicklistSchema<
           readonly ["active", "done", "skipped", "failed"],
-          `Invalid option: expected one of ${string}`
+          string
         >;
       },
       undefined
@@ -1281,7 +1278,7 @@ declare const AuthoringOpSchema: v.VariantSchema<
             readonly scope: v.OptionalSchema<
               v.PicklistSchema<
                 readonly ["workflow", "stage", "activity"],
-                `Invalid option: expected one of ${string}`
+                string
               >,
               undefined
             >;
@@ -1997,10 +1994,9 @@ export declare type ConditionVarBinding = "always" | "caller" | "spawn";
 
 /**
  * The one-doc read a reactive adapter subscribes with to observe a content doc
- * under a perspective stack — the same GROQ as the engine's own hydration read
- * ({@link hydrateSnapshot}), so the adapter and the engine resolve identical
- * content: draft/version content projected onto the published id, a doc that
- * exists only as a draft (or only inside a release) still visible.
+ * under a perspective stack. It uses the same perspective semantics as
+ * {@link hydrateSnapshot}: draft/version content is projected onto the published
+ * id, and a doc that exists only as a draft or release version remains visible.
  */
 export declare function contentDocQuery(documentId: string): CompiledQuery;
 
@@ -3457,11 +3453,13 @@ export declare type EffectHandler<
  */
 declare type EffectHandlerContext<Client extends WorkflowClient> = {
   /**
-   * The exact concrete client supplied to `createEngine`, bound to the
-   * workflow resource rather than an
-   * engine wrapper. Its class identity, namespaces, configuration, and
-   * credentials are preserved. Handler-owned requests are not automatically
-   * tagged by the engine.
+   * A concrete sibling of the client supplied to `createEngine`, bound to the
+   * workflow resource with the same namespaces and credentials. Untagged
+   * handler requests on its workflow-client surface carry the `workflow.effect`
+   * request tag by default. A concrete client's explicit tags compose beneath
+   * that prefix. On the structural fallback for minimal clients, pass-through
+   * namespaces are not stamped and core builders expose the engine's minimal
+   * workflow-client surface.
    */
   client: Client;
   /**
@@ -3477,8 +3475,8 @@ declare type EffectHandlerContext<Client extends WorkflowClient> = {
    * {@link GlobalDocumentReference}. Returns the `resourceClients` client
    * for that resource when one is mapped, {@link client} for the workflow
    * resource itself, and a sibling derived from {@link client}'s
-   * credentials otherwise. Mapped clients are returned unchanged; an
-   * unmapped foreign resource necessarily returns a configured sibling.
+   * credentials otherwise. Returned clients preserve their concrete APIs and
+   * apply the same default effect request tag.
    * Throws if `ref` isn't a GDR — a bare id can't
    * be routed, so failing loud beats silently patching the wrong dataset.
    */
@@ -3845,10 +3843,10 @@ export declare interface Engine {
  * {@link WorkflowClient.withConfig}, and `resourceClients`-resolved clients
  * are rebound the same way. A caller's configured `apiVersion` therefore
  * never reaches engine-owned traffic (the caller's own client instance is
- * untouched). Effect handlers are host traffic and deliberately receive the
- * caller's configuration unchanged. The other exception is a client that lacks `withConfig` and so
- * cannot be rebound — it must be built to serve this version; see
- * {@link WorkflowClient.withConfig}.
+ * untouched). Effect handlers keep the caller's `apiVersion`; their derived
+ * clients change only the request-tag prefix. The other exception is a client
+ * that lacks `withConfig` and so cannot be rebound — it must be built to serve
+ * this version; see {@link WorkflowClient.withConfig}.
  */
 export declare const ENGINE_API_VERSION = "2026-04-29";
 
@@ -4826,7 +4824,7 @@ export declare type GuardAction = v.InferOutput<typeof GuardActionSchema>;
 
 declare const GuardActionSchema: v.PicklistSchema<
   readonly ["create", "update", "delete", "publish", "unpublish"],
-  `Invalid option: expected one of ${string}`
+  string
 >;
 
 export declare type GuardMatch = Guard["match"];
@@ -4991,7 +4989,7 @@ declare const GuardSchema: v.StrictObjectSchema<
             v.ArraySchema<
               v.PicklistSchema<
                 readonly ["create", "update", "delete", "publish", "unpublish"],
-                `Invalid option: expected one of ${string}`
+                string
               >,
               undefined
             >,
@@ -5527,13 +5525,14 @@ export declare type InsightSite =
 export declare function instanceDocId(tag: string): string;
 
 /**
- * The per-instance guard filter — the single definition of "this instance's
- * guards in one datasource". The engine's verdict load
- * ({@link verdictGuardsForInstance}) fetches it once against the engine
- * datasource; the reactive adapters feed the same query/params to their
- * stores as a live subscription; {@link guardsForInstance} unions it across
- * datasources for housekeeping. Ordinary stage retraction deletes guards, so
- * results represent active persisted guard documents.
+ * The per-instance guard filter — "this instance's guards in one datasource".
+ * The engine's verdict load ({@link verdictGuardsForInstance}) fetches it once
+ * against the engine datasource, and {@link guardsForInstance} unions it
+ * across datasources for housekeeping; the reactive adapters subscribe the
+ * set-shaped {@link instancesGuardQuery} this delegates to (one shared
+ * live query per resource, sliced per `sourceInstanceId`), so every path
+ * reads through one filter definition. Ordinary stage retraction deletes
+ * guards, so results represent active persisted guard documents.
  */
 export declare function instanceGuardQuery(instanceId: string): CompiledQuery;
 
@@ -5586,6 +5585,12 @@ export declare interface InstanceSession {
    *  docs are processed), never from the commit itself — the commit's
    *  outcome is never masked by a store echo's failure. */
   update(docs: LoadedDoc[]): void;
+  /** Replace one held document without rebuilding the rest of the overlay.
+   *  Consumers with per-document streams use this after the initial
+   *  {@link InstanceSession.update} snapshot. Self-doc recency, commit-time
+   *  buffering, and deferred buffered-validation errors follow the same
+   *  contract as {@link InstanceSession.update}. */
+  updateDocument(doc: LoadedDoc): void;
   /** Replace the held live guards (the consumer's guard stream,
    *  last-write-wins). Guards are a separate stream from the watch-set:
    *  {@link InstanceSession.evaluate} pre-flights the instance write against
@@ -5647,6 +5652,18 @@ export declare interface InstancesForDocumentArgs {
   document: GdrUri;
 }
 
+/**
+ * The guard filter for a SET of instances in one datasource — the single
+ * definition every per-instance read delegates to ({@link instanceGuardQuery}).
+ * Reactive adapters subscribe it as ONE shared live query per resource for
+ * every co-mounted session, fanning results back out per `sourceInstanceId`,
+ * so a document's guard subscription count doesn't grow with its instance
+ * count. Deterministically ordered, matching {@link guardsForResource}.
+ */
+export declare function instancesGuardQuery(
+  instanceIds: readonly string[],
+): CompiledQuery;
+
 /**
  * The instance-list GROQ for a {@link InstancesQueryFilter}, ordered by
  * `startedAt` ascending (descending + sliced under
@@ -5740,6 +5757,10 @@ export declare function isClaimExpired(
   now: string,
 ): boolean;
 
+export declare function isClientProjectUser(
+  value: unknown,
+): value is ClientProjectUser;
+
 export { isComparisonOp };
 
 /**
@@ -6588,8 +6609,8 @@ export declare type ProgressTarget =
  * the session keys its overlay and snapshot by), and a draft/version
  * representation's stored id rides along as `_originalId` — session-side
  * conditions (including the `_originalId in path("versions.**")` shape) then
- * read exactly what the engine's own hydration ({@link contentDocQuery})
- * returns. Strict by construction: only the ids in
+ * read the same projected identity as the engine's perspective-aware hydration.
+ * Strict by construction: only the ids in
  * {@link watchRefRepresentations} are accepted — an id that merely *ends* in
  * the watched id (another doc's dotted id under a version prefix), a release
  * the perspective doesn't read, or a draft the perspective makes invisible is
@@ -6977,8 +6998,8 @@ export declare function resourceAliasesToMap(
  * refs to the resources it stops serving.
  *
  * Engine-owned verb scopes rebind resolved clients onto
- * `ENGINE_API_VERSION`. Effect handlers receive resolver clients unchanged
- * because handler traffic belongs to the host.
+ * `ENGINE_API_VERSION`. Effect handlers derive request-tagged siblings from
+ * resolver clients so their concrete APIs remain available and attributed.
  */
 export declare type ResourceClientResolver = (
   parsed: ParsedGdr,
@@ -7636,7 +7657,7 @@ declare const StoredFieldOpSchema: v.VariantSchema<
           {
             readonly scope: v.PicklistSchema<
               readonly ["workflow", "stage", "activity"],
-              `Invalid option: expected one of ${string}`
+              string
             >;
             readonly field: v.SchemaWithPipe<
               readonly [
@@ -7658,7 +7679,7 @@ declare const StoredFieldOpSchema: v.VariantSchema<
           {
             readonly scope: v.PicklistSchema<
               readonly ["workflow", "stage", "activity"],
-              `Invalid option: expected one of ${string}`
+              string
             >;
             readonly field: v.SchemaWithPipe<
               readonly [
@@ -7679,7 +7700,7 @@ declare const StoredFieldOpSchema: v.VariantSchema<
           {
             readonly scope: v.PicklistSchema<
               readonly ["workflow", "stage", "activity"],
-              `Invalid option: expected one of ${string}`
+              string
             >;
             readonly field: v.SchemaWithPipe<
               readonly [
@@ -7701,7 +7722,7 @@ declare const StoredFieldOpSchema: v.VariantSchema<
           {
             readonly scope: v.PicklistSchema<
               readonly ["workflow", "stage", "activity"],
-              `Invalid option: expected one of ${string}`
+              string
             >;
             readonly field: v.SchemaWithPipe<
               readonly [
@@ -7729,7 +7750,7 @@ declare const StoredFieldOpSchema: v.VariantSchema<
           {
             readonly scope: v.PicklistSchema<
               readonly ["workflow", "stage", "activity"],
-              `Invalid option: expected one of ${string}`
+              string
             >;
             readonly field: v.SchemaWithPipe<
               readonly [
@@ -7759,7 +7780,7 @@ declare const StoredFieldRefSchema: v.StrictObjectSchema<
   {
     readonly scope: v.PicklistSchema<
       readonly ["workflow", "stage", "activity"],
-      `Invalid option: expected one of ${string}`
+      string
     >;
     readonly field: v.SchemaWithPipe<
       readonly [
@@ -7794,7 +7815,7 @@ declare const StoredManualTargetSchema: v.VariantSchema<
           {
             readonly scope: v.PicklistSchema<
               readonly ["workflow", "stage", "activity"],
-              `Invalid option: expected one of ${string}`
+              string
             >;
             readonly field: v.SchemaWithPipe<
               readonly [
@@ -7822,7 +7843,7 @@ declare const StoredOpSchema: v.VariantSchema<
           {
             readonly scope: v.PicklistSchema<
               readonly ["workflow", "stage", "activity"],
-              `Invalid option: expected one of ${string}`
+              string
             >;
             readonly field: v.SchemaWithPipe<
               readonly [
@@ -7844,7 +7865,7 @@ declare const StoredOpSchema: v.VariantSchema<
           {
             readonly scope: v.PicklistSchema<
               readonly ["workflow", "stage", "activity"],
-              `Invalid option: expected one of ${string}`
+              string
             >;
             readonly field: v.SchemaWithPipe<
               readonly [
@@ -7865,7 +7886,7 @@ declare const StoredOpSchema: v.VariantSchema<
           {
             readonly scope: v.PicklistSchema<
               readonly ["workflow", "stage", "activity"],
-              `Invalid option: expected one of ${string}`
+              string
             >;
             readonly field: v.SchemaWithPipe<
               readonly [
@@ -7887,7 +7908,7 @@ declare const StoredOpSchema: v.VariantSchema<
           {
             readonly scope: v.PicklistSchema<
               readonly ["workflow", "stage", "activity"],
-              `Invalid option: expected one of ${string}`
+              string
             >;
             readonly field: v.SchemaWithPipe<
               readonly [
@@ -7915,7 +7936,7 @@ declare const StoredOpSchema: v.VariantSchema<
           {
             readonly scope: v.PicklistSchema<
               readonly ["workflow", "stage", "activity"],
-              `Invalid option: expected one of ${string}`
+              string
             >;
             readonly field: v.SchemaWithPipe<
               readonly [
@@ -7946,7 +7967,7 @@ declare const StoredOpSchema: v.VariantSchema<
         >;
         readonly status: v.PicklistSchema<
           readonly ["active", "done", "skipped", "failed"],
-          `Invalid option: expected one of ${string}`
+          string
         >;
       },
       undefined
@@ -8220,10 +8241,7 @@ declare const SubworkflowsSchema: v.StrictObjectSchema<
      * `$subworkflows`) decide.
      */
     readonly onExit: v.OptionalSchema<
-      v.PicklistSchema<
-        readonly ["detach", "abort"],
-        `Invalid option: expected one of ${string}`
-      >,
+      v.PicklistSchema<readonly ["detach", "abort"], string>,
       undefined
     >;
   },
@@ -8541,9 +8559,10 @@ declare type ValueExprInternal =
  * physically scoped: a guard doc in a watched content dataset that
  * self-declares the engine's resource id must never reach a verdict. This
  * keeps the advisory layer consistent (verdicts are UX, not enforcement);
- * it is not itself a security boundary. Runs the same query the reactive
- * adapters subscribe with ({@link instanceGuardQuery}), so the stateless and
- * reactive paths agree.
+ * it is not itself a security boundary. Reads through the same filter
+ * definition the reactive adapters subscribe with
+ * ({@link instanceGuardQuery}, the one-id form of the set-shaped
+ * {@link instancesGuardQuery}), so the stateless and reactive paths agree.
  */
 export declare function verdictGuardsForInstance(
   client: WorkflowClient,
@@ -9107,7 +9126,7 @@ export declare interface WorkflowClient {
    * Optional — present on the real `@sanity/client` and the in-memory test
    * fake. Returns a sibling client with the given config overrides,
    * inheriting everything else from the source (token, apiHost). The engine
-   * derives two things from it:
+   * derives three things from it:
    *
    * - **Cross-resource routing** (`resource` + the dataset pair): a sibling
    *   for a foreign GDR when `resourceClients` doesn't map it. A client
@@ -9121,6 +9140,10 @@ export declare interface WorkflowClient {
    *   rebound and is used as-is — it must be built to serve
    *   {@link ENGINE_API_VERSION} already; older dated versions fail
    *   silently incomplete, not loud.
+   * - **Effect request attribution** (`requestTagPrefix`): handlers receive a
+   *   derived client whose untagged traffic carries the effect tag while the
+   *   caller's own client remains untouched. A client without `withConfig`
+   *   uses the structural request wrapper instead.
    *
    * Dataset resources carry the `{projectId, dataset}` pair alongside
    * `resource`: the real client routes by `resource` (it takes precedence in
@@ -9129,7 +9152,7 @@ export declare interface WorkflowClient {
    * only — a canvas/media-library derivation on the fake aliases the current
    * store until the fake learns `resource` upstream.
    */
-  withConfig?: (config: WorkflowClientConfig) => WorkflowClient;
+  withConfig?: (config: WorkflowClientConfig) => this;
   /**
    * Optional — present on the real `@sanity/client`, absent on the
    * in-memory test client. The engine probes for it when auto-resolving
@@ -9155,14 +9178,15 @@ export declare interface WorkflowClient {
 /**
  * The config bag {@link WorkflowClient.withConfig} accepts — all optional: a
  * resource rebind (`resource`, plus the dataset pair for dataset targets), an
- * `apiVersion` rebind, or both. Everything omitted is inherited from the
- * source client.
+ * `apiVersion` rebind, a request-tag prefix, or any combination. Everything
+ * omitted is inherited from the source client.
  */
 export declare interface WorkflowClientConfig {
   resource?: WorkflowResource;
   projectId?: string;
   dataset?: string;
   apiVersion?: string;
+  requestTagPrefix?: string;
 }
 
 export declare interface WorkflowCommitOptions {