@sanoma-ai/workflows 0.1.0 → 0.2.0

package/src/describe.ts

@@ -2,13 +2,13 @@ import type { z } from "zod";
 import { type LintProblem, readSource, type SourceFile } from "./ast.ts";
 import { resolveConfig, type SanomaConfig } from "./config.ts";
 import { type Builtin, jsonSchemaOf, opIdsOf, type Use } from "./define.ts";
-import { DRIFT_WORKFLOW } from "./drift.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 DeclaredResource, readDataFiles, type ResourceProblem } from "./resources.ts";
+import { BUILT_IN_WORKFLOWS } from "./shared.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";
@@ -21,6 +21,21 @@ export {
   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";
+export {
+  LOCKFILE,
+  readLockfile,
+  serializeLockfile,
+  writeLockfile,
+  diffLockfiles,
+  type Binding,
+  type Bindings,
+  type Rebind,
+} from "./lockfile.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 +43,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` or `apply`, rather than the config: a label. It
    * starts like any other.
    */
   builtin?: true;
@@ -96,8 +111,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,7 +120,7 @@ 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[];
 }
 
@@ -129,6 +144,8 @@ export interface ConfigDescription {
    * 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`. */
@@ -155,7 +172,7 @@ export function describeConfig(config: SanomaConfig): ConfigDescription {
   // 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,7 +180,9 @@ 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));
 
@@ -184,18 +203,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"),
@@ -216,6 +235,7 @@ export function describeConfig(config: SanomaConfig): ConfigDescription {
     vendors,
     resourceTypes,
     resources: dataFiles.resources,
+    orphans: dataFiles.orphans,
     problems: dataFiles.problems,
     policy: {
       defined: resolved.policy !== allowAll,

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/expectations.ts

@@ -1,5 +1,6 @@
 import { isDeepStrictEqual } from "node:util";
 import type { Approver } from "./define.ts";
+import type { ApplyReport } from "./apply.ts";
 import type { DriftReport, DriftResult } from "./drift.ts";
 import type { LedgerRecord } from "./ledger.ts";
 import type { RecordedDecision } from "./policy.ts";
@@ -99,7 +100,7 @@ type Unstepped<T> = T extends unknown ? Omit<T, "step"> : never;
  * output, or undefined when the report found the resource as expected.
  */
 function driftDetail(
-  e: Extract<CoreExpectation, { declared: string }>,
+  e: Extract<CoreExpectation, { status: string }>,
   end: Extract<LedgerRecord, { type: "run.finished" }>,
 ): string | undefined {
   const report = end.output as Partial<DriftReport> | null | undefined;
@@ -115,14 +116,38 @@ function driftDetail(
   return `${e.declared} is ${found(resource)}, not ${e.status === "drifted" ? `drifted in ${e.field}` : e.status}`;
 }
 
+/**
+ * Why an apply expectation fails against the report a finished apply run returned as its output:
+ * the resource `created` (a step that created it, done), or `bound` to an object in the lockfile it ended with.
+ */
+function applyDetail(
+  e: Extract<CoreExpectation, { created: true } | { bound: string }>,
+  end: Extract<LedgerRecord, { type: "run.finished" }>,
+): string | undefined {
+  const report = end.output as Partial<ApplyReport> | null | undefined;
+  if (!Array.isArray(report?.results) || !report.lockfile) return "the run's output is not an apply report";
+  if ("bound" in e) {
+    const binding = report.lockfile.bindings[e.declared];
+    if (binding?.id === e.bound) return undefined;
+    return binding ? `${e.declared} is bound to ${binding.id}, not ${e.bound}` : `${e.declared} is not bound`;
+  }
+  const result = report.results.find((r) => r.id === e.declared);
+  // A gone object recreated is bound again; one forgotten is not.
+  const created =
+    result?.status === "done" && (result.action === "create" || (result.action === "gone" && !!result.binding));
+  if (created) return undefined;
+  if (!result) return `apply did nothing with ${e.declared}`;
+  return `apply's ${result.action} of ${e.declared} ${result.status === "failed" ? `failed: ${result.error}` : `was ${result.status}`}`;
+}
+
 /**
  * Why an expectation of the generic steps does not hold against a run's ledger records, or
  * undefined when it does. A call is an `op.called` record without an `error`; one with an error
  * (a policy denial, a rejected approval, a vendor's final failure) was attempted, not made. An
  * operation `was denied` when the policy's decision on some call to it is `deny`, and `was held
  * for` an approver when an approval for that approver holds it: one the policy asked for on its
- * call, or one that `covers` it. A drift expectation reads the report a finished drift run
- * returned. A step named in the workflow's outline is read by the `name` its records carry
+ * call, or one that `covers` it. A drift or apply expectation reads the report a finished run
+ * of it returned. A step named in the workflow's outline is read by the `name` its records carry
  * (its calls made, and `waitsOf`); a record written before steps had names has none.
  */
 export function detailOf(e: CoreExpectation, records: readonly LedgerRecord[]): string | undefined {
@@ -161,5 +186,6 @@ export function detailOf(e: CoreExpectation, records: readonly LedgerRecord[]):
   }
   // A finished run: what `the run succeeds` expects, and what a drift expectation reads its report from.
   if (end.type === "run.failed") return `the run failed: ${end.error.message}`;
-  return "declared" in e ? driftDetail(e, end) : undefined;
+  if (!("declared" in e)) return undefined;
+  return "status" in e ? driftDetail(e, end) : applyDetail(e, end);
 }

package/src/host.ts

@@ -0,0 +1,96 @@
+import type { z } from "zod";
+
+// The `Host` contract: what a resource type that runs the company (a container, a Render service,
+// a Fly app) declares about itself, so hosts are swappable and one conformance kit decides
+// whether one works. A host is a resource type like any other; this is what sets it apart.
+
+/** How a host keeps the runtime up: `long-lived`, or (later) woken on a schedule. */
+export type HostLifetime = "long-lived" | "wake-on-schedule";
+
+/** What a host can do, for choosing one. */
+export interface HostCapabilities {
+  lifetime: HostLifetime;
+  /** Its `url` is reachable from the internet, not only from this machine. */
+  publicUrl: boolean;
+  /** It builds the repository from git itself, at the revision apply gives it. */
+  buildsFromGit: boolean;
+  /** Its outbound connections come from fixed addresses, for a vendor's allow-list. */
+  staticEgress: boolean;
+}
+
+/** What a host's state says of it: where the app answers, which commit it runs, and whether it is up. */
+export interface HostOutputs {
+  url: string;
+  /** The commit it runs, when its state says. */
+  revision?: string;
+  healthy: boolean;
+}
+
+/**
+ * A resource type's `host`: the fields it takes the runtime's inputs in, by dotted path into its
+ * declared fields, and how its state reads as `HostOutputs`. A host is drifted when
+ * `outputs(state).revision` differs from what `sanoma.source.resolve` says `ref` is now.
+ */
+export interface HostSpec {
+  capabilities: HostCapabilities;
+  inputs: {
+    /** The repository's clone URL, or a reference to a declared repository whose state holds one (a `by` field). */
+    source: string;
+    /** The branch (or tag) it runs: `main`, never a commit. */
+    ref: string;
+    /** The secrets it passes the runtime (`SANOMA_DATABASE_URL`, `SANOMA_SECRETS_KEY`): a write-only field. */
+    secrets: string;
+    /** The port the app listens on. */
+    port: string;
+  };
+  /**
+   * The field apply fills with the commit `ref` resolves to, before it plans: hidden, as a data
+   * file may not declare it, so a merge to `ref` is a change to the host.
+   */
+  revision: string;
+  outputs: (state: Record<string, unknown>) => HostOutputs;
+}
+
+const LIFETIMES: readonly HostLifetime[] = ["long-lived", "wake-on-schedule"];
+
+/** True when `schema` has a field at the dotted `path`, looking through optional, nullable and default wrappers. */
+function hasPath(schema: z.ZodType, path: string): boolean {
+  let at: z.ZodType | undefined = schema;
+  for (const key of path.split(".")) {
+    at = unwrap(at);
+    const shape = (at as Partial<z.ZodObject>).shape;
+    at = shape?.[key];
+    if (!at) return false;
+  }
+  return true;
+}
+
+function unwrap(schema: z.ZodType): z.ZodType {
+  let at = schema;
+  while ("unwrap" in at && typeof at.unwrap === "function") at = at.unwrap() as z.ZodType;
+  return at;
+}
+
+/**
+ * Throws what is wrong with a resource type's `host`: an input or `revision` that names no field,
+ * `secrets` that is not write-only, a `revision` that is, an unknown lifetime, a type apply cannot
+ * change (not `writable`).
+ */
+export function checkHost(
+  what: string,
+  host: HostSpec,
+  type: { schema: z.ZodObject; fields: { writeOnly: readonly string[] }; writable?: boolean },
+): void {
+  const problems: string[] = [];
+  if (!type.writable) problems.push("it must be writable, so apply can create and update it");
+  if (!LIFETIMES.includes(host.capabilities?.lifetime)) {
+    problems.push(`capabilities.lifetime is one of ${LIFETIMES.join(", ")}`);
+  }
+  for (const [input, path] of [...Object.entries(host.inputs ?? {}), ["revision", host.revision] as const]) {
+    if (typeof path !== "string" || !hasPath(type.schema, path)) problems.push(`${input} names no field (${path})`);
+  }
+  if (!type.fields.writeOnly.includes(host.inputs?.secrets)) problems.push("inputs.secrets must be a write-only field");
+  if (type.fields.writeOnly.includes(host.revision)) problems.push("revision must not be write-only: drift reads it");
+  if (typeof host.outputs !== "function") problems.push("outputs must be a function of the state");
+  if (problems.length) throw new Error(`${what}: its host: ${problems.join("; ")}`);
+}

package/src/index.ts

@@ -38,14 +38,25 @@ export {
   defineResource,
   diffDeclared,
   type FieldReference,
+  type PlanAction,
   type References,
   type Resource,
   type ResourceFields,
   type ResourceOps,
   type ResourceSpec,
+  withoutWriteOnly,
 } from "./resource.ts";
 export { defineConfig, resolveConfig, resolveDatabaseUrl, type ResolvedConfig, type SanomaConfig } from "./config.ts";
 export { type CredentialStatus, credentialsOf } from "./env.ts";
+export {
+  APPLY_WORKFLOW,
+  ApplyInput,
+  type ApplyPlan,
+  type ApplyReport,
+  type ApplyResult,
+  type PlanAnswer,
+  type PlanStep,
+} from "./apply.ts";
 export {
   DRIFT_WORKFLOW,
   type DriftDeclared,
@@ -93,7 +104,19 @@ export { ApprovalMessage, APPROVALS_EVENT, decisionEventOf } from "./approvals.t
 export { RUNTIME_VERSION } from "./version.ts";
 export type { RunArgs } from "./run.ts";
 export { startWorker, type Worker, type WorkerOptions } from "./worker.ts";
-export { SanomaClient, type RunsFilter, type RunSummary, type StartOptions } from "./client.ts";
+// `secret` itself is at `@sanoma-ai/workflows/resources`, for data files; this is the drivers' side.
+export {
+  generateSecret,
+  isSecret,
+  memorySecrets,
+  type Resolved,
+  resolveSecrets,
+  type Secret,
+  type Secrets,
+} from "./secret.ts";
+export { resolveRevision, SOURCE_RESOLVE, type Source } from "./source.ts";
+export type { HostCapabilities, HostLifetime, HostOutputs, HostSpec } from "./host.ts";
+export { SanomaClient, type RunsFilter, type RunSummary, type StartOptions, type StoredSecret } from "./client.ts";
 // A raw DBOS client on the runtime's database, for tests and tools that read DBOS directly.
 export { dbosClient } from "./db.ts";
 // Also at `@sanoma-ai/workflows/shared`, which a browser bundle can import.