@sanoma-ai/workflows 0.1.0 → 0.2.0

package/src/lockfile.ts

@@ -0,0 +1,95 @@
+import { existsSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+import type { ResourceProblem } from "./resources.ts";
+
+// The lockfile: which vendor object each declaration means, kept apart from the data files (which
+// hold intent only), as `package-lock.json` is from `package.json`. Only apply writes it.
+
+/** Where the lockfile is, relative to the config's root. */
+export const LOCKFILE = "resources/sanoma.lock.json";
+
+/** Which vendor object a declaration means: its `<vendor>.<type>` and the vendor's stable id for it. */
+export interface Binding {
+  type: string;
+  id: string;
+}
+
+/** The lockfile's content: by declaration key, `<file>#<export>` (the file relative to the config's root, with `/`). */
+export type Bindings = Record<string, Binding>;
+
+const lockfile = z.record(
+  z.string().regex(/^resources\/[^#]+#[^#]+$/),
+  z.strictObject({ type: z.string().regex(/^[^.\s]+\.[^.\s]+$/), id: z.string().min(1) }),
+);
+
+/**
+ * The lockfile under `root`: no bindings when there is none, and no bindings with a problem when
+ * it is not JSON or not a map of `<file>#<export>` to `{ type, id }`.
+ */
+export function readLockfile(root: string): { bindings: Bindings; problems: ResourceProblem[] } {
+  const path = join(root, LOCKFILE);
+  if (!existsSync(path)) return { bindings: {}, problems: [] };
+  let json: unknown;
+  try {
+    json = JSON.parse(readFileSync(path, "utf8"));
+  } catch (e) {
+    return { bindings: {}, problems: [{ file: LOCKFILE, message: `not JSON: ${(e as Error).message}` }] };
+  }
+  const parsed = lockfile.safeParse(json);
+  if (!parsed.success) {
+    // One line: zod's own spans lines.
+    return {
+      bindings: {},
+      problems: [{ file: LOCKFILE, message: z.prettifyError(parsed.error).replaceAll(/\s*\n\s*/g, " ") }],
+    };
+  }
+  return { bindings: parsed.data, problems: [] };
+}
+
+/** The lockfile's text for `bindings`: keys sorted, two-space JSON, a trailing newline, so a diff shows only what changed. */
+export function serializeLockfile(bindings: Bindings): string {
+  const sorted = Object.entries(bindings)
+    .toSorted(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+    .map(([key, { type, id }]) => [key, { type, id }]);
+  return `${JSON.stringify(Object.fromEntries(sorted), null, 2)}\n`;
+}
+
+/** Writes the lockfile under `root` whole or not at all: to a file beside it, then renamed over it. Apply only. */
+export function writeLockfile(root: string, bindings: Bindings): void {
+  const path = join(root, LOCKFILE);
+  const temporary = `${path}.${process.pid}.tmp`;
+  try {
+    writeFileSync(temporary, serializeLockfile(bindings));
+    renameSync(temporary, path);
+  } catch (err) {
+    rmSync(temporary, { force: true });
+    throw err;
+  }
+}
+
+/**
+ * One change to the lockfile: a declaration bound for the first time (`bind`, `to`), pointed at
+ * another object (`rebind`, `from` and `to`), or no longer bound (`unbind`, `from`). `type` is
+ * the binding's `<vendor>.<type>`, the new one's for a rebind.
+ */
+export interface Rebind {
+  key: string;
+  type: string;
+  kind: "bind" | "rebind" | "unbind";
+  from?: string;
+  to?: string;
+}
+
+/** What changed from `before` to `after`, by key, sorted. */
+export function diffLockfiles(before: Bindings, after: Bindings): Rebind[] {
+  const keys = [...new Set([...Object.keys(before), ...Object.keys(after)])].toSorted();
+  return keys.flatMap((key): Rebind[] => {
+    const was = before[key];
+    const now = after[key];
+    if (!now) return was ? [{ key, type: was.type, kind: "unbind", from: was.id }] : [];
+    if (!was) return [{ key, type: now.type, kind: "bind", to: now.id }];
+    if (was.id === now.id && was.type === now.type) return [];
+    return [{ key, type: now.type, kind: "rebind", from: was.id, to: now.id }];
+  });
+}

package/src/op.ts

@@ -1,5 +1,6 @@
 import type { z } from "zod";
 import type { Fake } from "./fake.ts";
+import type { Secrets } from "./secret.ts";
 import type { Steps } from "./steps.ts";
 
 /**
@@ -235,6 +236,8 @@ export interface CallContext {
   opId: string;
   /** 1 on the first try; retries count up (idempotent operations only). */
   attempt: number;
+  /** The secrets store, for the values `secret()` markers name: `resolveSecrets(input, call.secrets)`. In memory for a fake. */
+  secrets: Secrets;
 }
 
 export type DriverFn<I = any, O = unknown> = (input: I, call: CallContext) => Promise<O>;

package/src/resource.ts

@@ -1,5 +1,7 @@
 import { z } from "zod";
+import { checkHost, type HostSpec } from "./host.ts";
 import { type Connector, type OpSpec, RESOURCE, VENDOR } from "./op.ts";
+import { isSanomaSecret, isSecret, type Secret } from "./secret.ts";
 
 /** Which fields of a resource are flagged, by dotted path (`pages.html_url`; a list's items have no index). */
 export interface ResourceFields {
@@ -47,20 +49,60 @@ export interface ResourceSpec<S extends z.ZodObject = z.ZodObject> {
   title: string;
   /**
    * How `find` makes the import id, for people: `name`, `repository_id:pattern`. The fields it
-   * names stay declarable even when the vendor sets them (Stripe's `id`).
+   * names stay declarable even when the vendor sets them. Absent with `find`: a type the vendor
+   * names alone (Stripe's) is found only by its binding.
    */
-  identity: string;
+  identity?: string;
   /** The resource's fields as a read returns them; a data file declares them, less the vendor-owned ones. */
   schema: S;
   fields: ResourceFields;
-  /** The vendor's id for a declared resource (the import id), from its declared fields. */
-  find: (desired: z.input<S>) => string;
+  /**
+   * The import id that finds a declared resource before it is bound, from its declared fields:
+   * its identity. Absent when its fields cannot name it.
+   */
+  find?: (desired: z.input<S>) => string;
+  /**
+   * The id a binding keeps for an object, from its state: stable for the object's life (GitHub's
+   * `node_id`, not its name), and one `import` accepts. Default: `String(state.id)`.
+   */
+  bindingId?: (state: State) => string;
   /**
    * The part of a state that a drift check compares, given what was declared. The check
    * compares `normalize(actual, desired)` with `normalize(desired, desired)`. Default:
    * `compareDeclared`, which keeps the declared fields only.
    */
   normalize?: (state: State, desired: z.input<S>) => State;
+  /**
+   * True when apply may change its objects: the type then has the change operations `plan`,
+   * `create`, `update` and `delete` besides `read` and `import`. Default false.
+   */
+  writable?: boolean;
+  /** Set when the type meets the `Host` contract: it runs the company. Such a type is `writable` and `stateless`. */
+  host?: HostSpec;
+  /**
+   * True when its objects hold no data, so one gone at the vendor is created again by apply
+   * without asking (a host running the company's code); otherwise apply asks first, as a
+   * recreated database looks fine and has lost its data. Default: true for a host, else false.
+   */
+  stateless?: boolean;
+  /**
+   * Operations apply calls, in order, right after it creates one of its objects and binds it: a
+   * Supabase project's health, until it is healthy, then its database URL stored.
+   */
+  afterCreate?: readonly AfterCreate[];
+}
+
+/** One operation apply calls after a create (`ResourceSpec.afterCreate`). */
+export interface AfterCreate {
+  /** The operation's id, among the config's: `supabase.database.storeUrl`. */
+  op: string;
+  /** Its input, from the new object's binding id and the data file's export that declares it. */
+  input: (made: { id: string; export: string }) => unknown;
+  /**
+   * Called again, every few seconds, until its output passes this, for up to 10 minutes; a call
+   * that fails meanwhile is one that did not pass, its output `undefined`.
+   */
+  until?: (output: any) => boolean;
 }
 
 /**
@@ -75,8 +117,8 @@ export interface Declared<Id extends string = string, T = State> {
   readonly [DECLARED]: Id;
   readonly vendor: string;
   readonly type: string;
-  /** The vendor's id for it: what `find` made of `desired`. */
-  readonly name: string;
+  /** Its identity, the import id that finds it unbound: what `find` made of `desired`; absent without `find`. */
+  readonly name?: string;
   /**
    * Its fields, each resource it names replaced by that resource's `name`: what its type
    * checked, and what a drift check compares.
@@ -91,20 +133,32 @@ export interface Declared<Id extends string = string, T = State> {
 
 /**
  * What a resource type's constructor takes: its fields, where `R` (its `fields.references`)
- * names a path, a declared resource of that type instead of a value (`repository_id: site`).
+ * names a path, a declared resource of that type instead of a value (`repository_id: site`), and
+ * where a string goes, a secret (`secret("NAME")`), which the constructor allows at a write-only
+ * field only.
  */
-export type Declaring<T, R extends References = {}> = [keyof R] extends [never] ? T : DeclaringAt<T, R, "">;
+export type Declaring<T, R extends References = {}> = [keyof R] extends [never]
+  ? WithSecrets<T>
+  : DeclaringAt<T, R, "">;
+
+type WithSecrets<V> = V extends string
+  ? V | Secret
+  : V extends readonly (infer I)[]
+    ? WithSecrets<I>[]
+    : V extends object
+      ? { [K in keyof V]: WithSecrets<V[K]> }
+      : V;
 
 type DeclaringAt<T, R extends References, P extends string> = T extends readonly (infer I)[]
   ? DeclaringAt<I, R, P>[]
   : T extends object
     ? { [K in keyof T]: K extends string ? DeclaringField<T[K], R, P extends "" ? K : `${P}.${K}`> : T[K] }
-    : T;
+    : WithSecrets<T>;
 
 type DeclaringField<V, R extends References, P extends string> = P extends keyof R
-  ? V | DeclaredOf<R[P]["type"]>
+  ? WithSecrets<V> | DeclaredOf<R[P]["type"]>
   : [Extract<keyof R, `${P}.${string}`>] extends [never]
-    ? V
+    ? WithSecrets<V>
     : DeclaringAt<V, R, P>;
 
 type DeclaredOf<Id> = Id extends string ? Declared<Id> : never;
@@ -113,28 +167,78 @@ const importId = z.string().min(1);
 /** What a driver keeps beside a state (an OpenTofu provider's private data and state version), passed back unchanged. */
 const handle = z.string().optional().describe("The driver's data for the object, opaque: pass it back unchanged");
 
+const record = z.record(z.string(), z.unknown());
+
+/** What a plan of a change says will happen, as `PlanResponse.Action` names it. */
+export const PLAN_ACTIONS = ["none", "create", "update", "replace", "delete"] as const;
+export type PlanAction = (typeof PLAN_ACTIONS)[number];
+
+/** The operations of a writable type that change its objects: only the apply workflow calls them (`isChangeOp`). */
+export const CHANGE_OPS = ["create", "update", "delete"] as const;
+
 const opsOf = <S extends z.ZodObject>(schema: S) => {
   // Both answer `{ gone: true }` when the vendor has no such object, and its state when it has.
   const output = z.object({ id: importId, gone: z.boolean(), state: schema.optional(), handle });
+  const known = { id: importId, state: record.optional(), handle };
+  // The declared fields, a secret marker (`{ $secret }`) at a write-only one: the driver resolves it.
+  const desired = record.describe("The declared fields; a write-only one may hold a secret marker");
+  const changed = z.object({ id: importId, state: schema, handle });
+  const action = z.enum(PLAN_ACTIONS);
+  /** Fields as dotted paths, a list item's with its index. */
+  const paths = z.array(z.string());
   return {
     import: { input: z.object({ id: importId }), output },
-    read: { input: z.object({ id: importId, state: z.record(z.string(), z.unknown()).optional(), handle }), output },
+    read: { input: z.object(known), output },
+    plan: {
+      input: z.object({ ...known, id: importId.optional(), desired: desired.optional() }),
+      output: z.object({
+        action,
+        // The new state, without write-only fields; a value known only after apply is `null`, its path in `unknown`.
+        planned: record.optional(),
+        unknown: paths,
+        replace: paths.describe("The fields whose change replaces the object: not empty exactly when `replace`"),
+      }),
+    },
+    create: { input: z.object({ desired }), output: changed },
+    update: {
+      input: z.object({ ...known, desired, expect: z.object({ action, replace: paths }).optional() }),
+      output: changed,
+    },
+    delete: { input: z.object(known), output: z.object({ id: importId, gone: z.literal(true) }) },
   };
 };
 
 /** What the ledger keeps of a resource operation's `handle`: its name, never its bytes. */
 const opaque = ["handle"] as const;
 
-/** The policy's `target` for a resource's operations: the import id. */
+/** The policy's `target` for a resource's operations: the id, an identity or a binding id. */
 const target = ({ id }: { id: string }) => id;
 
 type OpsOf<S extends z.ZodObject> = ReturnType<typeof opsOf<S>>;
-
-/** A resource type's operation specs: `read` and `import`. */
-export type ResourceOps<S extends z.ZodObject> = {
-  [N in keyof OpsOf<S>]: OpSpec<OpsOf<S>[N]["input"], OpsOf<S>[N]["output"]>;
+type Specs<S extends z.ZodObject, N extends keyof OpsOf<S>> = {
+  [K in N]: OpSpec<OpsOf<S>[K]["input"], OpsOf<S>[K]["output"]>;
 };
 
+/**
+ * A resource type's operation specs: `read` and `import`, and for a writable type (`W`) the
+ * change operations `plan`, `create`, `update` and `delete`.
+ */
+export type ResourceOps<S extends z.ZodObject, W extends boolean = false> = Specs<S, "read" | "import"> &
+  ([W] extends [true] ? Specs<S, "plan" | (typeof CHANGE_OPS)[number]> : {});
+
+/**
+ * True for an operation that changes a writable type's objects (`CHANGE_OPS`), which only the
+ * apply workflow may call: by its vendor, resource and name, so a copy of a connector is told too.
+ */
+export function isChangeOp(
+  op: { readonly vendor: string; readonly resource: string; readonly name: string },
+  types: ReadonlyMap<string, Pick<Resource, "writable">>,
+): boolean {
+  return (
+    (CHANGE_OPS as readonly string[]).includes(op.name) && types.get(`${op.vendor}.${op.resource}`)?.writable === true
+  );
+}
+
 /**
  * A resource type: call it to declare a resource in a data file, and give it to
  * `defineConnector` as a group, under its `type`: `defineConnector("github", { repository })`.
@@ -143,10 +247,18 @@ export interface Resource<
   S extends z.ZodObject = z.ZodObject,
   Id extends string = string,
   R extends References = {},
-> extends Readonly<Required<ResourceSpec<S>>> {
+  W extends boolean = boolean,
+>
+  extends
+    Readonly<Required<Omit<ResourceSpec<S>, "identity" | "find" | "writable" | "host" | "stateless" | "afterCreate">>>,
+    Readonly<Pick<ResourceSpec<S>, "identity" | "find" | "host" | "afterCreate">> {
   (desired: Declaring<z.input<S>, R>): Declared<Id, z.input<S>>;
-  /** `read` and `import`, each effect `read`, idempotent, with the import id as `target`. */
-  readonly ops: ResourceOps<S>;
+  /** `read` and `import`, each effect `read`, idempotent, with the id as `target`; for a writable type, the change operations too. */
+  readonly ops: ResourceOps<S, W>;
+  /** True when apply may change its objects: it has the change operations. */
+  readonly writable: W;
+  /** True when apply may recreate or replace its objects as routine: they keep no data. */
+  readonly stateless: boolean;
   readonly [RESOURCE]: true;
 }
 
@@ -262,21 +374,25 @@ function withAccepted(state: State, desired: State, accept: Readonly<Record<stri
   if (!paths.length) return state;
   const out = structuredClone(state);
   for (const [path, values] of paths) {
-    const keys = path.split(".");
-    const last = keys.pop()!;
-    const holder = keys.reduce<unknown>(
-      (v, key) => (isObject(v) || Array.isArray(v) ? (v as State)[key] : undefined),
-      out,
-    );
-    if (!isObject(holder) && !Array.isArray(holder)) continue;
-    const at = holder as State;
-    if (values.includes(at[last])) at[last] = valueAt(desired, path);
+    const at = holderOf(out, path);
+    if (at && values.includes(at.holder[at.key])) at.holder[at.key] = valueAt(desired, path);
   }
   return out;
 }
 
+/** The object or list holding the value at a dotted path (a list item's by its index), and its key there. */
+export function holderOf(value: unknown, path: string): { holder: State; key: string } | undefined {
+  const keys = path.split(".");
+  const key = keys.pop()!;
+  const holder = keys.reduce<unknown>((v, k) => (isObject(v) || Array.isArray(v) ? (v as State)[k] : undefined), value);
+  return isObject(holder) || Array.isArray(holder) ? { holder: holder as State, key } : undefined;
+}
+
+/** A field's dotted path as `fields` names it, without a list item's index: `teams.0` is `teams`. */
+export const fieldPathOf = (at: string) => at.replaceAll(/\.\d+(?=\.|$)/g, "");
+
 /** The value at a dotted path, a list item's by its index. */
-const valueAt = (value: unknown, path: string) =>
+export const valueAt = (value: unknown, path: string) =>
   path.split(".").reduce<unknown>((v, key) => (isObject(v) || Array.isArray(v) ? (v as State)[key] : undefined), value);
 
 /** True when the two are the same JSON, where a missing value is `null`. */
@@ -303,9 +419,19 @@ function changes(desired: unknown, actual: unknown, unordered: ReadonlySet<strin
   return same(desired, actual) ? [] : [{ path: at, desired: desired ?? null, actual: actual ?? null }];
 }
 
+/** The secret markers in a write-only value, in its place: the value itself, or a map of them (none: `[]`). */
+function markers(value: unknown): unknown[] {
+  if (isSecret(value)) return [value];
+  if (!isObject(value)) return [];
+  const kept = Object.entries(value).flatMap(([name, v]) => markers(v).map((m) => [name, m] as const));
+  return kept.length ? [Object.fromEntries(kept)] : [];
+}
+
 /**
- * `desired` without the fields the type marks write-only (a webhook's `secret`): what a run may
- * record of a declaration. A list's items lose them too.
+ * `desired` without the values at the fields the type marks write-only (a webhook's `secret`):
+ * what a run may record of a declaration. A list's items lose them too. A secret marker
+ * (`secret("NAME")`) stays, there or inside a write-only map (a host's `secrets`): it names a
+ * stored secret and holds none, and the driver resolves it.
  */
 export function withoutWriteOnly(fields: ResourceFields, desired: State): State {
   if (!fields.writeOnly.length) return desired;
@@ -316,13 +442,17 @@ export function withoutWriteOnly(fields: ResourceFields, desired: State): State
     return Object.fromEntries(
       Object.entries(value).flatMap(([name, v]) => {
         const at = joinPath(path, name);
-        return drop.has(at) ? [] : [[name, strip(v, at)]];
+        return drop.has(at) ? markers(v).map((m) => [name, m]) : [[name, strip(v, at)]];
       }),
     );
   };
   return strip(desired, "") as State;
 }
 
+/** True when `path` is one of `paths`, or a field inside one: a secret's map (`secrets.KEY`) is as write-only as the map. */
+const underAny = (path: string, paths: ReadonlySet<string>) =>
+  path.split(".").some((_, i, keys) => paths.has(keys.slice(0, i + 1).join(".")));
+
 /** The dotted paths in `value` that `paths` holds, looking into objects and lists' items. */
 function pathsIn(value: unknown, paths: ReadonlySet<string>, prefix = ""): string[] {
   if (Array.isArray(value)) return [...new Set(value.flatMap((item) => pathsIn(item, paths, prefix)))];
@@ -339,13 +469,31 @@ function pathsIn(value: unknown, paths: ReadonlySet<string>, prefix = ""): strin
  * derives its operations, `<vendor>.<type>.read` and `<vendor>.<type>.import`, both effect
  * `read` and idempotent, with the import id as the policy's `target`:
  *
- * - `import` takes `{ id }`, the import id, and returns `{ gone: false, state }`, the object's
+ * - `import` takes `{ id }`, an identity (what `find` makes) or a binding id (what `bindingId`
+ *   makes), and returns `{ gone: false, state }`, the object's
  *   state (with the driver's opaque `handle` when it keeps one), or `{ gone: true }` when the
  *   vendor has no such object.
  * - `read` takes `{ id, state?, handle? }`, a state from an earlier `import` or `read`, and
  *   returns the same: `{ gone: true }` when the object no longer exists, else its fresh
  *   `state`. A driver may import first when it is given no state.
  *
+ * A `writable` type has the change operations too, which only the apply workflow may call
+ * (`isChangeOp`): `create`, `update` and `delete` effect `write` (`delete` idempotent), and `plan`:
+ *
+ * - `plan` (`read`, idempotent) takes `{ id?, state?, handle?, desired? }`, no `desired` for a
+ *   delete and no `id` for a create, and returns `{ action, planned?, unknown, replace }`:
+ *   what apply would do, the new state without write-only fields, the paths known only after
+ *   apply, and those whose change replaces the object.
+ * - `create` (`target` `new:<vendor>.<type>`) takes `{ desired }` and returns `{ id, state,
+ *   handle? }`, `id` its binding id.
+ * - `update` takes `{ id, state?, handle?, desired, expect? }` and returns the same; given
+ *   `expect` (a plan's `action` and `replace`), it refuses a fresh plan that differs
+ *   (`DriverError`, `vendorCode` `plan_changed`).
+ * - `delete` takes `{ id, state?, handle? }` and returns `{ id, gone: true }`.
+ *
+ * `desired` may hold secret markers at write-only fields, which the driver resolves; no output
+ * holds a write-only value.
+ *
  * The ledger records a `handle` as `"<handle>"`, never its bytes (the operations' `opaque`).
  *
  * Calling the result declares one resource, for a data file: `repository({ name: "sanoma" })`
@@ -353,22 +501,64 @@ function pathsIn(value: unknown, paths: ReadonlySet<string>, prefix = ""): strin
  * schema does not have, fields the vendor owns (unless the identity names them), values the
  * schema rejects, and an empty identity. Where `fields.references` allows it, a field may name
  * another declared resource of that type (`repository_id: site`): `desired` holds, and the
- * schema and `find` read, that resource's `name`, and `refs` says where it was named.
+ * schema and `find` read, that resource's `name`, and `refs` says where it was named. A type
+ * without `find` declares resources without a `name`, found only by their bindings.
  */
 export function defineResource<
   S extends z.ZodObject,
   const V extends string,
   const T extends string,
   const R extends References = {},
->(spec: ResourceSpec<S> & { vendor: V; type: T; fields: { references?: R } }): Resource<S, `${V}.${T}`, R> {
-  const { vendor, type, schema, fields, find } = spec;
+  const W extends boolean = false,
+>(
+  spec: ResourceSpec<S> & { vendor: V; type: T; fields: { references?: R }; writable?: W },
+): Resource<S, `${V}.${T}`, R, W> {
+  const { vendor, type, schema, fields, find, identity, host } = spec;
+  const writable = (spec.writable ?? false) as W;
   const what: `${V}.${T}` = `${vendor}.${type}`;
+  if (host) checkHost(what, host, spec);
+  const title = spec.title.toLowerCase();
   const io = opsOf(schema);
-  const ops = {
+  // The policy's `target` for a create: the type, as no object has an id yet.
+  const created = `new:${what}`;
+  const changeOps = {
+    plan: {
+      effect: "read",
+      idempotent: true,
+      description: `Plan how apply would make a ${title} match its declaration (or delete it, given none); nothing changes`,
+      ...io.plan,
+      target: ({ id }: { id?: string }) => id ?? created,
+      opaque,
+    },
+    create: {
+      effect: "write",
+      description: `Create a ${title} as declared`,
+      ...io.create,
+      target: () => created,
+      opaque,
+    },
+    update: {
+      effect: "write",
+      description: `Change a ${title} to match its declaration, replacing it where a field cannot change in place`,
+      ...io.update,
+      target,
+      opaque,
+    },
+    delete: {
+      effect: "write",
+      // A retry reads first, and finds the object gone.
+      idempotent: true,
+      description: `Delete a ${title}; done already when it is gone`,
+      ...io.delete,
+      target,
+      opaque,
+    },
+  } satisfies Specs<S, "plan" | (typeof CHANGE_OPS)[number]>;
+  const base = {
     import: {
       effect: "read",
       idempotent: true,
-      description: `Find a ${spec.title.toLowerCase()} by its ${spec.identity} and read it; gone when there is none`,
+      description: `Find a ${title} by its ${identity ? `${identity} or its ` : ""}binding id and read it; gone when there is none`,
       ...io.import,
       target,
       opaque,
@@ -376,27 +566,43 @@ export function defineResource<
     read: {
       effect: "read",
       idempotent: true,
-      description: `Read a ${spec.title.toLowerCase()} as it is now; gone when it no longer exists`,
+      description: `Read a ${title} as it is now; gone when it no longer exists`,
       ...io.read,
       target,
       opaque,
     },
-  } satisfies ResourceOps<S>;
+  } satisfies Specs<S, "read" | "import">;
+  const ops = (writable ? { ...base, ...changeOps } : base) as unknown as ResourceOps<S, W>;
 
-  const named = new Set(spec.identity.match(/[A-Za-z_][\w.]*/g));
+  const named = new Set(identity?.match(/[A-Za-z_][\w.]*/g));
   const owned = new Set(fields.vendorOwned.filter((path) => !named.has(path)));
   const references: References = fields.references ?? {};
+  const writeOnly = new Set(fields.writeOnly);
   const declare = (given: Declaring<z.input<S>, R>): Declared<`${V}.${T}`, z.input<S>> => {
     const refs: Record<string, string> = {};
+    // Where a secret is given, with list items' indexes: the schema does not judge its marker.
+    const secrets = new Set<string>();
     // Each resource `given` names, where `references` allows one of its type, replaced by its name.
     // `path` is the field's, as `references` names it; `at` has list items' indexes too.
     const resolve = (value: unknown, path: string, at: string): unknown => {
+      if (isSecret(value)) {
+        if (!underAny(path, writeOnly)) {
+          throw new Error(`${what}: ${at} is not write-only, so it takes a value, not a secret (${value.$secret})`);
+        }
+        if (isSanomaSecret(value.$secret) && !(host && underAny(path, new Set([host.inputs.secrets])))) {
+          throw new Error(`${what}: ${at} names ${value.$secret}, one of sanoma's own: only a host's secrets may`);
+        }
+        secrets.add(at);
+        return value;
+      }
       if (isDeclared(value)) {
         const id = value[DECLARED];
         const wants = references[path];
         if (wants === undefined) throw new Error(`${what}: ${at} takes a value, not a resource (${id} ${value.name})`);
         if (wants.type !== id)
           throw new Error(`${what}: ${at} names a resource of type ${wants.type}, not ${id} (${value.name})`);
+        if (value.name === undefined)
+          throw new Error(`${what}: ${at} names a ${id}, which has no identity to name it by`);
         refs[at] = `${id}:${value.name}`;
         return value.name;
       }
@@ -409,6 +615,10 @@ export function defineResource<
     const desired = resolve(given, "", "") as z.input<S>;
     const unknown = Object.keys(desired ?? {}).filter((name) => !Object.hasOwn(schema.shape, name));
     if (unknown.length) throw new Error(`${what}: no field ${unknown.join(", ")}`);
+    // Apply fills a host's revision from its ref: the file names a branch, never a commit.
+    if (host && pathsIn(desired, new Set([host.revision])).length) {
+      throw new Error(`${what}: leave out ${host.revision}: apply sets it from ${host.inputs.ref}`);
+    }
     const vendors = pathsIn(desired, owned);
     if (vendors.length) {
       throw new Error(
@@ -416,20 +626,33 @@ export function defineResource<
       );
     }
     const parsed = schema.safeParse(desired);
-    if (!parsed.success) throw new Error(`${what}: ${z.prettifyError(parsed.error)}`);
-    const name = find(desired);
-    if (typeof name !== "string" || name === "") throw new Error(`${what}: its ${spec.identity} is missing`);
-    return Object.freeze({ [DECLARED]: what, vendor, type, name, desired, refs: Object.freeze(refs) });
+    const issues = parsed.error?.issues.filter((issue) => !secrets.has(issue.path.join(".")));
+    if (issues?.length) throw new Error(`${what}: ${z.prettifyError(new z.ZodError(issues))}`);
+    const name = find?.(desired);
+    if (find && (typeof name !== "string" || name === "")) throw new Error(`${what}: its ${identity} is missing`);
+    return Object.freeze({
+      [DECLARED]: what,
+      vendor,
+      type,
+      ...(name !== undefined && { name }),
+      desired,
+      refs: Object.freeze(refs),
+    });
   };
   const resource = Object.assign(declare, {
     vendor,
     type,
     title: spec.title,
-    identity: spec.identity,
+    identity,
     schema,
     fields,
     find,
+    bindingId: spec.bindingId ?? ((state: State) => String(state.id)),
     normalize: spec.normalize ?? ((state: State, desired: z.input<S>) => compareDeclared(fields, state, desired)),
+    writable,
+    ...(host && { host }),
+    stateless: spec.stateless ?? host !== undefined,
+    ...(spec.afterCreate && { afterCreate: spec.afterCreate }),
     ops,
     // A symbol, so `defineConnector` tells a resource type from a group of operations.
     [RESOURCE]: true as const,