@sanity/workflow-engine 0.4.0 → 0.6.0

package/dist/index.d.cts

@@ -6,6 +6,11 @@ export declare interface AbortInstanceArgs extends OperationArgs {
   reason?: string;
 }
 
+/** The free-text reason recorded on the aborted history entry, if any. */
+export declare function abortReason(
+  instance: Pick<WorkflowInstance, "history">,
+): string | undefined;
+
 export declare type Action = v.InferOutput<typeof StoredActionSchema>;
 
 export declare class ActionDisabledError extends Error {
@@ -90,6 +95,17 @@ export declare class ActionParamsInvalidError extends Error {
   });
 }
 
+/** The fireable-action verdict for one action on a task — its `allowed`
+ *  state, structured `disabledReason`, and declared params, tagged with the
+ *  owning task. The per-action atom both projections share:
+ *  {@link availableActions} flattens it across a stage's tasks; a consumer
+ *  that keeps per-task nesting (e.g. the MCP) maps it over a task's actions
+ *  directly, so the verdict shape has a single source. */
+export declare function actionVerdict(
+  task: TaskEvaluation,
+  action: ActionEvaluation,
+): AvailableAction;
+
 export declare interface Actor {
   kind: "user" | "ai" | "system";
   id: string;
@@ -120,6 +136,13 @@ export declare type Assignee =
       role: string;
     };
 
+/** The assignees recorded for a task in a stage — the runtime half of the
+ *  "who is this waiting on" answer. Empty when the task is unassigned. */
+export declare function assigneesOf(
+  stage: StageEntry | undefined,
+  taskName: string,
+): Assignee[];
+
 /**
  * Persisted document and effect-queue `_type` discriminators.
  */
@@ -6497,13 +6520,37 @@ declare const AuthoringWorkflowSchema: v.StrictObjectSchema<
   undefined
 >;
 
+export declare interface AvailableAction {
+  task: string;
+  taskStatus: TaskStatus;
+  action: string;
+  title: string | undefined;
+  allowed: boolean;
+  disabledReason: DisabledReason | undefined;
+  params: ActionParam[];
+}
+
+/** Flatten an evaluation's current-stage tasks into the actions the actor
+ *  could fire, each carrying whether it's allowed (and why not). */
+export declare function availableActions(
+  tasks: TaskEvaluation[],
+): AvailableAction[];
+
+/** The `workflow.availableActions` result — the projected actions plus the
+ *  evaluation they came from, so a consumer can read the instance/stage
+ *  context without a second projection. */
+export declare interface AvailableActionsResult {
+  evaluation: WorkflowEvaluation;
+  actions: AvailableAction[];
+}
+
 declare type Bound<
   Args extends {
     client: WorkflowClient;
-    tags: string[];
+    tag: string;
     workflowResource: WorkflowResource;
   },
-> = Omit<Args, "client" | "tags" | "workflowResource">;
+> = Omit<Args, "client" | "tag" | "workflowResource">;
 
 /**
  * Build a snapshot from a set of loaded docs. Pure transform.
@@ -6523,8 +6570,6 @@ export declare function buildSnapshot(args: {
   docs: LoadedDoc[];
 }): HydratedSnapshot;
 
-export declare function canonicalTag(tags: string[]): string;
-
 /**
  * Thrown when auto-transitions on an instance fail to stabilise within
  * {@link CascadeLimitError.limit} passes — the signature of a runaway
@@ -6612,6 +6657,13 @@ export declare interface CompleteEffectArgs extends OperationArgs {
   durationMs?: number;
 }
 
+/** Compare each definition against the deployed doc at its own docId. */
+export declare function computeDiffEntries(
+  client: Pick<WorkflowClient, "getDocument">,
+  defs: WorkflowDefinition[],
+  target: DeployTarget,
+): Promise<DiffEntry[]>;
+
 /**
  * Thrown when a `fireAction` commit loses the optimistic-locking race on
  * all {@link CONCURRENT_FIRE_ACTION_MAX_ATTEMPTS} attempts — every reload +
@@ -6659,10 +6711,11 @@ export declare function contentReleaseName(args: {
 }): string | undefined;
 
 /**
- * Construct an engine bound to a workflow resource + tags. The returned
+ * Construct an engine bound to a workflow resource + tag. The returned
  * object exposes the same verbs as the `workflow.*` namespace, minus
- * the boilerplate config arguments (client / tags / workflowResource)
- * which are pinned at construction.
+ * the boilerplate config arguments (client / tag / workflowResource)
+ * which are pinned at construction. The `tag` is required — see
+ * {@link validateTag} for the accepted shape.
  *
  * Effect handlers + missingHandler are stored for future drain wiring
  * (Step 10). They have no effect on `fireAction` / `tick` /
@@ -6674,7 +6727,14 @@ export declare function createEngine(args: CreateEngineArgs): Engine;
 export declare interface CreateEngineArgs {
   client: WorkflowClient;
   workflowResource: WorkflowResource;
-  tags: string[];
+  /**
+   * Engine-scope environment partition (e.g. `"test"`, `"prod"`). Every
+   * definition/instance the engine writes is stamped with this tag and
+   * every read is scoped to it. Required and never defaulted — the engine
+   * enforces nothing, so the partition is the only thing keeping reads and
+   * writes off the wrong environment.
+   */
+  tag: string;
   /**
    * Optional routing for cross-resource reads. When the engine needs
    * a doc whose GDR points at a resource other than its own, it calls
@@ -6718,6 +6778,49 @@ export declare function datasetResourceParts(id: string): {
  */
 export declare const defaultLoggerFactory: LoggerFactory;
 
+export declare interface DeleteDefinitionArgs {
+  client: WorkflowClient;
+  /** Engine-scope environment partition — required. See {@link validateTag} + `tags.ts`. */
+  tag: string;
+  /** The Sanity resource the engine's own data lives in. */
+  workflowResource: WorkflowResource;
+  /** Cross-resource routing — see `StartInstanceArgs.resourceClients`. */
+  resourceClients?: ResourceClientResolver;
+  /** The definition's `name` — delete addresses the workflow, not a doc id. */
+  definition: string;
+  /** Delete only this deployed version. Default: every deployed version. */
+  version?: number;
+  /**
+   * Abort every non-terminal instance pinned to the targeted versions
+   * before deleting. Instances are ONLY aborted — instance documents are
+   * never deleted; they stay in the lake as the audit record. Without
+   * this flag the delete refuses when such instances exist.
+   */
+  cascade?: boolean;
+  /** Free-text reason stamped on each cascade-abort history entry. */
+  reason?: string;
+  /** Optional access-state override — see `StartInstanceArgs.access`. */
+  access?: WorkflowAccessOverride;
+  /** URL path for grant resolution — see `StartInstanceArgs.grantsFromPath`. */
+  grantsFromPath?: string;
+}
+
+export declare interface DeleteDefinitionResult {
+  /** The definition's `name`. */
+  name: string;
+  /** Versions actually removed, newest first. */
+  deletedVersions: number[];
+  /** Instances hard-stopped by `cascade`, in abort order. Empty without it. */
+  abortedInstanceIds: string[];
+  /**
+   * Orphaned guard docs removed across the definition's statically-named
+   * datasources. Only populated when the LAST version goes — guard docs
+   * are stamped with the version-less `name`, so they stay while any
+   * version remains deployed.
+   */
+  deletedGuardCount: number;
+}
+
 /**
  * Run every guard whose `match` applies and collect those that DENY. Empty
  * result ⇒ allowed (optimistically).
@@ -6740,8 +6843,8 @@ export declare interface DeployDefinitionResult {
 
 export declare interface DeployDefinitionsArgs {
   client: WorkflowClient;
-  /** Engine-scope tags — required. See `validateTags` + `tags.ts`. */
-  tags: string[];
+  /** Engine-scope environment partition — required. See {@link validateTag} + `tags.ts`. */
+  tag: string;
   /**
    * The Sanity resource the engine's own data lives in. Used to mint
    * GDR URIs for every doc the engine writes (definitions, instances,
@@ -6771,6 +6874,103 @@ export declare interface DeployDefinitionsResult {
  */
 export declare function deployStageGuards(args: StageGuardArgs): Promise<void>;
 
+/** Where a definition deploys: the engine tag it partitions under, and the
+ *  workflow resource it belongs to. Structurally what `deployDefinitions`
+ *  receives, minus the definitions themselves. */
+export declare interface DeployTarget {
+  tag: string;
+  workflowResource: WorkflowResource;
+}
+
+/**
+ * The slice of an instance + its {@link WorkflowEvaluation} the classifier
+ * reads. Narrowed so callers (and tests) can craft an exact stuck permutation
+ * without standing up a full evaluation; {@link diagnoseInputFromEvaluation}
+ * builds it from a real {@link WorkflowEvaluation}.
+ */
+export declare interface DiagnoseInput {
+  instance: Pick<
+    WorkflowInstance,
+    | "currentStage"
+    | "stages"
+    | "completedAt"
+    | "abortedAt"
+    | "effectHistory"
+    | "pendingEffects"
+    | "history"
+  >;
+  tasks: TaskEvaluation[];
+  transitions: TransitionEvaluation[];
+}
+
+/** Narrow a full {@link WorkflowEvaluation} to the {@link DiagnoseInput} the
+ *  classifier reads. */
+export declare function diagnoseInputFromEvaluation(
+  evaluation: WorkflowEvaluation,
+): DiagnoseInput;
+
+/**
+ * Classify an instance. Terminal states win first; then the genuine stuck
+ * causes (nothing advances on its own or via a normal action); then `waiting`
+ * (an action is available — healthy); else `progressing` (a transition is
+ * already satisfied and will cascade).
+ */
+export declare function diagnoseInstance(input: DiagnoseInput): Diagnosis;
+
+/** The `workflow.diagnose` result — the verdict plus the evaluation it was
+ *  derived from, so a consumer can render the supporting evidence (current
+ *  stage tasks + transitions) without a second projection. */
+export declare interface DiagnoseResult {
+  evaluation: WorkflowEvaluation;
+  diagnosis: Diagnosis;
+}
+
+export declare type Diagnosis =
+  | {
+      state: "progressing";
+    }
+  | {
+      state: "waiting";
+      task: string;
+      assignees: Assignee[];
+      actions: string[];
+    }
+  | {
+      state: "completed";
+      at: string;
+    }
+  | {
+      state: "aborted";
+      at: string;
+      reason?: string;
+    }
+  | {
+      state: "stuck";
+      cause: StuckCause;
+    };
+
+export declare interface DiffEntry {
+  name: string;
+  version: number;
+  status: "create" | "update" | "unchanged";
+  docId: string;
+  expected: Record<string, unknown>;
+  existing?: Record<string, unknown>;
+}
+
+/**
+ * Compare one local definition against a deployed document (or its
+ * absence), classifying it as create / update / unchanged using the
+ * engine's own no-op verdict. Pure — callers own the fetch, so the same
+ * comparison serves both deploy's exact-docId lookup and `definition
+ * diff`'s latest-version query.
+ */
+export declare function diffEntry(
+  def: WorkflowDefinition,
+  existingRaw: Record<string, unknown> | undefined,
+  target: DeployTarget,
+): DiffEntry;
+
 export declare type DisabledReason =
   | {
       /**
@@ -7045,7 +7245,7 @@ export declare interface Engine {
    *  (e.g. test bench, drain workers) that need them; the verbs already
    *  thread them through internally. */
   readonly client: WorkflowClient;
-  readonly tags: readonly string[];
+  readonly tag: string;
   readonly workflowResource: WorkflowResource;
   readonly effectHandlers: Readonly<Record<string, EffectHandler>>;
   readonly missingHandler: MissingHandlerPolicy;
@@ -7060,10 +7260,22 @@ export declare interface Engine {
   evaluateInstance: (
     args: Bound<EvaluateArgs>,
   ) => ReturnType<typeof evaluateInstance>;
+  /** Diagnose why an instance is or isn't progressing — a classified
+   *  {@link DiagnoseResult} plus the evaluation it was derived from. */
+  diagnose: (args: Bound<EvaluateArgs>) => Promise<DiagnoseResult>;
+  /** The actions firable on the instance's current stage, each flagged
+   *  allowed/disabled, plus the evaluation they came from. */
+  availableActions: (
+    args: Bound<EvaluateArgs>,
+  ) => Promise<AvailableActionsResult>;
   /** Admin override — bypass filters/transitions and force the stage. */
   setStage: (args: Bound<SetStageArgs>) => Promise<DispatchResult>;
   /** Admin override — hard-stop an in-flight instance where it stands. */
   abortInstance: (args: Bound<AbortInstanceArgs>) => Promise<DispatchResult>;
+  /** Admin override — remove a deployed definition (instances are only ever aborted, never deleted). */
+  deleteDefinition: (
+    args: Bound<DeleteDefinitionArgs>,
+  ) => Promise<DeleteDefinitionResult>;
   /** Fetch a workflow instance by id. */
   getInstance: (args: { instanceId: string }) => Promise<WorkflowInstance>;
   /** The reactive {@link WatchSet} for an instance — every document whose
@@ -7110,8 +7322,8 @@ export declare interface Engine {
     instanceId: string;
     task?: string;
   }) => Promise<WorkflowInstance[]>;
-  /** GROQ query against the engine's workflow resource. `$engineTags`
-   *  is bound for tag-aware filtering. */
+  /** GROQ query against the engine's workflow resource. `$tag`
+   *  is bound for tag-scoped filtering. */
   query: <T = unknown>(args: {
     groq: string;
     params?: Record<string, unknown>;
@@ -7145,7 +7357,7 @@ export declare interface Engine {
     access?: WorkflowAccessOverride;
   }) => Promise<DrainEffectsResult>;
   /**
-   * Inspect every deployed definition in the engine's tags and apply
+   * Inspect every deployed definition in the engine's tag and apply
    * the configured missingHandler policy at `phase: "deploy"` for any
    * effect name without a registered handler. Catches "definition
    * shipped, handler removed" misconfigurations at startup instead of
@@ -7165,8 +7377,8 @@ export declare interface EngineLogger {
 
 export declare interface EvaluateArgs {
   client: WorkflowClient;
-  /** Engine-scope tags — required. */
-  tags: string[];
+  /** Engine-scope environment partition — required. */
+  tag: string;
   /** Engine workflow resource — required. */
   workflowResource: WorkflowResource;
   instanceId: string;
@@ -8160,10 +8372,16 @@ export declare interface OpAppliedSummary {
   resolved?: Record<string, unknown>;
 }
 
+/** The instance's current, not-yet-exited {@link StageEntry}, if it has one —
+ *  the engine's canonical {@link findOpenStageEntry}, over the diagnosis input. */
+export declare function openStage(
+  instance: Pick<WorkflowInstance, "currentStage" | "stages">,
+): StageEntry | undefined;
+
 export declare interface OperationArgs {
   client: WorkflowClient;
-  /** Engine-scope tags — required. */
-  tags: string[];
+  /** Engine-scope environment partition — required. */
+  tag: string;
   /** The Sanity resource the engine's own data lives in. */
   workflowResource: WorkflowResource;
   /** Cross-resource routing — see `StartInstanceArgs.resourceClients`. */
@@ -8502,8 +8720,8 @@ export declare type StageName = string;
 
 export declare interface StartInstanceArgs {
   client: WorkflowClient;
-  /** Engine-scope tags — required. */
-  tags: string[];
+  /** Engine-scope environment partition — required. */
+  tag: string;
   /** The Sanity resource the engine's own data lives in. */
   workflowResource: WorkflowResource;
   /**
@@ -11417,6 +11635,31 @@ export declare function stripSystemFields(
   doc: Record<string, unknown>,
 ): Record<string, unknown>;
 
+/**
+ * Why an in-flight instance is genuinely blocked — nothing advances it on its
+ * own OR via a normal action. Ordered most- to least-actionable in
+ * {@link diagnoseInstance}: a failed effect is the root cause even when it left
+ * its task looking merely "active", so it wins over the task- and
+ * transition-level symptoms it produces. Note an active task awaiting a human
+ * action is NOT here — that's the healthy {@link Diagnosis} `waiting` state.
+ */
+export declare type StuckCause =
+  | {
+      kind: "failed-effect";
+      effect: EffectHistoryEntry;
+    }
+  | {
+      kind: "hung-effect";
+      effect: PendingEffect;
+    }
+  | {
+      kind: "failed-task";
+      task: string;
+    }
+  | {
+      kind: "no-transition-fires";
+    };
+
 /**
  * A document the reactive layer should subscribe to, with its GDR
  * exploded so consumers never re-parse: the resource-addressing parts
@@ -11532,13 +11775,11 @@ declare const SubworkflowsSchema: v.StrictObjectSchema<
 
 /**
  * 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.
+ * visible when its `tag` equals the caller's `$tag` param. The single
+ * definition of "tag-scoped" shared by the engine's internal lookups, the
+ * `workflow.query` guard, and the CLI/MCP read helpers.
  */
-export declare function tagScopeFilter(param?: string): string;
+export declare function tagScopeFilter(): string;
 
 export declare type Task = v.InferOutput<typeof StoredTaskSchema>;
 
@@ -11628,18 +11869,25 @@ export declare function validateDefinition(
 ): void;
 
 /**
- * Engine-scope tags — the multi-tenant isolation primitive.
+ * Engine-scope tag — the environment partition primitive.
+ *
+ * Every engine operates against exactly one `tag` ("test", "prod", …).
+ * The tag partitions definitions and instances within a single workflow
+ * resource: `deploy(def, tag: "test")` and `deploy(def, tag: "prod")` are
+ * separate deployed workflows with independent lifecycles, and every read
+ * is scoped to one tag so test runs never surface in prod.
  *
- * Every engine takes a required `tags: string[]` set at construction.
- * Tags must be Sanity-ID-compatible since they're joined into IDs with
- * `.` — ASCII lowercase + digits + dashes, no leading dash, no dots.
+ * The tag must be Sanity-ID-compatible since it's joined into IDs with
+ * `.` — ASCII lowercase + digits + dashes, no leading dash, no dots. It
+ * is also the ID prefix for every definition/instance the engine writes.
  *
- * The first tag in the array is the *canonical* tag, used as the ID
- * prefix when the engine writes new definitions or instances. The full
- * tag set goes onto every written doc and is the basis for read
- * filtering (tag intersection between engine and doc).
+ * There is no default. The tag selects which environment the engine reads
+ * and writes, and the engine enforces nothing — so the partition is the
+ * only thing keeping test runs out of prod. Every entry point
+ * (`createEngine`, the CLI, the MCP server) requires it explicitly and
+ * fails when it's absent rather than guessing an environment.
  */
-export declare function validateTags(tags: string[]): void;
+export declare function validateTag(tag: string): void;
 
 /**
  * The guards allowed to influence this instance's verdicts, read from the
@@ -11729,6 +11977,16 @@ export declare const workflow: {
   deployDefinitions: (
     args: DeployDefinitionsArgs,
   ) => Promise<DeployDefinitionsResult>;
+  /**
+   * Remove a deployed workflow definition (all versions, or one via
+   * `version`). Refuses while non-terminal instances exist unless
+   * `cascade` aborts them first — instances are never deleted, only
+   * aborted in place; see {@link deleteDefinitionInternal} for the
+   * full contract (spawn-referrer check, guard-doc housekeeping).
+   */
+  deleteDefinition: (
+    args: Clocked<DeleteDefinitionArgs>,
+  ) => Promise<DeleteDefinitionResult>;
   /**
    * Spawn a new workflow instance from a deployed definition.
    *
@@ -11779,51 +12037,49 @@ export declare const workflow: {
   setStage: (args: Clocked<SetStageArgs>) => Promise<DispatchResult>;
   /**
    * Admin override — hard-stop an in-flight instance where it stands.
-   * No stage move, no transition effects, pending effects cancelled; see
-   * the engine-level {@link engineAbortInstance} for the full contract.
-   * Ancestors are propagated (not cascaded — the instance is terminal)
-   * so a parent gate waiting on this child re-evaluates.
+   * No stage move, no transition effects, pending effects cancelled;
+   * see {@link abortAndPropagate} for the abort + ancestor-propagation
+   * contract (propagated, not cascaded — the instance is terminal).
    */
   abortInstance: (args: Clocked<AbortInstanceArgs>) => Promise<DispatchResult>;
   /**
-   * Fetch a workflow instance by id, scoped to the engine's tags.
+   * Fetch a workflow instance by id, scoped to the engine's tag.
    * Throws when the instance doesn't exist or isn't visible to this
    * engine.
    */
   getInstance: (args: {
     client: WorkflowClient;
-    tags: string[];
+    tag: string;
     workflowResource: WorkflowResource;
     instanceId: string;
   }) => Promise<WorkflowInstance>;
   guardsForInstance: (args: {
     client: WorkflowClient;
-    tags: string[];
+    tag: string;
     workflowResource: WorkflowResource;
     instanceId: string;
     resourceClients?: ResourceClientResolver;
   }) => Promise<MutationGuardDoc[]>;
   guardsForDefinition: (args: {
     client: WorkflowClient;
-    tags: string[];
+    tag: string;
     workflowResource: WorkflowResource;
     /** The definition's `name`. */
     definition: string;
     resourceClients?: ResourceClientResolver;
   }) => Promise<MutationGuardDoc[]>;
   /**
-   * Run a caller-supplied GROQ query with the engine's tags bound as
-   * `$engineTags`. This does NOT rewrite the query — arbitrary GROQ
+   * Run a caller-supplied GROQ query with the engine's tag bound as
+   * `$tag`. This does NOT rewrite the query — arbitrary GROQ
    * can't be safely tag-scoped after the fact — so the CALLER MUST
-   * filter on `$engineTags` (e.g.
-   * `count(tags[@ in $engineTags]) > 0`). To guard against accidental
-   * cross-tenant reads, a query that never references `$engineTags` is
+   * filter on `$tag` (e.g. `tag == $tag`). To guard against accidental
+   * cross-partition reads, a query that never references `$tag` is
    * rejected before it reaches the lake. Caller is responsible for type
    * narrowing the result.
    */
   query: <T = unknown>(args: {
     client: WorkflowClient;
-    tags: string[];
+    tag: string;
     workflowResource: WorkflowResource;
     groq: string;
     params?: Record<string, unknown>;
@@ -11847,7 +12103,7 @@ export declare const workflow: {
   queryInScope: <T = unknown>(
     args: Clocked<{
       client: WorkflowClient;
-      tags: string[];
+      tag: string;
       workflowResource: WorkflowResource;
       resourceClients?: ResourceClientResolver;
       instanceId: string;
@@ -11861,7 +12117,7 @@ export declare const workflow: {
    */
   listPendingEffects: (args: {
     client: WorkflowClient;
-    tags: string[];
+    tag: string;
     workflowResource: WorkflowResource;
     instanceId: string;
   }) => Promise<PendingEffect[]>;
@@ -11872,7 +12128,7 @@ export declare const workflow: {
    */
   findPendingEffects: (args: {
     client: WorkflowClient;
-    tags: string[];
+    tag: string;
     workflowResource: WorkflowResource;
     instanceId: string;
     claimed?: boolean;
@@ -11887,6 +12143,26 @@ export declare const workflow: {
    * `fireAction` to gate writes via the same logic.
    */
   evaluate: (args: Clocked<EvaluateArgs>) => Promise<WorkflowEvaluation>;
+  /**
+   * Diagnose why an instance is or isn't progressing. Projects the
+   * instance (the same read as `evaluate`) and classifies it — terminal,
+   * `progressing`, `waiting` (an action is available — healthy), or `stuck`
+   * with a structured cause — returning that verdict as a
+   * {@link DiagnoseResult} alongside the evaluation it came from, so a
+   * consumer can render the supporting evidence without a second projection.
+   * Pure read.
+   */
+  diagnose: (args: Clocked<EvaluateArgs>) => Promise<DiagnoseResult>;
+  /**
+   * List the actions an actor could fire on an instance's current stage,
+   * each flagged `allowed` (with a structured `disabledReason` when not).
+   * Projects the instance from the actor's perspective and flattens its
+   * tasks' actions. Returns the evaluation alongside the actions so a
+   * consumer can read the instance/stage context. Pure read.
+   */
+  availableActions: (
+    args: Clocked<EvaluateArgs>,
+  ) => Promise<AvailableActionsResult>;
   /**
    * Materialised spawned children of a parent instance.
    *
@@ -11894,14 +12170,14 @@ export declare const workflow: {
    * record. (The per-task `spawnedInstances` field on the active stage
    * only exists while that stage is current; history survives.) Strips
    * the GDR URI on each `instanceRef` to a bare `_id`, fetches the
-   * instances, drops any that aren't visible to this engine's tags, and
+   * instances, drops any that aren't visible to this engine's tag, and
    * returns them sorted by `startedAt` ascending.
    *
    * Pass `task` to restrict to a single spawning task on the parent.
    */
   children: (args: {
     client: WorkflowClient;
-    tags: string[];
+    tag: string;
     workflowResource: WorkflowResource;
     instanceId: string;
     task?: string;
@@ -13854,11 +14130,11 @@ export declare interface WorkflowFetchOptions {
 export declare interface WorkflowInstance extends SanityDocument {
   _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
-   * any tag with this array can.
+   * Engine-scope environment partition stamped on the instance at create
+   * time. Reads are scoped to a single tag, so an engine only sees
+   * instances whose `tag` equals its own.
    */
-  tags: string[];
+  tag: string;
   /**
    * The Sanity resource this instance lives in. Stored on the doc so
    * any internal operation can mint GDRs for ancestors / spawned
@@ -14041,6 +14317,15 @@ export declare interface WorkflowTransaction {
    * clients drain it structurally.
    */
   patch: (patch: any) => WorkflowTransaction;
+  /**
+   * Queue a document delete. Deliberately a transaction-only capability —
+   * the top-level client surface stays delete-free so no engine code path
+   * can casually remove documents; the sole consumer is `deleteDefinition`
+   * housekeeping (definition docs + orphaned guard docs). Both the real
+   * `@sanity/client` Transaction and the test fake's TransactionHandle
+   * carry this shape.
+   */
+  delete: (id: string) => WorkflowTransaction;
   commit: () => Promise<unknown>;
 }