@sanoma-ai/workflows 0.1.0 → 0.4.0

package/src/shared.ts

@@ -1,6 +1,9 @@
+import type { RunSummary } from "./client.ts";
 import type { CredentialStatus } from "./env.ts";
 import type { ApprovalState, Approver, Principal } from "./define.ts";
-import type { ResourceProblem } from "./resources.ts";
+import type { LedgerRecord } from "./ledger.ts";
+import type { Effect } from "./op.ts";
+import type { DeclaredResource, ResourceProblem } from "./resources.ts";
 import type { OutlineNode } from "./outline.ts";
 
 // Types only: resource types as a UI reads them. Erased from the bundle.
@@ -15,6 +18,7 @@ export type {
 } from "./resource.ts";
 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";
 
 // What a UI in the browser may use from the runtime, besides types: `@sanoma-ai/workflows/shared`.
@@ -30,6 +34,124 @@ export const DEFAULT_SLEEP_NAME = "Sleep";
 /** The built-in drift workflow's name, which a config's own workflows may not take; a UI and the scenarios name its runs by it. */
 export const DRIFT_WORKFLOW = "drift";
 
+/**
+ * The built-in apply workflow's name: the only workflow that may call a writable resource type's
+ * change operations (`create`, `update`, `delete`).
+ */
+export const APPLY_WORKFLOW = "apply";
+
+/**
+ * The vendor of the collections' operations, `data.<collection>.<op>`: a collection's `get`,
+ * `list`, `save` and `delete`. No connector may take it.
+ */
+export const DATA_VENDOR = "data";
+
+/** Every effect an operation may have, each an action group (`effect:<effect>`) of the Cedar schema. */
+export const EFFECTS = ["read", "write", "publish", "send", "money", "access"] as const satisfies readonly Effect[];
+
+/** What a workflow start's action id starts with, as a policy names it: `workflow:<name>`. */
+export const WORKFLOW_ACTION = "workflow:";
+
+/** 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 record of a collection as `get`, `list` and `save` answer it: its key, the record, and when
+ * and by whom it was last saved (`updatedBy`: a person's id, or `run:<id>` for a run). A record
+ * saved under an older declaration comes back as it is stored, with `issues` saying where the
+ * fields no longer accept it.
+ */
+export type Saved<R = Record<string, unknown>> = {
+  key: string;
+  record: R;
+  /** ISO 8601. */
+  updatedAt: string;
+  updatedBy: string;
+  issues?: { path: (string | number)[]; message: string }[];
+};
+
+/**
+ * What a collection's `list` takes: fields equal to a value or within a range (`where`), the
+ * field to sort by (`-field` for descending; by key otherwise), and how many at most (1 to
+ * 1000, default 100).
+ */
+export type ListQuery<R> = {
+  where?: { [F in keyof R]?: Exclude<R[F], undefined> | Range<Exclude<R[F], undefined>> };
+  order?: (keyof R & string) | `-${keyof R & string}`;
+  limit?: number;
+};
+
+type Range<V> = { gt?: V; gte?: V; lt?: V; lte?: V };
+
+/** How many records a collection's `list` answers: `default` when the query names no `limit`, `max` at most. */
+export const LIST_LIMIT = { default: 100, max: 1000 } as const;
+
+/** The kinds of value a field holds: text, a number, true or false, a date (ISO 8601) or a person's id. */
+export const FIELD_TYPES = ["text", "number", "boolean", "date", "person"] as const;
+
+const COLLECTION_NAME = /^[a-z][a-zA-Z0-9]*$/;
+const FIELD_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const KINDS = `${FIELD_TYPES.map((t) => `"${t}"`).join(", ")}, { type, optional: true } or { enum: [...] }`;
+const isRecord = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v);
+
+/**
+ * Throws unless `collection()` takes this declaration: the name a lowercase letter then letters
+ * and digits, at least one field, each a type, the type marked optional or an enum of distinct
+ * strings, the key a required text field, the title a string. `collection()` and the reader of
+ * `resources/data.ts` both ask it, so `sanoma check` refuses what the runtime would.
+ */
+export function checkCollection(declaration: { name?: unknown; key?: unknown; fields?: unknown; title?: unknown }) {
+  const { name, key, fields, title } = declaration;
+  const where = `collection("${String(name)}")`;
+  if (typeof name !== "string" || !COLLECTION_NAME.test(name)) {
+    throw new Error(`${where}: the name must be a lowercase letter, then letters and digits, such as "outbound"`);
+  }
+  if (!isRecord(fields) || !Object.keys(fields).length) {
+    throw new Error(`${where}: it needs fields, by name: each one of ${KINDS}`);
+  }
+  for (const [field, kind] of Object.entries(fields)) checkField(where, field, kind);
+  const keyKind: unknown = typeof key === "string" && Object.hasOwn(fields, key) ? fields[key] : undefined;
+  if (!(keyKind === "text" || (isRecord(keyKind) && keyKind.type === "text" && keyKind.optional === undefined))) {
+    throw new Error(`${where}: the key "${String(key)}" must be one of its fields, a required "text" one`);
+  }
+  if (title !== undefined && typeof title !== "string") throw new Error(`${where}: the title must be a string`);
+}
+
+/** Throws unless `kind` is a field `collection()` takes: a type, the type marked optional, or an enum of distinct strings. */
+function checkField(where: string, field: string, kind: unknown): void {
+  const refused = (why: string) => new Error(`${where}: the field "${field}" ${why}`);
+  if (!FIELD_NAME.test(field)) throw refused("must be named with letters, digits and _, not a digit first");
+  const types: readonly unknown[] = FIELD_TYPES;
+  const kinds = `is ${JSON.stringify(kind)}; a field is one of ${KINDS}`;
+  if (typeof kind === "string") {
+    if (!types.includes(kind)) throw refused(kinds);
+    return;
+  }
+  if (!isRecord(kind)) throw refused(kinds);
+  const { type, enum: values, optional, ...rest } = kind;
+  if (Object.keys(rest).length || (type === undefined) === (values === undefined)) throw refused(kinds);
+  if (optional !== undefined && optional !== true) throw refused("may only be marked `optional: true`");
+  if (type !== undefined && !types.includes(type)) throw refused(kinds);
+  if (
+    values !== undefined &&
+    (!Array.isArray(values) ||
+      !values.length ||
+      values.some((v) => typeof v !== "string") ||
+      new Set(values).size < values.length)
+  ) {
+    throw refused("needs an enum of distinct strings, at least one");
+  }
+}
+
+/**
+ * The built-in call workflow's name: one operation that may be called directly (`isDirect`),
+ * made a run when the policy holds a direct call for an approval.
+ */
+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]);
+
 /**
  * Every run status, in the order a run may pass through them: waiting on the queue, running,
  * waiting for an approval, or ended. `waiting` is `running` with an approval pending.
@@ -46,12 +168,124 @@ export const ENDED_STATUSES = ["finished", "failed", "cancelled"] as const satis
 export const isEnded = (status: RunStatus): boolean => (ENDED_STATUSES as readonly RunStatus[]).includes(status);
 
 /**
- * True when `by` may decide the approval: `by.id` is the approver, or `by.groups` holds the
- * approver group. Pure: everything it reads is already recorded.
+ * Why the run's own actor may not decide an approval on it: separation of duties (`mayDecide`),
+ * while someone else could decide it.
+ */
+export const OWN_CHANGE = "own change";
+
+/** A run as `mayDecide` reads it: who started it, its own actor. */
+type DecidedRun = { actor?: Pick<Principal, "id"> | undefined };
+
+/**
+ * True when `by` may decide the approval on `run`: `by.id` is the approver, or `by.groups` holds
+ * the approver group. The run's own actor is refused only while someone else could decide (separation
+ * of duties): the approver is a group with another declared person in `people` (an agent does not
+ * count). Pure: everything it reads is passed in.
  */
-export function mayDecide(approval: Pick<ApprovalState, "approver">, by: Principal): boolean {
-  const { approver } = approval;
-  return typeof approver === "string" ? approver === by.id : (by.groups?.includes(approver.group) ?? false);
+export const mayDecide = (
+  approval: Pick<ApprovalState, "approver">,
+  by: Principal,
+  run: DecidedRun,
+  people: readonly PeopleResource[],
+): boolean => refusalOf(approval, by, run, people) === undefined;
+
+/** Why `by` may not decide the approval on `run` (`mayDecide`), naming who may, or `OWN_CHANGE`; undefined when they may. */
+export function refusalOf(
+  { approver }: Pick<ApprovalState, "approver">,
+  by: Principal,
+  run: DecidedRun,
+  people: readonly PeopleResource[],
+): string | undefined {
+  if (typeof approver === "string") {
+    return approver === by.id ? undefined : `${by.id} is not the approver; ${approverLabel(approver)} is`;
+  }
+  if (!by.groups?.includes(approver.group)) return `${by.id} is not in ${approverLabel(approver)}`;
+  if (by.id !== run.actor?.id) return undefined;
+  const someoneElse = personsOf(people).some(
+    ({ id }) => id !== by.id && principalOf(id, people)?.groups?.includes(approver.group),
+  );
+  return someoneElse ? OWN_CHANGE : undefined;
+}
+
+/** A declared resource as the people functions read it: only the runtime's people types count. */
+export type PeopleResource = Pick<DeclaredResource, "vendor" | "type" | "desired">;
+
+/** The group every agent is in, the runtime's own among them: no data file declares it. */
+export const AGENTS = "agents";
+
+/** 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 declared resources of one of the runtime's people types, by `desired`. */
+const peopleOfType = <T>(resources: readonly PeopleResource[], type: "person" | "agent" | "group") =>
+  resources.flatMap((r) => (r.vendor === "sanoma" && r.type === type ? [r.desired as T] : []));
+
+type PersonFields = { id: string; name?: string; email?: string; github?: string };
+type AgentFields = { id: string; onBehalfOf?: string };
+type GroupFields = { name: string; members: string[] };
+
+/** The groups a policy may name and a principal may be in: the declared ones and `agents`, sorted. */
+export const groupNamesOf = (resources: readonly PeopleResource[]): string[] =>
+  [...new Set([...peopleOfType<GroupFields>(resources, "group").map((g) => g.name), AGENTS])].toSorted();
+
+/** The declared people (`sanoma.person`), in the order declared: not agents, who never sign in. */
+export const personsOf = (resources: readonly PeopleResource[]): PersonFields[] =>
+  peopleOfType<PersonFields>(resources, "person");
+
+/** The ids of the declared people and agents (not the runtime's own). */
+export const principalIdsOf = (resources: readonly PeopleResource[]): string[] =>
+  [...personsOf(resources), ...peopleOfType<AgentFields>(resources, "agent")].map((p) => p.id);
+
+/** True when the data files declare a person, agent or group: then only a declared principal is admitted. */
+export const declaresPeople = (resources: readonly PeopleResource[]): boolean =>
+  resources.some((r) => r.vendor === "sanoma");
+
+/**
+ * The principal a declared person or agent (or one of the runtime's own agents) acts as, read
+ * from the data files' resources: its id, every group that lists it (and `agents` for an agent),
+ * sorted, and an agent's `onBehalfOf`. Undefined for an id nobody declares.
+ */
+export function principalOf(id: string, resources: readonly PeopleResource[]): Principal | undefined {
+  const agent = peopleOfType<AgentFields>(resources, "agent").find((a) => a.id === id);
+  const isAgent = agent !== undefined || RUNTIME_AGENTS.includes(id);
+  if (!isAgent && !peopleOfType<PersonFields>(resources, "person").some((p) => p.id === id)) return undefined;
+  const groups = peopleOfType<GroupFields>(resources, "group")
+    .filter((g) => g.members.includes(id))
+    .map((g) => g.name);
+  return {
+    id,
+    groups: [...new Set(isAgent ? [...groups, AGENTS] : groups)].toSorted(),
+    ...(agent?.onBehalfOf !== undefined && { onBehalfOf: agent.onBehalfOf }),
+  };
+}
+
+/**
+ * Who `name` is as an approver: a declared group's name (or `agents`) as `{ group }`, else a
+ * declared person's or agent's id; undefined when it is neither.
+ */
+export function approverOf(name: string, resources: readonly PeopleResource[]): Approver | undefined {
+  if (groupNamesOf(resources).includes(name)) return { group: name };
+  return principalOf(name, resources) && name;
+}
+
+/** True for two strings the same but for case: an email or a GitHub login. */
+const same = (a: string | undefined, b: string | undefined) =>
+  a !== undefined && b !== undefined && a.toLowerCase() === b.toLowerCase();
+
+/**
+ * The id of the declared person a sign-in vouches for, or undefined: by email first, then by
+ * GitHub login (each ignoring case), then by id. Never an agent's: agents do not sign in.
+ */
+export function personOf(
+  login: { email?: string; github?: string; id?: string },
+  resources: readonly PeopleResource[],
+): string | undefined {
+  const people = personsOf(resources);
+  return (
+    people.find((p) => same(p.email, login.email)) ??
+    people.find((p) => same(p.github, login.github)) ??
+    people.find((p) => login.id !== undefined && p.id === login.id)
+  )?.id;
 }
 
 /** Who may decide, as text: the person's id, or "group <name>". */
@@ -114,3 +348,42 @@ export const isLoopback = (host: string) =>
 /** Whether a driver's environment variable lets it run: set, or unset and optional. */
 export const credentialReady = ({ status, optional }: CredentialStatus): boolean =>
   status === "set" || (status === "missing" && optional);
+
+/**
+ * A workflow's name in a site's `api`: kebab-case made camelCase, `outbound-next` as
+ * `api.outboundNext`. `describeConfig` reports two workflows that come out the same, or one that
+ * comes out as a vendor's id or `data`, as a problem on the workflow.
+ */
+export const apiNameOf = (name: string): string => name.replace(/-([a-z0-9])/g, (_, c: string) => c.toUpperCase());
+
+/**
+ * A workflow as a site's `api` has it (`api.<apiNameOf(name)>`), started as the person on the
+ * page. Called, it starts a run and resolves with its output once the run ends, or rejects with
+ * its error; `start` gives the run's id at once, and the rest read runs of this workflow.
+ */
+export interface WorkflowFn<I, O> {
+  (input: I): Promise<O>;
+  /** Starts a run with this input, and answers with its id. */
+  start(input: I): Promise<{ runId: string }>;
+  /** The run's output once it ends, or its error; `run_running` when it has not ended within `waitMs` (at most 20 s). */
+  result(runId: string, waitMs?: number): Promise<O>;
+  /** The newest finished run's output, and when it finished (ms since the epoch); null when none has. */
+  latest(): Promise<{ runId: string; output: O; at: number } | null>;
+  /** Its latest runs, newest first. */
+  runs(query?: { limit?: number }): Promise<RunSummary[]>;
+  /** The run's approvals, decided and waiting. */
+  approvals(runId: string): Promise<ApprovalState[]>;
+  /** The run's ledger records, in order. */
+  ledger(runId: string): Promise<LedgerRecord[]>;
+}
+
+/** An operation a site may call directly (a read, or a collection's write), as the person on the page. */
+export type OpFn<I, O> = (input: I) => Promise<O>;
+
+/** A collection as a site's `api.data.<name>` has it: its four operations (`Saved`, `ListQuery`). */
+export interface CollectionApi<R> {
+  get: OpFn<{ key: string }, Saved<R> | null>;
+  list(query?: ListQuery<R>): Promise<Saved<R>[]>;
+  save: OpFn<{ record: R }, Saved<R>>;
+  delete: OpFn<{ key: string }, { deleted: boolean }>;
+}

package/src/sites.ts

@@ -0,0 +1,220 @@
+import { existsSync, readdirSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+import { childrenOf, type LintProblem, type Node, readSource, type SourceFile } from "./ast.ts";
+import { keyName } from "./datafile.ts";
+import type { ConfigDescription } from "./describe.ts";
+import { stringValue, unwrap } from "./outline.ts";
+import { filesUnder, isDirectory } from "./paths.ts";
+import { apiNameOf, DATA_VENDOR, SITE_NAME } from "./shared.ts";
+
+// What a company's sites call, read from their source with oxc and never run: the reverse index
+// a workflow's page shows as Used by, and the names `sanoma check` holds to the config.
+
+/** A call a site makes, as written in its source. */
+export interface SiteCall {
+  /** What it calls: a workflow, a collection (`api.data.<name>.<op>`) or an operation (`api.<vendor>.<resource>.<op>`). */
+  kind: "workflow" | "collection" | "op";
+  /**
+   * The workflow's name (`RunForm`'s `workflow`, or the workflow whose `apiNameOf` is the name
+   * `api` gives; that name itself when none is), the collection's name, or the operation's id.
+   */
+  target: string;
+  /** `<RunForm workflow="…" />` from `@sanoma-ai/app/ui`, or a call on `api` from `sanoma/site`. */
+  via: "RunForm" | "api";
+  /** The file, relative to the config's root, with `/`: `sites/sales/routes/index.tsx`. */
+  file: string;
+  /** From 1. */
+  line: number;
+  /** From 1, in UTF-16 code units. */
+  column: number;
+  /**
+   * The path of the page the file is, from its `createFileRoute` (or `createLazyFileRoute`) id: groups and pathless
+   * segments left out, no trailing slash (`/sites/sales`). Absent for a file that is no page,
+   * such as a component's.
+   */
+  page?: string;
+}
+
+/** A site, `sites/<name>/`, and what it calls. */
+export interface SiteEntry {
+  /** Its folder's name, where it is mounted: `/sites/<name>`. */
+  name: string;
+  /** `defineSite({ title })` in its `site.ts`, when that is a string literal. */
+  title?: string;
+  /** Its calls, by file and then in the file's order. */
+  calls: SiteCall[];
+  /** Each call to a workflow, a collection or an operation the config does not have, or to an operation a page may not call directly, at its file. */
+  problems: (LintProblem & { file: string })[];
+}
+
+/** Where a site's code is: its pages and its components. */
+const SITE_DIRS = ["routes", "components"];
+/** Where `api` 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 UI_SOURCES: ReadonlySet<string> = new Set(["@sanoma-ai/app/ui"]);
+const KIND_NAMES = { workflow: "workflow", collection: "collection", op: "operation" } as const;
+/** What makes a route from its id, whose first argument is the id. */
+const ROUTE_MAKERS: ReadonlySet<string> = new Set(["createFileRoute", "createLazyFileRoute"]);
+
+/**
+ * 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="…" />` whose `RunForm` is imported from `@sanoma-ai/app/ui`, and
+ * each use of `api` 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
+ * template with holes, a computed member) is skipped, as is a use through a namespace import or a
+ * destructured `api`. A call to what `description` does not have, or to an operation a page may
+ * not call directly, is a problem.
+ */
+export function readSites(
+  root: string | undefined,
+  description: Pick<ConfigDescription, "workflows" | "collections" | "ops">,
+): 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]));
+  // A workflow's api name to its name: two of one api name are a problem on the workflows.
+  const byApiName = new Map(description.workflows.map((wf) => [apiNameOf(wf.name), wf.name]));
+
+  /** A call as written, resolved as the app's `callApi` resolves it, with why it would fail. */
+  const resolve = ({ kind, name, via, ...at }: Written): { call: SiteCall; problem?: string } => {
+    const target = kind === "workflow" && via === "api" ? (byApiName.get(name) ?? name) : name;
+    const found =
+      kind === "workflow"
+        ? via === "api"
+          ? byApiName.has(name)
+          : workflows.has(name)
+        : kind === "collection"
+          ? collections.has(name)
+          : ops.has(name);
+    const problem = !found
+      ? `calls ${KIND_NAMES[kind]} "${target}", which does not exist`
+      : kind === "op" && !ops.get(name)!.direct
+        ? `calls operation "${target}", which a page may not call directly: start a workflow that calls it`
+        : undefined;
+    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)
+    .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 title = titleOf(join(dir, name, "site.ts"));
+      const calls = resolved.map((r) => r.call);
+      const problems = resolved.flatMap(({ call: { file, line, column }, problem }) =>
+        problem === undefined ? [] : [{ file, line, column, message: problem }],
+      );
+      return { name, ...(title !== undefined && { title }), calls, problems };
+    });
+}
+
+/** 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[] {
+  const api = importedAs(program, SITE_SOURCES, "api");
+  const runForm = importedAs(program, UI_SOURCES, "RunForm");
+  if (!api.size && !runForm.size) return [];
+  const found: Omit<Written, "page">[] = [];
+  let page: string | undefined;
+  const visit = (node: Node) => {
+    if (!node) return;
+    if (node.type === "MemberExpression") {
+      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) {
+      const callee = unwrap(node.callee);
+      if (callee?.type === "Identifier" && ROUTE_MAKERS.has(callee.name)) {
+        const id = stringValue(node.arguments[0]);
+        if (id !== undefined) page = pageOf(id);
+      }
+    } 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",
+      );
+      const value = attribute?.value?.type === "JSXExpressionContainer" ? attribute.value.expression : attribute?.value;
+      const name = stringValue(value);
+      if (name !== undefined) found.push({ kind: "workflow", name, via: "RunForm", file, ...at(node.start) });
+    }
+    for (const child of childrenOf(node)) visit(child);
+  };
+  visit(program);
+  return found.map((use) => (page === undefined ? use : { ...use, page }));
+}
+
+/** 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"> | undefined {
+  const path: string[] = [];
+  let node = member;
+  while (node?.type === "MemberExpression") {
+    const key: string | undefined = node.computed ? stringValue(node.property) : node.property.name;
+    if (key === undefined) return undefined;
+    path.unshift(key);
+    node = unwrap(node.object);
+  }
+  if (node?.type !== "Identifier" || !api.has(node.name)) return undefined;
+  const [first, second] = path as [string, ...string[]];
+  if (first === DATA_VENDOR) return path.length === 3 ? { kind: "collection", name: second! } : undefined;
+  if (path.length === 3) return { kind: "op", name: path.join(".") };
+  return path.length <= 2 ? { kind: "workflow", name: first } : undefined;
+}
+
+/** The local names `imported` has in the file, imported as a value from one of `sources`. */
+function importedAs(program: Node, sources: ReadonlySet<string>, imported: string): Set<string> {
+  const names = new Set<string>();
+  for (const statement of program.body) {
+    if (statement.type !== "ImportDeclaration" || statement.importKind === "type") continue;
+    if (!sources.has(statement.source.value)) continue;
+    for (const s of statement.specifiers) {
+      if (s.type === "ImportSpecifier" && s.importKind !== "type" && keyName(s.imported) === imported) {
+        names.add(s.local.name);
+      }
+    }
+  }
+  return names;
+}
+
+/** A site's title: the string `title` its `site.ts` exports by default through `defineSite`. */
+function titleOf(path: string): string | undefined {
+  const file = readSource(path);
+  if (typeof file === "string") return undefined;
+  const defineSite = importedAs(file.program, SITE_SOURCES, "defineSite");
+  const exported = file.program.body.find((s: Node) => s.type === "ExportDefaultDeclaration")?.declaration;
+  const call = unwrap(exported);
+  const callee = unwrap(call?.callee);
+  const options = unwrap(call?.arguments?.[0]);
+  if (call?.type !== "CallExpression" || callee?.type !== "Identifier" || !defineSite.has(callee.name))
+    return undefined;
+  if (options?.type !== "ObjectExpression") return undefined;
+  const title = options.properties.find(
+    (p: Node) => p.type === "Property" && !p.computed && keyName(p.key) === "title",
+  );
+  return stringValue(title?.value);
+}
+
+/**
+ * A route's path from its id, as the router serves it: `(group)` and `_pathless` segments left
+ * out, a `_` that ends a segment dropped, and no trailing slash.
+ */
+const pageOf = (id: string): string =>
+  `/${id
+    .split("/")
+    .filter((s) => s && !/^\(.*\)$/.test(s) && !s.startsWith("_"))
+    .map((s) => s.replace(/_$/, ""))
+    .join("/")}`;
+
+/** A site's source file: `.ts` or `.tsx`, but a test or a declaration. */
+const isSource = (name: string) => /\.tsx?$/.test(name) && !/\.(test|d)\.tsx?$/.test(name);

package/src/source.ts

@@ -0,0 +1,82 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { z } from "zod";
+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.
+
+/** A company's repository, as the runtime writes to it. */
+export interface Source {
+  /** The repository's root directory. */
+  root: string;
+  /**
+   * Records the files at `paths`, relative to `root`, as one change by `author` (who made it, as
+   * the app names them: a login or a typed name). Its revision; undefined when nothing changed.
+   */
+  commit(change: {
+    paths: string[];
+    message: string;
+    author: string;
+  }): { revision: string } | undefined | Promise<{ revision: string } | undefined>;
+  /** The revision `ref` names, the checked-out one by default. */
+  head(ref?: string): string | Promise<string>;
+  /** Pushes `ref` to the repository at `url`, signed in with `token`. */
+  push?(target: { url: string; token: string; ref: string }): void | Promise<void>;
+}
+
+/**
+ * The built-in operation `sanoma.source.resolve`: the commit `ref` names in the repository at
+ * `url` now, by `git ls-remote` (a branch first, then a tag, peeled; a full commit id is itself).
+ * Apply calls it to fill a host's revision before it plans, and drift to see a merge. `resolveConfig`
+ * registers it when a connector declares a host type.
+ */
+export const sourceOps = defineConnector("sanoma", {
+  source: {
+    resolve: {
+      effect: "read",
+      idempotent: true,
+      description: "Resolve a branch or tag of a git repository to the commit it names now",
+      input: z.object({ url: z.string().min(1), ref: z.string().min(1) }),
+      output: z.object({ revision: z.string() }),
+      target: ({ url, ref }: { url: string; ref: string }) => `${url}#${ref}`,
+    },
+  },
+});
+
+export const SOURCE_RESOLVE = "sanoma.source.resolve" satisfies typeof sourceOps.source.resolve.id;
+
+/** The driver of `sanoma.source.resolve`: git on this machine, with its own credential helpers. */
+export const sourceDriver = defineDriver(sourceOps, {
+  source: { resolve: async ({ url, ref }) => ({ revision: await resolveRevision(url, ref) }) },
+});
+
+const COMMIT = /^[0-9a-f]{40}([0-9a-f]{24})?$/;
+
+/** The commit `ref` (a branch, a tag, `HEAD`, a full ref or a commit id) names in the repository at `url`. */
+export async function resolveRevision(url: string, ref: string): Promise<string> {
+  if (COMMIT.test(ref)) return ref;
+  const { stdout } = await promisify(execFile)("git", ["ls-remote", "--", url, ref, `${ref}^{}`], {
+    // Never a prompt for credentials: a repository that needs them and has none fails.
+    env: { ...process.env, GIT_TERMINAL_PROMPT: "0" },
+    timeout: 30_000,
+  }).catch((err: { stderr?: string; message: string }) => {
+    throw new DriverError(`git ls-remote ${url} failed: ${err.stderr?.trim() || err.message}`, {
+      retryable: true,
+      cause: err,
+    });
+  });
+  const refs = new Map(
+    stdout.split("\n").flatMap((line) => {
+      const [sha, name] = line.split("\t");
+      return sha && name ? [[name, sha] as const] : [];
+    }),
+  );
+  for (const name of [`refs/heads/${ref}`, `refs/tags/${ref}^{}`, `refs/tags/${ref}`, ref]) {
+    const sha = refs.get(name);
+    if (sha) return sha;
+  }
+  throw new DriverError(`${url} has no branch or tag ${ref}`, { retryable: false, vendorCode: "no_such_ref" });
+}

package/src/version.ts

@@ -6,15 +6,16 @@ import { jsonSchemaOf, opIdsOf, type WorkflowDefinition } from "./define.ts";
 import { upFrom } from "./paths.ts";
 
 /** This package's version. A unit test keeps it equal to package.json. */
-export const RUNTIME_VERSION = "0.1.0";
+export const RUNTIME_VERSION = "0.4.0";
 
 /**
  * The sequence of DBOS calls the runtime makes around each `ctx` call: policy step, approval
  * events and messages, the driver step. Bump it whenever that sequence changes, even without a
  * 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).
  */
-export const STEP_LAYOUT = 2;
+export const STEP_LAYOUT = 3;
 
 let dbosVersion: string | undefined;