@sanity/workflow-engine 0.1.0 → 0.3.0

package/dist/define.js

@@ -1,67 +1,54 @@
-import { z } from "zod";
-const TASK_STATUSES = ["pending", "active", "done", "skipped", "failed"], STATE_SCOPES = ["workflow", "stage", "task"], DOCUMENT_VALUE_PERMISSIONS = ["create", "read", "update"], MUTATION_GUARD_ACTIONS = [
-  "create",
-  "update",
-  "delete",
-  "publish",
-  "unpublish"
-];
+import * as v from "valibot";
+import { formatValidationError, issuesFromValibot, WorkflowDefinitionSchema, StageSchema, TaskSchema, ActionSchema, TransitionSchema, FilterSchema, AssigneeSchema, PredicateSchema, EffectSchema } from "./_chunks-es/schema.js";
 function knownList(ids) {
   return [...ids].map((s) => `"${s}"`).join(", ");
 }
-function checkStagesAndTasks(def, ctx) {
+function checkStagesAndTasks(def, issues) {
   const stageIds = /* @__PURE__ */ new Set();
   for (const [i, stage] of def.stages.entries())
-    stageIds.has(stage.id) && ctx.addIssue({
-      code: "custom",
+    stageIds.has(stage.id) && issues.push({
       path: ["stages", i, "id"],
       message: `duplicate stage id "${stage.id}" (already declared earlier)`
-    }), stageIds.add(stage.id), stage.kind === "terminal" && stage.transitions && stage.transitions.length > 0 && ctx.addIssue({
-      code: "custom",
+    }), stageIds.add(stage.id), stage.kind === "terminal" && stage.transitions && stage.transitions.length > 0 && issues.push({
       path: ["stages", i, "transitions"],
       message: `terminal stage "${stage.id}" must not declare transitions`
-    }), checkDuplicateTaskIds(stage, i, ctx);
+    }), checkDuplicateTaskIds(stage, i, issues);
   return stageIds;
 }
-function checkDuplicateTaskIds(stage, i, ctx) {
+function checkDuplicateTaskIds(stage, i, issues) {
   const taskIds = /* @__PURE__ */ new Set();
   for (const [j, task] of (stage.tasks ?? []).entries())
-    taskIds.has(task.id) && ctx.addIssue({
-      code: "custom",
+    taskIds.has(task.id) && issues.push({
       path: ["stages", i, "tasks", j, "id"],
       message: `duplicate task id "${task.id}" in stage "${stage.id}"`
     }), taskIds.add(task.id);
 }
-function checkInitialStage(def, stageIds, ctx) {
-  stageIds.has(def.initialStageId) || ctx.addIssue({
-    code: "custom",
+function checkInitialStage(def, stageIds, issues) {
+  stageIds.has(def.initialStageId) || issues.push({
     path: ["initialStageId"],
     message: `initialStageId "${def.initialStageId}" is not a declared stage. Known stages: ${knownList(stageIds)}`
   });
 }
-function checkTransitionTargets(def, stageIds, ctx) {
+function checkTransitionTargets(def, stageIds, issues) {
   for (const [i, stage] of def.stages.entries())
     for (const [k, t] of (stage.transitions ?? []).entries())
-      stageIds.has(t.to) || ctx.addIssue({
-        code: "custom",
+      stageIds.has(t.to) || issues.push({
         path: ["stages", i, "transitions", k, "to"],
         message: `transition target "${t.to}" is not a declared stage. Known stages: ${knownList(stageIds)}`
       });
 }
-function collectPredicateIds(def, ctx) {
+function collectPredicateIds(def, issues) {
   const predicateIds = /* @__PURE__ */ new Set();
   for (const [i, p] of (def.predicates ?? []).entries())
-    predicateIds.has(p.id) && ctx.addIssue({
-      code: "custom",
+    predicateIds.has(p.id) && issues.push({
       path: ["predicates", i, "id"],
       message: `duplicate predicate id "${p.id}"`
     }), predicateIds.add(p.id);
   return predicateIds;
 }
-function checkFilterRefs(def, predicateIds, ctx) {
+function checkFilterRefs(def, predicateIds, issues) {
   const visit = (g, path) => {
-    g === void 0 || typeof g == "string" || predicateIds.has(g.ref) || ctx.addIssue({
-      code: "custom",
+    g === void 0 || typeof g == "string" || predicateIds.has(g.ref) || issues.push({
       path: [...path, "ref"],
       message: `Filter references predicate "${g.ref}" which is not declared. Known predicates: ${knownList(predicateIds) || "(none)"}`
     });
@@ -77,396 +64,16 @@ function checkFilterRefs(def, predicateIds, ctx) {
       visit(t.filter, ["stages", i, "transitions", k, "filter"]);
   }
 }
-function checkWorkflowInvariants(def, ctx) {
-  const stageIds = checkStagesAndTasks(def, ctx);
-  checkInitialStage(def, stageIds, ctx), checkTransitionTargets(def, stageIds, ctx);
-  const predicateIds = collectPredicateIds(def, ctx);
-  checkFilterRefs(def, predicateIds, ctx);
-}
-const NonEmpty = z.string().min(1, "must be a non-empty string"), GdrSchema = z.object({
-  id: z.string().regex(
-    /^(dataset|canvas|media-library|dashboard):/,
-    "must be a GDR URI of form '<scheme>:<...id-parts>' where scheme is one of: dataset, canvas, media-library, dashboard"
-  ),
-  type: NonEmpty
-}).strict(), SourceSchema = z.lazy(
-  () => z.union([
-    z.object({
-      source: z.literal("literal"),
-      value: z.union([z.string(), z.number(), z.boolean(), z.null()])
-    }).strict(),
-    z.object({ source: z.literal("param"), paramId: NonEmpty }).strict(),
-    z.object({ source: z.literal("actor") }).strict(),
-    z.object({ source: z.literal("now") }).strict(),
-    z.object({ source: z.literal("self") }).strict(),
-    z.object({ source: z.literal("stageId") }).strict(),
-    z.object({
-      source: z.literal("stateRead"),
-      scope: z.enum(STATE_SCOPES),
-      slotId: NonEmpty,
-      path: z.string().optional()
-    }).strict(),
-    // effectsContext lookup — reads from `instance.effectsContext[id === ID].value`.
-    // Used by chained effects where one handler's output feeds another's binding.
-    z.object({
-      source: z.literal("effectOutput"),
-      contextId: NonEmpty,
-      path: z.string().optional()
-    }).strict(),
-    z.object({ source: z.literal("row"), path: z.string().optional() }).strict(),
-    z.object({
-      source: z.literal("parentState"),
-      slotId: NonEmpty,
-      path: z.string().optional()
-    }).strict(),
-    // Compound object source — resolves each field's Source recursively
-    // and packages the result into a JSON object. Lets ops append rich
-    // rows to `checklist` / `notes` / `assignees` slots, e.g.
-    // `{ source: "object", fields: { signer: { source: "actor" },
-    //   at: { source: "now" } } }`.
-    z.object({
-      source: z.literal("object"),
-      fields: z.record(NonEmpty, SourceSchema)
-    }).strict()
-  ])
-), ScopeKeySchema = z.object({
-  scope: z.enum(STATE_SCOPES),
-  slotId: NonEmpty
-}).strict(), OpPredicateSchema = z.lazy(
-  () => z.union([
-    z.object({
-      field: NonEmpty,
-      equals: SourceSchema
-    }).strict(),
-    z.object({ all: z.array(OpPredicateSchema) }).strict(),
-    z.object({ any: z.array(OpPredicateSchema) }).strict()
-  ])
-), OpSchema = z.discriminatedUnion("type", [
-  z.object({
-    type: z.literal("workflow.op.state.set"),
-    target: ScopeKeySchema,
-    value: SourceSchema
-  }).strict(),
-  z.object({
-    type: z.literal("workflow.op.state.append"),
-    target: ScopeKeySchema,
-    item: SourceSchema
-  }).strict(),
-  z.object({
-    type: z.literal("workflow.op.state.updateWhere"),
-    target: ScopeKeySchema,
-    where: OpPredicateSchema,
-    merge: z.record(NonEmpty, SourceSchema)
-  }).strict(),
-  z.object({
-    type: z.literal("workflow.op.state.removeWhere"),
-    target: ScopeKeySchema,
-    where: OpPredicateSchema
-  }).strict(),
-  z.object({
-    type: z.literal("workflow.op.status.set"),
-    taskId: NonEmpty,
-    status: z.enum(TASK_STATUSES)
-  }).strict()
-]), StateSlotSourceSchema = z.union([
-  z.object({ kind: z.literal("init") }).strict(),
-  z.object({
-    kind: z.literal("query"),
-    query: NonEmpty,
-    resource: z.union([z.literal("workflow"), z.literal("subject"), GdrSchema]).optional()
-  }).strict(),
-  z.object({ kind: z.literal("write") }).strict(),
-  z.object({ kind: z.literal("computed"), compute: NonEmpty }).strict(),
-  /**
-   * Pre-populate the slot at resolution time with a constant value.
-   * Useful for stage- or task-scope slots that should start non-empty
-   * (e.g. a default headline, a starting tally).
-   */
-  z.object({ kind: z.literal("literal"), value: z.unknown() }).strict(),
-  /**
-   * Pre-populate by reading another already-resolved slot. `scope:
-   * "workflow"` reads from the workflow-scope `state[]` (resolved at
-   * startInstance). `scope: "stage"` reads from an earlier slot in
-   * this same stage entry's `state[]` (sequential resolution).
-   * Optional `path` selects a nested field (e.g. `path: "id"` on a
-   * doc.ref slot).
-   */
-  z.object({
-    kind: z.literal("stateRead"),
-    scope: z.union([z.literal("workflow"), z.literal("stage")]),
-    slotId: NonEmpty,
-    path: z.string().optional()
-  }).strict()
-]), StateSlotBase = {
-  id: NonEmpty,
-  title: z.string().optional(),
-  description: z.string().optional(),
-  source: StateSlotSourceSchema
-}, StateSlotKindSchema = z.enum([
-  "workflow.state.doc.ref",
-  "workflow.state.doc.refs",
-  // Release reference. A workflow declares this slot to say "I target a
-  // Content Release"; the runtime fills it with a specific release at
-  // start time, and the engine auto-derives the instance's read
-  // perspective from it.
-  "workflow.state.release.ref",
-  "workflow.state.query",
-  "workflow.state.value.string",
-  "workflow.state.value.url",
-  "workflow.state.value.number",
-  "workflow.state.value.boolean",
-  "workflow.state.value.dateTime",
-  "workflow.state.value.actor",
-  "workflow.state.checklist",
-  "workflow.state.notes",
-  "workflow.state.assignees"
-]), StateSlotSchema = z.discriminatedUnion(
-  "type",
-  StateSlotKindSchema.options.map(
-    (kind) => z.object({ type: z.literal(kind), ...StateSlotBase }).strict()
-  )
-), FilterSchema = z.union([
-  // Inline GROQ — only reserved params allowed at runtime.
-  NonEmpty,
-  // Reference to a named predicate, optionally with named args.
-  z.object({
-    ref: NonEmpty,
-    args: z.record(z.string(), z.unknown()).optional()
-  }).strict()
-]), PredicateParamSchema = z.object({
-  id: NonEmpty,
-  title: z.string().optional(),
-  description: z.string().optional(),
-  type: z.enum(["string", "number", "boolean", "string[]", "reference"]),
-  enum: z.array(z.string()).optional()
-}).strict(), PredicateSchema = z.object({
-  type: z.literal("workflow.predicate").optional(),
-  id: NonEmpty,
-  title: z.string().optional(),
-  description: z.string().optional(),
-  groq: NonEmpty,
-  params: z.array(PredicateParamSchema).optional()
-}).strict(), EffectSchema = z.object({
-  type: z.literal("workflow.effect").optional(),
-  id: NonEmpty,
-  title: z.string().optional(),
-  description: z.string().optional(),
-  // Bindings resolve typed Source values at commit time, producing
-  // concrete JSON in the queued effect's `params`. NO GROQ.
-  bindings: z.record(z.string(), SourceSchema).optional(),
-  input: z.record(z.string(), z.unknown()).optional()
-}).strict(), TerminalTaskStatus = z.enum(["done", "skipped", "failed"]), PermissionSchema = z.enum(DOCUMENT_VALUE_PERMISSIONS), ActionParamSchema = z.object({
-  type: z.literal("workflow.action.param").optional(),
-  id: NonEmpty,
-  title: z.string().optional(),
-  description: z.string().optional(),
-  paramType: z.enum([
-    "string",
-    "number",
-    "boolean",
-    "url",
-    "dateTime",
-    "actor",
-    "doc.ref",
-    "doc.refs",
-    "json"
-  ]),
-  required: z.boolean().optional()
-}).strict(), ActionSchema = z.object({
-  type: z.literal("workflow.action").optional(),
-  id: NonEmpty,
-  title: z.string().optional(),
-  description: z.string().optional(),
-  filter: FilterSchema.optional(),
-  /** Caller-supplied params, validated before ops/effects run. */
-  params: z.array(ActionParamSchema).optional(),
-  /**
-   * Status the task flips to when this action fires. Omit to leave
-   * the task status unchanged — used by intermediate `claim` /
-   * `assign` / partial-update actions where the task should stay
-   * active so a later action can fire on it. Declared values must
-   * be terminal (`done` / `skipped` / `failed`); the engine never
-   * mid-flip back to `active` outside of the `workflow.op.status.set`
-   * op explicit path.
-   */
-  setStatus: TerminalTaskStatus.optional(),
-  /**
-   * Inline state-mutation primitives executed during the action commit.
-   * Each op runs against the in-memory mutation (deterministic, no
-   * external I/O). Resolved Sources turn into concrete JSON before the
-   * op applies. Logged on `history[]` as `workflow.history.opApplied`
-   * and surfaced on the `ActionResult.ranOps`.
-   */
-  ops: z.array(OpSchema).optional(),
-  effects: z.array(EffectSchema).optional(),
-  /**
-   * Role gating — OR-match against `Actor.roles[]`. If omitted, no role
-   * gate. `"*"` in Actor.roles always matches (bench / all-access).
-   */
-  roles: z.array(NonEmpty).optional(),
-  /**
-   * When true, the actor must appear in the task's `assignees[]` (as a
-   * user-kind assignee matching by id) for the action to be allowed.
-   */
-  requireAssignment: z.boolean().optional(),
-  /**
-   * Which permission on the workflow.instance document the actor must
-   * hold (per supplied `grants`). Defaults to "update". Only checked
-   * when grants are supplied at evaluate/fireAction time.
-   */
-  requiredPermission: PermissionSchema.optional()
-}).strict(), CompletionPolicySchema = z.union([
-  z.object({ kind: z.literal("all") }).strict(),
-  z.object({ kind: z.literal("any") }).strict(),
-  z.object({
-    kind: z.literal("count"),
-    n: z.number().int().positive()
-  }).strict()
-]), LogicalDefinitionRefSchema = z.object({
-  workflowId: NonEmpty,
-  version: z.union([z.number().int().positive(), z.literal("latest")]).optional()
-}).strict(), SpawnForEachSchema = z.object({
-  groq: NonEmpty,
-  as: z.object({
-    initialState: z.array(
-      z.object({
-        type: StateSlotKindSchema,
-        id: NonEmpty,
-        value: SourceSchema
-      }).strict()
-    ).optional(),
-    effectsContext: z.record(z.string(), SourceSchema).optional()
-  }).strict()
-}).strict(), SpawnSchema = z.object({
-  type: z.literal("workflow.spawn").optional(),
-  id: z.string().optional(),
-  title: z.string().optional(),
-  description: z.string().optional(),
-  definitionRef: LogicalDefinitionRefSchema,
-  forEach: SpawnForEachSchema,
-  completionPolicy: CompletionPolicySchema.optional()
-}).strict(), AssigneeSchema = z.discriminatedUnion("kind", [
-  z.object({ kind: z.literal("user"), id: NonEmpty }).strict(),
-  z.object({ kind: z.literal("role"), role: NonEmpty }).strict()
-]), TaskSchema = z.object({
-  type: z.literal("workflow.task").optional(),
-  id: NonEmpty,
-  title: z.string().optional(),
-  description: z.string().optional(),
-  assignees: z.array(AssigneeSchema).optional(),
-  filter: FilterSchema.optional(),
-  invokeOn: z.enum(["stageEnter", "manual"]).optional(),
-  /**
-   * Auto-completion predicate — same shape as `transition.filter`. When
-   * truthy at activation or on any subsequent cascade, the engine
-   * flips the task to `done` with a `{ kind: "system", id: "engine.completeWhen" }`
-   * actor. A full filter, not just a wall-clock deadline.
-   */
-  completeWhen: FilterSchema.optional(),
-  /**
-   * Auto-failure predicate — symmetric to `completeWhen`. Same shape,
-   * same evaluation cadence (activation + every cascade), but flips
-   * the task to `failed` (not `done`) with a `{ kind: "system",
-   * id: "engine.failWhen" }` actor. When both `completeWhen` and
-   * `failWhen` resolve truthy on the same evaluation, `failWhen`
-   * wins — failure is the more notable signal and should not be
-   * silently swallowed.
-   */
-  failWhen: FilterSchema.optional(),
-  effects: z.array(EffectSchema).optional(),
-  actions: z.array(ActionSchema).optional(),
-  spawns: SpawnSchema.optional(),
-  contentRefs: z.array(z.unknown()).optional(),
-  /** Task-scoped state slots. Resolved at task activation time. */
-  state: z.array(StateSlotSchema).optional()
-}).strict(), TransitionSchema = z.object({
-  type: z.literal("workflow.transition").optional(),
-  id: NonEmpty,
-  title: z.string().optional(),
-  description: z.string().optional(),
-  to: NonEmpty,
-  on: z.string().optional(),
-  filter: FilterSchema.optional(),
-  effects: z.array(EffectSchema).optional()
-}).strict(), GuardActionSchema = z.enum(MUTATION_GUARD_ACTIONS), GuardMatchSchema = z.object({
-  /** Subject `_type`(s); empty matches any type. */
-  types: z.array(NonEmpty).optional(),
-  /** Target docs as `Source`s resolved at deploy to bare ids + the resource. */
-  idRefs: z.array(SourceSchema).optional(),
-  /** Glob id patterns (bare, resource-local). */
-  idPatterns: z.array(NonEmpty).optional(),
-  actions: z.array(GuardActionSchema).min(1, "a guard must match at least one action")
-}).strict(), GuardSchema = z.object({
-  name: z.string().optional(),
-  description: z.string().optional(),
-  match: GuardMatchSchema,
-  /**
-   * Lake GROQ predicate. Reads `document.before`/`document.after`, `mutation`,
-   * `guard`, and `identity()`. Bare ids/fields only — no GDRs. Omitted or
-   * empty means UNCONDITIONAL DENY.
-   */
-  predicate: z.string().optional(),
-  /**
-   * Projected workflow state the predicate reads as `guard.metadata.*`. Values
-   * are `Source`s resolved at deploy and re-synced by the engine. Copied data,
-   * never a cross-resource pointer.
-   */
-  metadata: z.record(NonEmpty, SourceSchema).optional()
-}).strict(), StageKindSchema = z.enum(["initial", "intermediate", "terminal", "waiting"]), StageSchema = z.object({
-  type: z.literal("workflow.stage").optional(),
-  id: NonEmpty,
-  title: z.string().optional(),
-  description: z.string().optional(),
-  kind: StageKindSchema.optional(),
-  tasks: z.array(TaskSchema).optional(),
-  transitions: z.array(TransitionSchema).optional(),
-  completion: FilterSchema.optional(),
-  onEnter: z.array(EffectSchema).optional(),
-  onExit: z.array(EffectSchema).optional(),
-  /**
-   * Lake mutation guards active while this stage holds. Each compiles to a
-   * `temp.system.guard` doc deployed on stage entry and retracted on exit.
-   * Plural because one stage's intent may span resources (one guard each).
-   */
-  guards: z.array(GuardSchema).optional(),
-  contentRefs: z.array(z.unknown()).optional(),
-  /** Stage-scoped state slots. Resolved at stage entry and persisted on
-   *  the StageEntry. */
-  state: z.array(StateSlotSchema).optional()
-}).strict(), WorkflowDefinitionShape = z.object({
-  workflowId: NonEmpty,
-  version: z.number().int().positive(),
-  title: NonEmpty,
-  description: z.string().optional(),
-  initialStageId: NonEmpty,
-  /**
-   * Workflow-level state slots. Persist for the instance lifetime.
-   * Every stage's filters/ops can read them via
-   * `*[_id == $self][0].state[key == "<key>"][0].value`. Init-sourced
-   * slots are supplied at `startInstance` via `initialState`.
-   */
-  state: z.array(StateSlotSchema).optional(),
-  stages: z.array(StageSchema).min(1, "must declare at least one stage"),
-  predicates: z.array(PredicateSchema).optional()
-}).strict(), WorkflowDefinitionSchema = WorkflowDefinitionShape.superRefine(checkWorkflowInvariants);
-function formatZodError(error, label) {
-  const lines = error.issues.map((issue) => `  - ${issue.path.length === 0 ? "(root)" : formatPath(issue.path)}: ${issue.message}`);
-  return `${label} failed validation (${error.issues.length} issue${error.issues.length === 1 ? "" : "s"}):
-${lines.join(`
-`)}`;
-}
-function formatPath(path) {
-  let out = "";
-  for (const seg of path)
-    typeof seg == "number" ? out += `[${seg}]` : out += out.length === 0 ? String(seg) : `.${String(seg)}`;
-  return out;
+function checkWorkflowInvariants(def) {
+  const issues = [], stageIds = checkStagesAndTasks(def, issues);
+  checkInitialStage(def, stageIds, issues), checkTransitionTargets(def, stageIds, issues);
+  const predicateIds = collectPredicateIds(def, issues);
+  return checkFilterRefs(def, predicateIds, issues), issues;
 }
 function defineWorkflow(definition) {
-  return parseOrThrow(
-    WorkflowDefinitionSchema,
-    definition,
-    typeof definition.workflowId == "string" ? `defineWorkflow("${definition.workflowId}")` : "defineWorkflow"
-  );
+  const workflowId = definition.workflowId, label = typeof workflowId == "string" ? `defineWorkflow("${workflowId}")` : "defineWorkflow", parsed = parseOrThrow(WorkflowDefinitionSchema, definition, label), issues = checkWorkflowInvariants(parsed);
+  if (issues.length > 0) throw new Error(formatValidationError(label, issues));
+  return parsed;
 }
 function defineStage(stage) {
   return parseOrThrow(StageSchema, stage, labelFor("defineStage", stage, "id"));
@@ -478,11 +85,11 @@ function defineAction(action) {
   return parseOrThrow(ActionSchema, action, labelFor("defineAction", action, "id"));
 }
 function defineTransition(transition) {
-  return parseOrThrow(
-    TransitionSchema,
-    transition,
-    typeof transition.id == "string" ? `defineTransition("${transition.id}")` : typeof transition.to == "string" ? `defineTransition(\u2192 "${transition.to}")` : "defineTransition"
-  );
+  return parseOrThrow(TransitionSchema, transition, transitionLabel(transition));
+}
+function transitionLabel(transition) {
+  const { id, to } = transition;
+  return typeof id == "string" ? `defineTransition("${id}")` : typeof to == "string" ? `defineTransition(\u2192 "${to}")` : "defineTransition";
 }
 function defineFilter(filter) {
   return parseOrThrow(FilterSchema, filter, "defineFilter");
@@ -501,15 +108,15 @@ function defineEffectDescriptor(descriptor) {
   return descriptor;
 }
 function parseOrThrow(schema, input, label) {
-  const result = schema.safeParse(input);
+  const result = v.safeParse(schema, input);
   if (!result.success)
-    throw new Error(formatZodError(result.error, label));
-  return result.data;
+    throw new Error(formatValidationError(label, issuesFromValibot(result.issues)));
+  return result.output;
 }
 function labelFor(fn, value, key) {
   if (value && typeof value == "object" && key in value) {
-    const v = value[key];
-    if (typeof v == "string") return `${fn}("${v}")`;
+    const raw = value[key];
+    if (typeof raw == "string") return `${fn}("${raw}")`;
   }
   return fn;
 }