@sanoma-ai/workflows 0.2.0 → 0.4.1

package/src/scenario.ts

@@ -13,6 +13,7 @@ import {
 } from "@cucumber/messages";
 import type { z } from "zod";
 import type { RunSummary, SanomaClient } from "./client.ts";
+import type { Approver } from "./define.ts";
 import type { ResolvedConfig } from "./config.ts";
 import {
   buildLibrary,
@@ -25,22 +26,30 @@ import {
   stepResults,
   StepStatus,
 } from "./cucumber.ts";
-import { errorInfo, SanomaError } from "./errors.ts";
+import { errorCode, errorInfo, SanomaError } from "./errors.ts";
 import { type CallRecord, contains, type CoreExpectation, detailOf, isCall } from "./expectations.ts";
 import type { Fake } from "./fake.ts";
-import { fill, isBug, seedFrom, shapeOf } from "./fill.ts";
+import { fill, isBug, objectUnder, restOf, seedFrom, shapeOf } from "./fill.ts";
 import type { LedgerRecord } from "./ledger.ts";
 import type { Driver, Op } from "./op.ts";
 import { type OutlineNode, outlineWorkflow } from "./outline.ts";
+import { isObject } from "./resource.ts";
+import { admit, type DeclaredPeople, readPeople } from "./resources.ts";
 import { memorySecrets } from "./secret.ts";
 import {
   APPLY_WORKFLOW,
   BUILT_IN_WORKFLOWS,
+  DATA_VENDOR,
+  declaresPeople,
   DRIFT_WORKFLOW,
   errorMessage,
   fitsOp,
   flatten,
+  groupNamesOf,
   isEnded,
+  principalIdsOf,
+  problemLine,
+  RUNTIME_AGENTS,
 } from "./shared.ts";
 import type { Call, RunView, Seed } from "./steps.ts";
 
@@ -98,9 +107,11 @@ export interface Decision {
 /**
  * What the run should do: call an operation (with at least this input) or not, run the step
  * `name`d in the workflow's outline or not, or a number of `times`, have the policy deny an
- * operation (`denied`) or hold one for an approver (`held`), end a certain way, for a drift
- * run, report the resource `declared` (`<file>#<export>`) clean, gone, absent, or drifted in a
- * field, or for an apply run, create it, or leave it bound to an object (`bound`, its vendor's id).
+ * operation (`denied`, for a `reason` when the step names one) or hold one for an approver
+ * (`held`: a person's id or a group's name, or `{ group }` a group's alone), end a certain way,
+ * for a drift run, report the resource `declared` (`<file>#<export>`) clean, gone, absent, or
+ * drifted in a field, or for an apply run, create it, or leave it bound to an object (`bound`,
+ * its vendor's id).
  * A step whose own code checks the run (a connector's or the company's, or an operation's own
  * test's) is `custom`, with what it is about.
  */
@@ -108,8 +119,8 @@ export type Expectation =
   | { step: string; op: string; input?: unknown; called: boolean }
   | { step: string; name: string; input?: unknown; called: boolean }
   | { step: string; name: string; times: number }
-  | { step: string; op: string; decision: "denied" }
-  | { step: string; op: string; decision: "held"; approver: string }
+  | { step: string; op: string; decision: "denied"; reason?: string }
+  | { step: string; op: string; decision: "held"; approver: Approver }
   | { step: string; outcome: "finished" | "failed"; code?: string }
   | { step: string; declared: string; status: "clean" | "gone" | "absent" }
   | { step: string; declared: string; status: "drifted"; field: string }
@@ -132,6 +143,8 @@ export interface Scenario {
   text: string;
   /** Every step in order, for a list and for marking graph nodes. */
   steps: ScenarioStep[];
+  /** Who starts the run, by id, when a `Given <who> is acting` says: a declared person or agent. */
+  startedBy?: string;
   given: Given[];
   input: unknown;
   decisions: Decision[];
@@ -152,10 +165,14 @@ export interface Check {
 }
 
 /**
- * What steps can name: the config's operations, workflows and resource types by id, the steps
- * its connectors (and the company) ship, and where the feature files are.
+ * What steps can name: the config's operations, workflows, resource types and collections by id,
+ * the steps its connectors (and the company) ship, where the feature files are, and the root
+ * whose data files declare its people.
  */
-export type Scope = Pick<ResolvedConfig, "ops" | "workflows" | "scenarios" | "types" | "steps">;
+export type Scope = Pick<
+  ResolvedConfig,
+  "ops" | "workflows" | "scenarios" | "types" | "collections" | "steps" | "root"
+>;
 
 type Kind = ScenarioStep["kind"];
 type Fault = Extract<Seed, { fault: unknown }>["fault"];
@@ -170,9 +187,13 @@ interface Then {
   verify(run: RunView): string | undefined;
 }
 
-/** What a step of each kind reads into; `any` is a decision, which a step of any keyword may make. */
+/**
+ * What a step of each kind reads into; `any` is a decision, which a step of any keyword may make,
+ * and `actor` a `Given` saying who starts the run (`{who} is acting`), by id.
+ */
 interface Items {
   given: Unstepped<Given>[];
+  actor: string;
   when: When;
   then: Then;
   any: Unstepped<Decision>;
@@ -209,22 +230,50 @@ const FAULTS = {
   "loses its reply once": "loseReply",
 } as const;
 
-/** The schema of the field `name` of an object schema (`owner`, for the error); throws naming the fields it has. */
+/**
+ * The schema of the field `name` of an object schema (`owner`, for the error), or of the fields it
+ * takes besides its own (`restOf`); throws naming the fields it has.
+ */
 function fieldOf(schema: z.ZodType, name: string, owner: string): z.ZodType {
   const shape = shapeOf(schema);
-  if (!Object.hasOwn(shape, name)) {
-    throw new Error(`no field "${name}" in ${owner}; it has ${Object.keys(shape).join(", ") || "none"}`);
-  }
-  return shape[name]!;
+  if (Object.hasOwn(shape, name)) return shape[name]!;
+  const rest = restOf(schema);
+  if (rest) return rest;
+  throw new Error(`no field "${name}" in ${owner}; it has ${Object.keys(shape).join(", ") || "none"}`);
 }
 
 const issues = (error: z.ZodError) => error.issues.map((i) => i.message).join("; ");
 
+/**
+ * Why `field` refuses `value`, or undefined when it takes it. `partial`, for what a `Then` expects
+ * at least: an object may leave fields out at any depth, and only the fields it has are checked.
+ */
+function refusal(field: z.ZodType, value: unknown, what: string, partial: boolean): string | undefined {
+  const object = partial && isObject(value) ? objectUnder(field) : undefined;
+  if (object) return fieldsRefusal(object, value as Record<string, unknown>, what, true);
+  const parsed = field.safeParse(value);
+  return parsed.success ? undefined : `${what} cannot be ${JSON.stringify(value)}: ${issues(parsed.error)}`;
+}
+
+/** Why the object schema refuses the first of `fields` it refuses (`refusal`), `owner` its owner in errors. */
+function fieldsRefusal(
+  schema: z.ZodType,
+  fields: Record<string, unknown>,
+  owner: string,
+  partial: boolean,
+): string | undefined {
+  for (const [name, v] of Object.entries(fields)) {
+    const why = refusal(fieldOf(schema, name, owner), v, `${name} in ${owner}`, partial);
+    if (why) return why;
+  }
+  return undefined;
+}
+
 /**
  * The value text from a table cell or a phrase gives a field: the text itself when the field
  * takes it, else the text read as JSON (a number, `true`, a list) when the field takes that.
  */
-function valueFor(field: z.ZodType, text: string, what: string): unknown {
+function valueFor(field: z.ZodType, text: string, what: string, partial = false): unknown {
   const asText = field.safeParse(text);
   if (asText.success) return text;
   let json: unknown;
@@ -233,17 +282,18 @@ function valueFor(field: z.ZodType, text: string, what: string): unknown {
   } catch {
     throw new Error(`${what} cannot be ${JSON.stringify(text)}: ${issues(asText.error)}`);
   }
-  const asJson = field.safeParse(json);
-  if (!asJson.success) throw new Error(`${what} cannot be ${text}: ${issues(asJson.error)}`);
+  const why = refusal(field, json, what, partial);
+  if (why) throw new Error(why);
   return json;
 }
 
 /**
  * The fields the step's doc string (a JSON object) or two-column table gives `owner` (an
  * operation's input, or a resource), each checked against its field in `schema`: a field it
- * lacks, or a value it refuses, is an error.
+ * lacks, or a value it refuses, is an error. `partial` (a `Then`'s "at least these fields"):
+ * an object value may leave fields out, at any depth.
  */
-function fieldsFrom(pickle: PickleStep, schema: z.ZodType, owner: string): Record<string, unknown> {
+function fieldsFrom(pickle: PickleStep, schema: z.ZodType, owner: string, partial = false): Record<string, unknown> {
   const { docString, dataTable } = pickle.argument ?? {};
   const what = (name: string) => `${name} in ${owner}`;
   if (dataTable) {
@@ -251,7 +301,7 @@ function fieldsFrom(pickle: PickleStep, schema: z.ZodType, owner: string): Recor
       dataTable.rows.map(({ cells }) => {
         if (cells.length !== 2) throw new Error(`the table after "${pickle.text}" needs two columns: name | value`);
         const [name, text] = cells.map((c) => c.value) as [string, string];
-        return [name, valueFor(fieldOf(schema, name, owner), text, what(name))];
+        return [name, valueFor(fieldOf(schema, name, owner), text, what(name), partial)];
       }),
     );
   }
@@ -262,14 +312,10 @@ function fieldsFrom(pickle: PickleStep, schema: z.ZodType, owner: string): Recor
   } catch (err) {
     throw new Error(`the doc string after "${pickle.text}" is not JSON: ${errorMessage(err)}`, { cause: err });
   }
-  if (typeof value !== "object" || value === null || Array.isArray(value)) {
-    throw new Error(`"${pickle.text}" needs a JSON object`);
-  }
-  for (const [name, v] of Object.entries(value)) {
-    const parsed = fieldOf(schema, name, owner).safeParse(v);
-    if (!parsed.success) throw new Error(`${what(name)} cannot be ${JSON.stringify(v)}: ${issues(parsed.error)}`);
-  }
-  return value as Record<string, unknown>;
+  if (!isObject(value)) throw new Error(`"${pickle.text}" needs a JSON object`);
+  const why = fieldsRefusal(schema, value, owner, partial);
+  if (why) throw new Error(why);
+  return value;
 }
 
 /** A parameter's transform: the name, when `ids` has it. */
@@ -314,7 +360,9 @@ function builtFor(scope: Scope): Built {
     cached &&
     cached.scope.workflows === scope.workflows &&
     cached.scope.types === scope.types &&
-    cached.scope.steps === scope.steps
+    cached.scope.collections === scope.collections &&
+    cached.scope.steps === scope.steps &&
+    cached.scope.root === scope.root
   ) {
     return cached;
   }
@@ -333,24 +381,59 @@ const expecting = (expect: CoreExpectation): Then => ({ expect, verify: (run) =>
 
 /** The rules a scope has, and the parameter types their expressions use. */
 function rulesOf(scope: Scope): { rules: Rule[]; parameterTypes: ParameterTypeSpec[] } {
-  const { types } = scope;
+  const { types, collections } = scope;
+  // A collection's records are seeded as a resource's objects are, by `data.<name>`, through its operations.
+  const collectionOf = (id: unknown) =>
+    (id as string).startsWith(`${DATA_VENDOR}.`)
+      ? collections.get((id as string).slice(DATA_VENDOR.length + 1))
+      : undefined;
+  const seedable = new Map<string, unknown>([
+    ...types,
+    ...[...collections.keys()].map((n) => [`${DATA_VENDOR}.${n}`, n] as const),
+  ]);
   const parameterTypes: ParameterTypeSpec[] = [
     { name: "op", regexp: /\S+/, transformer: known("operation", scope.ops) },
     { name: "workflow", regexp: /\S+/, transformer: known("workflow", scope.workflows) },
     { name: "who", regexp: /\S+/, transformer: (s) => s },
-    { name: "resource", regexp: /\S+/, transformer: known("resource type", types) },
+    { name: "resource", regexp: /\S+/, transformer: known("resource type", seedable) },
     // A declared resource, as a drift report names it: `<file>#<export>`.
     { name: "declared", regexp: /[^\s#]+#\S+/, transformer: (s) => s },
     { name: "field", regexp: /\S+/, transformer: (s) => s },
   ];
   const opOf = (id: unknown) => scope.ops.get(id as string)!;
   const workflowOf = (name: unknown) => scope.workflows.get(name as string)!;
+  // The people as the root's data files declare them when a step names one (`readPeople`, read
+  // again only once a file changed): while they declare no one, any id and any group go.
+  /** `who`, as a run's start admits them (`admit`): a declared person or agent. */
+  const actorNamed = (who: string) => {
+    const declared = readPeople(scope.root);
+    try {
+      return admit({ id: who }, declared).id;
+    } catch (err) {
+      if (errorCode(err) !== "not_admitted" || declared.problems.length) throw err;
+      const ids = [...principalIdsOf(declared.people), ...RUNTIME_AGENTS].join(", ");
+      throw new Error(`${who} is not a declared person or agent; resources/ declares ${ids}`, { cause: err });
+    }
+  };
+  /** `group`, a declared group or `agents`, while the people's files have no problems. */
+  const groupNamed = (group: string) => {
+    const { people, problems } = readPeople(scope.root);
+    if (problems.length) {
+      throw new Error(
+        `no group can be told while the people's files have problems: ${problems.map(problemLine).join("; ")}`,
+      );
+    }
+    const groups = groupNamesOf(people);
+    if (!declaresPeople(people) || groups.includes(group)) return group;
+    throw new Error(`no group "${group}"; resources/ declares ${groups.join(", ")}`);
+  };
   /** A resource step's object: its type's id, vendor and type, and its import id. */
   const object = (id: unknown, name: unknown) => {
     const { vendor, type } = types.get(id as string)!;
     return { resource: id as string, vendor, type, name: name as string };
   };
   const rules: Rule[] = [
+    { kind: "actor", source: "{who} is acting", read: ([who]) => actorNamed(who as string) },
     {
       kind: "given",
       source: "{op} was called with",
@@ -368,21 +451,32 @@ function rulesOf(scope: Scope): { rules: Rule[]; parameterTypes: ParameterTypeSp
       kind: "given",
       source: "{resource} {string} has",
       takes: TAKES_OBJECT,
-      read: ([resource, name], pickle) => [
-        {
-          ...object(resource, name),
-          fields: fieldsFrom(
-            pickle,
-            types.get(resource as string)!.schema,
-            `${resource as string} "${name as string}"`,
-          ),
-        },
-      ],
+      read: ([resource, name], pickle) => {
+        const owner = `${resource as string} "${name as string}"`;
+        const c = collectionOf(resource);
+        if (c) {
+          // The record with its key, the fields the step gives, and the rest made up.
+          const record = shapeOf(opOf(c.save.id).input).record!;
+          const fields = fieldsFrom(pickle, record, owner);
+          if (Object.hasOwn(fields, c.key) && fields[c.key] !== name) {
+            throw new Error(
+              `${c.key} in ${owner} is ${JSON.stringify(fields[c.key])}: it is the key, "${name as string}"`,
+            );
+          }
+          return [{ op: c.save.id, input: { record: fill(record, { ...fields, [c.key]: name }) } }];
+        }
+        return [
+          { ...object(resource, name), fields: fieldsFrom(pickle, types.get(resource as string)!.schema, owner) },
+        ];
+      },
     },
     {
       kind: "given",
       source: "{resource} {string} is gone",
-      read: ([resource, name]) => [{ ...object(resource, name), gone: true }],
+      read: ([resource, name]) => {
+        const c = collectionOf(resource);
+        return [c ? { op: c.delete.id, input: { key: name } } : { ...object(resource, name), gone: true }];
+      },
     },
     {
       kind: "when",
@@ -436,7 +530,7 @@ function rulesOf(scope: Scope): { rules: Rule[]; parameterTypes: ParameterTypeSp
       source: "{op} was called with",
       takes: TAKES_OBJECT,
       read: ([op], pickle) =>
-        expecting({ op: op as string, input: fieldsFrom(pickle, opOf(op).input, inputOf(op)), called: true }),
+        expecting({ op: op as string, input: fieldsFrom(pickle, opOf(op).input, inputOf(op), true), called: true }),
     },
     ...[true, false].map((called): Rule => ({
       kind: "then",
@@ -448,11 +542,22 @@ function rulesOf(scope: Scope): { rules: Rule[]; parameterTypes: ParameterTypeSp
       source: "{op} was denied",
       read: ([op]) => expecting({ op: op as string, decision: "denied" }),
     },
+    {
+      kind: "then",
+      source: "{op} was denied with {string}",
+      read: ([op, reason]) => expecting({ op: op as string, decision: "denied", reason: reason as string }),
+    },
     {
       kind: "then",
       source: "{op} was held for {who}",
       read: ([op, who]) => expecting({ op: op as string, decision: "held", approver: who as string }),
     },
+    {
+      kind: "then",
+      source: "{op} was held for group {string}",
+      read: ([op, group]) =>
+        expecting({ op: op as string, decision: "held", approver: { group: groupNamed(group as string) } }),
+    },
     {
       kind: "then",
       source: "step {string} was called with",
@@ -466,7 +571,11 @@ function rulesOf(scope: Scope): { rules: Rule[]; parameterTypes: ParameterTypeSp
         // An unnamed call with a computed segment is named by the operation it calls.
         const op = scope.ops.get(node.id) ?? (node.name === undefined ? scope.ops.get(name as string) : undefined);
         if (!op) throw new Error(`${step} calls ${node.id}, whose input cannot be read: name its operation in full`);
-        return expecting({ name: name as string, input: fieldsFrom(pickle, op.input, inputOf(op.id)), called: true });
+        return expecting({
+          name: name as string,
+          input: fieldsFrom(pickle, op.input, inputOf(op.id), true),
+          called: true,
+        });
       },
     },
     ...[true, false].map((called): Rule => ({
@@ -524,7 +633,7 @@ function rulesOf(scope: Scope): { rules: Rule[]; parameterTypes: ParameterTypeSp
           const last = lastCall(records);
           if (typeof last === "string") return last;
           if (last.error) return `it failed: ${last.error.code ?? last.error.name}: ${last.error.message}`;
-          const expected = fieldsFrom(pickle, opOf(last.op).output, `${last.op}'s output`);
+          const expected = fieldsFrom(pickle, opOf(last.op).output, `${last.op}'s output`, true);
           return contains(last.output, expected) ? undefined : `it returned ${JSON.stringify(last.output)}`;
         },
       }),
@@ -628,9 +737,13 @@ function rulesOf(scope: Scope): { rules: Rule[]; parameterTypes: ParameterTypeSp
           transformer: (...g) => field(g),
         });
       }
+      // An `expect` phrase, like `was called with`, may give some of an object's fields.
       const given = (values: unknown[]) =>
         Object.fromEntries(
-          fields.map((name, i) => [name, valueFor(schemas[i]!, values[i] as string, `${name} in ${inputOf(op.id)}`)]),
+          fields.map((name, i) => [
+            name,
+            valueFor(schemas[i]!, values[i] as string, `${name} in ${inputOf(op.id)}`, kind === "then"),
+          ]),
         );
       const common = { source: template, group: op.id, expression: template.replaceAll(/\{([^}]*)\}/g, "{field_$1}") };
       rules.push(
@@ -650,7 +763,8 @@ function lastCall(records: readonly LedgerRecord[]): CallRecord | string {
 
 /** Every step the scope knows, for an error: the generic ones by keyword, then each operation's phrases and each step library's steps under its name. */
 function knownSteps(rules: Rule[]): string {
-  const keyword = (kind: Rule["kind"]) => (kind === "any" ? "Given/When/Then" : kind[0]!.toUpperCase() + kind.slice(1));
+  const keyword = (kind: Rule["kind"]) =>
+    kind === "any" ? "Given/When/Then" : kind === "actor" ? "Given" : kind[0]!.toUpperCase() + kind.slice(1);
   const line = (r: Rule) => `${keyword(r.kind)} ${r.source}${r.takes ? ` (and ${r.takes})` : ""}`;
   const { generic = [], ...groups } = Object.groupBy(rules, (r) => r.group ?? "generic");
   return [
@@ -804,7 +918,9 @@ const ambiguous = (text: string, sources: string[]) =>
 function ruleFor(built: Built, expression: string, pickle: PickleStep): Rule {
   const kind = pickle.type && KINDS[pickle.type];
   if (!kind) throw new Error(`"${pickle.text}" needs a Given, When or Then before it`);
-  const rules = built.byExpression.get(expression)!.filter((r) => r.kind === kind || r.kind === "any");
+  const rules = built.byExpression
+    .get(expression)!
+    .filter((r) => r.kind === kind || r.kind === "any" || (r.kind === "actor" && kind === "given"));
   if (rules.length === 0) throw new Error(noMatch(built, pickle.text));
   if (rules.length > 1)
     throw new Error(
@@ -837,6 +953,11 @@ function compileWorld(built: Built, specs: Map<string, Spec>) {
         const { text } = pickle;
         const step: ScenarioStep = { text, kind: KINDS[pickle.type!]! };
         switch (rule.kind) {
+          case "actor":
+            if (spec.startedBy !== undefined)
+              throw new Error(`${spec.startedBy} is acting already: a run has one actor`);
+            spec.startedBy = rule.read(args, pickle);
+            break;
           case "given": {
             const items = rule.read(args, pickle);
             spec.given.push(...items.map((item) => ({ step: text, ...item }) as Given));
@@ -988,6 +1109,8 @@ function testWorld(built: Built, { driver, fake }: FeatureTarget) {
             throw new Error(
               `"${text}" decides an approval: a step for a scenario in scenarios/, not an operation's own test`,
             );
+          case "actor":
+            throw new Error(`"${text}" says who starts a run: a step for a scenario in scenarios/`);
           case "then": {
             const detail = rule.read(args, pickle).verify(viewOf(records));
             if (detail !== undefined) throw new Error(detail);
@@ -1179,18 +1302,22 @@ async function compile(scope: Scope, dir: string, files: string[]): Promise<Load
 }
 
 /**
- * Each scope's scenarios as last read, with the stamp of the files they were read from. By
- * scope, since what a file means depends on its operations and workflows.
+ * Each scope's scenarios as last read, with the stamp of the files they were read from and the
+ * people they were checked against (`readPeople`'s answer, the same object until a data file
+ * changes). By scope, since what a file means depends on its operations and workflows.
  */
-const loadedByScope = new WeakMap<Scope, { stamp: string; loaded: Promise<LoadedScenarios> }>();
+const loadedByScope = new WeakMap<
+  Scope,
+  { stamp: string; people: DeclaredPeople | undefined; loaded: Promise<LoadedScenarios> }
+>();
 
 /**
  * Every scenario in the `.feature` files under `scenarios` (a `file:` URL to a directory),
  * compiled by Cucumber, with an error for each file that does not compile and each name used
  * twice. No directory, or none given, is no scenarios. Rejects when an operation's phrase names
  * a field it lacks. The files are compiled again only once one is added, removed or written
- * (its name, `mtimeMs` or size changes): until then each call returns the same object, which
- * callers must not change.
+ * (its name, `mtimeMs` or size changes), or the people's data files change: until then each
+ * call returns the same object, which callers must not change.
  */
 export async function loadScenarios(scope: Scope): Promise<LoadedScenarios> {
   if (!scope.scenarios) return { scenarios: [], errors: [] };
@@ -1206,10 +1333,12 @@ export async function loadScenarios(scope: Scope): Promise<LoadedScenarios> {
       return [file, mtimeMs, size];
     }),
   ]);
+  // None without a root, which declares no one.
+  const people = scope.root === undefined ? undefined : readPeople(scope.root);
   const cached = loadedByScope.get(scope);
-  if (cached?.stamp === stamp) return cached.loaded;
+  if (cached?.stamp === stamp && cached.people === people) return cached.loaded;
   const loaded = files.length ? compile(scope, dir, files) : Promise.resolve({ scenarios: [], errors: [] });
-  loadedByScope.set(scope, { stamp, loaded });
+  loadedByScope.set(scope, { stamp, people, loaded });
   // A compile that throws (a bug) is not kept: the next call tries again.
   loaded.catch(() => {
     if (loadedByScope.get(scope)?.loaded === loaded) loadedByScope.delete(scope);

package/src/scenarios.ts

@@ -18,21 +18,28 @@ export interface RunScenarioOptions {
   client: SanomaClient;
   /** What the scenario was loaded from (`loadScenarios`), whose feature files its run is checked against: the resolved config. */
   scope: Scope;
-  /** Who starts the run. Defaults to `{ id: "scenarios" }`. */
-  startedBy?: Principal;
+  /**
+   * Who starts the run, by id (`"ada"` or `{ id: "ada" }`), unless the scenario says who is acting.
+   * Defaults to `scenarios`, one of the runtime's own agents.
+   */
+  startedBy?: Principal | string;
   /** How long the run may take, passed to `drive`. */
   timeoutMs?: number;
 }
 
 /**
- * Runs a scenario as a sandbox run: starts its workflow with its input, decides its approvals
- * as it says, and checks the run's ledger against it (`check`: Cucumber runs its `Then` steps).
+ * Runs a scenario as a sandbox run: starts its workflow with its input, as whoever it says is
+ * acting, decides its approvals as it says, and checks the run's ledger against it (`check`:
+ * Cucumber runs its `Then` steps).
  */
 export async function runScenario(
   scenario: Scenario,
-  { client, scope, startedBy = { id: "scenarios" }, timeoutMs }: RunScenarioOptions,
+  { client, scope, startedBy = "scenarios", timeoutMs }: RunScenarioOptions,
 ): Promise<{ runId: string; run: RunSummary; ledger: LedgerRecord[]; checks: Check[] }> {
-  const runId = await client.start(scenario.workflow, scenario.input, { startedBy, sandbox: scenario.name });
+  const runId = await client.start(scenario.workflow, scenario.input, {
+    startedBy: scenario.startedBy ?? startedBy,
+    sandbox: scenario.name,
+  });
   const run = await drive(client, runId, scenario, { timeoutMs });
   const ledger = await client.ledger(runId);
   return { runId, run, ledger, checks: await check(scope, scenario, ledger) };
@@ -49,8 +56,8 @@ export interface ScenarioFailure {
 export interface RunScenariosOptions {
   /** The Postgres the worker and the client run on, instead of the config's: a database of its own. */
   databaseUrl: string;
-  /** Who starts the runs. Defaults to `{ id: "scenarios" }`. */
-  startedBy?: Principal;
+  /** Who starts the runs whose scenario does not say who is acting (`runScenario`'s). */
+  startedBy?: Principal | string;
   /** How long each run may take (`drive`'s; 15 seconds by default). */
   timeoutMs?: number;
   /** Receives a line per scenario as it ends. */