@sanity/workflow-engine 0.2.0 → 0.3.0

package/dist/index.d.cts

@@ -517,6 +517,24 @@ declare type Bound<
   },
 > = Omit<Args, "client" | "tags" | "workflowResource">;
 
+/**
+ * Build a snapshot from a set of loaded docs. Pure transform.
+ *
+ * For each `LoadedDoc { doc, resource }`:
+ *   - The doc's `_id` is rewritten to `gdrFromResource(resource, _id)`.
+ *   - Every nested `_ref` value (recursively, through objects and arrays)
+ *     is rewritten the same way: bare ref → URI in the parent's resource.
+ *     Already-qualified `_ref` URIs (containing `:`) are left alone.
+ *
+ * Plain string fields, numbers, booleans — anything that isn't an
+ * object with a `_ref` field — pass through untouched. The rewriter is
+ * structural, not schema-aware: only the `_ref` field on an object is
+ * treated as a Sanity reference. Everything else is user data.
+ */
+export declare function buildSnapshot(args: {
+  docs: LoadedDoc[];
+}): HydratedSnapshot;
+
 export declare function canonicalTag(tags: string[]): string;
 
 /**
@@ -627,6 +645,29 @@ export declare class ConcurrentFireActionError extends Error {
   });
 }
 
+/**
+ * The Content Release a watched doc resolves under, or `undefined` for a raw
+ * read — how a reactive adapter turns the watch-set's perspective into the
+ * per-doc release its store needs. Instance / ancestor / `system.release` docs
+ * read raw ({@link readsRaw}); a content doc resolves under the **leading**
+ * release in the stack. The engine never forms the `versions.<release>.<id>`
+ * id — the adapter does (Studio's `editState` version arg, the SDK handle
+ * `{releaseName}`). A non-array perspective (`raw`/`published`/`drafts`)
+ * carries no release, so content falls back to draft/published.
+ *
+ * Note: this resolves a **single** release — the documented `instance.perspective`
+ * shapes (`[release]` / `[release, "drafts"]`). The stores' per-doc reads take
+ * one release, so a multi-release stack can't be observed reactively here; the
+ * engine's own fetch path ({@link hydrateSnapshot}) honours the full stack via
+ * `client.fetch({perspective})`.
+ */
+export declare function contentReleaseName(args: {
+  ref: {
+    type: string;
+  };
+  perspective: WorkflowPerspective | undefined;
+}): string | undefined;
+
 /**
  * Construct an engine bound to a workflow resource + tags. The returned
  * object exposes the same verbs as the `workflow.*` namespace, minus
@@ -994,6 +1035,28 @@ export declare interface Engine {
   setStage: (args: Bound<SetStageArgs>) => Promise<DispatchResult>;
   /** Fetch a workflow instance by id. */
   getInstance: (args: { instanceId: string }) => Promise<WorkflowInstance>;
+  /** The reactive {@link WatchSet} for an instance — every document whose
+   *  change should re-evaluate it (the instance, its ancestors, and the docs
+   *  named by `doc.ref`/`doc.refs`/`release.ref` slots on the workflow scope
+   *  + current stage) as exploded {@link SubscriptionDocument}s, plus the
+   *  instance's read perspective. Fetches the instance, then derives. A
+   *  reactive adapter that already holds the live instance calls the pure
+   *  `subscriptionDocumentsForInstance` directly instead, to avoid the re-fetch. */
+  subscriptionDocumentsForInstance: (args: {
+    instanceId: string;
+  }) => Promise<WatchSet>;
+  /** Opt into reactivity: bind the engine to an instance doc and get a stateful
+   *  {@link InstanceSession}. Push the docs it lists in `subscriptionDocuments`
+   *  via `update`, then `evaluate`/`tick`/`fireAction` against the held state —
+   *  pushed content is never refetched. The session never observes or ticks on
+   *  its own; the consumer drives it. */
+  instance: (
+    instanceDoc: WorkflowInstance,
+    opts?: {
+      access?: WorkflowAccessOverride;
+      grantsFromPath?: string;
+    },
+  ) => InstanceSession;
   /** Every lake mutation guard this instance registered, unioned across the
    *  instance's own resource and the resource of each `doc.ref`/`doc.refs`
    *  GDR it holds in state. For coherency refresh and housekeeping. */
@@ -1100,6 +1163,43 @@ export declare interface EvaluateArgs {
   resourceClients?: (parsed: ParsedGdr) => WorkflowClient | undefined;
 }
 
+/**
+ * The pure projection at the heart of {@link evaluateInstance}: given an
+ * instance, its definition, the resolved actor/grants, and a snapshot,
+ * compute "what can this actor do right now, and why not the rest." No
+ * I/O — feed it a fresh snapshot (e.g. rebuilt from a live store on
+ * change) for reactive re-evaluation. Best-effort by design: the lake's
+ * mutation guards + ACL are the real enforcement.
+ */
+export declare function evaluateFromSnapshot(
+  args: EvaluateFromSnapshotArgs,
+): Promise<WorkflowEvaluation>;
+
+export declare interface EvaluateFromSnapshotArgs {
+  instance: WorkflowInstance;
+  definition: WorkflowDefinition;
+  actor: Actor;
+  /**
+   * Resolved grants for the actor. Omit to skip the `permission-denied`
+   * gate (graceful degradation — the real lake write boundary still
+   * enforces).
+   */
+  grants?: Grant[];
+  /**
+   * The in-memory snapshot to evaluate against. The caller assembles it
+   * from whatever source — a fetch (see {@link evaluateInstance}) or a
+   * live store. The `_id` of every doc must be in GDR-URI form, as
+   * {@link buildSnapshot} produces.
+   */
+  snapshot: HydratedSnapshot;
+  /**
+   * The `$now` reading every filter in this projection shares. Omit to
+   * use {@link wallClock}; a reactive consumer (or the bench) passes its
+   * own clock reading for a stable/deterministic timeline.
+   */
+  now?: string;
+}
+
 declare function evaluateInstance(
   args: Clocked<EvaluateArgs>,
 ): Promise<WorkflowEvaluation>;
@@ -1239,7 +1339,7 @@ export declare type GdrScheme =
  * type + runtime guarantee that no bare-string id reaches the
  * snapshot, slot, or filter layer.
  */
-declare type GdrUri = `${GdrScheme}:${string}`;
+export declare type GdrUri = `${GdrScheme}:${string}`;
 
 /** Compose a GDR URI from parts. Inverse of `parseGdr`. */
 export declare function gdrUri(
@@ -1603,6 +1703,22 @@ export declare type HistoryEntry =
       actor?: Actor;
     };
 
+/**
+ * The in-memory groq-js dataset filters evaluate against. Built once
+ * per cascade entry (in the shell), passed through to `evaluateFilter`
+ * (in the core) for every filter check.
+ */
+export declare interface HydratedSnapshot {
+  /** All hydrated docs, keyed by GDR URI as `_id`. */
+  docs: SanityDocument[];
+  /**
+   * The set of GDR URIs present in `docs`. Helpful for tests and shells
+   * that want to assert "is this doc in scope?" — the core eval pipeline
+   * itself doesn't read it.
+   */
+  knownIds: Set<string>;
+}
+
 /**
  * Initial value for an `init`-sourced slot — what a caller supplies at
  * `startInstance` (or `setStage`). Same discriminator shape as
@@ -1618,6 +1734,28 @@ export declare type InitialStateValue = {
   };
 }[Exclude<StateSlotKind, "workflow.state.query">];
 
+export declare interface InstanceSession {
+  /** The watch-set to feed via {@link InstanceSession.update}, derived from the
+   *  held instance. Recompute after the instance changes (a new stage changes it). */
+  readonly subscriptionDocuments: WatchSet;
+  /** Replace the held content with the current values the consumer observed
+   *  (last-write-wins, scoped). A doc whose id is the instance itself updates
+   *  the held instance. Buffered if a commit is in flight. */
+  update(docs: LoadedDoc[]): void;
+  /** Best-effort projection against the held content. No network (async only
+   *  because filter evaluation runs on groq-js). */
+  evaluate(): Promise<WorkflowEvaluation>;
+  /** Advance the instance against the held content: cascade auto-transitions,
+   *  deploy guards, queue effects, commit with `ifRevisionId`. */
+  tick(): Promise<DispatchResult>;
+  /** Fire an action against a task, gated on the held content, then cascade. */
+  fireAction(args: {
+    taskId: string;
+    action: string;
+    params?: Record<string, unknown>;
+  }): Promise<DispatchResult>;
+}
+
 /**
  * Compare a deployed definition document to what we'd write next. Skip
  * Sanity-managed system fields (`_rev`, `_createdAt`, `_updatedAt`) —
@@ -1639,6 +1777,16 @@ export declare function lakeGuardId(args: {
   index: number;
 }): string;
 
+/**
+ * One loaded doc plus the resource it came from. The shell builds
+ * this list by routing reads to the right client for each doc, then
+ * hands it to `buildSnapshot`.
+ */
+export declare interface LoadedDoc {
+  doc: SanityDocument;
+  resource: WorkflowResource;
+}
+
 export declare type LoggerFactory = (name: string) => EngineLogger;
 
 /**
@@ -2122,6 +2270,17 @@ declare const PredicateSchema: v.StrictObjectSchema<
   undefined
 >;
 
+/**
+ * Whether a watched ref reads RAW — never perspective-scoped. The
+ * instance, its ancestors (both `workflow.instance`), and `release.ref`
+ * system docs (`system.release`) are not versioned by a release
+ * perspective; everything else is content and resolves to its
+ * version/draft/published form. This is the single encoding of the rule
+ * the {@link WatchSet} `perspective` contract describes to consumers, and
+ * the rule {@link hydrateSnapshot} applies on the fetch side.
+ */
+export declare function readsRaw(ref: { type: string }): boolean;
+
 /** Make a GDR pointer to a Canvas-resource doc. */
 export declare function refCanvas(
   resourceId: string,
@@ -2241,6 +2400,8 @@ declare type ResourceClientResolver = (
   parsed: ParsedGdr,
 ) => WorkflowClient | undefined;
 
+export declare function resourceFromParsed(parsed: ParsedGdr): WorkflowResource;
+
 /**
  * Retract every guard for a stage being exited (lift predicate to allow), but
  * only once the instance has genuinely moved off that stage. Skip if it is
@@ -4404,6 +4565,36 @@ export declare function stripSystemFields(
   doc: Record<string, unknown>,
 ): Record<string, unknown>;
 
+/**
+ * A document the reactive layer should subscribe to, with its GDR
+ * exploded so consumers never re-parse: the resource-addressing parts
+ * (from {@link ParsedGdr}), the round-trip `globalDocumentId` URI, and
+ * the target doc's schema `_type`. The resource parts let an adapter
+ * detect refs pointing at a project/dataset/resource it isn't
+ * configured for; `type` feeds per-doc handles (`useDocument` /
+ * `editState`).
+ */
+export declare interface SubscriptionDocument extends ParsedGdr {
+  /** Full GDR URI — resource-qualified identity, for round-trip / snapshot keying. */
+  globalDocumentId: GdrUri;
+  /** Target doc's schema `_type`. */
+  type: string;
+}
+
+export declare function subscriptionDocumentsForInstance(
+  instance: WorkflowInstance,
+): WatchSet;
+
+/**
+ * The engine's read-partition invariant as a GROQ predicate: a document is
+ * visible when its `tags[]` intersect the caller's tag set.
+ *
+ * @param param - GROQ parameter holding the caller's tags. Defaults to
+ *   `engineTags`, matching the `workflow.query` guard so any query built with
+ *   it stays tag-scoped.
+ */
+export declare function tagScopeFilter(param?: string): string;
+
 export declare type Task = v.InferOutput<typeof TaskSchema>;
 
 /**
@@ -5541,6 +5732,35 @@ export declare interface VerifyDeployedDefinitionsResult {
 /** The default clock: real wall-clock time as an ISO-8601 string. */
 export declare const wallClock: Clock;
 
+/**
+ * The reactive subscription target for an instance: the exploded,
+ * deduped watch-set plus the instance's read {@link WorkflowPerspective}.
+ */
+export declare interface WatchSet {
+  /**
+   * Docs to subscribe to — instance + ancestors + the docs named by
+   * `doc.ref`/`doc.refs`/`release.ref` slots — deduped by
+   * `globalDocumentId`. Refs that aren't resource-qualified GDR URIs are
+   * skipped (without a resource there's nothing to subscribe against).
+   */
+  documents: SubscriptionDocument[];
+  /**
+   * The instance's effective read perspective (a release stack like
+   * `[releaseName]` or `[releaseName, "drafts"]`), already resolved at
+   * `startInstance`. `undefined` means raw/published.
+   *
+   * The engine does not form `versions.<release>.<id>` ids — it has no
+   * such concept (it reads content through `client.fetch({perspective})`
+   * for queries). A reactive consumer applies this perspective when it
+   * subscribes: a **content** doc must be resolved to its version /
+   * draft / published form (e.g. Studio `editState`'s version param, or
+   * the SDK's `getVersionId`), while instance / ancestor / `system.release`
+   * docs are always raw. The `type` on each {@link SubscriptionDocument}
+   * tells the consumer which is which.
+   */
+  perspective?: WorkflowPerspective;
+}
+
 /**
  * The four-method workflow API.
  */
@@ -5740,6 +5960,20 @@ export declare const workflow: {
   };
 };
 
+/**
+ * The lake document type for a deployed workflow definition. Single source of
+ * truth — every tag-scoped lookup query and the deploy write derive their
+ * `_type` from here, mirroring {@link WORKFLOW_INSTANCE_TYPE}.
+ */
+export declare const WORKFLOW_DEFINITION_TYPE = "workflow.definition";
+
+/**
+ * The lake document type for a workflow instance. Single source of truth — the
+ * {@link WorkflowInstance} `_type`, every tag-scoped query, and the create
+ * write all derive from here, mirroring {@link WORKFLOW_DEFINITION_TYPE}.
+ */
+export declare const WORKFLOW_INSTANCE_TYPE = "workflow.instance";
+
 /**
  * The engine's view of "who am I, what can I do?". `actor` is who
  * the engine stamps onto history / `completedBy` / `Source.actor`.
@@ -8284,7 +8518,7 @@ export declare interface WorkflowFetchOptions {
 }
 
 export declare interface WorkflowInstance extends SanityDocument {
-  _type: "workflow.instance";
+  _type: typeof WORKFLOW_INSTANCE_TYPE;
   /**
    * Engine-scope tags stamped on the instance at create time. Engines
    * with disjoint tag sets cannot read this instance; engines sharing

package/dist/index.d.ts

@@ -517,6 +517,24 @@ declare type Bound<
   },
 > = Omit<Args, "client" | "tags" | "workflowResource">;
 
+/**
+ * Build a snapshot from a set of loaded docs. Pure transform.
+ *
+ * For each `LoadedDoc { doc, resource }`:
+ *   - The doc's `_id` is rewritten to `gdrFromResource(resource, _id)`.
+ *   - Every nested `_ref` value (recursively, through objects and arrays)
+ *     is rewritten the same way: bare ref → URI in the parent's resource.
+ *     Already-qualified `_ref` URIs (containing `:`) are left alone.
+ *
+ * Plain string fields, numbers, booleans — anything that isn't an
+ * object with a `_ref` field — pass through untouched. The rewriter is
+ * structural, not schema-aware: only the `_ref` field on an object is
+ * treated as a Sanity reference. Everything else is user data.
+ */
+export declare function buildSnapshot(args: {
+  docs: LoadedDoc[];
+}): HydratedSnapshot;
+
 export declare function canonicalTag(tags: string[]): string;
 
 /**
@@ -627,6 +645,29 @@ export declare class ConcurrentFireActionError extends Error {
   });
 }
 
+/**
+ * The Content Release a watched doc resolves under, or `undefined` for a raw
+ * read — how a reactive adapter turns the watch-set's perspective into the
+ * per-doc release its store needs. Instance / ancestor / `system.release` docs
+ * read raw ({@link readsRaw}); a content doc resolves under the **leading**
+ * release in the stack. The engine never forms the `versions.<release>.<id>`
+ * id — the adapter does (Studio's `editState` version arg, the SDK handle
+ * `{releaseName}`). A non-array perspective (`raw`/`published`/`drafts`)
+ * carries no release, so content falls back to draft/published.
+ *
+ * Note: this resolves a **single** release — the documented `instance.perspective`
+ * shapes (`[release]` / `[release, "drafts"]`). The stores' per-doc reads take
+ * one release, so a multi-release stack can't be observed reactively here; the
+ * engine's own fetch path ({@link hydrateSnapshot}) honours the full stack via
+ * `client.fetch({perspective})`.
+ */
+export declare function contentReleaseName(args: {
+  ref: {
+    type: string;
+  };
+  perspective: WorkflowPerspective | undefined;
+}): string | undefined;
+
 /**
  * Construct an engine bound to a workflow resource + tags. The returned
  * object exposes the same verbs as the `workflow.*` namespace, minus
@@ -994,6 +1035,28 @@ export declare interface Engine {
   setStage: (args: Bound<SetStageArgs>) => Promise<DispatchResult>;
   /** Fetch a workflow instance by id. */
   getInstance: (args: { instanceId: string }) => Promise<WorkflowInstance>;
+  /** The reactive {@link WatchSet} for an instance — every document whose
+   *  change should re-evaluate it (the instance, its ancestors, and the docs
+   *  named by `doc.ref`/`doc.refs`/`release.ref` slots on the workflow scope
+   *  + current stage) as exploded {@link SubscriptionDocument}s, plus the
+   *  instance's read perspective. Fetches the instance, then derives. A
+   *  reactive adapter that already holds the live instance calls the pure
+   *  `subscriptionDocumentsForInstance` directly instead, to avoid the re-fetch. */
+  subscriptionDocumentsForInstance: (args: {
+    instanceId: string;
+  }) => Promise<WatchSet>;
+  /** Opt into reactivity: bind the engine to an instance doc and get a stateful
+   *  {@link InstanceSession}. Push the docs it lists in `subscriptionDocuments`
+   *  via `update`, then `evaluate`/`tick`/`fireAction` against the held state —
+   *  pushed content is never refetched. The session never observes or ticks on
+   *  its own; the consumer drives it. */
+  instance: (
+    instanceDoc: WorkflowInstance,
+    opts?: {
+      access?: WorkflowAccessOverride;
+      grantsFromPath?: string;
+    },
+  ) => InstanceSession;
   /** Every lake mutation guard this instance registered, unioned across the
    *  instance's own resource and the resource of each `doc.ref`/`doc.refs`
    *  GDR it holds in state. For coherency refresh and housekeeping. */
@@ -1100,6 +1163,43 @@ export declare interface EvaluateArgs {
   resourceClients?: (parsed: ParsedGdr) => WorkflowClient | undefined;
 }
 
+/**
+ * The pure projection at the heart of {@link evaluateInstance}: given an
+ * instance, its definition, the resolved actor/grants, and a snapshot,
+ * compute "what can this actor do right now, and why not the rest." No
+ * I/O — feed it a fresh snapshot (e.g. rebuilt from a live store on
+ * change) for reactive re-evaluation. Best-effort by design: the lake's
+ * mutation guards + ACL are the real enforcement.
+ */
+export declare function evaluateFromSnapshot(
+  args: EvaluateFromSnapshotArgs,
+): Promise<WorkflowEvaluation>;
+
+export declare interface EvaluateFromSnapshotArgs {
+  instance: WorkflowInstance;
+  definition: WorkflowDefinition;
+  actor: Actor;
+  /**
+   * Resolved grants for the actor. Omit to skip the `permission-denied`
+   * gate (graceful degradation — the real lake write boundary still
+   * enforces).
+   */
+  grants?: Grant[];
+  /**
+   * The in-memory snapshot to evaluate against. The caller assembles it
+   * from whatever source — a fetch (see {@link evaluateInstance}) or a
+   * live store. The `_id` of every doc must be in GDR-URI form, as
+   * {@link buildSnapshot} produces.
+   */
+  snapshot: HydratedSnapshot;
+  /**
+   * The `$now` reading every filter in this projection shares. Omit to
+   * use {@link wallClock}; a reactive consumer (or the bench) passes its
+   * own clock reading for a stable/deterministic timeline.
+   */
+  now?: string;
+}
+
 declare function evaluateInstance(
   args: Clocked<EvaluateArgs>,
 ): Promise<WorkflowEvaluation>;
@@ -1239,7 +1339,7 @@ export declare type GdrScheme =
  * type + runtime guarantee that no bare-string id reaches the
  * snapshot, slot, or filter layer.
  */
-declare type GdrUri = `${GdrScheme}:${string}`;
+export declare type GdrUri = `${GdrScheme}:${string}`;
 
 /** Compose a GDR URI from parts. Inverse of `parseGdr`. */
 export declare function gdrUri(
@@ -1603,6 +1703,22 @@ export declare type HistoryEntry =
       actor?: Actor;
     };
 
+/**
+ * The in-memory groq-js dataset filters evaluate against. Built once
+ * per cascade entry (in the shell), passed through to `evaluateFilter`
+ * (in the core) for every filter check.
+ */
+export declare interface HydratedSnapshot {
+  /** All hydrated docs, keyed by GDR URI as `_id`. */
+  docs: SanityDocument[];
+  /**
+   * The set of GDR URIs present in `docs`. Helpful for tests and shells
+   * that want to assert "is this doc in scope?" — the core eval pipeline
+   * itself doesn't read it.
+   */
+  knownIds: Set<string>;
+}
+
 /**
  * Initial value for an `init`-sourced slot — what a caller supplies at
  * `startInstance` (or `setStage`). Same discriminator shape as
@@ -1618,6 +1734,28 @@ export declare type InitialStateValue = {
   };
 }[Exclude<StateSlotKind, "workflow.state.query">];
 
+export declare interface InstanceSession {
+  /** The watch-set to feed via {@link InstanceSession.update}, derived from the
+   *  held instance. Recompute after the instance changes (a new stage changes it). */
+  readonly subscriptionDocuments: WatchSet;
+  /** Replace the held content with the current values the consumer observed
+   *  (last-write-wins, scoped). A doc whose id is the instance itself updates
+   *  the held instance. Buffered if a commit is in flight. */
+  update(docs: LoadedDoc[]): void;
+  /** Best-effort projection against the held content. No network (async only
+   *  because filter evaluation runs on groq-js). */
+  evaluate(): Promise<WorkflowEvaluation>;
+  /** Advance the instance against the held content: cascade auto-transitions,
+   *  deploy guards, queue effects, commit with `ifRevisionId`. */
+  tick(): Promise<DispatchResult>;
+  /** Fire an action against a task, gated on the held content, then cascade. */
+  fireAction(args: {
+    taskId: string;
+    action: string;
+    params?: Record<string, unknown>;
+  }): Promise<DispatchResult>;
+}
+
 /**
  * Compare a deployed definition document to what we'd write next. Skip
  * Sanity-managed system fields (`_rev`, `_createdAt`, `_updatedAt`) —
@@ -1639,6 +1777,16 @@ export declare function lakeGuardId(args: {
   index: number;
 }): string;
 
+/**
+ * One loaded doc plus the resource it came from. The shell builds
+ * this list by routing reads to the right client for each doc, then
+ * hands it to `buildSnapshot`.
+ */
+export declare interface LoadedDoc {
+  doc: SanityDocument;
+  resource: WorkflowResource;
+}
+
 export declare type LoggerFactory = (name: string) => EngineLogger;
 
 /**
@@ -2122,6 +2270,17 @@ declare const PredicateSchema: v.StrictObjectSchema<
   undefined
 >;
 
+/**
+ * Whether a watched ref reads RAW — never perspective-scoped. The
+ * instance, its ancestors (both `workflow.instance`), and `release.ref`
+ * system docs (`system.release`) are not versioned by a release
+ * perspective; everything else is content and resolves to its
+ * version/draft/published form. This is the single encoding of the rule
+ * the {@link WatchSet} `perspective` contract describes to consumers, and
+ * the rule {@link hydrateSnapshot} applies on the fetch side.
+ */
+export declare function readsRaw(ref: { type: string }): boolean;
+
 /** Make a GDR pointer to a Canvas-resource doc. */
 export declare function refCanvas(
   resourceId: string,
@@ -2241,6 +2400,8 @@ declare type ResourceClientResolver = (
   parsed: ParsedGdr,
 ) => WorkflowClient | undefined;
 
+export declare function resourceFromParsed(parsed: ParsedGdr): WorkflowResource;
+
 /**
  * Retract every guard for a stage being exited (lift predicate to allow), but
  * only once the instance has genuinely moved off that stage. Skip if it is
@@ -4404,6 +4565,36 @@ export declare function stripSystemFields(
   doc: Record<string, unknown>,
 ): Record<string, unknown>;
 
+/**
+ * A document the reactive layer should subscribe to, with its GDR
+ * exploded so consumers never re-parse: the resource-addressing parts
+ * (from {@link ParsedGdr}), the round-trip `globalDocumentId` URI, and
+ * the target doc's schema `_type`. The resource parts let an adapter
+ * detect refs pointing at a project/dataset/resource it isn't
+ * configured for; `type` feeds per-doc handles (`useDocument` /
+ * `editState`).
+ */
+export declare interface SubscriptionDocument extends ParsedGdr {
+  /** Full GDR URI — resource-qualified identity, for round-trip / snapshot keying. */
+  globalDocumentId: GdrUri;
+  /** Target doc's schema `_type`. */
+  type: string;
+}
+
+export declare function subscriptionDocumentsForInstance(
+  instance: WorkflowInstance,
+): WatchSet;
+
+/**
+ * The engine's read-partition invariant as a GROQ predicate: a document is
+ * visible when its `tags[]` intersect the caller's tag set.
+ *
+ * @param param - GROQ parameter holding the caller's tags. Defaults to
+ *   `engineTags`, matching the `workflow.query` guard so any query built with
+ *   it stays tag-scoped.
+ */
+export declare function tagScopeFilter(param?: string): string;
+
 export declare type Task = v.InferOutput<typeof TaskSchema>;
 
 /**
@@ -5541,6 +5732,35 @@ export declare interface VerifyDeployedDefinitionsResult {
 /** The default clock: real wall-clock time as an ISO-8601 string. */
 export declare const wallClock: Clock;
 
+/**
+ * The reactive subscription target for an instance: the exploded,
+ * deduped watch-set plus the instance's read {@link WorkflowPerspective}.
+ */
+export declare interface WatchSet {
+  /**
+   * Docs to subscribe to — instance + ancestors + the docs named by
+   * `doc.ref`/`doc.refs`/`release.ref` slots — deduped by
+   * `globalDocumentId`. Refs that aren't resource-qualified GDR URIs are
+   * skipped (without a resource there's nothing to subscribe against).
+   */
+  documents: SubscriptionDocument[];
+  /**
+   * The instance's effective read perspective (a release stack like
+   * `[releaseName]` or `[releaseName, "drafts"]`), already resolved at
+   * `startInstance`. `undefined` means raw/published.
+   *
+   * The engine does not form `versions.<release>.<id>` ids — it has no
+   * such concept (it reads content through `client.fetch({perspective})`
+   * for queries). A reactive consumer applies this perspective when it
+   * subscribes: a **content** doc must be resolved to its version /
+   * draft / published form (e.g. Studio `editState`'s version param, or
+   * the SDK's `getVersionId`), while instance / ancestor / `system.release`
+   * docs are always raw. The `type` on each {@link SubscriptionDocument}
+   * tells the consumer which is which.
+   */
+  perspective?: WorkflowPerspective;
+}
+
 /**
  * The four-method workflow API.
  */
@@ -5740,6 +5960,20 @@ export declare const workflow: {
   };
 };
 
+/**
+ * The lake document type for a deployed workflow definition. Single source of
+ * truth — every tag-scoped lookup query and the deploy write derive their
+ * `_type` from here, mirroring {@link WORKFLOW_INSTANCE_TYPE}.
+ */
+export declare const WORKFLOW_DEFINITION_TYPE = "workflow.definition";
+
+/**
+ * The lake document type for a workflow instance. Single source of truth — the
+ * {@link WorkflowInstance} `_type`, every tag-scoped query, and the create
+ * write all derive from here, mirroring {@link WORKFLOW_DEFINITION_TYPE}.
+ */
+export declare const WORKFLOW_INSTANCE_TYPE = "workflow.instance";
+
 /**
  * The engine's view of "who am I, what can I do?". `actor` is who
  * the engine stamps onto history / `completedBy` / `Source.actor`.
@@ -8284,7 +8518,7 @@ export declare interface WorkflowFetchOptions {
 }
 
 export declare interface WorkflowInstance extends SanityDocument {
-  _type: "workflow.instance";
+  _type: typeof WORKFLOW_INSTANCE_TYPE;
   /**
    * Engine-scope tags stamped on the instance at create time. Engines
    * with disjoint tag sets cannot read this instance; engines sharing