@sanity/workflow-engine 0.4.0 → 0.5.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,6 +6520,30 @@ 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;
@@ -6612,6 +6659,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 +
@@ -6718,6 +6772,49 @@ export declare function datasetResourceParts(id: string): {
  */
 export declare const defaultLoggerFactory: LoggerFactory;
 
+export declare interface DeleteDefinitionArgs {
+  client: WorkflowClient;
+  /** Engine-scope tags — required. See `validateTags` + `tags.ts`. */
+  tags: 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).
@@ -6771,6 +6868,103 @@ export declare interface DeployDefinitionsResult {
  */
 export declare function deployStageGuards(args: StageGuardArgs): Promise<void>;
 
+/** Where a definition deploys: the engine tags it partitions under, and the
+ *  workflow resource it belongs to. Structurally what `deployDefinitions`
+ *  receives, minus the definitions themselves. */
+export declare interface DeployTarget {
+  tags: 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 =
   | {
       /**
@@ -7060,10 +7254,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
@@ -8160,6 +8366,12 @@ 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. */
@@ -11417,6 +11629,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
@@ -11729,6 +11966,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,10 +12026,9 @@ 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>;
   /**
@@ -11887,6 +12133,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.
    *
@@ -14041,6 +14307,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>;
 }