@sanoma-ai/workflows 0.6.0 → 0.7.1

package/src/grid.ts

@@ -0,0 +1,100 @@
+import type { ResolvedConfig } from "./config.ts";
+import type { Principal } from "./define.ts";
+import type { ConfigDescription } from "./describe.ts";
+import type { PreviewAnswer, PreviewRequest } from "./policy.ts";
+import {
+  AGENTS,
+  ANONYMOUS,
+  ANONYMOUS_PRINCIPAL,
+  groupNamesOf,
+  previewRequests,
+  VISITORS,
+  visitorPrincipal,
+} from "./shared.ts";
+
+// The Permissions grid: what the policy would answer each group, for every workflow's start, the
+// operations it may call, and each direct operation. A pure function of a resolved config's policy
+// and its description, so the app's Permissions page and `sanoma check` (a draft's grid, on its
+// `checked` event) compute it the one way, and a change is reviewed as one grid against another.
+
+/** A row of the grid: a workflow (its start) or an operation, and the policy's answer for each column. */
+export interface PermissionsRow {
+  id: string;
+  title?: string;
+  cells: PreviewAnswer[];
+}
+
+/**
+ * The grid: its columns (`null` for someone in no group, then the declared groups, `agents` and
+ * `visitors`, sorted, then `anonymous`), a row for each workflow's start, with a row for each
+ * operation it uses (`ops`, in its order), and a row for each operation a person may call
+ * directly, each with a cell per column.
+ */
+export interface PermissionsGrid {
+  groups: (string | null)[];
+  workflows: (PermissionsRow & { ops: PermissionsRow[] })[];
+  ops: PermissionsRow[];
+}
+
+/**
+ * Whom the `agents` column's agent acts for: a hold `@hold("on-behalf-of")` asks them. Only an
+ * agent acts for someone, so in any other column that hold refuses, as it does a person.
+ */
+const ACTS_FOR = "whom it acts for";
+
+/** Whom a column of the grid asks about: someone in the group alone, a visitor, or `anonymous`. */
+export function columnPrincipal(group: string | null): Principal {
+  if (group === null) return { id: "group:", groups: [] };
+  if (group === ANONYMOUS) return ANONYMOUS_PRINCIPAL;
+  if (group === VISITORS) return visitorPrincipal("grid", "visitor");
+  return { id: `group:${group}`, groups: [group], ...(group === AGENTS && { onBehalfOf: ACTS_FOR }) };
+}
+
+/**
+ * The grid of `resolved`'s policy over `description`: for someone in no group, then for each
+ * group, the declared ones, `agents` and `visitors` (the visitors' only beside a public site),
+ * then for `anonymous`, what the policy would answer someone in it alone (`columnPrincipal`), the
+ * input unknown (`Policy.preview`), for the start of each of the config's own workflows, by name,
+ * each with the operations it uses, in the order it declares them (`previewRequests`), then each
+ * operation a person may call directly, by id.
+ */
+export function permissionsGrid(
+  { policy }: Pick<ResolvedConfig, "policy">,
+  description: ConfigDescription,
+): PermissionsGrid {
+  // A visitor's columns only beside a public site, where there are visitors.
+  const visitors = description.sites.some((site) => site.public);
+  const groups = [
+    null,
+    ...groupNamesOf(description.resources).filter((g) => visitors || g !== VISITORS),
+    ...(visitors ? [ANONYMOUS] : []),
+  ];
+  const opsById = new Map(description.ops.map((op) => [op.id, op]));
+  const workflows = description.workflows.filter((w) => !w.builtin);
+  const direct = description.ops.filter((op) => op.direct).toSorted((a, b) => a.id.localeCompare(b.id));
+  // Every row's question, in the grid's order: each workflow's start, then the operations it may
+  // call, as the run form asks them; then each direct operation.
+  const asked = workflows.map((w) => previewRequests(w, opsById));
+  const requests: Omit<PreviewRequest, "principal">[] = [
+    ...asked.flat(),
+    ...direct.map(({ id, effect }) => ({ action: { id, effect } })),
+  ];
+  const columns = groups.map((group) => {
+    const principal = columnPrincipal(group);
+    return policy.preview(requests.map((request) => ({ ...request, principal })));
+  });
+  const rows = requests.map(({ action: { id } }, i): PermissionsRow => ({
+    id,
+    cells: columns.map((answers) => answers[i]!),
+  }));
+  // Each workflow's rows, as many as it asked: its start, then one per operation it may call.
+  let at = 0;
+  return {
+    groups,
+    workflows: workflows.map(({ name, title }, i) => {
+      const [start, ...called] = rows.slice(at, (at += asked[i]!.length));
+      return { ...start!, id: name, ...(title !== undefined && { title }), ops: called };
+    }),
+    ops: rows.slice(at),
+  };
+}

package/src/host.ts

@@ -4,8 +4,16 @@ import type { z } from "zod";
 // a Fly app) declares about itself, so hosts are swappable and one conformance kit decides
 // whether one works. A host is a resource type like any other; this is what sets it apart.
 
-/** How a host keeps the runtime up: `long-lived`, or (later) woken on a schedule. */
-export type HostLifetime = "long-lived" | "wake-on-schedule";
+/**
+ * How a host keeps the runtime up:
+ * - `long-lived`: the process is restarted if it exits, and never stopped for being quiet (Docker).
+ * - `stops-when-quiet`: the host stops the instance after a while without inbound requests, and
+ *   starts it again on the next request (a free Render service, Cloudflare Containers).
+ *
+ * A host that stops needs a declared `Wakeup` for what is due at a time while it is stopped.
+ * Later: `stops-on-exit`, with a host that stops the instance when its process exits (Fly).
+ */
+export type HostLifetime = "long-lived" | "stops-when-quiet";
 
 /** What a host can do, for choosing one. */
 export interface HostCapabilities {
@@ -53,10 +61,10 @@ export interface HostSpec {
   outputs: (state: Record<string, unknown>) => HostOutputs;
 }
 
-const LIFETIMES: readonly HostLifetime[] = ["long-lived", "wake-on-schedule"];
+const LIFETIMES: readonly HostLifetime[] = ["long-lived", "stops-when-quiet"];
 
 /** True when `schema` has a field at the dotted `path`, looking through optional, nullable and default wrappers. */
-function hasPath(schema: z.ZodType, path: string): boolean {
+export function hasPath(schema: z.ZodType, path: string): boolean {
   let at: z.ZodType | undefined = schema;
   for (const key of path.split(".")) {
     at = unwrap(at);

package/src/index.ts

@@ -14,6 +14,7 @@ export {
   isSvgElement,
   type LoginContext,
   type LoginHalf,
+  type ModelContext,
   type Op,
   type OpSpec,
   type ResourceGroup,
@@ -33,6 +34,7 @@ export {
   type Ctx,
   type SleepRequest,
   type StepOptions,
+  type Trigger,
   type Use,
   type WorkflowDefinition,
 } from "./define.ts";
@@ -51,7 +53,14 @@ export {
   type ResourceSpec,
   withoutWriteOnly,
 } from "./resource.ts";
-export { defineConfig, resolveConfig, resolveDatabaseUrl, type ResolvedConfig, type SanomaConfig } from "./config.ts";
+export {
+  declaredWakeup,
+  defineConfig,
+  resolveConfig,
+  resolveDatabaseUrl,
+  type ResolvedConfig,
+  type SanomaConfig,
+} from "./config.ts";
 // `sanoma` itself (the people types' constructors) is at `@sanoma-ai/workflows/resources`, for data files.
 // `collection()` itself is at `@sanoma-ai/workflows/data`, for `resources/data.ts`; this tells one apart, as the launcher does.
 export { isCollection } from "./collection.ts";
@@ -66,6 +75,16 @@ export {
   type PlanStep,
 } from "./apply.ts";
 export { CALL_WORKFLOW, CallInput } from "./call-workflow.ts";
+export {
+  type ChangeEvent,
+  ChangeFacts,
+  ChangeInput,
+  changeOps,
+  type ChangeReport,
+  type ChangeState,
+  runtimeHold,
+  touchesOf,
+} from "./change.ts";
 export { isDirect } from "./direct.ts";
 export {
   DRIFT_WORKFLOW,
@@ -113,6 +132,7 @@ export {
   PolicyDeniedError,
   RejectedError,
   SanomaError,
+  WithdrawnError,
 } from "./errors.ts";
 export {
   jsonlLedger,
@@ -123,10 +143,13 @@ export {
   type LedgerRecord,
   type LedgerStore,
 } from "./ledger.ts";
-export { ApprovalMessage, APPROVALS_EVENT, decisionEventOf } from "./approvals.ts";
+export { ApprovalMessage, APPROVALS_EVENT, ApprovalWithdrawal, decisionEventOf } from "./approvals.ts";
 export { RUNTIME_VERSION } from "./version.ts";
 export type { RunArgs } from "./run.ts";
 export { startWorker, type Worker, type WorkerOptions } from "./worker.ts";
+export { superviseWorker, type Supervisor, type SupervisorOptions } from "./supervisor.ts";
+export type { DeadlineSource, Deadlines, SelfStop, Wait } from "./deadlines.ts";
+export { nextFire, nextScheduledFire } from "./schedules.ts";
 // `secret` itself is at `@sanoma-ai/workflows/resources`, for data files; this is the drivers' side.
 export {
   generateSecret,
@@ -137,10 +160,43 @@ export {
   type Secret,
   type Secrets,
 } from "./secret.ts";
-export { resolveRevision, SOURCE_RESOLVE, type Source } from "./source.ts";
+export {
+  type CheckResult,
+  type Draft,
+  type DraftDiff,
+  type HostEnforcement,
+  type PullRequest,
+  type RemoteContext,
+  type RemoteEvent,
+  type RemoteHalf,
+  remoteFor,
+  type RepoRef,
+  resolveRevision,
+  SOURCE_RESOLVE,
+  type Source,
+  type SourceHost,
+} from "./source.ts";
 export type { HostCapabilities, HostLifetime, HostOutputs, HostSpec } from "./host.ts";
+export {
+  checkDatabase,
+  type DatabaseCapabilities,
+  type DatabaseOutputs,
+  type DatabaseSpec,
+  databaseUrlSecret,
+  storeDatabaseUrl,
+} from "./database.ts";
+export type { Chat, Chats } from "./chats.ts";
+export {
+  checkWakeup,
+  type DeclaredWakeup,
+  type WakeupOutputs,
+  type WakeupRegistration,
+  type WakeupSpec,
+  wakeupHostTypes,
+} from "./wakeup.ts";
 export {
   type CallOptions,
+  type ClientOptions,
   SanomaClient,
   type RunsFilter,
   type RunSummary,
@@ -156,11 +212,18 @@ export {
   ANONYMOUS_PRINCIPAL,
   approverLabel,
   approverOf,
+  CHANGE_CLOSE,
+  CHANGE_EVENT,
+  CHANGE_MERGE,
+  CHANGE_OPEN,
+  CHANGE_REVIEW,
+  CHANGE_WORKFLOW,
   declaresPeople,
   type PeopleResource,
   personOf,
   principalOf,
   RUNTIME_AGENTS,
+  SCHEDULE_AGENT,
   credentialReady,
   DEFAULT_SLEEP_NAME,
   ENDED_STATUSES,

package/src/ledger.ts

@@ -17,7 +17,7 @@ import { errorMessage } from "./shared.ts";
  * decision, every approval, and how it ended. Records are append-only.
  *
  * `id` is deterministic (`<runId>:<type>:<seq>`, `<runId>:<type>:<approvalId>` for an
- * approval requested or decided, `<runId>:approval.refused:<approvalId>:refused:<n>` for
+ * approval requested, decided or withdrawn, `<runId>:approval.refused:<approvalId>:refused:<n>` for
  * the nth message an approval ignored) so that when DBOS replays a run after a restart,
  * the records it writes again have the same ids and the store skips them. `seq` orders a
  * run's records. `v` is the record format's version; `app` is the config's `appName`.
@@ -34,7 +34,12 @@ export type LedgerRecord = {
   /** Set on every record written while a `ctx.all` member runs; absent outside one. */
   group?: LedgerGroup;
 } & (
-  | { type: "run.started"; input: unknown }
+  | {
+      type: "run.started";
+      input: unknown;
+      /** For a run its schedule started (`trigger: { schedule }`): the tick's time, ISO 8601, which may be before `at`. */
+      scheduledFor?: string;
+    }
   | {
       type: "op.called";
       op: string;
@@ -61,7 +66,7 @@ export type LedgerRecord = {
       durationMs: number;
       /** Which try produced the output or the final error, from 1. Idempotent operations are retried. */
       attempt?: number;
-      /** The approval that held the call, when its rejection stopped it. */
+      /** The approval that held the call, when its rejection or withdrawal stopped it. */
       approval?: string;
     }
   | {
@@ -94,6 +99,13 @@ export type LedgerRecord = {
       /** Set when `by` started the run: nobody else could decide (`mayDecide`). */
       alone?: true;
     }
+  /** The approval no longer stands: withdrawn while pending, or retired by its run once approved. */
+  | {
+      type: "approval.withdrawn";
+      approval: string;
+      /** Who withdrew it, when someone did rather than its run. */ by?: string;
+      reason: string;
+    }
   /**
    * A `ctx.sleep` began; `until` is when it ends, in ms since the epoch: the time asked for, or
    * for a duration the record's `at` plus the duration, as the runtime saw it. Written

package/src/lint.ts

@@ -29,7 +29,7 @@ const ALLOWED_PACKAGE = new RegExp(`^(${[...AUTHOR_PACKAGES, "@sanoma-ai/connect
 const REFUSED_PACKAGES: [RegExp, string][] = [
   [/^@sanoma-ai\/testing(\/|$)/, `fakes and test helpers belong in tests; ${THROUGH_CTX}`],
   [/^@sanoma-ai\/app(\/|$)/, "the app starts runs and decides approvals, so a workflow could approve itself"],
-  [/^@sanoma-ai\/connector-[^/]+\/(fake|driver)(\/|$)/, `${THROUGH_CTX}; import the connector itself`],
+  [/^@sanoma-ai\/connector-[^/]+\/(fake|driver|remote)(\/|$)/, `${THROUGH_CTX}; import the connector itself`],
   [/^sanoma\//, "`sanoma` has no entry points for a workflow: import its names from `sanoma` itself"],
 ];
 
@@ -55,7 +55,7 @@ const NOT_ALLOWED =
  * copy, which is no instance of them, so a branch on it goes another way than the first time
  * and the run's steps fall out of step. Read the code with `errorCode(err)` instead.
  */
-const ERROR_CLASSES = new Set(["DriverError", "SanomaError", "PolicyDeniedError", "RejectedError"]);
+const ERROR_CLASSES = new Set(["DriverError", "SanomaError", "PolicyDeniedError", "RejectedError", "WithdrawnError"]);
 
 /**
  * Checks a workflow file. Imports allowed: the names in `WORKFLOW_IMPORTS` and any

package/src/op.ts

@@ -1,6 +1,8 @@
+import type { ProviderV4 } from "@ai-sdk/provider";
 import type { z } from "zod";
 import type { Fake } from "./fake.ts";
 import type { Secrets } from "./secret.ts";
+import type { RemoteHalf } from "./source.ts";
 import type { Steps } from "./steps.ts";
 
 /**
@@ -306,8 +308,9 @@ export interface Driver {
  * What a connector package attaches to its connector (`withSetup`), for the config's resolver
  * to call: the config then names the connector alone, and never a driver, a fake, steps or a
  * login. Any may be missing: a workflow using an operation of a connector with no driver is
- * refused, a connector with no fake has none for sandbox runs, and one with no login half signs
- * no visitor in.
+ * refused, a connector with no fake has none for sandbox runs, one with no login half signs no
+ * visitor in, one with no model half gives the app no models, and one with no remote half hosts
+ * no repository a change is reviewed on.
  */
 export interface ConnectorSetup {
   /** Makes the live driver, which reads its credentials from the environment when called: once per resolved config. */
@@ -321,8 +324,25 @@ export interface ConnectorSetup {
    * starts; a login that needs tables migrates them here (serialized, idempotent).
    */
   login?: (context: LoginContext) => LoginHalf | Promise<LoginHalf>;
+  /**
+   * Makes the connector's AI SDK provider, the vendor's adapter as the transport: by the app,
+   * once per resolved config and client (again after one that throws), whose registry names its
+   * models `<vendor>/<model-id>`. It answers `languageModel("default")` with the connector's own
+   * default model, and reads its credentials through `context.secrets` when a model is called, so
+   * a key set on the connector page later is used (unless the environment sets one, which wins),
+   * and a missing one fails that call.
+   */
+  model?: (context: ModelContext) => ProviderV4 | Promise<ProviderV4>;
+  /**
+   * Makes the connector's remote half, a git host's pull requests, statuses and webhooks: once per
+   * resolved config (`ResolvedConfig.remotes`). It reads its credentials when called.
+   */
+  remote?: () => RemoteHalf;
 }
 
+/** What the app gives a connector's model half (`ConnectorSetup.model`): the secrets, as a login half reads them. */
+export type ModelContext = Pick<LoginContext, "secrets">;
+
 /** What the app gives a connector's login half (`ConnectorSetup.login`) when it makes it for a public site. */
 export interface LoginContext {
   /** The company's database (`resolved.databaseUrl`), where a login like Better Auth keeps its users. */

package/src/person.ts

@@ -68,8 +68,11 @@ const group = defineResource({
  */
 export const sanoma = { person, agent, group };
 
+/** The runtime's own vendor, as a data file imports its constructors: `import { sanoma } from "sanoma/resources"`. */
+export const SANOMA_INFO = { title: "Sanoma", package: "sanoma" };
+
 /**
  * The runtime's own connector of the people types: every config's, so its data files may declare
  * them. Its package is `sanoma`, whose `/resources` entry exports `sanoma`.
  */
-export const peopleConnector = defineConnector("sanoma", sanoma, { title: "Sanoma", package: "sanoma" });
+export const peopleConnector = defineConnector("sanoma", sanoma, SANOMA_INFO);

package/src/policy.ts

@@ -32,6 +32,11 @@ export interface PolicyCall {
   run: { id: string; workflow: string; approvals: readonly ApprovalState[] };
   /** For a collection's `save` or `delete`: the record as it was, when there was one. */
   before?: unknown;
+  /**
+   * The attributes of the entity the call acts on, when its action is on one with attributes: a
+   * `sanoma.change.merge`'s `Sanoma::Change`, the change's facts (`ChangeFacts`).
+   */
+  entity?: Record<string, unknown>;
 }
 
 /**
@@ -145,7 +150,8 @@ export const denyAll = (reason: string): Policy => {
 /**
  * True when an approval in the run was approved, covers the operation, and was addressed to
  * `approver`. Check all three: a workflow can request an approval covering any operation from
- * anyone it names, so an approval's `covers` alone does not say the right person approved.
+ * anyone it names, so an approval's `covers` alone does not say the right person approved. A
+ * withdrawn approval is no longer approved, so it lifts nothing.
  */
 export function approvedFor(approvals: readonly ApprovalState[], opId: string, approver: Approver): boolean {
   return approvals.some(

package/src/resource.ts

@@ -1,7 +1,9 @@
 import { z } from "zod";
+import { checkDatabase, type DatabaseSpec } from "./database.ts";
 import { checkHost, type HostSpec } from "./host.ts";
 import { type Connector, type OpSpec, RESOURCE, VENDOR } from "./op.ts";
 import { isSanomaSecret, isSecret, type Secret } from "./secret.ts";
+import { checkWakeup, type WakeupSpec } from "./wakeup.ts";
 
 /** Which fields of a resource are flagged, by dotted path (`pages.html_url`; a list's items have no index). */
 export interface ResourceFields {
@@ -79,6 +81,16 @@ export interface ResourceSpec<S extends z.ZodObject = z.ZodObject> {
   writable?: boolean;
   /** Set when the type meets the `Host` contract: it runs the company. Such a type is `writable` and `stateless`. */
   host?: HostSpec;
+  /**
+   * Set when the type meets the `Wakeup` contract: it wakes a stopped instance at a time. Such a
+   * type is `writable`, and its connector has the operation `register` names.
+   */
+  wakeup?: WakeupSpec;
+  /**
+   * Set when the type meets the `Database` contract: it holds the company's database. Such a type
+   * is `writable`, not `stateless`, and its `afterCreate` calls the operation `storeUrl` names.
+   */
+  database?: DatabaseSpec;
   /**
    * True when its objects hold no data, so one gone at the vendor is created again by apply
    * without asking (a host running the company's code); otherwise apply asks first, as a
@@ -269,10 +281,13 @@ export interface Resource<
   extends
     Readonly<
       Required<
-        Omit<ResourceSpec<S>, "identity" | "find" | "writable" | "host" | "stateless" | "afterCreate" | "vendorless">
+        Omit<
+          ResourceSpec<S>,
+          "identity" | "find" | "writable" | "host" | "wakeup" | "database" | "stateless" | "afterCreate" | "vendorless"
+        >
       >
     >,
-    Readonly<Pick<ResourceSpec<S>, "identity" | "find" | "host" | "afterCreate">> {
+    Readonly<Pick<ResourceSpec<S>, "identity" | "find" | "host" | "wakeup" | "database" | "afterCreate">> {
   (desired: Declaring<z.input<S>, R>): Declared<Id, z.input<S>>;
   /** `read` and `import`, each effect `read`, idempotent, with the id as `target`; for a writable type, the change operations too. */
   readonly ops: ResourceOps<S, W>;
@@ -536,10 +551,12 @@ export function defineResource<
 >(
   spec: ResourceSpec<S> & { vendor: V; type: T; fields: { references?: R }; writable?: W },
 ): Resource<S, `${V}.${T}`, R, W> {
-  const { vendor, type, schema, fields, find, identity, host } = spec;
+  const { vendor, type, schema, fields, find, identity, host, wakeup, database } = spec;
   const writable = (spec.writable ?? false) as W;
   const what: `${V}.${T}` = `${vendor}.${type}`;
   if (host) checkHost(what, host, spec);
+  if (wakeup) checkWakeup(what, wakeup, spec);
+  if (database) checkDatabase(what, database, spec);
   if (spec.vendorless && (writable || host))
     throw new Error(`${what}: a vendorless type has no object to change or host`);
   const title = spec.title.toLowerCase();
@@ -677,6 +694,8 @@ export function defineResource<
     normalize: spec.normalize ?? ((state: State, desired: z.input<S>) => compareDeclared(fields, state, desired)),
     writable,
     ...(host && { host }),
+    ...(wakeup && { wakeup }),
+    ...(database && { database }),
     stateless: spec.stateless ?? host !== undefined,
     vendorless: spec.vendorless ?? false,
     ...(spec.afterCreate && { afterCreate: spec.afterCreate }),

package/src/resources.ts

@@ -12,7 +12,8 @@ import {
 import { type Binding, type Bindings, LOCKFILE, readLockfile } from "./lockfile.ts";
 import { type Connector, VENDOR } from "./op.ts";
 import { filesUnder } from "./paths.ts";
-import { peopleConnector } from "./person.ts";
+import { peopleConnector, sanoma } from "./person.ts";
+import { wakeupOps } from "./wakeup-type.ts";
 import type { Span } from "./outline.ts";
 import { type Declared, type Resource, resourceTypesOf } from "./resource.ts";
 import { Principal } from "./define.ts";
@@ -112,7 +113,7 @@ export interface DeclaredPeople {
 }
 
 /** A file that imports the runtime's constructors, `sanoma` (by any local name): the files `readPeople` reads. */
-const DECLARES_PEOPLE = /\{[^}]*\bsanoma\b[^}]*\}\s*from\s*["'](?:sanoma|@sanoma-ai\/workflows)\/resources["']/;
+export const DECLARES_PEOPLE = /\{[^}]*\bsanoma\b[^}]*\}\s*from\s*["'](?:sanoma|@sanoma-ai\/workflows)\/resources["']/;
 /** The last read of the people under each root, by what its data files were then (`filesStamp`). */
 const peopleRead = new Map<string, { stamp: string; read: DeclaredPeople }>();
 
@@ -144,8 +145,9 @@ export function readPeople(root: string | undefined): DeclaredPeople {
   const stamp = filesStamp(root);
   const cached = peopleRead.get(root);
   if (cached?.stamp === stamp) return cached.read;
-  const read = readDataFiles(root, [peopleConnector], undefined, (source) => DECLARES_PEOPLE.test(source));
-  const people = read.resources;
+  // With the wakeup's type, which the same constructors declare: read, and only the people's kept.
+  const read = readDataFiles(root, [peopleConnector, wakeupOps], undefined, (source) => DECLARES_PEOPLE.test(source));
+  const people = read.resources.filter((r) => Object.hasOwn(sanoma, r.type));
   // The people are never bound, so the lockfile's problems are not theirs.
   const own = read.problems.filter((p) => p.file !== LOCKFILE);
   const ids = new Map<string, DeclaredResource>();
@@ -424,6 +426,17 @@ export function readDataFiles(
       done.set(id, undefined);
     }
   }
+  // An instance registers with one wakeup: several are each a problem, and left out, as is any that names one.
+  const wakeups = [...declarations].filter(
+    ([, { file, exp }]) => types.get(`${vendors.get(file)!.get(exp.vendor)}.${exp.type}`)?.wakeup,
+  );
+  if (wakeups.length > 1) {
+    for (const [id, { file, exp }] of wakeups) {
+      const others = wakeups.filter(([other]) => other !== id).map(([other]) => other);
+      file.problem(exp.start, `an instance has one wakeup: leave out this one or ${others.join(", ")}`);
+      done.set(id, undefined);
+    }
+  }
   const keys = new Set([...files.values()].flatMap((f) => f.data.declared.map((name) => `${f.rel}#${name}`)));
   const orphans = Object.entries(lock.bindings)
     .filter(([key]) => !keys.has(key))

package/src/run.ts

@@ -1,5 +1,6 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import type { Collection } from "./collection.ts";
+import type { DeadlineRegistry } from "./deadlines.ts";
 import type { ApprovalState, Approver, Principal, WorkflowDefinition } from "./define.ts";
 import type { Fake } from "./fake.ts";
 import type { LedgerStore } from "./ledger.ts";
@@ -45,6 +46,8 @@ export interface WorkerState {
   drivers: Map<string, DriverFn>;
   /** The makers of the config's fake vendors, by vendor id: a sandbox run makes its own of each when it is seeded. */
   fakes: Map<string, () => Fake<any, any>>;
+  /** The instance's fakes, by vendor id, when it runs on them (`fakes: "instance"`): its sandbox runs seed and call these, not fakes of their own. */
+  instanceFakes?: ReadonlyMap<string, Fake<any, any>>;
   /** Where sandbox runs' scenarios are, the resource types their steps may name, and the steps the connectors ship. */
   scenarios?: URL;
   /** The worker's `source`, when it was given one. */
@@ -75,6 +78,8 @@ export interface WorkerState {
    * how it really ends (see `isInfrastructureError`).
    */
   stopped: boolean;
+  /** Which of its runs are executing and which wait, until when: what the worker's `idle` reads. */
+  deadlines: DeadlineRegistry;
 }
 
 /** What a run keeps in memory. Rebuilt the same way when DBOS replays the run. */