@sanity/workflow-engine 0.10.0 → 0.12.0

package/dist/define.js

@@ -1,5 +1,5 @@
 import * as v from "valibot";
-import { andConditions, expandRequiredRoles, GROQ_IDENTIFIER, formatValidationError, issuesFromValibot, AuthoringWorkflowSchema, AuthoringStageSchema, AuthoringTaskSchema, AuthoringActionSchema, AuthoringTransitionSchema, AuthoringFieldEntrySchema, AuthoringOpSchema, GuardSchema, EffectSchema } from "./_chunks-es/schema.js";
+import { andConditions, expandRequiredRoles, normalizeRoleAliases, GROQ_IDENTIFIER, formatValidationError, issuesFromValibot, AuthoringWorkflowSchema, AuthoringStageSchema, AuthoringActivitySchema, AuthoringActionSchema, AuthoringTransitionSchema, AuthoringFieldEntrySchema, AuthoringOpSchema, GuardSchema, EffectSchema } from "./_chunks-es/schema.js";
 function groq(strings, ...values) {
   return strings.reduce((out, part, i) => i === 0 ? part : `${out}${serializeGroqValue(values[i - 1])}${part}`, "");
 }
@@ -12,24 +12,26 @@ function serializeGroqValue(value) {
   return serialized;
 }
 function desugarWorkflow(authoring) {
-  const ctx = {
-    issues: [],
+  const issues = [];
+  checkReservedRoleAliasKeys(authoring.roleAliases, issues);
+  const roleAliases = normalizeRoleAliases(authoring.roleAliases), ctx = {
+    issues,
     claimFields: /* @__PURE__ */ new Map(),
     claimedFields: /* @__PURE__ */ new Set(),
-    roleAliases: authoring.roleAliases
+    roleAliases
   }, workflowFields = desugarFieldEntries(authoring.fields, ["fields"], ctx), workflowLayer = layerOf(workflowFields), stages = authoring.stages.map((stage, i) => {
     const path = ["stages", i], stageFields = desugarFieldEntries(stage.fields, [...path, "fields"], ctx), stageEnv = {
       layers: [
         { scope: "stage", entries: layerOf(stageFields) },
         { scope: "workflow", entries: workflowLayer }
       ]
-    }, tasks = (stage.tasks ?? []).map(
-      (task, j) => desugarTask(task, [...path, "tasks", j], stageEnv, ctx)
+    }, activities = (stage.activities ?? []).map(
+      (activity, j) => desugarActivity(activity, [...path, "activities", j], stageEnv, ctx)
     ), transitions = (stage.transitions ?? []).map(
       (transition, k) => desugarTransition(transition, [...path, "transitions", k], stageEnv, ctx)
     ), editable = desugarStageEditable(
       stage.editable,
-      editableSlotNames(workflowFields, stageFields, tasks),
+      editableSlotNames(workflowFields, stageFields, activities),
       [...path, "editable"],
       ctx
     );
@@ -41,7 +43,7 @@ function desugarWorkflow(authoring) {
         guards: stage.guards
       }),
       ...stageFields ? { fields: stageFields } : {},
-      ...tasks.length > 0 ? { tasks } : {},
+      ...activities.length > 0 ? { activities } : {},
       ...transitions.length > 0 ? { transitions } : {},
       ...editable ? { editable } : {}
     };
@@ -49,41 +51,76 @@ function desugarWorkflow(authoring) {
   return checkUnclaimedClaimFields(ctx), { definition: {
     ...stripUndefined({
       name: authoring.name,
-      version: authoring.version,
       title: authoring.title,
       description: authoring.description,
       role: authoring.role,
       initialStage: authoring.initialStage,
       predicates: authoring.predicates,
-      roleAliases: authoring.roleAliases
+      roleAliases
     }),
     ...workflowFields ? { fields: workflowFields } : {},
     stages
   }, issues: ctx.issues };
 }
+function checkReservedRoleAliasKeys(aliases, issues) {
+  for (const key of Object.keys(aliases ?? {}))
+    key.startsWith("$") && issues.push({
+      path: ["roleAliases", key],
+      message: `role alias key "${key}" uses the reserved "$" prefix \u2014 that namespace is the engine's stored spelling for the universal fulfiller. Use "*" to mean "fulfills any gate", or rename the role.`
+    });
+}
+const TODOLIST_OF = [
+  { type: "string", name: "label", title: "Label" },
+  { type: "string", name: "status", title: "Status" },
+  { type: "assignee", name: "assignee", title: "Assignee" },
+  { type: "date", name: "dueDate", title: "Due date" }
+], NOTES_OF = [
+  { type: "text", name: "body", title: "Body" },
+  { type: "actor", name: "actor", title: "Actor" },
+  { type: "datetime", name: "at", title: "At" }
+];
 function desugarFieldEntries(entries, path, ctx) {
-  return !entries || entries.length === 0 ? entries === void 0 ? void 0 : [] : entries.map((entry, i) => {
-    if (entry.type === "claim") {
-      const desugared = {
-        ...stripUndefined({ name: entry.name, title: entry.title, description: entry.description }),
-        type: "value.actor",
-        source: { type: "write" }
-      };
-      return ctx.claimFields.set(desugared, { name: entry.name, path: [...path, i] }), desugared;
-    }
-    const editable = normalizeEditable(entry.editable, [...path, i, "editable"], ctx);
-    return {
-      ...stripUndefined({
-        type: entry.type,
-        name: entry.name,
-        title: entry.title,
-        description: entry.description,
-        required: entry.required,
-        editable
-      }),
-      source: entry.source
-    };
-  });
+  return !entries || entries.length === 0 ? entries === void 0 ? void 0 : [] : entries.map((entry, i) => desugarFieldEntry(entry, [...path, i], ctx));
+}
+function desugarFieldEntry(entry, path, ctx) {
+  if (entry.type === "claim") return desugarClaimField(entry, path, ctx);
+  if (entry.type === "todoList" || entry.type === "notes") return desugarListField(entry, path, ctx);
+  const editable = normalizeEditable(entry.editable, [...path, "editable"], ctx);
+  return {
+    ...stripUndefined({
+      type: entry.type,
+      name: entry.name,
+      title: entry.title,
+      description: entry.description,
+      required: entry.required,
+      initialValue: entry.initialValue,
+      editable,
+      fields: entry.fields,
+      of: entry.of
+    })
+  };
+}
+function desugarClaimField(entry, path, ctx) {
+  const desugared = {
+    ...stripUndefined({ name: entry.name, title: entry.title, description: entry.description }),
+    type: "actor"
+  };
+  return ctx.claimFields.set(desugared, { name: entry.name, path }), desugared;
+}
+function desugarListField(entry, path, ctx) {
+  const editable = normalizeEditable(entry.editable, [...path, "editable"], ctx);
+  return {
+    ...stripUndefined({
+      name: entry.name,
+      title: entry.title,
+      description: entry.description,
+      required: entry.required,
+      initialValue: entry.initialValue,
+      editable
+    }),
+    type: "array",
+    of: entry.type === "todoList" ? TODOLIST_OF : NOTES_OF
+  };
 }
 function normalizeEditable(editable, path, ctx) {
   if (editable === void 0 || editable === !0) return editable;
@@ -100,12 +137,12 @@ function normalizeEditable(editable, path, ctx) {
   }
   return editable;
 }
-function editableSlotNames(workflowFields, stageFields, tasks) {
+function editableSlotNames(workflowFields, stageFields, activities) {
   const names = /* @__PURE__ */ new Set(), collect = (entries) => {
     for (const entry of entries ?? []) entry.editable !== void 0 && names.add(entry.name);
   };
   collect(workflowFields), collect(stageFields);
-  for (const task of tasks) collect(task.fields);
+  for (const activity of activities) collect(activity.fields);
   return names;
 }
 function desugarStageEditable(overrides, inScope, path, ctx) {
@@ -115,7 +152,7 @@ function desugarStageEditable(overrides, inScope, path, ctx) {
     if (!inScope.has(name)) {
       ctx.issues.push({
         path: [...path, name],
-        message: `stage editable override "${name}" does not narrow an editable slot in scope \u2014 name a workflow/stage/task slot of this stage that declares \`editable\``
+        message: `stage editable override "${name}" does not narrow an editable slot in scope \u2014 name a workflow/stage/activity slot of this stage that declares \`editable\``
       });
       continue;
     }
@@ -127,35 +164,46 @@ function desugarStageEditable(overrides, inScope, path, ctx) {
 function layerOf(entries) {
   return new Map((entries ?? []).map((entry) => [entry.name, entry]));
 }
-function desugarTask(task, path, stageEnv, ctx) {
-  const taskFields = desugarFieldEntries(task.fields, [...path, "fields"], ctx), env = {
-    layers: [{ scope: "task", entries: layerOf(taskFields) }, ...stageEnv.layers]
-  }, ops = desugarOps(task.ops, [...path, "ops"], env, task.name, ctx), actions = (task.actions ?? []).map(
-    (action, a) => desugarAction(action, [...path, "actions", a], env, task.name, ctx)
-  );
+function desugarActivity(activity, path, stageEnv, ctx) {
+  const activityFields = desugarFieldEntries(activity.fields, [...path, "fields"], ctx), env = {
+    layers: [{ scope: "activity", entries: layerOf(activityFields) }, ...stageEnv.layers]
+  }, ops = desugarOps(activity.ops, [...path, "ops"], env, activity.name, ctx), actions = (activity.actions ?? []).map(
+    (action, a) => desugarAction(action, [...path, "actions", a], env, activity.name, ctx)
+  ), target = desugarTarget(activity.target, env, [...path, "target"], ctx);
   return {
     ...stripUndefined({
-      name: task.name,
-      title: task.title,
-      description: task.description,
-      filter: task.filter,
-      requirements: task.requirements,
-      completeWhen: task.completeWhen,
-      failWhen: task.failWhen,
-      effects: task.effects,
-      subworkflows: task.subworkflows
+      name: activity.name,
+      title: activity.title,
+      description: activity.description,
+      kind: activity.kind,
+      filter: activity.filter,
+      requirements: activity.requirements,
+      completeWhen: activity.completeWhen,
+      failWhen: activity.failWhen,
+      effects: activity.effects,
+      subworkflows: activity.subworkflows
     }),
-    activation: task.activation ?? "manual",
-    ...taskFields ? { fields: taskFields } : {},
+    activation: activity.activation ?? "manual",
+    ...target ? { target } : {},
+    ...activityFields ? { fields: activityFields } : {},
     ...ops ? { ops } : {},
     ...actions.length > 0 ? { actions } : {}
   };
 }
-function desugarAction(action, path, env, taskName, ctx) {
+const TARGET_DOC_KINDS = ["doc.ref", "doc.refs", "release.ref"];
+function desugarTarget(target, env, path, ctx) {
+  if (target === void 0 || target.type === "url") return target;
+  const ref = typeof target.field == "string" ? { field: target.field } : target.field, field = resolveRef(ref, env, [...path, "field"], ctx) ?? fallbackRef(ref), entry = entryAt(env, field);
+  return entry && !TARGET_DOC_KINDS.includes(entry.type) && ctx.issues.push({
+    path: [...path, "field"],
+    message: `manual activity target references "${field.field}" of kind "${entry.type}" \u2014 a deep-link target needs a document-valued entry (${TARGET_DOC_KINDS.join(", ")})`
+  }), { type: "field", field };
+}
+function desugarAction(action, path, env, activityName, ctx) {
   if ("type" in action)
     return desugarClaimAction(action, path, env, ctx);
-  const filter = andConditions([rolesCondition(action.roles, ctx.roleAliases), action.filter]), ops = desugarOps(action.ops, [...path, "ops"], env, taskName, ctx) ?? [];
-  return action.status !== void 0 && ops.push({ type: "status.set", task: taskName, status: action.status }), {
+  const filter = andConditions([rolesCondition(action.roles, ctx.roleAliases), action.filter]), ops = desugarOps(action.ops, [...path, "ops"], env, activityName, ctx) ?? [];
+  return action.status !== void 0 && ops.push({ type: "status.set", activity: activityName, status: action.status }), {
     ...stripUndefined({
       name: action.name,
       title: action.title,
@@ -171,9 +219,9 @@ function desugarClaimAction(action, path, env, ctx) {
   const ref = typeof action.field == "string" ? { field: action.field } : action.field, resolved = resolveRef(ref, env, [...path, "field"], ctx);
   if (resolved) {
     const entry = entryAt(env, resolved);
-    entry && entry.type !== "value.actor" && ctx.issues.push({
+    entry && entry.type !== "actor" && ctx.issues.push({
       path: [...path, "field"],
-      message: `claim action "${action.name}" references "${resolved.field}" of kind "${entry.type}" \u2014 a claim pair needs an actor-valued entry (a "claim" or "value.actor" field declaration)`
+      message: `claim action "${action.name}" references "${resolved.field}" of kind "${entry.type}" \u2014 a claim pair needs an actor-valued entry (a "claim" or "actor" field declaration)`
     }), checkShadowedClaimTarget(action.name, ref.field, resolved, env, [...path, "field"], ctx), entry && ctx.claimedFields.add(entry);
   }
   const noSteal = `!defined($fields.${ref.field})`, filter = andConditions([
@@ -204,7 +252,7 @@ function checkUnclaimedClaimFields(ctx) {
   for (const [entry, { name, path }] of ctx.claimFields)
     ctx.claimedFields.has(entry) || ctx.issues.push({
       path,
-      message: `claim field "${name}" is never referenced by a claim action \u2014 you announced the pattern and wrote half of it. Declare a defineAction({ type: "claim", field: "${name}" }) or use a raw value.actor entry`
+      message: `claim field "${name}" is never referenced by a claim action \u2014 you announced the pattern and wrote half of it. Declare a defineAction({ type: "claim", field: "${name}" }) or use a raw actor entry`
     });
 }
 function desugarTransition(transition, path, stageEnv, ctx) {
@@ -217,21 +265,21 @@ function desugarTransition(transition, path, stageEnv, ctx) {
       to: transition.to,
       effects: transition.effects
     }),
-    filter: transition.filter ?? "$allTasksDone",
+    filter: transition.filter ?? "$allActivitiesDone",
     ...ops ? { ops } : {}
   };
 }
-function desugarOps(ops, path, env, firingTask, ctx) {
+function desugarOps(ops, path, env, firingActivity, ctx) {
   if (ops)
-    return ops.map((op, i) => desugarOp(op, [...path, i], env, firingTask, ctx));
+    return ops.map((op, i) => desugarOp(op, [...path, i], env, firingActivity, ctx));
 }
-function desugarOp(op, path, env, firingTask, ctx) {
+function desugarOp(op, path, env, firingActivity, ctx) {
   if (op.type === "status.set") {
-    const task = op.task ?? firingTask;
-    return task === void 0 && ctx.issues.push({
-      path: [...path, "task"],
-      message: "status.set outside an action must name its target task"
-    }), { type: "status.set", task: task ?? "", status: op.status };
+    const activity = op.activity ?? firingActivity;
+    return activity === void 0 && ctx.issues.push({
+      path: [...path, "activity"],
+      message: "status.set outside an action must name its target activity"
+    }), { type: "status.set", activity: activity ?? "", status: op.status };
   }
   if (op.type === "audit") return desugarAuditOp(op, path, env, ctx);
   const target = resolveRef(op.target, env, [...path, "target"], ctx) ?? fallbackRef(op.target);
@@ -295,14 +343,14 @@ const RESERVED_CONDITION_VARS = [
   "row",
   "now",
   "effects",
-  "tasks",
+  "activities",
   "subworkflows",
   "self",
   "stage",
   "parent",
   "ancestors",
-  "allTasksDone",
-  "anyTaskFailed"
+  "allActivitiesDone",
+  "anyActivityFailed"
 ], PREDICATE_CALLER_VARS = ["actor", "assigned", "can"];
 function knownList(ids) {
   return [...ids].map((s) => `"${s}"`).join(", ");
@@ -320,12 +368,12 @@ function checkStages(def, issues) {
     issues
   );
   for (const [i, stage] of def.stages.entries()) {
-    const taskNames = checkDuplicates(
-      (stage.tasks ?? []).map((task, j) => ({
-        name: task.name,
-        path: ["stages", i, "tasks", j, "name"]
+    const activityNames = checkDuplicates(
+      (stage.activities ?? []).map((activity, j) => ({
+        name: activity.name,
+        path: ["stages", i, "activities", j, "name"]
       })),
-      `task name in stage "${stage.name}"`,
+      `activity name in stage "${stage.name}"`,
       issues
     );
     checkDuplicates(
@@ -335,34 +383,34 @@ function checkStages(def, issues) {
       })),
       `transition name in stage "${stage.name}"`,
       issues
-    ), checkTasks(def, i, taskNames, issues);
+    ), checkActivities(def, i, activityNames, issues);
   }
   return stageNames;
 }
-function checkTasks(def, i, taskNames, issues) {
+function checkActivities(def, i, activityNames, issues) {
   const stage = def.stages[i];
-  for (const [j, task] of (stage.tasks ?? []).entries()) {
-    const path = ["stages", i, "tasks", j];
+  for (const [j, activity] of (stage.activities ?? []).entries()) {
+    const path = ["stages", i, "activities", j];
     checkDuplicates(
-      (task.actions ?? []).map((action, a) => ({
+      (activity.actions ?? []).map((action, a) => ({
         name: action.name,
         path: [...path, "actions", a, "name"]
       })),
-      `action name in task "${task.name}"`,
+      `action name in activity "${activity.name}"`,
       issues
-    ), checkStatusSetTargets(task, taskNames, path, issues);
+    ), checkStatusSetTargets(activity, activityNames, path, issues);
   }
 }
-function checkStatusSetTargets(task, taskNames, path, issues) {
-  checkStatusSetOps(task.ops, taskNames, [...path, "ops"], issues);
-  for (const [a, action] of (task.actions ?? []).entries())
-    checkStatusSetOps(action.ops, taskNames, [...path, "actions", a, "ops"], issues);
+function checkStatusSetTargets(activity, activityNames, path, issues) {
+  checkStatusSetOps(activity.ops, activityNames, [...path, "ops"], issues);
+  for (const [a, action] of (activity.actions ?? []).entries())
+    checkStatusSetOps(action.ops, activityNames, [...path, "actions", a, "ops"], issues);
 }
-function checkStatusSetOps(ops, taskNames, path, issues) {
+function checkStatusSetOps(ops, activityNames, path, issues) {
   for (const [o, op] of (ops ?? []).entries())
-    op.type !== "status.set" || taskNames.has(op.task) || issues.push({
-      path: [...path, o, "task"],
-      message: `status.set targets task "${op.task}" which is not declared in this stage. Known tasks: ${knownList(taskNames)}`
+    op.type !== "status.set" || activityNames.has(op.activity) || issues.push({
+      path: [...path, o, "activity"],
+      message: `status.set targets activity "${op.activity}" which is not declared in this stage. Known activities: ${knownList(activityNames)}`
     });
 }
 function checkInitialStage(def, stageNames, issues) {
@@ -382,10 +430,14 @@ function checkTransitionTargets(def, stageNames, issues) {
 function checkEffectNames(def, issues) {
   const sites = [];
   for (const [i, stage] of def.stages.entries()) {
-    for (const [j, task] of (stage.tasks ?? []).entries()) {
-      collectEffects(task.effects, ["stages", i, "tasks", j, "effects"], sites);
-      for (const [a, action] of (task.actions ?? []).entries())
-        collectEffects(action.effects, ["stages", i, "tasks", j, "actions", a, "effects"], sites);
+    for (const [j, activity] of (stage.activities ?? []).entries()) {
+      collectEffects(activity.effects, ["stages", i, "activities", j, "effects"], sites);
+      for (const [a, action] of (activity.actions ?? []).entries())
+        collectEffects(
+          action.effects,
+          ["stages", i, "activities", j, "actions", a, "effects"],
+          sites
+        );
     }
     for (const [k, t] of (stage.transitions ?? []).entries())
       collectEffects(t.effects, ["stages", i, "transitions", k, "effects"], sites);
@@ -420,12 +472,12 @@ function fieldScopes(def) {
       path: ["stages", i, "fields"],
       label: `stage "${stage.name}" fields`
     });
-    for (const [j, task] of (stage.tasks ?? []).entries())
+    for (const [j, activity] of (stage.activities ?? []).entries())
       scopes.push({
-        entries: task.fields,
-        scope: "task",
-        path: ["stages", i, "tasks", j, "fields"],
-        label: `task "${task.name}" fields`
+        entries: activity.fields,
+        scope: "activity",
+        path: ["stages", i, "activities", j, "fields"],
+        label: `activity "${activity.name}" fields`
       });
   }
   return scopes;
@@ -433,13 +485,20 @@ function fieldScopes(def) {
 function checkRequiredField(def, issues) {
   for (const { entries, scope, path, label } of fieldScopes(def))
     for (const [n, entry] of (entries ?? []).entries())
-      entry.required === !0 && (scope !== "workflow" ? issues.push({
-        path: [...path, n, "required"],
-        message: `${label} entry "${entry.name}" is \`required\`, but \`required\` applies only to workflow-scope \`init\` entries \u2014 only those are caller-supplied at start/spawn`
-      }) : entry.source.type !== "init" && issues.push({
-        path: [...path, n, "required"],
-        message: `field entry "${entry.name}" is \`required\` but its source is "${entry.source.type}" \u2014 \`required\` applies only to \`init\`-sourced entries (the caller fills them at start/spawn)`
-      }));
+      if (entry.required === !0) {
+        if (scope !== "workflow")
+          issues.push({
+            path: [...path, n, "required"],
+            message: `${label} entry "${entry.name}" is \`required\`, but \`required\` applies only to workflow-scope \`input\` entries \u2014 only those are caller-supplied at start/spawn`
+          });
+        else if (entry.initialValue?.type !== "input") {
+          const seed = entry.initialValue?.type ?? "working memory (no initialValue)";
+          issues.push({
+            path: [...path, n, "required"],
+            message: `field entry "${entry.name}" has initialValue "${seed}" \u2014 \`required\` applies only to \`input\`-sourced entries (the caller fills them at start/spawn)`
+          });
+        }
+      }
 }
 function checkFieldEntryNames(def, issues) {
   for (const { entries, path, label } of fieldScopes(def))
@@ -495,34 +554,34 @@ function nonActionFilterConditionSites(def) {
         `transition "${t.name}"`,
         sites
       );
-    for (const [j, task] of (stage.tasks ?? []).entries())
-      collectTaskConditionSites(task, ["stages", i, "tasks", j], sites);
+    for (const [j, activity] of (stage.activities ?? []).entries())
+      collectActivityConditionSites(activity, ["stages", i, "activities", j], sites);
   }
   return sites;
 }
-function collectTaskConditionSites(task, path, sites) {
+function collectActivityConditionSites(activity, path, sites) {
   for (const field of ["filter", "completeWhen", "failWhen"]) {
-    const groq2 = task[field];
-    groq2 !== void 0 && sites.push({ groq: groq2, path: [...path, field], label: `task "${task.name}".${field}` });
+    const groq2 = activity[field];
+    groq2 !== void 0 && sites.push({ groq: groq2, path: [...path, field], label: `activity "${activity.name}".${field}` });
   }
-  collectBindingSites(task.effects, [...path, "effects"], `task "${task.name}"`, sites);
-  for (const [a, action] of (task.actions ?? []).entries())
+  collectBindingSites(activity.effects, [...path, "effects"], `activity "${activity.name}"`, sites);
+  for (const [a, action] of (activity.actions ?? []).entries())
     collectBindingSites(
       action.effects,
       [...path, "actions", a, "effects"],
       `action "${action.name}"`,
       sites
     );
-  collectSubworkflowSites(task, path, sites);
+  collectSubworkflowSites(activity, path, sites);
 }
-function collectSubworkflowSites(task, path, sites) {
-  const sub = task.subworkflows;
+function collectSubworkflowSites(activity, path, sites) {
+  const sub = activity.subworkflows;
   if (sub === void 0) return;
   const subPath = [...path, "subworkflows"];
   sites.push({
     groq: sub.forEach,
     path: [...subPath, "forEach"],
-    label: `task "${task.name}".subworkflows.forEach`
+    label: `activity "${activity.name}".subworkflows.forEach`
   });
   for (const [group, record] of [
     ["with", sub.with],
@@ -532,7 +591,7 @@ function collectSubworkflowSites(task, path, sites) {
       sites.push({
         groq: groq2,
         path: [...subPath, group, key],
-        label: `task "${task.name}".subworkflows.${group} "${key}"`
+        label: `activity "${activity.name}".subworkflows.${group} "${key}"`
       });
 }
 function collectBindingSites(effects, path, label, sites) {
@@ -551,9 +610,49 @@ function checkAssigneesEntries(def, issues) {
       message: "at most one assignees-kind field entry per scope \u2014 the inbox reads it by kind"
     });
 }
+function activityShape(activity) {
+  return {
+    hasActions: (activity.actions ?? []).length > 0,
+    hasEffects: (activity.effects ?? []).length > 0,
+    hasCompleteWhen: activity.completeWhen !== void 0,
+    hasSubworkflows: activity.subworkflows !== void 0
+  };
+}
+const KIND_SHAPE_RULES = {
+  user: (s) => s.hasActions ? [] : ["needs at least one action for a person to fire"],
+  service: (s) => s.hasEffects ? [] : ["needs at least one effect \u2014 the automated work it performs"],
+  manual: (s) => [
+    s.hasActions || s.hasCompleteWhen ? void 0 : "needs a way to complete \u2014 an action to acknowledge it, or a `completeWhen` predicate to verify it (otherwise it auto-resolves on activation)",
+    s.hasSubworkflows ? "is off-system work, not a fan-out \u2014 drop `subworkflows` or move it to its own activity" : void 0
+  ].filter((m) => m !== void 0),
+  receive: (s) => [
+    s.hasCompleteWhen || s.hasSubworkflows ? void 0 : "needs a `completeWhen` (or `subworkflows`) condition to wait on",
+    s.hasActions ? "has no actor, so it cannot carry actions" : void 0
+  ].filter((m) => m !== void 0),
+  script: (s) => [
+    s.hasActions ? "runs inline with no actor, so it cannot carry actions" : void 0,
+    s.hasCompleteWhen ? "resolves on activation, so it cannot carry a `completeWhen` (that is a `receive`/`service` wait)" : void 0,
+    s.hasSubworkflows ? "resolves on activation, so it cannot fan out with `subworkflows`" : void 0
+  ].filter((m) => m !== void 0)
+};
+function checkActivityKinds(def, issues) {
+  for (const [i, stage] of def.stages.entries())
+    for (const [j, activity] of (stage.activities ?? []).entries()) {
+      const path = ["stages", i, "activities", j];
+      if (activity.target !== void 0 && activity.kind !== "manual" && issues.push({
+        path: [...path, "target"],
+        message: `activity "${activity.name}" has a \`target\` but is not \`kind: "manual"\` \u2014 a target is the deep-link for off-system manual work`
+      }), activity.kind !== void 0)
+        for (const fault of KIND_SHAPE_RULES[activity.kind](activityShape(activity)))
+          issues.push({
+            path: [...path, "kind"],
+            message: `activity "${activity.name}" declares kind "${activity.kind}" but ${fault}`
+          });
+    }
+}
 function checkWorkflowInvariants(def) {
   const issues = [], stageNames = checkStages(def, issues);
-  return checkInitialStage(def, stageNames, issues), checkTransitionTargets(def, stageNames, issues), checkEffectNames(def, issues), checkGuardNames(def, issues), checkFieldEntryNames(def, issues), checkRequiredField(def, issues), checkPredicates(def, issues), checkCanOutsideActionFilters(def, issues), checkAssigneesEntries(def, issues), issues;
+  return checkInitialStage(def, stageNames, issues), checkTransitionTargets(def, stageNames, issues), checkEffectNames(def, issues), checkGuardNames(def, issues), checkFieldEntryNames(def, issues), checkRequiredField(def, issues), checkPredicates(def, issues), checkCanOutsideActionFilters(def, issues), checkAssigneesEntries(def, issues), checkActivityKinds(def, issues), issues;
 }
 function defineWorkflow(definition) {
   const label = labelFor("defineWorkflow", definition), parsed = parseOrThrow(AuthoringWorkflowSchema, definition, label), { definition: stored, issues: desugarIssues } = desugarWorkflow(parsed), issues = [...desugarIssues, ...checkWorkflowInvariants(stored)];
@@ -563,8 +662,8 @@ function defineWorkflow(definition) {
 function defineStage(stage) {
   return parseOrThrow(AuthoringStageSchema, stage, labelFor("defineStage", stage));
 }
-function defineTask(task) {
-  return parseOrThrow(AuthoringTaskSchema, task, labelFor("defineTask", task));
+function defineActivity(activity) {
+  return parseOrThrow(AuthoringActivitySchema, activity, labelFor("defineActivity", activity));
 }
 function defineAction(action) {
   return parseOrThrow(AuthoringActionSchema, action, labelFor("defineAction", action));
@@ -607,13 +706,13 @@ function labelFor(fn, value) {
 }
 export {
   defineAction,
+  defineActivity,
   defineEffect,
   defineEffectDescriptor,
   defineField,
   defineGuard,
   defineOp,
   defineStage,
-  defineTask,
   defineTransition,
   defineWorkflow,
   groq