@suluk/provision 0.1.0

package/src/app.ts

@@ -0,0 +1,29 @@
+/**
+ * The provision "app" (C047) — what a `provision.config.ts` exports, the drizzle-kit `drizzle.config.ts` analog. It binds
+ * the declarative config (the desired instances) to the runtime wiring the CLI needs: the broker registry (service id →
+ * the executor that talks to the provider), the state journal, and the binding sink. `plan`/`check`/`status` need only
+ * the config + journal; `apply` needs the brokers + sink. `defineProvisionApp` validates the config up front.
+ */
+import type { Broker, BindingSink, StateStore } from "./types";
+import type { MigrationStore } from "./migration-store";
+import { defineProvision, type ProvisionConfig } from "./config";
+
+export interface ProvisionApp {
+  /** the desired instances (+ pruneOrphans default). */
+  config: ProvisionConfig;
+  /** service id → broker (the executors `apply` dispatches to). */
+  brokers: Record<string, Broker>;
+  /** the journal (defaults to a file store in a real config). */
+  store: StateStore;
+  /** where bound credentials land (defaults to the @suluk/env sink). Optional. */
+  sink?: BindingSink;
+  /** the committed migration history — enables `generate` + `migrate` (the drizzle-style repeatable path). Optional;
+   *  a real config points it at `fileMigrationStore("provision")`. */
+  migrations?: MigrationStore;
+}
+
+/** Validate + return a provision app config (the CLI imports this as the config file's default export). */
+export function defineProvisionApp(app: ProvisionApp): ProvisionApp {
+  defineProvision(app.config); // throws on dup ref / unknown ref / cycle
+  return app;
+}

package/src/apply.ts

@@ -0,0 +1,124 @@
+/**
+ * The executor (C047) — drizzle-kit's `push` for infrastructure. Walks a {@link ProvisionPlan} in binding-DAG order and
+ * calls the OSB verbs: `provision` (idempotent), poll `lastOperation` until an async create settles, `bind` for the
+ * credentials, land them in the {@link BindingSink}, and accumulate each instance's outputs so a downstream `@ref.key`
+ * param resolves to a freshly-provisioned value. Orphans (when pruning) are deprovisioned last. Provider calls live in
+ * the brokers; this is the pure orchestration over them — the clock + sleep are injected so it's deterministically
+ * testable.
+ */
+import type { Broker, BindingSink, InstanceState, ProvisionResult, StateStore } from "./types";
+import type { ProvisionConfig } from "./config";
+import type { PlanStep, StepAction } from "./plan";
+import { plan } from "./plan";
+import { resolveParams, fingerprint } from "./refs";
+import { pollToDone, type PollOptions } from "./poll";
+
+export interface ApplyOptions {
+  /** broker id → broker (the catalog of executors). A step whose `service` is absent here is an error. */
+  brokers: Record<string, Broker>;
+  /** the journal load/save (a JSON file in prod; memory in tests). */
+  store: StateStore;
+  /** where bound credentials land (the @suluk/env manifest in prod; memory in tests). Optional — omit to skip sinking. */
+  sink?: BindingSink;
+  /** deprovision orphans (state − config). Defaults to the config's `pruneOrphans`. */
+  prune?: boolean;
+  /** async-poll tuning + seams (see {@link PollOptions}). */
+  poll?: PollOptions;
+  log?: (msg: string) => void;
+}
+
+export interface AppliedStep {
+  ref: string;
+  action: StepAction;
+  instanceId?: string;
+  outputs?: Record<string, string>;
+}
+
+export interface ApplyResult {
+  steps: AppliedStep[];
+  state: InstanceState[];
+  /** every instance's resolved outputs after the run (for assertions + downstream tooling). */
+  outputsByRef: Record<string, Record<string, string>>;
+}
+
+/** Resolve the instance id from a provision result, settling an async op first via polling. */
+async function settle(
+  broker: Broker,
+  spec: { ref: string; name: string },
+  result: ProvisionResult,
+  poll: PollOptions,
+  log: (m: string) => void,
+): Promise<{ instanceId: string; outputs: Record<string, string> }> {
+  if (result.state === "succeeded") return { instanceId: result.instanceId, outputs: result.outputs ?? {} };
+  // async: the ack must carry the id (often known at submit time, like a D1 uuid); poll until the op settles, then
+  // thread any outputs the ack already surfaced.
+  if (!result.instanceId) throw new Error(`provision: ${spec.ref} async provision must return an instanceId alongside the operation`);
+  await pollToDone(broker, { ref: spec.ref, name: spec.name, instanceId: result.instanceId, operation: result.operation }, poll, log);
+  return { instanceId: result.instanceId, outputs: result.outputs ?? {} };
+}
+
+/** Execute the plan for `config`. Idempotent end-to-end: re-running a settled config is all-noops, touches no provider. */
+export async function apply(config: ProvisionConfig, opts: ApplyOptions): Promise<ApplyResult> {
+  const log = opts.log ?? (() => {});
+  const poll = opts.poll ?? {};
+  const now = poll.now ?? Date.now;
+  const prune = opts.prune ?? config.pruneOrphans ?? false;
+
+  const prior = await opts.store.load();
+  const p = plan(config, prior, prune);
+  const specByRef = new Map(config.instances.map((i) => [i.ref, i]));
+  const stateByRef = new Map(prior.map((s) => [s.ref, s]));
+  // seed downstream-ref resolution with EXISTING outputs (a noop producer still feeds a changed consumer).
+  const outputsByRef: Record<string, Record<string, string>> = Object.fromEntries(prior.map((s) => [s.ref, s.outputs]));
+  const applied: AppliedStep[] = [];
+
+  for (const step of p.steps) {
+    const broker = opts.brokers[step.service];
+    if (!broker && step.action !== "noop") throw new Error(`provision: no broker registered for service "${step.service}" (instance ${step.ref})`);
+
+    if (step.action === "noop") {
+      applied.push({ ref: step.ref, action: "noop", instanceId: stateByRef.get(step.ref)?.instanceId, outputs: outputsByRef[step.ref] });
+      continue;
+    }
+
+    if (step.action === "deprovision") {
+      const s = stateByRef.get(step.ref)!;
+      if (broker.deprovision) {
+        const res = await broker.deprovision({ ref: s.ref, name: s.name, instanceId: s.instanceId, operation: "deprovision" });
+        if (res.state === "in progress") await pollToDone(broker, { ref: s.ref, name: s.name, instanceId: s.instanceId, operation: res.operation ?? "deprovision" }, poll, log);
+      }
+      stateByRef.delete(step.ref);
+      delete outputsByRef[step.ref];
+      applied.push({ ref: step.ref, action: "deprovision" });
+      log(`✗ deprovisioned ${step.ref} (${step.name})`);
+      continue;
+    }
+
+    // create | update
+    const spec = specByRef.get(step.ref)!;
+    const params = resolveParams(spec, outputsByRef);
+    log(`${step.action === "create" ? "+" : "~"} ${step.action} ${step.ref} (${spec.service} · ${spec.name})`);
+    const result = await broker.provision({ ref: spec.ref, name: spec.name, plan: spec.plan, params });
+    const { instanceId, outputs: provisionOutputs } = await settle(broker, spec, result, poll, log);
+
+    let outputs = { ...provisionOutputs };
+    if (broker.bind) {
+      const bound = await broker.bind({ ref: spec.ref, name: spec.name, instanceId, params });
+      outputs = { ...outputs, ...bound.outputs };
+    }
+    outputsByRef[spec.ref] = outputs;
+    if (opts.sink && spec.bind && Object.keys(spec.bind).length) await opts.sink.write(outputs, spec.bind);
+
+    stateByRef.set(spec.ref, {
+      ref: spec.ref, service: spec.service, plan: spec.plan, name: spec.name,
+      instanceId, outputs, fingerprint: fingerprint(spec), protected: spec.protected, provisionedAt: now(),
+    });
+    applied.push({ ref: spec.ref, action: step.action as StepAction, instanceId, outputs });
+  }
+
+  const state = [...stateByRef.values()];
+  await opts.store.save(state);
+  return { steps: applied, state, outputsByRef };
+}
+
+export type { PlanStep };

package/src/brokers/cloudflare-domains.ts

@@ -0,0 +1,53 @@
+/**
+ * The Cloudflare Pages custom-domain broker (C047) — the ASYNC OSB showcase (this is the core of `provision-domains.ts`).
+ * Attaching a custom hostname to a Pages project is idempotent, but the edge CERT issues over seconds-to-minutes, so this
+ * is the textbook OSB last-operation flow: `provision` attaches + returns `in progress`, then `lastOperation` polls the
+ * domain status until it's `active` (cert live). The project + hostname are encoded in the instance id (the OSB operation
+ * anchor), so `lastOperation` + `deprovision` are self-contained — they need no params. The redirect-rule / DNS policy
+ * that's specific to one app stays in that app's config, not here.
+ */
+import type { CloudflareClient } from "@suluk/cloudflare";
+import type { Broker, Catalog, OperationState } from "../types";
+
+interface PagesDomain {
+  name: string;
+  status?: string;
+}
+
+const ANCHOR = "::"; // instanceId = `${project}::${hostname}`
+const catalog = (): Catalog => ({
+  services: [{ id: "cloudflare-pages-domain", name: "Cloudflare Pages Custom Domain", description: "A custom hostname on a Pages project (cert issued asynchronously)", bindable: false, plans: [{ id: "standard", name: "Standard", free: true }] }],
+});
+
+export function cloudflarePagesDomain(cf: CloudflareClient): Broker {
+  const domainsPath = (acct: string, project: string) => `/accounts/${acct}/pages/projects/${project}/domains`;
+
+  return {
+    catalog,
+    async provision(req) {
+      const project = req.params.project as string | undefined;
+      if (!project) throw new Error(`provision: cloudflare-pages-domain ${req.ref} needs a params.project`);
+      const hostname = req.name;
+      const acct = await cf.resolveAccountId();
+      const list = (await cf.request<PagesDomain[]>("GET", domainsPath(acct, project))) ?? [];
+      if (!list.some((d) => d.name === hostname)) await cf.request("POST", domainsPath(acct, project), { json: { name: hostname } });
+      // cert issuance is async → poll lastOperation until "active". outputs are known now (the hostname + its URL).
+      const instanceId = `${project}${ANCHOR}${hostname}`;
+      return { state: "in progress", operation: instanceId, instanceId, outputs: { hostname, url: `https://${hostname}` } };
+    },
+    async lastOperation(req) {
+      const [project, hostname] = (req.instanceId ?? req.operation).split(ANCHOR);
+      const acct = await cf.resolveAccountId();
+      const list = (await cf.request<PagesDomain[]>("GET", domainsPath(acct, project))) ?? [];
+      const status = list.find((d) => d.name === hostname)?.status ?? "pending";
+      const state: OperationState = status === "active" ? "succeeded" : "in progress";
+      return { state, description: status };
+    },
+    async deprovision(req) {
+      const [project, hostname] = (req.instanceId ?? "").split(ANCHOR);
+      const acct = await cf.resolveAccountId();
+      await cf.request("DELETE", `${domainsPath(acct, project)}/${hostname}`);
+      return { state: "succeeded" };
+    },
+  };
+}

package/src/brokers/cloudflare.ts

@@ -0,0 +1,111 @@
+/**
+ * The Cloudflare brokers (C047) — D1, KV, R2, and Worker secrets, each an OSB {@link Broker} that WRAPS @suluk/cloudflare's
+ * already-witnessed idempotent provisioners. The broker is thin on purpose: it advertises a catalog, maps a provision
+ * request onto the provisioner, and surfaces the resource id as a binding output (a D1 `database_id`, a KV `namespace_id`,
+ * an R2 `bucket_name`) for the binding chain. The provider calls all live in @suluk/cloudflare; these never re-implement
+ * them. Construct each with a configured `CloudflareClient` (the credentials seam).
+ */
+import type { CloudflareClient } from "@suluk/cloudflare";
+import { provisionD1, provisionKvNamespace, provisionR2Bucket, applyMigrations, putSecrets, type Migration } from "@suluk/cloudflare";
+import type { Broker, Catalog, OperationState } from "../types";
+
+const onePlan = (id: string, name: string, description: string, bindable: boolean): Catalog => ({
+  services: [{ id, name, description, bindable, plans: [{ id: "standard", name: "Standard", free: true }] }],
+});
+
+/** Best-effort delete via the Cloudflare REST API; maps to an OSB sync deprovision. */
+async function del(cf: CloudflareClient, path: string): Promise<{ state: OperationState }> {
+  const acct = await cf.resolveAccountId();
+  await cf.request("DELETE", `/accounts/${acct}${path}`);
+  return { state: "succeeded" };
+}
+
+/** D1 database. Provision is create-or-get; when `params.migrations` (a `Migration[]`) is present they're applied through
+ *  the @suluk/cloudflare ledger (each runs at most once). Output: `database_id`. */
+export function cloudflareD1(cf: CloudflareClient): Broker {
+  return {
+    catalog: () => onePlan("cloudflare-d1", "Cloudflare D1", "A serverless SQLite database", false),
+    async provision(req) {
+      const db = await provisionD1(cf, req.name);
+      const migrations = req.params.migrations as Migration[] | undefined;
+      if (migrations?.length) await applyMigrations(cf, db.uuid, migrations);
+      return { state: "succeeded", instanceId: db.uuid, outputs: { database_id: db.uuid } };
+    },
+    async fetch(req) {
+      if (!req.instanceId) return { exists: false };
+      const acct = await cf.resolveAccountId();
+      try {
+        await cf.request("GET", `/accounts/${acct}/d1/database/${req.instanceId}`);
+        return { exists: true, outputs: { database_id: req.instanceId } };
+      } catch {
+        return { exists: false }; // 404 / deleted in the dashboard → external drift
+      }
+    },
+    async list() {
+      const acct = await cf.resolveAccountId();
+      const dbs = (await cf.request<{ uuid: string; name: string }[]>("GET", `/accounts/${acct}/d1/database`)) ?? [];
+      return dbs.map((d) => ({ name: d.name, instanceId: d.uuid, outputs: { database_id: d.uuid } }));
+    },
+    deprovision: (req) => del(cf, `/d1/database/${req.instanceId}`),
+  };
+}
+
+/** Workers KV namespace. Provision is create-or-get. Output: `namespace_id`. */
+export function cloudflareKv(cf: CloudflareClient): Broker {
+  return {
+    catalog: () => onePlan("cloudflare-kv", "Cloudflare KV", "A Workers KV namespace", false),
+    async provision(req) {
+      const ns = await provisionKvNamespace(cf, req.name);
+      return { state: "succeeded", instanceId: ns.id, outputs: { namespace_id: ns.id } };
+    },
+    deprovision: (req) => del(cf, `/storage/kv/namespaces/${req.instanceId}`),
+  };
+}
+
+/** R2 bucket. Provision is create-or-get. Output: `bucket_name` (R2's id IS its name). */
+export function cloudflareR2(cf: CloudflareClient): Broker {
+  return {
+    catalog: () => onePlan("cloudflare-r2", "Cloudflare R2", "An R2 object-storage bucket", false),
+    async provision(req) {
+      const bucket = await provisionR2Bucket(cf, req.name);
+      return { state: "succeeded", instanceId: bucket.name, outputs: { bucket_name: bucket.name } };
+    },
+    deprovision: (req) => del(cf, `/r2/buckets/${req.instanceId}`),
+  };
+}
+
+/** A scoped, least-privilege Cloudflare API token (this is `mint-service-tokens.ts`). `params.permissionGroups` is the
+ *  permission-group id list; `params.resources` defaults to the whole account. The token VALUE is returned only at
+ *  creation, so it rides out as the `token` binding on provision (the framework's noop on re-apply never re-mints).
+ *  deprovision revokes it. The minting parent credential is the broker's own `CloudflareClient`. */
+export function cloudflareToken(cf: CloudflareClient): Broker {
+  return {
+    catalog: () => onePlan("cloudflare-token", "Cloudflare API Token", "A scoped, least-privilege API token", true),
+    async provision(req) {
+      const acct = await cf.resolveAccountId();
+      const groups = (req.params.permissionGroups ?? []) as string[];
+      const resources = (req.params.resources ?? { [`com.cloudflare.api.account.${acct}`]: "*" }) as Record<string, string>;
+      const body = { name: req.name, policies: [{ effect: "allow", resources, permission_groups: groups.map((id) => ({ id })) }] };
+      const tok = await cf.request<{ id?: string; value?: string }>("POST", `/accounts/${acct}/tokens`, { json: body });
+      if (!tok?.id || !tok?.value) throw new Error(`provision: cloudflare-token ${req.ref} mint returned no value`);
+      return { state: "succeeded", instanceId: tok.id, outputs: { token: tok.value, token_id: tok.id } };
+    },
+    deprovision: (req) => del(cf, `/tokens/${req.instanceId}`),
+  };
+}
+
+/** Worker secrets — the runtime-secret SINK as a broker (this is `sync-secrets.ts`). `params.script` is the Worker name;
+ *  `params.secrets` is a `Record<string,string>` of secret name → value (resolved from upstream `@ref.key` bindings).
+ *  Provision is an idempotent `wrangler secret put` for the whole set. Output: `secrets_set` (the names pushed). */
+export function cloudflareSecrets(cf: CloudflareClient): Broker {
+  return {
+    catalog: () => onePlan("cloudflare-secrets", "Cloudflare Worker Secrets", "Encrypted Worker runtime secrets", false),
+    async provision(req) {
+      const script = req.params.script as string | undefined;
+      const secrets = (req.params.secrets ?? {}) as Record<string, string | undefined>;
+      if (!script) throw new Error(`provision: cloudflare-secrets ${req.ref} needs a params.script (the Worker name)`);
+      const set = await putSecrets(cf, script, secrets);
+      return { state: "succeeded", instanceId: `${script}:secrets`, outputs: { secrets_set: set.join(",") } };
+    },
+  };
+}

package/src/check.ts

@@ -0,0 +1,31 @@
+/**
+ * The drift gate (C047) — drizzle-kit's `check` for infrastructure. `checkDrift` diffs config against the journal and
+ * returns the non-noop steps; `assertNoDrift` throws when any exist. Compose it into a CI gate (or @suluk/cockpit
+ * conformance) so a PR that adds an instance to the config without provisioning it, or leaves an orphan behind, fails.
+ */
+import type { InstanceState } from "./types";
+import type { ProvisionConfig } from "./config";
+import { plan, type PlanStep } from "./plan";
+
+export interface DriftReport {
+  clean: boolean;
+  /** the steps that would change something (create/update/deprovision) — empty when in sync. */
+  drift: PlanStep[];
+  orphans: string[];
+}
+
+/** Report whether live state matches the config (orphans counted only when pruning is the config default). */
+export function checkDrift(config: ProvisionConfig, state: InstanceState[]): DriftReport {
+  const p = plan(config, state);
+  return { clean: p.clean, drift: p.steps.filter((s) => s.action !== "noop"), orphans: p.orphans };
+}
+
+/** Fail-closed: throw when there's any drift (the CI gate). */
+export function assertNoDrift(config: ProvisionConfig, state: InstanceState[]): void {
+  const r = checkDrift(config, state);
+  if (!r.clean) {
+    const lines = r.drift.map((s) => `  ${s.action} ${s.ref} (${s.reason})`);
+    if (r.orphans.length) lines.push(`  orphans: ${r.orphans.join(", ")}`);
+    throw new Error(`provision: infrastructure drift detected\n${lines.join("\n")}`);
+  }
+}

package/src/cli.ts

@@ -0,0 +1,140 @@
+/**
+ * The CLI (C047) — drizzle-kit's command surface for infrastructure: `plan` (diff desired vs live), `apply`/`push`
+ * (provision + bind + sink), `check` (the drift CI gate, non-zero on drift), `status`/`studio` (the live inventory).
+ * `runCli` is PURE of the process — it returns `{ output, exitCode }` (no `process.exit`, no direct console), so it's
+ * unit-testable; `bin/provision.ts` is the thin shell that loads the config file, prints, and exits.
+ */
+import type { ProvisionApp } from "./app";
+import { plan, type ProvisionPlan, type PlanStep } from "./plan";
+import { apply, type AppliedStep } from "./apply";
+import { checkDrift } from "./check";
+import { pull, reconcile } from "./pull";
+import { teardown } from "./teardown";
+import { generate } from "./generate";
+import { migrate } from "./migrate";
+import type { InstanceState } from "./types";
+
+export interface CliResult {
+  output: string;
+  exitCode: number;
+}
+
+const SYM: Record<PlanStep["action"], string> = { create: "+", update: "~", noop: "=", deprovision: "-" };
+const APPLIED_SYM: Record<AppliedStep["action"], string> = { create: "+", update: "~", noop: "=", deprovision: "-" };
+
+function renderPlan(p: ProvisionPlan, out: (s: string) => void): void {
+  if (!p.steps.length) return out("No instances declared.");
+  for (const s of p.steps) out(`  ${SYM[s.action]} ${s.action.padEnd(11)} ${s.ref} (${s.service} · ${s.name}) — ${s.reason}`);
+  const counts = p.steps.reduce<Record<string, number>>((a, s) => ({ ...a, [s.action]: (a[s.action] ?? 0) + 1 }), {});
+  const summary = (["create", "update", "noop", "deprovision"] as const).filter((k) => counts[k]).map((k) => `${counts[k]} ${k}`).join(", ");
+  out(`\n${p.clean ? "✓ in sync" : `plan: ${summary}`}${!p.orphans.length ? "" : `  ·  orphans: ${p.orphans.join(", ")}`}`);
+}
+
+export async function runCli(app: ProvisionApp, argv: string[]): Promise<CliResult> {
+  const cmd = argv[0] ?? "plan";
+  const prune = argv.includes("--prune");
+  const lines: string[] = [];
+  const out = (s: string) => lines.push(s);
+  const done = (exitCode = 0): CliResult => ({ output: lines.join("\n"), exitCode });
+
+  switch (cmd) {
+    case "plan": {
+      const state = await app.store.load();
+      out(`── provision plan ${prune ? "(--prune)" : ""}──`);
+      renderPlan(plan(app.config, state, prune), out);
+      return done();
+    }
+    case "apply":
+    case "push": {
+      out(`── provision apply ${prune ? "(--prune)" : ""}──`);
+      const res = await apply(app.config, { brokers: app.brokers, store: app.store, sink: app.sink, prune, log: out });
+      const changed = res.steps.filter((s) => s.action !== "noop");
+      out(`\n✓ applied: ${changed.length ? changed.map((s) => `${APPLIED_SYM[s.action]}${s.ref}`).join(" ") : "nothing (all in sync)"}`);
+      return done();
+    }
+    case "check": {
+      const state = await app.store.load();
+      const r = checkDrift(app.config, state);
+      if (r.clean) {
+        out("✓ infrastructure in sync — no drift");
+        return done(0);
+      }
+      out("✗ infrastructure drift detected:");
+      for (const s of r.drift) out(`  ${SYM[s.action]} ${s.ref} (${s.reason})`);
+      if (r.orphans.length) out(`  orphans: ${r.orphans.join(", ")}`);
+      return done(1); // the CI gate
+    }
+    case "status":
+    case "studio": {
+      const state = (await app.store.load()) as InstanceState[];
+      if (!state.length) {
+        out("(nothing provisioned yet)");
+        return done();
+      }
+      out("── provisioned ──");
+      for (const s of state) {
+        const outs = Object.keys(s.outputs).length ? ` → ${Object.entries(s.outputs).map(([k, v]) => `${k}=${v}`).join(", ")}` : "";
+        out(`  ${s.ref} (${s.service} · ${s.name})${s.protected ? " 🔒" : ""}${outs}`);
+      }
+      return done();
+    }
+    case "pull": {
+      const state = await app.store.load();
+      const report = await pull(state, app.brokers);
+      out("── provision pull (live vs journal) ──");
+      for (const e of report.entries) out(`  ${e.status.padEnd(8)} ${e.ref} (${e.service} · ${e.name})`);
+      if (report.clean) {
+        out("\n✓ journal matches the provider");
+        return done();
+      }
+      out(`\ndrift: ${report.missing.length} missing, ${report.drifted.length} changed`);
+      if (argv.includes("--reconcile")) {
+        await app.store.save(reconcile(state, report));
+        out("✓ reconciled the journal (externally-deleted dropped, drifted outputs updated)");
+      } else {
+        out("run `pull --reconcile` to fold this into the journal");
+      }
+      return done();
+    }
+    case "teardown": {
+      const yes = argv.includes("--yes");
+      const force = argv.includes("--force");
+      const res = await teardown({ brokers: app.brokers, store: app.store, force, dryRun: !yes, log: out });
+      if (!yes) {
+        out(`\n⚠ DRY RUN — would tear down ${res.torn.length} instance(s)${res.kept.length ? `, keep ${res.kept.length}` : ""}. Re-run with --yes to DESTROY${res.kept.some((k) => k.reason === "protected") ? " (--force to include protected)" : ""}.`);
+        return done();
+      }
+      out(`\n✗ torn down ${res.torn.length} instance(s)${res.kept.length ? `; kept ${res.kept.map((k) => `${k.ref} (${k.reason})`).join(", ")}` : ""}.`);
+      return done();
+    }
+    case "generate": {
+      if (!app.migrations) {
+        out("no migration store configured — set `migrations` in the config to use generate/migrate");
+        return done(2);
+      }
+      const ni = argv.indexOf("--name");
+      const name = ni >= 0 ? argv[ni + 1] : undefined;
+      const m = await generate(app.config, app.migrations, name);
+      if (!m) {
+        out("✓ no changes — the config matches the last snapshot");
+        return done();
+      }
+      out(`✓ generated ${m.tag}:`);
+      for (const s of m.steps) out(`  ${SYM[s.action]} ${s.action.padEnd(11)} ${s.ref} (${s.service} · ${s.name})`);
+      return done();
+    }
+    case "migrate": {
+      if (!app.migrations) {
+        out("no migration store configured — set `migrations` in the config to use generate/migrate");
+        return done(2);
+      }
+      out("── provision migrate ──");
+      const res = await migrate({ brokers: app.brokers, store: app.store, migrations: app.migrations, sink: app.sink, log: out });
+      out(res.upToDate ? "\n✓ up to date — no pending migrations" : `\n✓ applied ${res.applied.length} migration(s)`);
+      return done();
+    }
+    default:
+      out(`unknown command "${cmd}". Commands: plan | apply (push) | generate | migrate | check | status | pull | teardown. Flags: --prune --reconcile --yes --force --name`);
+      return done(2);
+  }
+}

package/src/config.ts

@@ -0,0 +1,23 @@
+/**
+ * The declarative provision config (C047) — drizzle-kit's `drizzle.config.ts` for infrastructure. You list the instances
+ * you want (each an OSB broker + name + plan + params + binding map); `plan`/`apply`/`check` are pure functions of THIS
+ * plus live state. `defineProvision` validates the static shape (unique refs, an acyclic binding DAG) at authoring time,
+ * so an unreferenceable ref or a binding loop is caught before any provider is called.
+ */
+import type { InstanceSpec } from "./types";
+import { topoOrder } from "./dag";
+
+export interface ProvisionConfig {
+  /** the instances to provision (desired state). Order is free — the binding DAG decides apply order. */
+  instances: InstanceSpec[];
+  /** orphan mitigation default: deprovision instances in state but not in config. DEFAULT false (destructive — opt in
+   *  here or per-apply). `apply --prune` / `check` honour it. */
+  pruneOrphans?: boolean;
+}
+
+/** Validate + return a provision config. Throws on a duplicate ref, an undeclared-ref reference, or a binding cycle
+ *  (via {@link topoOrder}) — all the static errors, surfaced before `apply` touches a provider. */
+export function defineProvision(config: ProvisionConfig): ProvisionConfig {
+  topoOrder(config.instances); // throws on dup ref / unknown ref / cycle
+  return config;
+}

package/src/dag.ts

@@ -0,0 +1,53 @@
+/**
+ * Topological ordering of the declared instances (C047) by their binding edges (from `@ref.key` params), so every
+ * instance is provisioned AFTER the producers its params reference — the binding chain (create D1 → its id feeds the
+ * Worker; mint a scoped token → it feeds the secrets push). Kahn's algorithm; throws on a cycle or an unknown ref.
+ */
+import type { InstanceSpec } from "./types";
+import { depsOf } from "./refs";
+
+/** Order `instances` so each comes after its binding producers. Stable (config order breaks ties). Throws on a cycle or
+ *  a reference to an undeclared instance. */
+export function topoOrder(instances: InstanceSpec[]): InstanceSpec[] {
+  const byRef = new Map(instances.map((i) => [i.ref, i]));
+  const seen = new Set<string>();
+  const refs = instances.map((i) => i.ref);
+  if (new Set(refs).size !== refs.length) {
+    const dupe = refs.find((r, idx) => refs.indexOf(r) !== idx);
+    throw new Error(`provision: duplicate instance ref "${dupe}" — refs must be unique`);
+  }
+
+  const indegree = new Map<string, number>();
+  const dependents = new Map<string, string[]>(); // producer ref → the refs that depend on it
+  for (const i of instances) {
+    indegree.set(i.ref, 0);
+    dependents.set(i.ref, []);
+  }
+  for (const i of instances) {
+    for (const dep of depsOf(i)) {
+      if (!byRef.has(dep)) throw new Error(`provision: ${i.ref} references @${dep}.* but no instance "${dep}" is declared`);
+      indegree.set(i.ref, (indegree.get(i.ref) ?? 0) + 1);
+      dependents.get(dep)!.push(i.ref);
+    }
+  }
+
+  // Seed the queue in config order (stable output) with the zero-indegree instances.
+  const queue = instances.filter((i) => (indegree.get(i.ref) ?? 0) === 0).map((i) => i.ref);
+  const ordered: InstanceSpec[] = [];
+  while (queue.length) {
+    const ref = queue.shift()!;
+    if (seen.has(ref)) continue;
+    seen.add(ref);
+    ordered.push(byRef.get(ref)!);
+    for (const d of dependents.get(ref) ?? []) {
+      indegree.set(d, (indegree.get(d) ?? 0) - 1);
+      if ((indegree.get(d) ?? 0) === 0) queue.push(d);
+    }
+  }
+
+  if (ordered.length !== instances.length) {
+    const cyclic = instances.filter((i) => !seen.has(i.ref)).map((i) => i.ref);
+    throw new Error(`provision: binding cycle among instances [${cyclic.join(", ")}] — a chain of @ref.key params loops`);
+  }
+  return ordered;
+}

package/src/env-sink.ts

@@ -0,0 +1,29 @@
+/**
+ * The @suluk/env binding sink (C047) — where provisioned credentials LAND: each (output → env var) goes through
+ * @suluk/env/node's `setVar`, which writes the `.env` and POST-QUANTUM-ENCRYPTS secret values so the file stays
+ * commit-safe. This closes the binding chain: `apply` resolves a token/id, the sink persists it as a typed, encrypted
+ * env var the app + the next instance read. By default every binding is encrypted (the safe default); pass `plain` to
+ * mark the non-secret ones (a database_id, a bucket name) readable.
+ */
+import { setVar } from "@suluk/env/node";
+import type { BindingSink } from "./types";
+
+type SetVarOpts = NonNullable<Parameters<typeof setVar>[2]>;
+
+export interface EnvSinkOptions extends Omit<SetVarOpts, "plain"> {
+  /** predicate: which env vars are written PLAINTEXT (non-secret). Default: none — every binding is encrypted. */
+  plain?: (envVar: string) => boolean;
+}
+
+/** A {@link BindingSink} that persists bindings into a `.env` via @suluk/env (encrypted by default; commit-safe). */
+export function envSink(opts: EnvSinkOptions = {}): BindingSink {
+  const { plain, ...fileOpts } = opts;
+  return {
+    async write(outputs, mapping) {
+      for (const [outKey, envVar] of Object.entries(mapping)) {
+        if (!(outKey in outputs)) continue;
+        await setVar(envVar, outputs[outKey], { ...fileOpts, plain: plain?.(envVar) ?? false });
+      }
+    },
+  };
+}

package/src/file-store.ts

@@ -0,0 +1,25 @@
+/**
+ * The file-backed {@link StateStore} (C047) — the provision journal on disk (default `.suluk/provision.json`), the
+ * record `plan` diffs against, like drizzle's `meta/_journal.json`. A missing file reads as empty state (a first
+ * provision); a save writes pretty JSON (reviewable in a PR). Commit it: it's the source of truth for what's live.
+ */
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { dirname } from "node:path";
+import type { InstanceState, StateStore } from "./types";
+
+export function fileStore(path = ".suluk/provision.json"): StateStore {
+  return {
+    async load(): Promise<InstanceState[]> {
+      try {
+        return JSON.parse(await readFile(path, "utf8")) as InstanceState[];
+      } catch (e) {
+        if ((e as NodeJS.ErrnoException).code === "ENOENT") return []; // first run — no journal yet
+        throw e;
+      }
+    },
+    async save(state: InstanceState[]): Promise<void> {
+      await mkdir(dirname(path), { recursive: true });
+      await writeFile(path, `${JSON.stringify(state, null, 2)}\n`);
+    },
+  };
+}

package/src/generate.ts

@@ -0,0 +1,20 @@
+/**
+ * `generate` (C047) — drizzle-kit's `generate` for infrastructure. Diffs the current config against the last committed
+ * snapshot; if anything changed, writes the next migration (the ordered delta) + its snapshot and appends the journal.
+ * Pure of any provider — this only records the intended change (repeatable + reviewable in a PR); `migrate` applies it.
+ * Returns the migration, or null when the config already matches the last snapshot (nothing to generate).
+ */
+import type { ProvisionConfig } from "./config";
+import type { MigrationStore } from "./migration-store";
+import { diffSnapshots, migrationTag, type Migration } from "./migration";
+import { snapshot } from "./snapshot";
+
+export async function generate(config: ProvisionConfig, store: MigrationStore, name?: string): Promise<Migration | null> {
+  const prev = await store.lastSnapshot();
+  const steps = diffSnapshots(prev, config);
+  if (!steps.length) return null; // config == last snapshot → nothing to record
+  const idx = prev.idx + 1;
+  const migration: Migration = { idx, tag: migrationTag(idx, name), steps };
+  await store.write(migration, snapshot(idx, config));
+  return migration;
+}