@sanoma-ai/workflows 0.1.0 → 0.4.0

package/src/describe.ts

@@ -1,26 +1,74 @@
 import type { z } from "zod";
 import { type LintProblem, readSource, type SourceFile } from "./ast.ts";
-import { resolveConfig, type SanomaConfig } from "./config.ts";
+import { type Field, recordSchemaOf } from "./collection.ts";
+import { connectorsOf, resolveConfig, rootOf, type SanomaConfig } from "./config.ts";
 import { type Builtin, jsonSchemaOf, opIdsOf, type Use } from "./define.ts";
-import { DRIFT_WORKFLOW } from "./drift.ts";
+import { isDirect } from "./direct.ts";
 import { lintWorkflow } from "./lint.ts";
 import { type Effect, VENDOR, type VendorInfo } from "./op.ts";
 import { type Outline, outlineWithSource } from "./outline.ts";
 import { allowAll, policyOpOf } from "./policy.ts";
 import { type ResourceFields, resourceTypesOf } from "./resource.ts";
-import { type DeclaredResource, readDataFiles, type ResourceProblem } from "./resources.ts";
+import {
+  type DataFiles,
+  type DeclaredCollection,
+  type DeclaredResource,
+  readDataFiles,
+  type ResourceProblem,
+} from "./resources.ts";
+import { apiNameProblem } from "./sdk.ts";
+import { apiNameOf, BUILT_IN_WORKFLOWS, DATA_VENDOR, problemLine } from "./shared.ts";
+import { readSites, type SiteEntry } from "./sites.ts";
 
 // `@sanoma-ai/workflows/describe`: what a UI renders from, apart from the main entry.
 export { outlineWorkflow, type Outline, type OutlineNode, type Span } from "./outline.ts";
 // The reader parses data files with oxc-parser too.
 export type { LintProblem } from "./ast.ts";
 export {
+  admit,
   readDataFiles,
-  readResources,
+  readPeople,
   type DataFiles,
+  type DeclaredCollection,
+  type DeclaredPeople,
   type DeclaredResource,
   type ResourceProblem,
 } from "./resources.ts";
+// The writer: setting a resource's fields in its data file, and rendering a new one.
+export { formatOptions, renderDataFile, setFields, type DataFileContent } from "./writer.ts";
+export { Reference, type DataValue } from "./datafile.ts";
+
+/**
+ * The resources the config's data files declare, read without importing or running them; throws
+ * one error listing every problem, each at `file:line:column`, for a test or CI to fail on.
+ * `describeConfig` lists the same, with the problems beside them instead.
+ */
+export function readResources(config: SanomaConfig): DeclaredResource[] {
+  const { resources, problems } = readDataFiles(rootOf(config), connectorsOf(config));
+  if (problems.length) {
+    const lines = problems.map((p) => `  ${problemLine(p)}`);
+    throw new Error(`The resources' data files have problems:\n${lines.join("\n")}`);
+  }
+  return resources;
+}
+export {
+  LOCKFILE,
+  readLockfile,
+  serializeLockfile,
+  writeLockfile,
+  diffLockfiles,
+  type Binding,
+  type Bindings,
+  type Rebind,
+} from "./lockfile.ts";
+// What the sites call, read from their source: a workflow's Used by.
+export { readSites, type SiteCall, type SiteEntry } from "./sites.ts";
+// The generated SDK, `.sanoma/api.ts`: a site's `api` typed from this description.
+export { API_FILE, generateApi, writeApi, writeGenerated } from "./sdk.ts";
+// The Cedar schema, `.sanoma/schema.cedarschema`: what a company's policies are validated and decided against.
+export { SCHEMA_FILE, schemaOf, schemaText, type CedarSchemaJson } from "./schema.ts";
+// The apply workflow's plan and report, which the app renders.
+export type { ApplyInput, ApplyPlan, ApplyReport, ApplyResult, PlanAnswer, PlanStep } from "./apply.ts";
 
 /** What a workflow is, read from its definition: enough to draw a start form and show what it may call. */
 export interface WorkflowEntry {
@@ -28,7 +76,7 @@ export interface WorkflowEntry {
   title?: string;
   trigger: "manual";
   /**
-   * Set for a workflow the runtime adds itself, `drift`, rather than the config: a label. It
+   * Set for a workflow the runtime adds itself, `drift`, `apply` or `call`, rather than the config: a label. It
    * starts like any other.
    */
   builtin?: true;
@@ -69,6 +117,8 @@ export interface OpEntry {
   description?: string;
   /** How a scenario's steps name it: Cucumber expressions over its input's fields. */
   phrases?: { given?: string; expect?: string };
+  /** Whether it may be called directly, outside a run (`isDirect`): the one rule, read here, never derived again. */
+  direct: boolean;
   /** What a call sends, as JSON Schema (`io: "input"`: fields with defaults are optional). */
   input: Record<string, unknown>;
   /** What a call returns once its schema has parsed the vendor's reply (`io: "output"`). */
@@ -96,8 +146,8 @@ export interface ResourceTypeEntry {
   vendor: string;
   type: string;
   title: string;
-  /** How a declared resource's import id is made, such as `name` or `repository_id:pattern`. */
-  identity: string;
+  /** How a declared resource's identity is made, such as `name` or `repository_id:pattern`; absent when it is found only by its binding. */
+  identity?: string;
   /** Its flagged fields, by dotted path. */
   fields: ResourceFields;
   /**
@@ -105,10 +155,26 @@ export interface ResourceTypeEntry {
    * `sanoma:resource-type/<id>`: the operations' contracts `$ref` it instead of repeating it.
    */
   schema: Record<string, unknown>;
-  /** Its operations' ids: `<id>.import` and `<id>.read`. */
+  /** Its operations' ids, sorted: `<id>.import` and `<id>.read`, and for a writable type its change operations. */
   ops: string[];
 }
 
+/** A collection the config declares (`collection()`). */
+export interface CollectionEntry {
+  name: string;
+  title?: string;
+  /** The field each record is found by. */
+  key: string;
+  /** Its fields as declared. */
+  fields: Record<string, Field>;
+  /** What `save` accepts, as JSON Schema, with `$id` `sanoma:collection/<name>`. */
+  record: Record<string, unknown>;
+  /** Its operations' ids: `data.<name>.get`, `.list`, `.save` and `.delete`. */
+  ops: string[];
+  /** Where `resources/data.ts` declares it, read as the data files are; absent for one declared elsewhere. */
+  declared?: DeclaredCollection;
+}
+
 /**
  * A plain-JSON description of what a config can do: its workflows, the operations they call,
  * and whether a policy gates them. The app server builds it from the config and sends it to the
@@ -124,15 +190,27 @@ export interface ConfigDescription {
   vendors: Record<string, VendorEntry>;
   /** The resource types the connectors declare, by `id`. */
   resourceTypes: ResourceTypeEntry[];
+  /** The config's collections, by name. */
+  collections: CollectionEntry[];
   /**
    * The resources the data files under `resources/` declare, by file and then in file order,
    * less any with a problem and any that names one.
    */
   resources: DeclaredResource[];
+  /** Each binding in the lockfile (`LOCKFILE`) whose key no data file declares, as `readDataFiles` reports it. */
+  orphans: DataFiles["orphans"];
   /** What is wrong in the data files (`readDataFiles`), each at its file, relative to the root, line and column. A workflow's are on its entry. */
   problems: ResourceProblem[];
-  /** `defined` is false for `allowAll`. */
-  policy: { defined: boolean; version?: string };
+  /**
+   * `defined` when the root has `policies/**\/*.cedar` (else the policy is `allowAll`), with their
+   * `version`, or while they have `problems` (`policyProblems`), none: then every call and start is refused.
+   */
+  policy: { defined: boolean; version?: string; problems?: string[] };
+  /**
+   * The sites under `sites/`, by name, with what each calls (`readSites`), and its calls to what
+   * the config does not have as its problems; none when the root has no `sites/`.
+   */
+  sites: SiteEntry[];
 }
 
 /**
@@ -140,7 +218,8 @@ export interface ConfigDescription {
  * credentials (`SanomaClient.credentials` gives their statuses) and what is wrong in a workflow's
  * file, which the worker refuses when it reads the outline: that is data, on each workflow's
  * entry, as the data files' problems are, `problems`, beside the resources read without any.
- * Each workflow's file is read and parsed once, however many workflows it defines.
+ * Each workflow's file is read and parsed once, however many workflows it defines. The sites'
+ * code is read too (`readSites`): what each calls, and its calls to what the config lacks as its problems.
  */
 export function describeConfig(config: SanomaConfig): ConfigDescription {
   const resolved = resolveConfig(config);
@@ -151,11 +230,11 @@ export function describeConfig(config: SanomaConfig): ConfigDescription {
     const { id, info } = connector[VENDOR];
     vendors[id] ??= vendorEntry(id, info, resolved.fakes.has(id));
   }
-  const resources = resourceTypesOf(config.connectors);
+  const resources = resourceTypesOf(connectorsOf(config));
   // Each resource type's state is described once, on its entry, and referenced from its operations.
   const refs = new Map<z.ZodType, string>([...resources].map(([id, r]) => [r.schema, resourceTypeUri(id)]));
   const resourceTypes: ResourceTypeEntry[] = [...resources]
-    .map(([id, { vendor, type, title, identity, fields, schema }]) => ({
+    .map(([id, { vendor, type, title, identity, fields, schema, ops }]) => ({
       id,
       vendor,
       type,
@@ -163,15 +242,32 @@ export function describeConfig(config: SanomaConfig): ConfigDescription {
       identity,
       fields,
       schema: { $id: resourceTypeUri(id), ...toJsonSchema(schema, `${id} state`, "output") },
-      ops: [`${id}.import`, `${id}.read`],
+      ops: Object.keys(ops)
+        .map((name) => `${id}.${name}`)
+        .toSorted(),
     }))
     .toSorted((a, b) => a.id.localeCompare(b.id));
 
+  const dataFiles = readDataFiles(resolved.root, connectorsOf(config), resources);
+  const declared = new Map(dataFiles.collections.map((d) => [d.name, d]));
+  const collections: CollectionEntry[] = [...resolved.collections.values()]
+    .map((c) => ({
+      name: c.name,
+      ...(c.title !== undefined && { title: c.title }),
+      key: c.key,
+      fields: c.fields,
+      record: { $id: `sanoma:collection/${c.name}`, ...toJsonSchema(recordSchemaOf(c), `${c.name} record`, "input") },
+      ops: [c.get, c.list, c.save, c.delete].map((op) => op.id),
+      ...(declared.has(c.name) && { declared: declared.get(c.name) }),
+    }))
+    .toSorted((a, b) => a.name.localeCompare(b.name));
+
   const ops: OpEntry[] = [...resolved.ops.values()].map((op) => ({
     ...policyOpOf(op),
     idempotent: op.idempotent,
     description: op.description,
     ...(op.phrases && { phrases: op.phrases }),
+    direct: isDirect(op, resolved.types),
     input: toJsonSchema(op.input, `${op.id} input`, "input", refs),
     output: toJsonSchema(op.output, `${op.id} output`, "output", refs),
   }));
@@ -184,18 +280,18 @@ export function describeConfig(config: SanomaConfig): ConfigDescription {
     const { outline, source, found } = outlineWithSource(wf, file);
     // What the lint does not report: the file unread, or no workflow of this name in it.
     const own = "error" in outline && !found && (typeof file === "string" || !file.problems.length);
-    const problems =
-      wf.name === DRIFT_WORKFLOW
-        ? []
-        : [
-            ...(typeof file === "string" ? [] : lint(file)),
-            ...(own ? [{ line: 1, column: 1, message: outline.error }] : []),
-          ];
+    const builtin = BUILT_IN_WORKFLOWS.has(wf.name);
+    const problems = builtin
+      ? []
+      : [
+          ...(typeof file === "string" ? [] : lint(file)),
+          ...(own ? [{ line: 1, column: 1, message: outline.error }] : []),
+        ];
     return {
       name: wf.name,
       title: wf.title,
       trigger: wf.trigger,
-      ...(wf.name === DRIFT_WORKFLOW && { builtin: true as const }),
+      ...(builtin && { builtin: true as const }),
       input: toJsonSchema(wf.input, `${wf.name} input`, "input"),
       ops: opIdsOf(wf),
       builtins: (wf.uses as Use[]).filter((u): u is Builtin => typeof u === "string"),
@@ -206,7 +302,7 @@ export function describeConfig(config: SanomaConfig): ConfigDescription {
     };
   });
   workflows.sort((a, b) => a.name.localeCompare(b.name));
-  const dataFiles = readDataFiles(resolved.root, config.connectors, resources);
+  addApiNameProblems(workflows, new Set(ops.map((op) => op.vendor)));
 
   return {
     appName: resolved.appName,
@@ -215,15 +311,42 @@ export function describeConfig(config: SanomaConfig): ConfigDescription {
     ops,
     vendors,
     resourceTypes,
+    collections,
     resources: dataFiles.resources,
+    orphans: dataFiles.orphans,
     problems: dataFiles.problems,
     policy: {
       defined: resolved.policy !== allowAll,
       ...(resolved.policy.version === undefined ? {} : { version: resolved.policy.version }),
+      ...(resolved.policyProblems.length ? { problems: resolved.policyProblems } : {}),
     },
+    sites: readSites(resolved.root, { workflows, collections, ops }),
   };
 }
 
+/**
+ * A site's `api` names each workflow `apiNameOf(name)` beside the vendors' operations and the
+ * collections (`api.data`), so a workflow whose name comes out as another's, a vendor's id or
+ * `data` is a problem, at 1:1 of its file. A built-in is never the one renamed.
+ */
+function addApiNameProblems(workflows: WorkflowEntry[], vendors: ReadonlySet<string>) {
+  for (const wf of workflows) {
+    if (wf.builtin) continue;
+    const api = apiNameOf(wf.name);
+    const others = workflows.filter((other) => other !== wf && apiNameOf(other.name) === api);
+    const taken = others.length
+      ? `as workflow ${others.map((other) => `"${other.name}"`).join(" and ")} is`
+      : api === DATA_VENDOR
+        ? "which is the collections'"
+        : vendors.has(api)
+          ? `which is the vendor ${api}'s operations`
+          : api === "then"
+            ? "which a promise would take for its own"
+            : undefined;
+    if (taken) wf.problems.push({ line: 1, column: 1, message: apiNameProblem(api, taken) });
+  }
+}
+
 /** `fn`, called once per argument for as long as the returned function lives. */
 function memoised<A, R>(fn: (arg: A) => R): (arg: A) => R {
   const seen = new Map<A, R>();

package/src/direct.ts

@@ -0,0 +1,15 @@
+import type { Op } from "./op.ts";
+import { isResourceOp } from "./resource.ts";
+import { DATA_VENDOR } from "./shared.ts";
+
+/**
+ * Whether an operation may be called directly, outside a run (`SanomaClient.call`), as the
+ * person: a collection's (`data.<name>.<op>`), or a `read` that is neither the runtime's own
+ * (the vendor `sanoma`) nor a resource type's (`isResourceOp`), which only drift and apply call.
+ * Anything else (an effect at a vendor) is a workflow's. The one rule: the built-in `call`
+ * workflow, the SDK and the app read it, from here or from `OpEntry.direct`, and never derive it.
+ */
+export const isDirect = (
+  op: Pick<Op, "vendor" | "resource" | "effect">,
+  types: ReadonlyMap<string, unknown>,
+): boolean => op.vendor === DATA_VENDOR || (op.effect === "read" && op.vendor !== "sanoma" && !isResourceOp(op, types));

package/src/drift.ts

@@ -2,9 +2,10 @@ import { z } from "zod";
 import { defineWorkflow, type WorkflowDefinition } from "./define.ts";
 import { isRunControlError } from "./errors.ts";
 import type { Op } from "./op.ts";
-import { type DriftField, diffDeclared, type Resource } from "./resource.ts";
+import { type DriftField, diffDeclared, fieldPathOf, type Resource, valueAt } from "./resource.ts";
 import type { DeclaredResource, ResourceProblem } from "./resources.ts";
 import { type DRIFT_WORKFLOW, errorMessage } from "./shared.ts";
+import { SOURCE_RESOLVE, type sourceOps } from "./source.ts";
 
 export type { DriftField } from "./resource.ts";
 export { DRIFT_WORKFLOW } from "./shared.ts";
@@ -14,11 +15,12 @@ export { DRIFT_WORKFLOW } from "./shared.ts";
 // vendor call goes through `ctx`: the policy sees each (effect `read`) and the ledger records it.
 
 /**
- * How a declared resource compares: `clean` when every declared field holds its declared value,
- * `drifted` when one does not, `gone` when the vendor has no such object, and `error` when it
- * could not be read (the vendor's error, a policy denial, or no driver for its type).
+ * How a declared resource compares: `clean` when every declared field of its bound object holds
+ * its declared value, `drifted` when one does not, `gone` when the vendor no longer has its bound
+ * object, `absent` when it is bound to none (whether or not its identity finds one: `found`), and
+ * `error` when it could not be read (the vendor's error, a policy denial, or no driver for its type).
  */
-export type DriftStatus = "clean" | "drifted" | "gone" | "error";
+export type DriftStatus = "clean" | "drifted" | "gone" | "absent" | "error";
 
 /** One declared resource in a drift report. */
 export interface DriftResult {
@@ -27,9 +29,13 @@ export interface DriftResult {
   /** Its type within the vendor, such as `repository`. */
   type: string;
   vendor: string;
-  /** Its import id. */
+  /** What people call it: its identity, else its export's name. */
   name: string;
   status: DriftStatus;
+  /** The vendor's id of the object the lockfile binds it to; absent when unbound. */
+  binding?: string;
+  /** For `absent`: the binding id of the object its identity found, which apply may bind it to. */
+  found?: string;
   /** The declared fields that differ; empty unless `drifted`. */
   fields: DriftField[];
   /** Why it could not be read, for `error`. */
@@ -59,7 +65,7 @@ export const DriftInput = z.object({}).strict();
  * write-only values, and the problems.
  */
 export interface DriftDeclared {
-  resources: Pick<DeclaredResource, "id" | "vendor" | "type" | "name" | "desired" | "refs">[];
+  resources: Pick<DeclaredResource, "id" | "vendor" | "type" | "name" | "identity" | "binding" | "desired" | "refs">[];
   problems: ResourceProblem[];
 }
 
@@ -67,9 +73,99 @@ type State = Record<string, unknown>;
 
 // A resource type's import, as `ctx` gives it: by vendor and type, both only known per run.
 type ImportOp = Op<string, string, "import", { id: string }, { id: string; gone: boolean; state?: State }>;
+// The built-in `sanoma.source.resolve`, which a host's check calls for the commit its ref names now.
+export type ResolveOp = typeof sourceOps.source.resolve;
+
+/** A clone URL (a scheme's, or scp-like `user@host:path`): what a `by` field of a host's source holds, told from an id. */
+const CLONE_URL = /^((https?|ssh|git|file):\/\/|[\w.-]+@[\w.-]+:)/;
 
 /** What one import found: the object's state, that it is gone, or why it could not be read. */
-type Found = { state: State } | { gone: true } | { error: string };
+export type Found = { state: State } | { gone: true } | { error: string };
+/** What a host's ref names now, or why it could not be resolved. */
+export type Revision = { revision: string } | { error: string };
+
+// What drift and apply share. Observing a resource is one `ctx` call, which a workflow makes in
+// its own `run` (the outline draws only those): `observeBy` says what each import is called with,
+// `observed` reads its answer, and `compare` turns what every import found into drift's results.
+
+/** The `import` ops of the types among `ops` with a driver, by type, sorted: what observing them uses. */
+export function importsOf(
+  types: ReadonlyMap<string, Resource>,
+  ops: ReadonlyMap<string, Op>,
+  drivers: ReadonlyMap<string, unknown>,
+): ImportOp[] {
+  return [...types.keys()].toSorted().flatMap((type) => {
+    const op = ops.get(`${type}.import`);
+    return op && drivers.has(op.id) ? [op as ImportOp] : [];
+  });
+}
+
+/**
+ * What a declared resource is observed by: the import id (`by`, default its binding, else its
+ * identity), or without one what it is found to be: `gone` for none, `error` when its type is
+ * not the connectors' or has no import among `imports`.
+ */
+export function observeBy(
+  { vendor, type, binding, identity }: Pick<DeclaredResource, "vendor" | "type" | "binding" | "identity">,
+  types: ReadonlyMap<string, Resource>,
+  imports: readonly Pick<Op, "id">[],
+  by = binding ?? identity,
+): { id: string } | Found {
+  const key = `${vendor}.${type}`;
+  if (!types.has(key)) return { error: `the config's connectors declare no resource type ${key}` };
+  if (!imports.some((op) => op.id === `${key}.import`)) return { error: `no driver for ${key}.import` };
+  return by === undefined ? { gone: true } : { id: by };
+}
+
+/** What an import's answer found. */
+export const observed = (out: { gone: boolean; state?: State }): Found =>
+  out.gone || !out.state ? { gone: true } : { state: out.state };
+
+/**
+ * Each declared resource against what its import `found`: `error`, `absent` (unbound, with the
+ * binding id of what its identity found as `found`), `gone`, else the state and the declared
+ * fields compared by `diffDeclared`, a reference against the state of the resource it names
+ * (so GitHub's node id for a repository counts as its name). A host with a `revisions` entry
+ * also compares its revision against the commit its ref names now (or is that entry's `error`).
+ */
+export function compare(
+  types: ReadonlyMap<string, Resource>,
+  resources: DriftDeclared["resources"],
+  found: ReadonlyMap<string, Found>,
+  revisions: ReadonlyMap<string, Revision> = new Map(),
+): DriftResult[] {
+  return resources.map(({ id, vendor, type, name, binding, desired, refs }): DriftResult => {
+    const row = { id, type, vendor, name, ...(binding !== undefined && { binding }) };
+    const now = found.get(id)!;
+    if ("error" in now) return { ...row, status: "error", fields: [], error: now.error };
+    const resource = types.get(`${vendor}.${type}`)!;
+    if (binding === undefined) {
+      return {
+        ...row,
+        status: "absent",
+        fields: [],
+        ...("state" in now && { found: resource.bindingId(now.state) }),
+      };
+    }
+    if ("gone" in now) return { ...row, status: "gone", fields: [] };
+    // Each reference, by where it is: the values the vendor may hold there for its resource.
+    const accept: Record<string, unknown[]> = {};
+    for (const [at, target] of Object.entries(refs)) {
+      const by = resource.fields.references?.[fieldPathOf(at)]?.by ?? [];
+      const named = found.get(target);
+      if (named && "state" in named) accept[at] = by.map((field) => named.state[field]).filter((v) => v != null);
+    }
+    const fields = diffDeclared(resource, now.state, desired, accept);
+    const resolved = revisions.get(id);
+    if (resolved && "error" in resolved) return { ...row, status: "error", fields: [], error: resolved.error };
+    // A host whose state does not say which commit it runs is not compared.
+    const actual = resource.host?.outputs(now.state).revision;
+    if (resolved && actual !== undefined && actual !== resolved.revision) {
+      fields.push({ path: resource.host!.revision, desired: resolved.revision, actual });
+    }
+    return { ...row, status: fields.length ? "drifted" : "clean", fields };
+  });
+}
 
 /**
  * The drift workflow for a config: it `uses` the `import` of every resource type the connectors
@@ -77,11 +173,13 @@ type Found = { state: State } | { gone: true } | { error: string };
  * files. `resolveConfig` adds it to a config whose connectors declare resource types, with
  * `declared`, the step that reads the data files.
  *
- * A run reads the data files (`declared`, recorded as a step, so a replay checks the same list),
- * then imports each resource by its import id (its `name`), in the files' order: one vendor call
- * each. An import that says gone is `gone`. Else the state and the declared fields are compared
- * by `diffDeclared`, a reference against the state of the resource it names, read in the same run
- * (so GitHub's node id for a repository counts as its name). A failed call is that resource's
+ * A run reads the data files and the lockfile (`declared`, recorded as a step, so a replay checks
+ * the same list), then imports each resource by its binding, else by its identity, in the files'
+ * order: one vendor call each, none for a resource with neither. A bound resource whose import
+ * says gone is `gone`; an unbound one is `absent`, with the binding id of what its identity found
+ * as `found`. Else the state and the declared fields are compared by `diffDeclared`, a reference
+ * against the state of the resource it names, read in the same run (so GitHub's node id for a
+ * repository counts as its name). A failed call is that resource's
  * `error`, and the run goes on to the next; a failure that ends the run (`isRunControlError`)
  * ends it.
  */
@@ -90,16 +188,10 @@ export function driftWorkflow(
   ops: ReadonlyMap<string, Op>,
   drivers: ReadonlyMap<string, unknown>,
   declared: () => Promise<DriftDeclared>,
-): WorkflowDefinition<readonly ImportOp[], typeof DriftInput> {
-  const uses = [...types.keys()].toSorted().flatMap((type) => {
-    const op = ops.get(`${type}.import`);
-    return op && drivers.has(op.id) ? [op as ImportOp] : [];
-  });
-  // Why a resource of each type cannot be read, if it cannot.
-  const unreadable = new Map<string, string>();
-  for (const type of types.keys()) {
-    if (!uses.some((op) => op.id === `${type}.import`)) unreadable.set(type, `no driver for ${type}.import`);
-  }
+): WorkflowDefinition<readonly (ImportOp | ResolveOp)[], typeof DriftInput> {
+  const imports = importsOf(types, ops, drivers);
+  const resolve = ops.get(SOURCE_RESOLVE) as ResolveOp | undefined;
+  const uses = [...imports, ...(resolve ? [resolve] : [])];
   return defineWorkflow({
     // The literal, held to the one name: the outline finds a workflow by a string, or a const of its own file.
     name: "drift" satisfies typeof DRIFT_WORKFLOW,
@@ -112,38 +204,56 @@ export function driftWorkflow(
       const { resources, problems } = await declared();
       // Every import first, so a reference compares against what its resource holds now.
       const found = new Map<string, Found>();
-      for (const { id, vendor, type, name } of resources) {
-        const key = `${vendor}.${type}`;
-        const why = types.has(key) ? unreadable.get(key) : `the config's connectors declare no resource type ${key}`;
+      for (const resource of resources) {
+        const by = observeBy(resource, types, imports);
         // An if/else, not a `continue`: the outline draws the import as the way past the error.
-        if (why !== undefined) found.set(id, { error: why });
+        if (!("id" in by)) found.set(resource.id, by);
         else {
           try {
-            const out = await ctx[vendor]![type]!.import({ id: name });
-            found.set(id, out.gone || !out.state ? { gone: true } : { state: out.state });
+            found.set(resource.id, observed(await ctx[resource.vendor]![resource.type]!.import({ id: by.id })));
           } catch (err) {
             if (isRunControlError(err)) throw err;
-            found.set(id, { error: errorMessage(err) });
+            found.set(resource.id, { error: errorMessage(err) });
           }
         }
       }
-      const results = resources.map(({ id, vendor, type, name, desired, refs }): DriftResult => {
-        const row = { id, type, vendor, name };
-        const now = found.get(id)!;
-        if ("error" in now) return { ...row, status: "error", fields: [], error: now.error };
-        if ("gone" in now) return { ...row, status: "gone", fields: [] };
-        const resource = types.get(`${vendor}.${type}`)!;
-        // Each reference, by where it is: the values the vendor may hold there for its resource.
-        const accept: Record<string, unknown[]> = {};
-        for (const [at, target] of Object.entries(refs)) {
-          const by = resource.fields.references?.[at.replaceAll(/\.\d+(?=\.|$)/g, "")]?.by ?? [];
-          const named = found.get(target);
-          if (named && "state" in named) accept[at] = by.map((field) => named.state[field]).filter((v) => v != null);
+      // A host's revision against the commit its ref names now: a merge is drift on the host.
+      const revisions = new Map<string, Revision>();
+      for (const { id, vendor, type, desired, refs } of resources) {
+        const resource = types.get(`${vendor}.${type}`);
+        const host = resource?.host;
+        const source = host && sourceUrl(desired, refs[host.inputs.source], resource, found);
+        const ref = host && valueAt(desired, host.inputs.ref);
+        if (host && "state" in found.get(id)! && source !== undefined && typeof ref === "string" && ref) {
+          try {
+            revisions.set(id, await ctx.sanoma!.source!.resolve({ url: source, ref }));
+          } catch (err) {
+            if (isRunControlError(err)) throw err;
+            revisions.set(id, { error: errorMessage(err) });
+          }
         }
-        const fields = diffDeclared(resource, now.state, desired, accept);
-        return { ...row, status: fields.length ? "drifted" : "clean", fields };
-      });
+      }
+      const results = compare(types, resources, found, revisions);
       return { startedAt, finishedAt: await ctx.now(), problems, resources: results } satisfies DriftReport;
     },
   });
 }
+
+/**
+ * A host's source: the clone URL its data file gives, or, when it names a declared repository
+ * (`target`), the first of the reference's `by` fields that holds one in that repository's state,
+ * read in this run.
+ */
+export function sourceUrl(
+  desired: State,
+  target: string | undefined,
+  { host, fields }: Resource,
+  found: ReadonlyMap<string, Found>,
+): string | undefined {
+  const path = host!.inputs.source;
+  const named = target === undefined ? undefined : found.get(target);
+  const by = fields.references?.[path]?.by ?? [];
+  const values =
+    target === undefined ? [valueAt(desired, path)] : named && "state" in named ? by.map((f) => named.state[f]) : [];
+  return values.find((v): v is string => typeof v === "string" && CLONE_URL.test(v));
+}

package/src/errors.ts

@@ -1,7 +1,7 @@
 import { Error as DBOSErrors } from "@dbos-inc/dbos-sdk";
 import type { z } from "zod";
 import type { Principal } from "./define.ts";
-import { errorMessage } from "./shared.ts";
+import { CALL_WORKFLOW, errorMessage } from "./shared.ts";
 
 const CODES = [
   "policy_denied",
@@ -15,6 +15,8 @@ const CODES = [
   "run_ended",
   "run_running",
   "call_not_in_outline",
+  "approval_pending",
+  "not_admitted",
 ] as const;
 
 /**
@@ -79,6 +81,39 @@ export class PolicyDeniedError extends SanomaError {
   }
 }
 
+/**
+ * Thrown by a direct call (`SanomaClient.call`) the policy holds for an approval: the call is now
+ * run `runId` of the built-in `call` workflow, which makes it once approved.
+ */
+export class ApprovalPendingError extends SanomaError {
+  constructor(op: string, runId: string) {
+    super("approval_pending", `${op} needs an approval: it waits in run ${runId}`, {
+      runId,
+      workflow: CALL_WORKFLOW,
+      op,
+    });
+    this.name = "ApprovalPendingError";
+  }
+}
+
+/**
+ * Thrown when the data files declare people (`sanoma.person`, in `resources/people.ts` by
+ * convention) and not this principal's id: nothing is started, called or decided.
+ */
+export class NotAdmittedError extends SanomaError {
+  /** `problems`: what is wrong in the people's files, while nobody is admitted. */
+  constructor(id: string, problems: readonly string[] = []) {
+    super(
+      "not_admitted",
+      problems.length
+        ? `${id} cannot be admitted while the people's files have problems: ${problems.join("; ")}`
+        : `${id} is not declared in resources/people.ts`,
+      { principal: id, ...(problems.length && { problems }) },
+    );
+    this.name = "NotAdmittedError";
+  }
+}
+
 /** Thrown into the run when an approver rejects. The run fails with it. */
 export class RejectedError extends SanomaError {
   /**