@sanoma-ai/workflows 0.6.0 → 0.7.0

package/src/scenario.ts

@@ -135,7 +135,19 @@ export interface Scenario {
   file: string;
   /** Its line in the file: its keyword's, or for an outline's row, the row's. */
   line: number;
-  workflow: string;
+  /**
+   * The workflow its `When` runs. Absent for a scenario with no `When`, a *world*: its `Given`
+   * steps alone, which a demo applies to the instance (`applyGivens`) and nothing runs or checks.
+   */
+  workflow?: string;
+  /** Its tags, as written (`@slow`), the feature's and its own. */
+  tags: string[];
+  /**
+   * When it is tagged `@moment(<person>,<path>)` (no space: a Gherkin tag has none): a moment,
+   * which a demo starts as a sandbox run by `person`, a declared person, and leaves waiting, for
+   * a visitor signed in as them to land on at `path`.
+   */
+  moment?: Moment;
   /**
    * The scenario's own lines of its feature file, for display: from its keyword line to the end
    * of its last step (a step's doc string or table included, and an outline's examples), less
@@ -158,6 +170,12 @@ export interface Scenario {
   expect: Expectation[];
 }
 
+/** A moment's visitor and where they land: `@moment(<person>,<path>)`. */
+export interface Moment {
+  person: string;
+  path: string;
+}
+
 /** The result of one expectation against a run's ledger. */
 export interface Check {
   step: string;
@@ -380,6 +398,22 @@ function builtFor(scope: Scope): Built {
 /** A `Then` step of the generic steps: its expectation, checked against the run's records. */
 const expecting = (expect: CoreExpectation): Then => ({ expect, verify: (run) => detailOf(expect, run.records) });
 
+/**
+ * `who`, as a run's start admits them (`admit`): a declared person or agent, or `anonymous`. The
+ * people are the root's data files' (`readPeople`, read again only once a file changed): while
+ * they declare no one, any id goes.
+ */
+function actorNamed(scope: Scope, who: string): 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 });
+  }
+}
+
 /** The rules a scope has, and the parameter types their expressions use. */
 function rulesOf(scope: Scope): { rules: Rule[]; parameterTypes: ParameterTypeSpec[] } {
   const { types, collections } = scope;
@@ -403,20 +437,10 @@ function rulesOf(scope: Scope): { rules: Rule[]; parameterTypes: ParameterTypeSp
   ];
   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, or `anonymous`. */
-  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. */
+  /**
+   * `group`, a declared group or `agents`, while the people's files have no problems (`readPeople`,
+   * read again only once a file changed): while they declare no one, any group goes.
+   */
   const groupNamed = (group: string) => {
     const { people, problems } = readPeople(scope.root);
     if (problems.length) {
@@ -434,7 +458,7 @@ function rulesOf(scope: Scope): { rules: Rule[]; parameterTypes: ParameterTypeSp
     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: "actor", source: "{who} is acting", read: ([who]) => actorNamed(scope, who as string) },
     // A visitor of a public site, as a login would vouch for one; `anonymous` is a `{who}`.
     { kind: "actor", source: "a visitor is acting", read: () => visitorPrincipal("scenario", "visitor").id },
     {
@@ -881,7 +905,7 @@ function namesOf(report: Report): Map<string, string> {
 }
 
 /** What one scenario's steps said, as compiling it records them. */
-type Spec = Omit<Scenario, "workflow" | "approvals" | "file" | "line" | "text"> & { workflow?: string };
+type Spec = Omit<Scenario, "approvals" | "file" | "line" | "text" | "tags" | "moment">;
 
 /** The run's records, as a `Then` step reads them. */
 function viewOf(records: readonly LedgerRecord[]): RunView {
@@ -1177,6 +1201,28 @@ function stepError(built: Built, result: StepResult | undefined, step: PickleSte
   }
 }
 
+/**
+ * The moment its tags make a scenario (`@moment(<person>,<path>)`), the person admitted as a run's
+ * starter is, or undefined for none; throws, at `where`, for a malformed one or a second.
+ */
+function momentOf(scope: Scope, tags: readonly string[], where: string): Moment | undefined {
+  const tagged = tags.filter((t) => t === "@moment" || t.startsWith("@moment("));
+  if (tagged.length === 0) return undefined;
+  if (tagged.length > 1) throw new Error(`${where}: ${tagged.join(" and ")}: a moment has one person and one page`);
+  const [, person, path] = /^@moment\(([^,()]+),(\/[^()]*)\)$/.exec(tagged[0]!) ?? [];
+  if (person === undefined || path === undefined) {
+    throw new Error(
+      `${where}: ${tagged[0]} needs a person and a path, as in @moment(alex,/sites/portal/requests), with no space: a tag has none`,
+    );
+  }
+  try {
+    return { person: actorNamed(scope, person), path };
+  } catch (err) {
+    if (isBug(err)) throw err;
+    throw new Error(`${where}: ${tagged[0]}: ${errorMessage(err)}`, { cause: err });
+  }
+}
+
 /** The `.feature` files under `dir`, relative to it, with `/` between directories, in order. */
 function featureFiles(dir: string): string[] {
   return readdirSync(dir, { recursive: true, encoding: "utf8" })
@@ -1197,8 +1243,9 @@ const parseErrorOf = ({ uri, line, message }: Report["parseErrors"][number]) =>
 
 /**
  * Compiles the feature files `files` (relative to `dir`) into scenarios: Cucumber runs each,
- * and its steps record what they say. A file with an error has none of its scenarios: the
- * first error in it (a step that fails or matches no step or two, a scenario with no `When`,
+ * and its steps record what they say. A file none of whose scenarios has a `When` is of worlds.
+ * A file with an error has none of its scenarios: the
+ * first error in it (a step that fails or matches no step or two, a scenario with no `When` beside one with,
  * a name used twice, a file Gherkin cannot parse, no scenarios at all) is its error.
  */
 async function compile(scope: Scope, dir: string, files: string[]): Promise<LoadedScenarios> {
@@ -1234,6 +1281,8 @@ async function compile(scope: Scope, dir: string, files: string[]): Promise<Load
       try {
         const list = pickles.get(file) ?? [];
         if (list.length === 0) throw new Error(`${file}: no scenarios; add one with "Scenario: <name>"`);
+        // A feature none of whose scenarios has a When is of worlds; elsewhere a missing When is a mistake.
+        const ofWorlds = list.every((p) => specs.get(p.id)!.workflow === undefined);
         for (const pickle of list) {
           const line = lineOf(report, pickle);
           const scenario = query.findLineageBy(pickle)!.scenario!;
@@ -1242,16 +1291,37 @@ async function compile(scope: Scope, dir: string, files: string[]): Promise<Load
             const error = stepError(built, results.get(step.id), step, whereOf(report, file, step));
             if (error) throw new Error(error);
           }
-          const { workflow, ...spec } = specs.get(pickle.id)!;
+          const spec = specs.get(pickle.id)!;
+          const { workflow } = spec;
           const name = names.get(pickle.id)!;
           if (inFile.some((s) => s.name === name)) {
             throw new Error(`${where}: a second scenario named "${name}"; give each its own name`);
           }
-          if (workflow === undefined) {
+          const tags = pickle.tags.map((t) => t.name);
+          const moment = momentOf(scope, tags, where);
+          const common = { name, file, line, tags, text: textOf(scenario, report.texts.get(file) ?? "") };
+          if (workflow === undefined && !ofWorlds) {
             throw new Error(
-              `${where}: scenario "${name}" has no When: say which workflow runs, such as "When <workflow> runs with"`,
+              `${where}: scenario "${name}" has no When: say which workflow runs, such as "When <workflow> runs with" (a feature with no When in any scenario is of worlds)`,
             );
           }
+          if (workflow === undefined) {
+            // A world: its Givens alone, which nothing runs or checks.
+            const runs = moment
+              ? "is a moment, which starts a run"
+              : spec.expect[0]
+                ? `checks a run ("${spec.expect[0].step}")`
+                : spec.decisions[0]
+                  ? `decides an approval ("${spec.decisions[0].step}")`
+                  : undefined;
+            if (runs) {
+              throw new Error(
+                `${where}: scenario "${name}" has no When, so it is a world, Givens only, but it ${runs}: say which workflow runs, such as "When <workflow> runs with"`,
+              );
+            }
+            inFile.push({ ...spec, ...common, approvals: [] });
+            continue;
+          }
           // A step about a declared resource reads the report of the built-in it is about.
           for (const e of spec.expect) {
             const reads: string = "declared" in e ? ("status" in e ? DRIFT_WORKFLOW : APPLY_WORKFLOW) : workflow;
@@ -1263,11 +1333,9 @@ async function compile(scope: Scope, dir: string, files: string[]): Promise<Load
           }
           inFile.push({
             ...spec,
-            name,
-            file,
-            line,
+            ...common,
             workflow,
-            text: textOf(scenario, report.texts.get(file) ?? ""),
+            ...(moment && { moment }),
             approvals: approvalsOf(scope.workflows.get(workflow)!),
           });
         }
@@ -1358,10 +1426,11 @@ export async function loadScenarios(scope: Scope): Promise<LoadedScenarios> {
  */
 export async function check(scope: Scope, scenario: Scenario, records: readonly LedgerRecord[]): Promise<Check[]> {
   if (!scope.scenarios) throw new Error(`No scenarios directory to check scenario "${scenario.name}" from`);
+  const { file, line, name, workflow } = scenario;
+  if (workflow === undefined) throw new Error(`Scenario "${name}" is a world: it runs nothing to check`);
   const built = builtFor(scope);
-  const { file, line, name } = scenario;
   const verdicts = new Map<string, string | undefined>();
-  const report = await runFeatures(built.library, checkWorld(built, scenario.workflow, viewOf(records), verdicts), {
+  const report = await runFeatures(built.library, checkWorld(built, workflow, viewOf(records), verdicts), {
     cwd: fileURLToPath(scope.scenarios),
     files: [file],
     line,

package/src/scenarios.ts

@@ -6,11 +6,13 @@ import { type Check, check, drive, loadScenarios, type Scenario, type Scope } fr
 import { errorMessage } from "./shared.ts";
 import { startWorker } from "./worker.ts";
 
+export { type DemoState, demoState, reseed } from "./demo.ts";
+
 /*
  * `@sanoma-ai/workflows/scenarios`: runs a config's scenarios as sandbox runs, with no test
  * framework. Server-side only, like `./scenario`: it loads Cucumber and starts a worker.
  * `sanoma check` runs every scenario through `runScenarios`; `@sanoma-ai/testing/scenarios` wraps
- * `runScenario` in a vitest test per scenario.
+ * `runScenario` in a vitest test per scenario. A demo seeds its instance with `reseed`.
  */
 
 export interface RunScenarioOptions {
@@ -30,12 +32,15 @@ export interface RunScenarioOptions {
 /**
  * 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).
+ * Cucumber runs its `Then` steps). Refuses a world, which runs nothing.
  */
 export async function runScenario(
   scenario: Scenario,
   { client, scope, startedBy = "scenarios", timeoutMs }: RunScenarioOptions,
 ): Promise<{ runId: string; run: RunSummary; ledger: LedgerRecord[]; checks: Check[] }> {
+  if (scenario.workflow === undefined) {
+    throw new Error(`Scenario "${scenario.name}" is a world: it seeds a demo's instance, and runs nothing`);
+  }
   const runId = await client.start(scenario.workflow, scenario.input, {
     startedBy: scenario.startedBy ?? startedBy,
     sandbox: scenario.name,
@@ -64,6 +69,13 @@ export interface RunScenariosOptions {
   log?: (line: string) => void;
 }
 
+/**
+ * True for a scenario that is a test: one that runs a workflow (not a world), and not a moment
+ * that decides nothing, which a demo leaves waiting at its first approval.
+ */
+export const isTest = (scenario: Scenario): scenario is Scenario & { workflow: string } =>
+  scenario.workflow !== undefined && !(scenario.moment && scenario.decisions.length === 0);
+
 /**
  * Runs every scenario in `scenarios/` in the config's root, one after another, as sandbox runs
  * on a worker it starts on `databaseUrl` with an in-memory ledger (the config's `ledger` is not
@@ -72,6 +84,7 @@ export interface RunScenariosOptions {
  * could not be read, with why. A scenario whose run cannot be driven to its end (an approval
  * with no decision, a run still going after `timeoutMs`) fails with that error at its `When`
  * step. A config whose root has no `scenarios/`, or none in it, passes nothing and fails nothing.
+ * Worlds and moments that decide nothing are no tests (`isTest`): they are left out, each logged as skipped.
  */
 export async function runScenarios(
   config: SanomaConfig,
@@ -79,7 +92,9 @@ export async function runScenarios(
 ): Promise<{ passed: string[]; failed: ScenarioFailure[] }> {
   const shared: SanomaConfig = { ...config, databaseUrl, ledger: memoryLedger() };
   const resolved = resolveConfig(shared);
-  const { scenarios, errors } = await loadScenarios(resolved);
+  const { scenarios: loaded, errors } = await loadScenarios(resolved);
+  const scenarios = loaded.filter(isTest);
+  for (const s of loaded) if (!isTest(s)) log?.(`skipped ${s.file} › ${s.name}: ${s.moment ? "a moment" : "a world"}`);
   const failed: ScenarioFailure[] = errors.map(({ file, message }) => ({
     scenario: file,
     step: "did not load",
@@ -88,8 +103,9 @@ export async function runScenarios(
   const passed: string[] = [];
   if (scenarios.length === 0) return { passed, failed };
 
-  // Quiet: the scenarios call the fakes alone, so no vendor need be configured.
-  const worker = await startWorker(shared, { promote: true, quiet: true });
+  // Quiet: the scenarios call the fakes alone, so no vendor need be configured; and no schedule
+  // is applied, since a tick's run would be live.
+  const worker = await startWorker(shared, { promote: true, quiet: true, schedules: false });
   try {
     const client = await SanomaClient.connect(shared);
     try {

package/src/schedules.ts

@@ -0,0 +1,206 @@
+import { DBOS, type ScheduledWorkflowFn, type WorkflowSchedule } from "@dbos-inc/dbos-sdk";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import type { ResolvedConfig } from "./config.ts";
+import { type Db, WAKEUP_TABLE } from "./db.ts";
+import type { Principal, WorkflowDefinition } from "./define.ts";
+import { readPeople, admit } from "./resources.ts";
+import type { WorkerState } from "./run.ts";
+import { errorMessage, SCHEDULE_AGENT } from "./shared.ts";
+
+// Server-only: the worker's side of `trigger: { schedule, timezone? }`. DBOS fires the schedules
+// (its scheduler, `DBOS.applySchedules`); this names them, keeps them to the config's, fires a
+// tick missed while the instance was stopped, and decides each scheduled start.
+
+/** A workflow on a schedule: its cron expression of five fields, and the IANA time zone it is read in. */
+export interface ScheduledWorkflow {
+  name: string;
+  schedule: string;
+  /** UTC when the trigger names none: DBOS would read the cron in the process's own zone. */
+  timezone: string;
+}
+
+/** The config's workflows on a schedule, in the config's order. */
+export const scheduledWorkflows = ({ workflows }: Pick<ResolvedConfig, "workflows">): ScheduledWorkflow[] =>
+  [...workflows.values()].flatMap(({ name, trigger }) =>
+    trigger === "manual" ? [] : [{ name, schedule: trigger.schedule, timezone: trigger.timezone ?? "UTC" }],
+  );
+
+/**
+ * A workflow's schedule's name in DBOS: `<appName>/<workflow>`. Names are unique across every app
+ * on the system database, so the app's name comes first, and the app's own are those under it.
+ */
+const scheduleName = (appName: string, workflow: string): string => `${appName}/${workflow}`;
+
+/**
+ * Makes DBOS's schedules of the app the config's: one per scheduled workflow (`scheduleName`),
+ * firing it by its registered function in `registry` on the app's queue, with DBOS's automatic
+ * backfill (from the schedule's last fire); every other schedule under the app's name is deleted.
+ * Each keeps, as its context, from when its ticks are due (`since`). Then, when the instance last
+ * stopped (`sanoma_wakeup.stopped_at`), it fires once each tick missed since, of a schedule that
+ * has never fired, which DBOS's backfill leaves out, never one from before `since`, and moves
+ * `since` to now. A repeat is harmless anyway: a tick's run id is its time, so DBOS starts it once.
+ * Only the app's latest version calls this (`startWorker`): an older one must not undo a newer's.
+ */
+export async function applyScheduled(
+  resolved: Pick<ResolvedConfig, "appName" | "queueName" | "workflows">,
+  registry: ReadonlyMap<string, ScheduledWorkflowFn>,
+  db: () => Promise<Db>,
+): Promise<void> {
+  const { appName, queueName } = resolved;
+  const before = new Map(
+    (await DBOS.listSchedules({ scheduleNamePrefix: scheduleName(appName, "") })).map((s) => [s.scheduleName, s]),
+  );
+  const now = new Date();
+  const declared = scheduledWorkflows(resolved).map(({ name, schedule, timezone }) => {
+    const named = scheduleName(appName, name);
+    // A schedule whose cron or zone changed is a new one: its ticks before now were never due.
+    const prior = before.get(named);
+    const same = prior?.schedule === schedule && (prior.cronTimezone ?? "UTC") === timezone;
+    const since = (same && sinceOf(prior)) || now;
+    const context: ScheduleContext = { since: since.toISOString() };
+    return {
+      since,
+      schedule: {
+        scheduleName: named,
+        workflowFn: registry.get(name)!,
+        schedule,
+        cronTimezone: timezone,
+        automaticBackfill: true,
+        queueName,
+        context,
+      },
+    };
+  });
+  if (declared.length) await DBOS.applySchedules(declared.map((d) => d.schedule));
+  const names = new Set(declared.map((d) => d.schedule.scheduleName));
+  await Promise.all([...before.keys()].filter((name) => !names.has(name)).map((name) => DBOS.deleteSchedule(name)));
+  const unfired = declared.filter((d) => before.get(d.schedule.scheduleName)?.lastFiredAt === null);
+  if (!unfired.length) return;
+  const stoppedAt = await lastStopped(await db());
+  if (!stoppedAt) return;
+  for (const { schedule, since } of unfired) {
+    const from = stoppedAt > since ? stoppedAt : since;
+    if (from >= now) continue;
+    await DBOS.backfillSchedule(schedule.scheduleName, from, now);
+    // Fired up to now: the next start backfills from here, not over the same ticks again.
+    const covered: ScheduleContext = { since: now.toISOString() };
+    await DBOS.updateSchedule(schedule.scheduleName, { context: covered });
+  }
+}
+
+/**
+ * What a schedule keeps in DBOS's `context`: from when its ticks are the runtime's to fire, ISO
+ * 8601: when it was applied with its cron and zone, or the end of its last backfill.
+ */
+interface ScheduleContext {
+  since: string;
+}
+
+/** When the schedule was first applied, from its context; undefined for none, or one without it. */
+function sinceOf(schedule: WorkflowSchedule | undefined): Date | undefined {
+  const since = (schedule?.context as Partial<ScheduleContext> | null | undefined)?.since;
+  const at = typeof since === "string" ? new Date(since) : undefined;
+  return at && !Number.isNaN(at.getTime()) ? at : undefined;
+}
+
+/** When the instance's worker last stopped, from the wakeup's row; undefined while it never has. */
+async function lastStopped(db: Db): Promise<Date | undefined> {
+  const { rows } = await db.query<{ stopped_at: Date | null }>(`SELECT stopped_at FROM ${WAKEUP_TABLE} WHERE id = 1`);
+  return rows[0]?.stopped_at ?? undefined;
+}
+
+/** Who starts a scheduled run, as `scheduledStarter` admitted them, or why they were not. */
+export interface ScheduledStarter {
+  startedBy: Principal;
+  refused?: string;
+}
+
+/**
+ * Who starts a scheduled run: the runtime's `schedule` agent as the data files declare it
+ * (`admit`), in a step, since the files may change before a replay. A refusal is the step's
+ * answer, for the run to throw once it has started, so the ledger records it; the run starts as
+ * the agent alone then. A failure of the step itself (the worker stopping) is thrown as it is.
+ */
+export async function scheduledStarter(state: Pick<WorkerState, "root">): Promise<ScheduledStarter> {
+  const admitted = await DBOS.runStep(
+    async (): Promise<{ startedBy: Principal } | { refused: string }> => {
+      try {
+        return { startedBy: admit({ id: SCHEDULE_AGENT }, readPeople(state.root)) };
+      } catch (err) {
+        return { refused: errorMessage(err) };
+      }
+    },
+    { name: "schedule:starter" },
+  );
+  return "refused" in admitted ? { startedBy: { id: SCHEDULE_AGENT }, refused: admitted.refused } : admitted;
+}
+
+/** DBOS's cron parser (`TimeMatcher`), as its scheduler and backfill use it. */
+interface TimeMatcher {
+  match(date: Date | number): boolean;
+  /** The first instant strictly after `date` that matches; one that does not at the end of its search horizon. */
+  nextWakeupTime(date: Date | number): Date;
+}
+type TimeMatcherClass = new (pattern: string, timezone?: string) => TimeMatcher;
+
+let matcherClass: TimeMatcherClass | undefined;
+
+/**
+ * DBOS's `TimeMatcher`, from `dist/src/scheduler/crontab.js` beside its main module: the package's
+ * exports leave it out (dbos-sdk 5.2.11), so it is loaded by path, and a test holds it there.
+ */
+export function timeMatcher(): TimeMatcherClass {
+  if (matcherClass) return matcherClass;
+  const require = createRequire(import.meta.url);
+  const file = join(dirname(require.resolve("@dbos-inc/dbos-sdk")), "scheduler", "crontab.js");
+  const loaded = (require(file) as { TimeMatcher?: unknown }).TimeMatcher;
+  if (typeof loaded !== "function") throw new Error(`DBOS's cron parser is not in ${file} any more`);
+  return (matcherClass = loaded as TimeMatcherClass);
+}
+
+/**
+ * When `schedule` (a cron expression read in `timezone`, UTC without one) fires next, strictly
+ * after `from`: as DBOS's scheduler finds it. Throws for a schedule that never fires.
+ */
+export function nextFire(schedule: string, timezone: string | undefined, from: Date): Date {
+  const matcher = new (timeMatcher())(schedule, timezone ?? "UTC");
+  // Past a horizon of a century DBOS answers an instant that does not match, as its scheduler
+  // would wait for it and look again: a few looks find any schedule that ever fires.
+  let at = from.getTime();
+  for (let look = 0; look < 4; look++) {
+    const next = matcher.nextWakeupTime(at);
+    if (matcher.match(next)) return next;
+    at = next.getTime();
+  }
+  throw new Error("it never fires");
+}
+
+/**
+ * Throws when DBOS could not run the workflow's schedule: a cron its parser refuses (a minute of
+ * 61), or one that never fires (30 February). `resolveConfig` runs it, so the worker, the app and
+ * `sanoma check` refuse the config before any schedule is applied.
+ */
+export function checkSchedule({ name, trigger }: Pick<WorkflowDefinition, "name" | "trigger">): void {
+  if (trigger === "manual") return;
+  try {
+    nextFire(trigger.schedule, trigger.timezone, new Date());
+  } catch (err) {
+    throw new Error(`Workflow "${name}": DBOS cannot run its schedule "${trigger.schedule}": ${errorMessage(err)}`, {
+      cause: err,
+    });
+  }
+}
+
+/**
+ * The earliest next fire, strictly after `from`, of the config's scheduled workflows; undefined
+ * when none is on a schedule: the deadline a schedule sets for a worker that stops when quiet.
+ */
+export function nextScheduledFire(resolved: Pick<ResolvedConfig, "workflows">, from: Date): Date | undefined {
+  let earliest: Date | undefined;
+  for (const { schedule, timezone } of scheduledWorkflows(resolved)) {
+    const next = nextFire(schedule, timezone, from);
+    if (!earliest || next < earliest) earliest = next;
+  }
+  return earliest;
+}

package/src/schema.ts

@@ -8,11 +8,12 @@ import type {
   Type,
   TypeOfAttribute,
 } from "@cedar-policy/cedar-wasm/nodejs";
+import { ChangeFacts } from "./change.ts";
 import { recordSchemaOf } from "./collection.ts";
 import type { ResolvedConfig } from "./config.ts";
 import { jsonSchemaOf } from "./define.ts";
 import { isObject } from "./resource.ts";
-import { DATA_VENDOR, EFFECTS, groupNamesOf, type PeopleResource, WORKFLOW_ACTION } from "./shared.ts";
+import { CHANGE_MERGE, DATA_VENDOR, EFFECTS, groupNamesOf, type PeopleResource, WORKFLOW_ACTION } from "./shared.ts";
 
 // The Cedar schema a company's policies are validated and decided against: made from the
 // resolved config and the people, in memory for the evaluator, and written as text to
@@ -36,6 +37,9 @@ export const NAMESPACE = "Sanoma";
 /** The action group every workflow start (`workflow:<name>`) is in. */
 export const START = "start";
 
+/** The entity type a change's merge acts on (`Sanoma::Change`), its attributes the change's facts. */
+export const CHANGE = "Change";
+
 const STRING = { type: "EntityOrCommon", name: "String" } as const;
 const LONG = { type: "EntityOrCommon", name: "Long" } as const;
 const BOOL = { type: "EntityOrCommon", name: "Bool" } as const;
@@ -72,7 +76,8 @@ const WRITES = new Set(["save", "delete"]);
  *   `Target in [Collection]`; `Workflow`;
  * - an action per operation id, in its effect's group (`effect:money`), on a `Target`, with
  *   `context` `{ input, before? }`: `input` from the operation's input schema, `before` the record
- *   as it was for a collection's `save` and `delete`;
+ *   as it was for a collection's `save` and `delete`; `sanoma.change.merge` on a `Change`, whose
+ *   attributes are a change's facts (`ChangeFacts`), so a rule reads `resource.touches`;
  * - `workflow:<name>` per workflow, in the group `start`, on a `Workflow`, with its `input`.
  *
  * Zod to Cedar, through the JSON Schema of the parsed value: string and enum `String`, integer `Long`, boolean `Bool`,
@@ -97,7 +102,10 @@ function buildSchema(
     const before = collection && typeOf(recordSchemaOf(collection));
     actions[op.id] = {
       memberOf: [{ id: `effect:${op.effect}` }],
-      appliesTo: applies("Target", { ...input(op.input), ...(before && { before: optional(before) }) }),
+      appliesTo: applies(op.id === CHANGE_MERGE ? CHANGE : "Target", {
+        ...input(op.input),
+        ...(before && { before: optional(before) }),
+      }),
     };
   }
   for (const name of [...resolved.workflows.keys()].toSorted()) {
@@ -112,6 +120,7 @@ function buildSchema(
     Collection: {},
     Target: { memberOfTypes: ["Collection"] },
     Workflow: {},
+    [CHANGE]: { shape: typeOf(ChangeFacts) as RecordType<string> & { type: "Record" } },
   };
   return { [NAMESPACE]: { entityTypes, actions } };
 }
@@ -221,6 +230,10 @@ const allowsNull = (schema: unknown): boolean =>
 /** Cedar's message, with its help when it has one. */
 export const messageOf = (e: DetailedError) => (e.help ? `${e.message} (${e.help})` : e.message);
 
+/** The attributes of an entity type in the schema, when it has any (`Change`'s). */
+export const shapeOf = (schema: CedarSchemaJson, type: string) =>
+  (schema[NAMESPACE]?.entityTypes[type] as { shape?: RecordType<string> & { type: "Record" } } | undefined)?.shape;
+
 /** An action's context type in the schema: a record, when the action is there. */
 export const contextTypeOf = (schema: CedarSchemaJson, action: string) =>
   schema[NAMESPACE]?.actions[action]?.appliesTo?.context as (RecordType<string> & { type: "Record" }) | undefined;

package/src/shared.ts

@@ -1,8 +1,10 @@
 import type { RunSummary } from "./client.ts";
 import type { CredentialStatus } from "./env.ts";
 import type { ApprovalState, Approver, Principal } from "./define.ts";
+import type { OpEntry, WorkflowEntry } from "./describe.ts";
 import type { LedgerRecord } from "./ledger.ts";
 import type { Effect } from "./op.ts";
+import type { PreviewRequest } from "./policy.ts";
 import type { DeclaredResource, ResourceProblem } from "./resources.ts";
 import type { OutlineNode } from "./outline.ts";
 
@@ -20,6 +22,7 @@ export type { DeclaredResource, ResourceProblem } from "./resources.ts";
 export type { DriftField, DriftReport, DriftResult, DriftStatus } from "./drift.ts";
 export type { ApplyPlan, ApplyReport, ApplyResult, PlanAnswer, PlanStep } from "./apply.ts";
 export type { CredentialStatus } from "./env.ts";
+export type { ChangeEvent, ChangeFacts, ChangeReport, ChangeState } from "./change.ts";
 
 // What a UI in the browser may use from the runtime, besides types: `@sanoma-ai/workflows/shared`.
 // Nothing here imports DBOS, Node or zod, so a browser bundle can carry it; the runtime uses the
@@ -52,6 +55,24 @@ export const EFFECTS = ["read", "write", "publish", "send", "money", "access"] a
 /** What a workflow start's action id starts with, as a policy names it: `workflow:<name>`. */
 export const WORKFLOW_ACTION = "workflow:";
 
+/**
+ * What to ask the policy ahead of a run of `workflow` (`Policy.preview`, the principal aside): its
+ * start, then each operation it may call, with its effect, in the run (`inRun`). The run form's
+ * will-ask line asks it for the person; the Permissions grid (`permissionsGrid`) for each group.
+ */
+export function previewRequests(
+  workflow: Pick<WorkflowEntry, "name" | "ops">,
+  ops: ReadonlyMap<string, Pick<OpEntry, "effect">>,
+): Omit<PreviewRequest, "principal">[] {
+  return [
+    { action: { id: `${WORKFLOW_ACTION}${workflow.name}` } },
+    ...workflow.ops.map((id) => {
+      const effect = ops.get(id)?.effect;
+      return { action: effect === undefined ? { id } : { id, effect }, inRun: true };
+    }),
+  ];
+}
+
 /** A site's folder name under `sites/`, its URL segment: what the app mounts and `readSites` reads. */
 export const SITE_NAME = /^[a-z][a-z0-9-]*$/;
 
@@ -184,8 +205,30 @@ function checkField(where: string, field: string, kind: unknown): void {
  */
 export const CALL_WORKFLOW = "call";
 
-/** The workflows the runtime adds itself, which a config's own may not be named: drift, apply and call. */
-export const BUILT_IN_WORKFLOWS: ReadonlySet<string> = new Set([DRIFT_WORKFLOW, APPLY_WORKFLOW, CALL_WORKFLOW]);
+/**
+ * The built-in change workflow's name: the life of a change to the company's repository, from its
+ * pull request to its merge. The only workflow that may call `sanoma.change.*`.
+ */
+export const CHANGE_WORKFLOW = "change";
+
+/** Opens a change: its draft's branch pushed and a pull request opened for it. */
+export const CHANGE_OPEN = "sanoma.change.open";
+/** Reports Sanoma's review of a change to its host (the `sanoma` commit status). */
+export const CHANGE_REVIEW = "sanoma.change.review";
+/** Merges a change; its resource is the `Sanoma::Change`, whose attributes are its facts (`ChangeFacts`). */
+export const CHANGE_MERGE = "sanoma.change.merge";
+/** Closes a change without merging it. */
+export const CHANGE_CLOSE = "sanoma.change.close";
+/** The DBOS event a change run publishes its `ChangeState` on. */
+export const CHANGE_EVENT = "change";
+
+/** The workflows the runtime adds itself, which a config's own may not be named: drift, apply, call and change. */
+export const BUILT_IN_WORKFLOWS: ReadonlySet<string> = new Set([
+  DRIFT_WORKFLOW,
+  APPLY_WORKFLOW,
+  CALL_WORKFLOW,
+  CHANGE_WORKFLOW,
+]);
 
 /**
  * Every run status, in the order a run may pass through them: waiting on the queue, running,
@@ -277,8 +320,12 @@ export function visitorPrincipal(login: string, subject: string): Principal {
 /** Who a public page runs as when nobody is signed in. */
 export const ANONYMOUS_PRINCIPAL: Principal = Object.freeze({ id: ANONYMOUS, groups: [] });
 
-/** The runtime's own agents (scenarios, the host check, scheduled runs), declared whether a data file names them or not. */
-export const RUNTIME_AGENTS: readonly string[] = ["scenarios", "host-check", "schedule"];
+/** The runtime's agent that registers the instance's wakeup (`register`'s `CallContext.by`). */
+export const WAKEUP_AGENT = "wakeup";
+/** The runtime's agent a scheduled run is started by (`trigger: { schedule }`): the policy decides its starts. */
+export const SCHEDULE_AGENT = "schedule";
+/** The runtime's own agents (scenarios, the host check, scheduled runs, the wakeup's registration), declared whether a data file names them or not. */
+export const RUNTIME_AGENTS: readonly string[] = ["scenarios", "host-check", SCHEDULE_AGENT, WAKEUP_AGENT];
 
 /** The declared resources of one of the runtime's people types, by `desired`. */
 const peopleOfType = <T>(resources: readonly PeopleResource[], type: "person" | "agent" | "group") =>