@sanoma-ai/workflows 0.5.0 → 0.7.0

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,9 +55,34 @@ 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-]*$/;
 
+/**
+ * A public site's language, as `defineSite({ locales })` names it: a BCP 47 language tag of a
+ * language and subtags (`en`, `fr`, `pt-BR`), which is also its URL segment (`/pt-BR/…`) and a
+ * content file's suffix (`<slug>.pt-BR.md`).
+ */
+export const LOCALE = /^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$/;
+
 /** A public site's domain: a host name of two labels or more, lowercase (`sanoma.example`). */
 export const DOMAIN_NAME = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$/;
 
@@ -177,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,
@@ -270,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") =>
@@ -395,6 +449,10 @@ export function problemLine(p: { file?: string; line?: number; column?: number;
   return p.line === undefined ? `${p.file}: ${p.message}` : `${p.file}:${p.line}:${p.column ?? 1}: ${p.message}`;
 }
 
+/** A warning as one line, as `problemLine` with `warning: ` before its message: what is worth fixing but not wrong. */
+export const warningLine = (p: Parameters<typeof problemLine>[0]): string =>
+  problemLine({ ...p, message: `warning: ${p.message}` });
+
 /**
  * Whether a host is this machine: `localhost`, `127.x.x.x` or `::1` (bare, or bracketed as a URL's
  * `hostname` has it). The one rule for what the app listens on and answers to, and for where the

package/src/sites.ts

@@ -12,6 +12,7 @@ import {
   apiNameOf,
   BUILT_IN_WORKFLOWS,
   DATA_VENDOR,
+  LOCALE,
   SITE_NAME,
   VISITORS,
   WORKFLOW_ACTION,
@@ -51,6 +52,18 @@ export interface SiteCall {
   page?: string;
 }
 
+/** A page of a site: a route file's path, and for a page per content entry the kind it reads. */
+export interface SitePage {
+  /** As `SiteCall.page` has it: `/sites/www`, `/sites/www/blog/$slug`. */
+  path: string;
+  /**
+   * For a path with one parameter (`$slug`), the content kind whose entries are its pages: the one
+   * kind its file reads by that parameter, `content.<kind>.get(params.slug)` (or `slug`,
+   * destructured) with `content` from `sanoma/site`.
+   */
+  content?: string;
+}
+
 /** A site, `sites/<name>/`, and what it calls. */
 export interface SiteEntry {
   /** Its folder's name, where it is mounted: `/sites/<name>`. */
@@ -61,8 +74,15 @@ export interface SiteEntry {
   public?: true;
   /** `defineSite({ login })`, the connector whose login half signs visitors in, as written: one that names none is among `problems`. */
   login?: string;
+  /**
+   * `defineSite({ locales })`, a public site's languages, the first its default: kept only when
+   * every one is a `LOCALE`, written once, on a public site with no login; else a problem.
+   */
+  locales?: string[];
   /** The host a public site answers on: set by `startApp` from its `domains`, never by `readSites`. */
   domain?: string;
+  /** Its pages, by path: one for each path its `routes/` files give (a layout and its index are one). */
+  pages: SitePage[];
   /** Its calls, by file and then in the file's order. */
   calls: SiteCall[];
   /**
@@ -71,6 +91,11 @@ export interface SiteEntry {
    * make, at its file; then what is wrong in its `site.ts`.
    */
   problems: (LintProblem & { file: string })[];
+  /**
+   * On a public site, each page with one parameter whose file reads content the sitemap cannot
+   * tie to it (`SitePage.content`), so the sitemap lists none of its pages: at the first read.
+   */
+  warnings: (LintProblem & { file: string })[];
 }
 
 /** Where a site's code is: its pages and its components. */
@@ -78,6 +103,8 @@ const SITE_DIRS = ["routes", "components"];
 /** Where `api`, `RunForm` and `defineSite` come from: `sanoma/site`, which re-exports the app's. */
 const SITE_SOURCES: ReadonlySet<string> = new Set(["sanoma/site", "@sanoma-ai/app/site"]);
 const KIND_NAMES = { workflow: "workflow", collection: "collection", op: "operation" } as const;
+/** What a route's loader and head name its path's parameters by. */
+const PARAMS: ReadonlySet<string> = new Set(["params"]);
 /** What makes a route from its id, whose first argument is the id. */
 const ROUTE_MAKERS: ReadonlySet<string> = new Set(["createFileRoute", "createLazyFileRoute"]);
 
@@ -85,7 +112,7 @@ const ROUTE_MAKERS: ReadonlySet<string> = new Set(["createFileRoute", "createLaz
  * The sites under `root`: each folder of `sites/` with a `routes/` whose name is a URL segment,
  * by name (as `@sanoma-ai/app/build`'s `sitesOf` mounts them). Reads `routes/**` and
  * `components/**` (`.ts` and `.tsx`, less tests and declarations) of each with oxc, never running
- * them: each `<RunForm workflow="…" />` and each use of `api`, both imported from `sanoma/site`,
+ * them: each page (`SitePage`, from a route's id), each `<RunForm workflow="…" />` and each use of `api`, both imported from `sanoma/site`,
  * called or passed on (`queryFn: api.data.leads.list`):
  * `api.<name>` and `api.<name>.<method>` are a workflow, `api.data.<collection>.<op>` a collection,
  * and `api.<vendor>.<resource>.<op>` an operation. A name that is not written out (a variable, a
@@ -107,7 +134,6 @@ export function readSites(
 ): SiteEntry[] {
   if (root === undefined) return [];
   const dir = join(root, "sites");
-  if (!isDirectory(dir)) return [];
   const workflows = new Set(description.workflows.map((wf) => wf.name));
   const collections = new Set(description.collections.map((c) => c.name));
   const ops = new Map(description.ops.map((op) => [op.id, op]));
@@ -167,39 +193,105 @@ export function readSites(
     return { call: { kind, target, via, ...at }, ...(problem && { problem }) };
   };
 
-  return readdirSync(dir, { withFileTypes: true })
-    .filter((d) => d.isDirectory() && SITE_NAME.test(d.name) && existsSync(join(dir, d.name, "routes")))
-    .map((d) => d.name)
+  return siteNames(dir).map((name) => {
+    const read = readSiteFiles(root, name);
+    const resolved = read.flatMap(({ uses }) => uses.map(resolve));
+    const pages = pagesOf(read);
+    const siteFile = `sites/${name}/site.ts`;
+    const { problems: optionProblems, ...options } = siteOptionsOf(join(root, siteFile), connectors);
+    const calls = resolved.map((r) => r.call);
+    const problems = [
+      ...resolved.flatMap(({ call, problem }) => {
+        const message = problem ?? (options.public ? refused(call, options.login) : undefined);
+        return message === undefined ? [] : [{ file: call.file, line: call.line, column: call.column, message }];
+      }),
+      ...optionProblems.map((p) => ({ file: siteFile, ...p })),
+    ];
+    const sorted = [...pages.keys()].toSorted().map((path) => pages.get(path)!);
+    // A page's file it warns of, unless another of its files (a lazy one, its layout) gives its kind.
+    const warnings = options.public
+      ? read.flatMap(({ route, warning }) => (warning && !pages.get(route!.path)?.content ? [warning] : []))
+      : [];
+    return { name, ...options, pages: sorted, calls, problems, warnings };
+  });
+}
+
+/** A site's pages, by path, from its files: a layout's and its index's (one path) merged. */
+function pagesOf(read: readonly { route?: SitePage }[]): Map<string, SitePage> {
+  const pages = new Map<string, SitePage>();
+  for (const { route } of read) {
+    if (route) pages.set(route.path, { ...pages.get(route.path), ...route });
+  }
+  return pages;
+}
+
+/** Each of site `name`'s files under `root`, as `readSiteFile` reads it, by path. */
+const readSiteFiles = (root: string, name: string) =>
+  SITE_DIRS.flatMap((sub) => filesUnder(join(root, "sites", name, sub), isSource))
     .toSorted()
-    .map((name) => {
-      const files = SITE_DIRS.flatMap((sub) => filesUnder(join(dir, name, sub), isSource)).toSorted();
-      const resolved = files.flatMap((path) => {
-        const file = readSource(path);
-        return typeof file === "string" ? [] : usesIn(file, relative(root, path).split(sep).join("/")).map(resolve);
-      });
-      const siteFile = `sites/${name}/site.ts`;
-      const { problems: optionProblems, ...options } = siteOptionsOf(join(root, siteFile), connectors);
-      const calls = resolved.map((r) => r.call);
-      const problems = [
-        ...resolved.flatMap(({ call, problem }) => {
-          const message = problem ?? (options.public ? refused(call, options.login) : undefined);
-          return message === undefined ? [] : [{ file: call.file, line: call.line, column: call.column, message }];
-        }),
-        ...optionProblems.map((p) => ({ file: siteFile, ...p })),
-      ];
-      return { name, ...options, calls, problems };
+    .flatMap((path) => {
+      const file = readSource(path);
+      return typeof file === "string" ? [] : [readSiteFile(file, relative(root, path).split(sep).join("/"))];
     });
+
+/**
+ * Each site's pages under `root` whose entries are a content kind's (`SitePage.content`), path to
+ * kind: what the app's build gives its router (`virtual:sanoma/locales`), so a page lists only the
+ * languages its entry is in. Read as `readSites` reads them, never run.
+ */
+export function siteContentPages(root: string): Record<string, string> {
+  return Object.fromEntries(
+    siteNames(join(root, "sites")).flatMap((name) =>
+      [...pagesOf(readSiteFiles(root, name)).values()].flatMap(({ path, content }) =>
+        content ? [[path, content]] : [],
+      ),
+    ),
+  );
+}
+
+/**
+ * Each site's languages (`defineSite({ locales })`, the first its default) under `root`, by name,
+ * for the sites whose `site.ts` gives them without a problem there: what the app's build gives
+ * its router (`virtual:sanoma/locales`). Read as `readSites` reads them, never run.
+ */
+export function siteLocales(root: string): Record<string, string[]> {
+  const none = new Set<string>();
+  return Object.fromEntries(
+    siteNames(join(root, "sites")).flatMap((name) => {
+      const { locales } = siteOptionsOf(join(root, "sites", name, "site.ts"), { vendors: none, logins: none });
+      return locales ? [[name, locales]] : [];
+    }),
+  );
 }
 
+/** The sites in `dir`: each folder with a `routes/` whose name is a URL segment, sorted. */
+const siteNames = (dir: string): string[] =>
+  isDirectory(dir)
+    ? readdirSync(dir, { withFileTypes: true })
+        .filter((d) => d.isDirectory() && SITE_NAME.test(d.name) && existsSync(join(dir, d.name, "routes")))
+        .map((d) => d.name)
+        .toSorted()
+    : [];
+
 /** A use of `api` or a `RunForm`, as written: the name it gives, before it is resolved. */
 type Written = Omit<SiteCall, "target"> & { name: string };
 
-/** The uses in one file, in its order. */
-function usesIn({ program, at }: SourceFile, file: string): Written[] {
+/**
+ * What one file holds: its uses, in its order, and the page it is, from its route's id, with the
+ * content kind whose entry its one parameter names (`SitePage.content`). A file under `routes/` is
+ * read whole; any other only when it imports `api` or `RunForm`.
+ */
+function readSiteFile(
+  { program, at }: SourceFile,
+  file: string,
+): { uses: Written[]; route?: SitePage; warning?: LintProblem & { file: string } } {
   const api = importedAs(program, SITE_SOURCES, "api");
   const runForm = importedAs(program, SITE_SOURCES, "RunForm");
-  if (!api.size && !runForm.size) return [];
+  const content = importedAs(program, SITE_SOURCES, "content");
+  if (!api.size && !runForm.size && !file.includes("/routes/")) return { uses: [] };
   const found: Omit<Written, "page">[] = [];
+  /** Each `content.<kind>.get(arg)`: its kind, its argument and where it is. */
+  const gets: { kind: string; arg: Node; start: number }[] = [];
   let page: string | undefined;
   const visit = (node: Node) => {
     if (!node) return;
@@ -207,12 +299,14 @@ function usesIn({ program, at }: SourceFile, file: string): Written[] {
       const named = apiPath(node, api);
       // The outermost member of a path on `api`: what it names, called or not; its inner members are not visited.
       if (named) return void found.push({ ...named, via: "api", file, ...at(node.start) });
-    } else if (node.type === "CallExpression" && page === undefined) {
+    } else if (node.type === "CallExpression") {
       const callee = unwrap(node.callee);
-      if (callee?.type === "Identifier" && ROUTE_MAKERS.has(callee.name)) {
+      if (callee?.type === "Identifier" && ROUTE_MAKERS.has(callee.name) && page === undefined) {
         const id = stringValue(node.arguments[0]);
         if (id !== undefined) page = pageOf(id);
       }
+      const kind = contentKind(callee, content);
+      if (kind !== undefined) gets.push({ kind, arg: unwrap(node.arguments[0]), start: node.start });
     } else if (node.type === "JSXOpeningElement" && node.name.type === "JSXIdentifier" && runForm.has(node.name.name)) {
       const attribute = node.attributes.find(
         (a: Node) => a.type === "JSXAttribute" && a.name.type === "JSXIdentifier" && a.name.name === "workflow",
@@ -224,11 +318,46 @@ function usesIn({ program, at }: SourceFile, file: string): Written[] {
     for (const child of childrenOf(node)) visit(child);
   };
   visit(program);
-  return found.map((use) => (page === undefined ? use : { ...use, page }));
+  const uses = found.map((use) => (page === undefined ? use : { ...use, page }));
+  if (page === undefined) return { uses };
+  // The one parameter's name (not a splat's), and the kinds whose `get` is given it (`params.slug`, or `slug` destructured).
+  const params = page.split("/").filter((segment) => segment.startsWith("$"));
+  if (params.length !== 1 || params[0] === "$") return { uses, route: { path: page } };
+  const param = params[0]!.slice(1);
+  const kinds = new Set(
+    gets
+      .filter(({ arg }) =>
+        arg?.type === "Identifier"
+          ? arg.name === param
+          : arg?.type === "MemberExpression" && memberPath(arg, PARAMS)?.join(".") === param,
+      )
+      .map(({ kind }) => kind),
+  );
+  if (kinds.size === 1) return { uses, route: { path: page, content: [...kinds][0]! } };
+  // A read by the parameter in a form the sitemap does not follow (`params.id.toLowerCase()`, two kinds).
+  const unfollowed = gets.find(({ arg }) => mentions(arg, param));
+  if (!unfollowed) return { uses, route: { path: page } };
+  const message =
+    `the sitemap lists none of this page's entries: it reads content by the page's parameter in a way it cannot follow. ` +
+    `Read one kind by it as written, \`content.<kind>.get(params.${param})\` (or \`${param}\` destructured)`;
+  return { uses, route: { path: page }, warning: { file, ...at(unfollowed.start), message } };
 }
 
-/** What a member path on `api` names; undefined for a path on anything else, a name not written out, or no name. */
-function apiPath(member: Node, api: ReadonlySet<string>): Pick<Written, "kind" | "name" | "method"> | undefined {
+/** Whether `node` reads the parameter `param` anywhere in it: `params.<param>`, or `param` destructured (not another parameter, nor a property's name, `post.slug` or `{ slug: x }`). */
+const mentions = (node: Node, param: string): boolean => {
+  if (!node) return false;
+  if (node.type === "Identifier") return node.name === param;
+  if (node.type === "Property" && !node.computed) return mentions(node.value, param);
+  if (node.type === "MemberExpression") {
+    const path = memberPath(node, PARAMS);
+    if (path) return path[0] === param;
+    if (!node.computed) return mentions(node.object, param);
+  }
+  return childrenOf(node).some((child) => mentions(child, param));
+};
+
+/** The names of a member path on one of `roots` (`api.data.leads.list` is `data`, `leads`, `list`); undefined for a path on anything else or a name not written out. */
+function memberPath(member: Node, roots: ReadonlySet<string>): string[] | undefined {
   const path: string[] = [];
   let node = member;
   while (node?.type === "MemberExpression") {
@@ -237,7 +366,19 @@ function apiPath(member: Node, api: ReadonlySet<string>): Pick<Written, "kind" |
     path.unshift(key);
     node = unwrap(node.object);
   }
-  if (node?.type !== "Identifier" || !api.has(node.name)) return undefined;
+  return node?.type === "Identifier" && roots.has(node.name) ? path : undefined;
+}
+
+/** The kind of `content.<kind>.get`, a callee on `content` imported from `sanoma/site`; undefined for any other. */
+function contentKind(callee: Node, content: ReadonlySet<string>): string | undefined {
+  const path = callee?.type === "MemberExpression" ? memberPath(callee, content) : undefined;
+  return path?.length === 2 && path[1] === "get" ? path[0] : undefined;
+}
+
+/** What a member path on `api` names; undefined for a path on anything else, a name not written out, or no name. */
+function apiPath(member: Node, api: ReadonlySet<string>): Pick<Written, "kind" | "name" | "method"> | undefined {
+  const path = memberPath(member, api);
+  if (!path?.length) return undefined;
   const [first, second, third] = path as [string, ...string[]];
   if (first === DATA_VENDOR)
     return path.length === 3 ? { kind: "collection", name: second!, method: third } : undefined;
@@ -273,13 +414,14 @@ const unread = (what: string, as: string) => `${what} is read without running si
 /**
  * What `site.ts` says of its site, read without running it, and what is wrong there: its default
  * export must be `defineSite({ … })` written out, so it can be read at all; then `title` when it is
- * a string, `public` and `login`, which must be literals. `login` is kept as written; one on a
+ * a string, `public`, `login` and `locales`, which must be literals. `login` is kept as written; one on a
  * site that is not public, or naming no connector of the config with a login half, is a problem.
+ * `locales` is kept only when it has no problem.
  */
 function siteOptionsOf(
   path: string,
   connectors: SiteConnectors,
-): Pick<SiteEntry, "title" | "public" | "login"> & { problems: LintProblem[] } {
+): Pick<SiteEntry, "title" | "public" | "login" | "locales"> & { problems: LintProblem[] } {
   const file = readSource(path);
   if (typeof file === "string") return { problems: [] };
   const problems: LintProblem[] = [...file.problems];
@@ -329,10 +471,33 @@ function siteOptionsOf(
   };
   const message = loginAt && loginProblem();
   if (message) problem(loginAt, message);
+
+  const localesAt = property("locales");
+  const list = unwrap(localesAt?.value);
+  // A hole or a spread is no string.
+  const tags: (string | undefined)[] | undefined =
+    list?.type === "ArrayExpression" ? list.elements.map((e: Node) => stringValue(e)) : undefined;
+  const locales = tags?.every((tag): tag is string => tag !== undefined) ? tags : undefined;
+  const localesProblem = (): string | undefined => {
+    if (locales === undefined) return unread("`locales`", "an array of strings");
+    if (!locales.length) return "`locales` names a site's languages, its default first: give one or more, or remove it";
+    const bad = locales.find((locale) => !LOCALE.test(locale));
+    if (bad !== undefined) return `"${bad}" is not a language tag such as "en", "fr" or "pt-BR"`;
+    const twice = locales.find((locale, i) => locales.indexOf(locale) !== i);
+    if (twice !== undefined) return `"${twice}" is in \`locales\` twice`;
+    // When `public` is what is wrong, it is said there.
+    if ((!isPublic && !publicUnread) || loginAt) {
+      return "`locales` are for a public site with no login: add `public: true`, or remove `locales`";
+    }
+    return undefined;
+  };
+  const localesMessage = localesAt && localesProblem();
+  if (localesMessage) problem(localesAt, localesMessage);
   return {
     ...(title !== undefined && { title }),
     ...(isPublic && { public: true as const }),
     ...(login !== undefined && { login }),
+    ...(localesAt && !localesMessage && isPublic && !loginAt && { locales }),
     problems,
   };
 }

package/src/source.ts

@@ -1,12 +1,14 @@
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { z } from "zod";
+import type { PermissionsGrid } from "./grid.ts";
 import { defineConnector, defineDriver, DriverError } from "./op.ts";
 
 // Where a company's files live, and how a change to them is recorded: a git repository on this
 // machine, or one a host cloned. The runtime's writers (the app's Adopt, apply's lockfile) change
 // files under `root`, then commit them through it. The launcher makes one; a config without one
-// writes the files and commits nothing.
+// writes the files and commits nothing. A writer that must leave the live checkout alone writes
+// in a draft instead: a checkout of its own, on a branch of its own.
 
 /** A company's repository, as the runtime writes to it. */
 export interface Source {
@@ -21,10 +23,63 @@ export interface Source {
     message: string;
     author: string;
   }): { revision: string } | undefined | Promise<{ revision: string } | undefined>;
-  /** The revision `ref` names, the checked-out one by default. */
+  /** The revision `ref` names, the checked-out one by default (a draft's by its `branch`). */
   head(ref?: string): string | Promise<string>;
-  /** Pushes `ref` to the repository at `url`, signed in with `token`. */
+  /** Pushes `ref` to the repository at `url`, signed in with `token` (a draft by its `branch`). */
   push?(target: { url: string; token: string; ref: string }): void | Promise<void>;
+  /**
+   * The draft `id` (letters, digits, `_` and `-`), opened: made from the checked-out revision the
+   * first time, then the same one, edits and all, until its branch is deleted.
+   */
+  draft?(id: string): Promise<Draft>;
+  /** The open drafts' ids, sorted. */
+  drafts?(): Promise<string[]>;
+  /** What the draft `id` has committed since its branch left the checked-out one (read from the branch alone). */
+  diff?(id: string): Promise<DraftDiff>;
+  /** Closes the draft `id`: its checkout removed and its branch deleted, whatever it held; nothing when it is gone. */
+  closeDraft?(id: string): Promise<void>;
+  /**
+   * `sanoma check` on the draft `id`, as a child in its checkout, one at a time in the process. A
+   * check that gives no result (a config that does not load, no install, a timeout) is a result
+   * of one problem saying why.
+   */
+  check?(id: string): Promise<CheckResult>;
+  /** The URL of the repository this one was cloned from (`origin`); undefined when it has none. */
+  remoteUrl?(): Promise<string | undefined>;
+  /**
+   * Fast-forwards the checked-out branch to `ref` in the repository at `url`, signed in with
+   * `token`, as `push` is: only when `ref` is checked out, nothing is uncommitted and the remote's
+   * `ref` contains it; otherwise `skipped`, saying why. The checked-out revision after.
+   */
+  follow?(target: { url: string; token: string; ref: string }): Promise<{ revision: string } | { skipped: string }>;
+}
+
+/**
+ * A draft: a checkout of its own, at `root`, on `branch`, which `commit` records in as
+ * `Source.commit` does in its root. Its `node_modules` may be the root's own install, linked in:
+ * a writer never writes under it.
+ */
+export interface Draft {
+  branch: string;
+  root: string;
+  commit: Source["commit"];
+}
+
+/** A draft's change: the files it touches, relative to the root, and git's `--stat` of it. */
+export interface DraftDiff {
+  files: string[];
+  summary: string;
+}
+
+/** What `sanoma check` finds in a repo (a draft's too). */
+export interface CheckResult {
+  ok: boolean;
+  /** One printable line each: `<file>:<line>:<col>: <message>`, or `<scenario> › <step>: <message>`. */
+  problems: string[];
+  /** What is worth fixing but not wrong, one line each, `<file>:<line>:<col>: warning: <message>`: the sites' `warnings`. */
+  warnings: string[];
+  /** The repo's Permissions grid (`permissionsGrid`), when its config loaded and its policies hold: what a change is reviewed by. */
+  grid?: PermissionsGrid;
 }
 
 /**

package/src/supervisor.ts

@@ -0,0 +1,107 @@
+import { resolveConfig, type SanomaConfig } from "./config.ts";
+import { shouldWake } from "./db.ts";
+import type { SelfStop } from "./deadlines.ts";
+import { warn } from "./log.ts";
+import { errorMessage } from "./shared.ts";
+import { startWorker, type Worker, type WorkerOptions } from "./worker.ts";
+
+// One worker at a time in a process that outlives it. A worker that stops itself when idle (a
+// wakeup declared) cannot launch again, so the next write that needs one, or the wakeup's wake,
+// starts a fresh worker. `sanoma serve` runs its worker through it, and so does the testing
+// kit's host in this process.
+
+/** A worker under a supervisor (`superviseWorker`). */
+export interface Supervisor {
+  /** True from the moment the worker stopped itself until a fresh one starts. */
+  readonly stopped: boolean;
+  /**
+   * Starts a fresh worker when the last one stopped itself, for a write that needs one (a run's
+   * start, an approval's decision); while one starts or runs, it is heard (below). Resolves once it runs, or
+   * once its failure to start is logged: the next call tries again. Never rejects.
+   */
+  resume(): Promise<void>;
+  /**
+   * A wakeup's `GET /wake?generation=N`: `resume` when the worker stopped with `generation`
+   * registered (`shouldWake`); a no-op for any other, and while one starts or runs.
+   */
+  wake(generation: number): Promise<void>;
+  /** Stops the worker running or starting, and starts none again. */
+  stop(): Promise<void>;
+}
+
+export interface SupervisorOptions extends Omit<WorkerOptions, "onStopped"> {
+  /**
+   * False: the worker never stops itself, as on an app on this machine alone, whose wakeup
+   * would wake the instance the host runs. Default true.
+   */
+  selfStop?: boolean;
+  /** Told each time the worker stops itself, once a fresh one is starting for a write it heard, or `stopped` is true. */
+  onStopped?: (stopped: SelfStop) => void;
+}
+
+/**
+ * Starts a worker on `config` that stops itself when idle with a wakeup declared (`onStopped`
+ * in `WorkerOptions`), and a fresh one each time `resume` or `wake` asks after it did. Throws
+ * when the first does not start. A write heard while a worker starts or runs may land after its last check
+ * for being idle, so a worker that stops itself after one is started again at once: it stops
+ * again on its own when nothing came of it.
+ */
+export async function superviseWorker(config: SanomaConfig, options: SupervisorOptions = {}): Promise<Supervisor> {
+  const { onStopped, selfStop = true, ...workerOptions } = options;
+  let worker: Worker | undefined;
+  let starting: Promise<void> | undefined;
+  let closed = false;
+  // A write while the worker starts or runs, since it began starting.
+  let heard = false;
+  let databaseUrl: string | undefined;
+
+  const launch = async () => {
+    heard = false;
+    const started = await startWorker(config, { ...workerOptions, ...(selfStop && { onStopped: selfStopped }) });
+    if (closed) await started.stop();
+    else worker = started;
+  };
+  const selfStopped = (stopped: SelfStop) => {
+    worker = undefined;
+    if (closed) return;
+    // Resumed first, so `stopped` is false when `onStopped` (the exit rule) looks.
+    if (heard) void supervisor.resume();
+    onStopped?.(stopped);
+  };
+
+  const supervisor: Supervisor = {
+    get stopped() {
+      return !closed && !worker && !starting;
+    },
+    resume() {
+      if (closed) return Promise.resolve();
+      if (worker) {
+        heard = true;
+        return Promise.resolve();
+      }
+      if (starting) {
+        heard = true;
+        return starting;
+      }
+      return (starting = launch()
+        .catch((err: unknown) => warn(`the worker could not start again: ${errorMessage(err)}`))
+        .finally(() => {
+          starting = undefined;
+        }));
+    },
+    async wake(generation) {
+      if (!supervisor.stopped) return;
+      databaseUrl ??= resolveConfig(config).databaseUrl;
+      if (await shouldWake(databaseUrl, generation)) await supervisor.resume();
+    },
+    async stop() {
+      closed = true;
+      await starting;
+      const running = worker;
+      worker = undefined;
+      await running?.stop();
+    },
+  };
+  await launch();
+  return supervisor;
+}

package/src/version.ts

@@ -16,8 +16,10 @@ export const RUNTIME_VERSION = (
  * package release, so a run in flight on the old layout is not replayed against the new one.
  * 2: calls run in program order; a decision event per approval (2026-10-07).
  * 3: a start the policy holds waits on its approval before the body (2026-10-21).
+ * 4: a sleep for a duration reads DBOS's clock for its start (2026-10-25).
+ * 5: a scheduled run admits its starter and asks the policy in two steps before the body (2026-10-25).
  */
-export const STEP_LAYOUT = 3;
+export const STEP_LAYOUT = 5;
 
 let dbosVersion: string | undefined;