@suluk/provision 0.1.0

package/src/index.ts

@@ -0,0 +1,39 @@
+/**
+ * @suluk/provision — declarative service provisioning for a Suluk app, modelled on the Open Service Broker API and
+ * driven like drizzle-kit (C047). Declare the infra you want in one config; each service (Cloudflare D1/KV/R2/secrets,
+ * Stripe, a domain, a scoped token) is an OSB {@link Broker} advertising a {@link Catalog} and answering provision /
+ * bind / deprovision. `plan` diffs desired-vs-live (pure), `apply` walks the binding DAG (provision → poll async
+ * last-operation → bind → land credentials in @suluk/env), `assertNoDrift` is the CI gate. This package is the OSB
+ * *client* / orchestrator — a layer ABOVE @suluk/cloudflare / @suluk/deploy / @suluk/env, which it composes as brokers +
+ * the binding sink. This barrel is the CORE framework; the concrete brokers + the CLI ship alongside it.
+ */
+export type {
+  OperationState, ServicePlan, ServiceOffering, Catalog,
+  InstanceSpec, InstanceState,
+  ProvisionRequest, ProvisionResult, BindRequest, BindResult, OperationRequest,
+  Broker, BindingSink, StateStore,
+} from "./types";
+export { defineProvision, type ProvisionConfig } from "./config";
+export { topoOrder } from "./dag";
+export { parseRef, depsOf, resolveParams, stableStringify, fingerprint } from "./refs";
+export { plan, type ProvisionPlan, type PlanStep, type StepAction } from "./plan";
+export { apply, type ApplyOptions, type ApplyResult, type AppliedStep } from "./apply";
+export { pollToDone, type PollOptions } from "./poll";
+export { checkDrift, assertNoDrift, type DriftReport } from "./check";
+export { pull, reconcile, discover, type PullReport, type PullEntry, type PullStatus, type DiscoveredInstance } from "./pull";
+export { teardown, type TeardownOptions, type TeardownResult } from "./teardown";
+// the drizzle-style snapshot + migration model (repeatable, documentable steps).
+export { snapshot, EMPTY_SNAPSHOT, SNAPSHOT_VERSION, type Snapshot } from "./snapshot";
+export { diffSnapshots, migrationTag, type Migration, type MigrationStep } from "./migration";
+export { memoryMigrationStore, fileMigrationStore, type MigrationStore, type MigrationJournal } from "./migration-store";
+export { generate } from "./generate";
+export { migrate, type MigrateOptions, type MigrateResult } from "./migrate";
+export { memoryStore, memorySink } from "./memory";
+export { fileStore } from "./file-store";
+export { envSink, type EnvSinkOptions } from "./env-sink";
+// the concrete Cloudflare brokers (wrap @suluk/cloudflare's idempotent provisioners).
+export { cloudflareD1, cloudflareKv, cloudflareR2, cloudflareSecrets, cloudflareToken } from "./brokers/cloudflare";
+export { cloudflarePagesDomain } from "./brokers/cloudflare-domains";
+// the drizzle-kit-style app config + CLI (plan / apply / check / status).
+export { defineProvisionApp, type ProvisionApp } from "./app";
+export { runCli, type CliResult } from "./cli";

package/src/memory.ts

@@ -0,0 +1,31 @@
+/**
+ * In-memory {@link StateStore} + {@link BindingSink} (C047) — the default seams for a dry-run, a test, or a `plan`
+ * preview that should touch no disk. The file-backed store + the @suluk/env sink are separate adapters; these keep the
+ * core dependency-free + deterministic.
+ */
+import type { BindingSink, InstanceState, StateStore } from "./types";
+
+/** A StateStore over an in-memory array (cloned on load/save so callers can't mutate the journal by reference). */
+export function memoryStore(initial: InstanceState[] = []): StateStore & { snapshot(): InstanceState[] } {
+  let state: InstanceState[] = structuredClone(initial);
+  return {
+    load: () => structuredClone(state),
+    save: (s) => {
+      state = structuredClone(s);
+    },
+    snapshot: () => structuredClone(state),
+  };
+}
+
+/** A BindingSink that records every (envVar → value) it lands — for assertions + a dry-run "what would be set" preview. */
+export function memorySink(): BindingSink & { values: Record<string, string> } {
+  const values: Record<string, string> = {};
+  return {
+    values,
+    write(outputs, mapping) {
+      for (const [outKey, envVar] of Object.entries(mapping)) {
+        if (outKey in outputs) values[envVar] = outputs[outKey];
+      }
+    },
+  };
+}

package/src/migrate.ts

@@ -0,0 +1,51 @@
+/**
+ * `migrate` (C047) — drizzle-kit's `migrate` for infrastructure. Runs the PENDING migrations (those not in this
+ * environment's applied-ledger) in index order, marking each applied — so the same committed history brings any
+ * environment (prod, preview, a fresh account) to the same state, repeatably. Each migration is executed by replaying its
+ * SNAPSHOT as the desired state through `apply` (pruning, so a migration's deprovision runs; `protected` still guards) —
+ * which REUSES the whole engine: the binding chain, async last-operation polling, the sink. The migration's step list is
+ * the documented record; the snapshot is what actually executes.
+ */
+import type { Broker, BindingSink, StateStore } from "./types";
+import type { MigrationStore } from "./migration-store";
+import type { PollOptions } from "./poll";
+import { apply } from "./apply";
+
+export interface MigrateOptions {
+  brokers: Record<string, Broker>;
+  /** the live journal (InstanceState). */
+  store: StateStore;
+  /** the committed migrations + this env's applied-ledger. */
+  migrations: MigrationStore;
+  sink?: BindingSink;
+  poll?: PollOptions;
+  log?: (msg: string) => void;
+}
+
+export interface MigrateResult {
+  applied: number[];
+  upToDate: boolean;
+}
+
+export async function migrate(opts: MigrateOptions): Promise<MigrateResult> {
+  const log = opts.log ?? (() => {});
+  const all = await opts.migrations.listMigrations();
+  const done = new Set(await opts.migrations.applied());
+  const pending = all.filter((m) => !done.has(m.idx));
+  if (!pending.length) {
+    log("✓ migrations up to date");
+    return { applied: [], upToDate: true };
+  }
+  const applied: number[] = [];
+  for (const m of pending) {
+    const snap = await opts.migrations.loadSnapshot(m.idx);
+    if (!snap) throw new Error(`provision: migration ${m.tag} has no snapshot`);
+    log(`▸ ${m.tag} (${m.steps.length} step${m.steps.length === 1 ? "" : "s"})`);
+    // replay the snapshot as the desired state; prune so a dropped instance in this migration is deprovisioned (protected
+    // still guards). apply is idempotent, so a re-run after a mid-migration failure resumes cleanly.
+    await apply({ instances: snap.instances, pruneOrphans: true }, { brokers: opts.brokers, store: opts.store, sink: opts.sink, poll: opts.poll, log: opts.log });
+    await opts.migrations.markApplied(m.idx);
+    applied.push(m.idx);
+  }
+  return { applied, upToDate: false };
+}

package/src/migration-store.ts

@@ -0,0 +1,110 @@
+/**
+ * The migration store (C047) — the on-disk shape drizzle-kit uses: a committed `meta/_journal.json` (the ordered list of
+ * migrations), one `NNNN_tag.json` per migration (the delta), one `meta/NNNN_snapshot.json` per migration (the
+ * point-in-time desired state), and an env-local `meta/_applied.json` (which migrations THIS environment has run — like
+ * drizzle's `__drizzle_migrations` table; gitignore it, prod ≠ preview). The memory impl is for tests/dry-runs.
+ */
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { EMPTY_SNAPSHOT, SNAPSHOT_VERSION, type Snapshot } from "./snapshot";
+import type { Migration } from "./migration";
+
+export interface MigrationJournal {
+  version: string;
+  entries: { idx: number; tag: string }[];
+}
+
+export interface MigrationStore {
+  /** the latest committed snapshot, or EMPTY when there are no migrations yet. */
+  lastSnapshot(): Promise<Snapshot>;
+  loadSnapshot(idx: number): Promise<Snapshot | null>;
+  /** all migrations, in index order. */
+  listMigrations(): Promise<Migration[]>;
+  /** write a new migration + its snapshot, appending the journal. */
+  write(migration: Migration, snapshot: Snapshot): Promise<void>;
+  /** which migration indices THIS environment has applied. */
+  applied(): Promise<number[]>;
+  markApplied(idx: number): Promise<void>;
+}
+
+/** An in-memory migration store (tests / dry-runs). */
+export function memoryMigrationStore(): MigrationStore {
+  const migrations: Migration[] = [];
+  const snapshots = new Map<number, Snapshot>();
+  const appliedSet: number[] = [];
+  return {
+    async lastSnapshot() {
+      const last = migrations.at(-1);
+      return last ? snapshots.get(last.idx) ?? EMPTY_SNAPSHOT : EMPTY_SNAPSHOT;
+    },
+    async loadSnapshot(idx) {
+      return snapshots.get(idx) ?? null;
+    },
+    async listMigrations() {
+      return migrations.map((m) => ({ ...m }));
+    },
+    async write(migration, snap) {
+      migrations.push(migration);
+      snapshots.set(snap.idx, snap);
+    },
+    async applied() {
+      return [...appliedSet];
+    },
+    async markApplied(idx) {
+      if (!appliedSet.includes(idx)) appliedSet.push(idx);
+    },
+  };
+}
+
+/** A file-backed migration store rooted at `dir` (default `provision/`). Commits `NNNN_tag.json` + `meta/_journal.json` +
+ *  `meta/NNNN_snapshot.json`; keeps the env-local `meta/_applied.json` (gitignore it). */
+export function fileMigrationStore(dir = "provision"): MigrationStore {
+  const meta = join(dir, "meta");
+  const journalPath = join(meta, "_journal.json");
+  const appliedPath = join(meta, "_applied.json");
+  const pretty = (v: unknown) => `${JSON.stringify(v, null, 2)}\n`;
+
+  async function readJson<T>(path: string, fallback: T): Promise<T> {
+    try {
+      return JSON.parse(await readFile(path, "utf8")) as T;
+    } catch (e) {
+      if ((e as NodeJS.ErrnoException).code === "ENOENT") return fallback;
+      throw e;
+    }
+  }
+  const pad = (idx: number) => String(idx).padStart(4, "0");
+  const journal = () => readJson<MigrationJournal>(journalPath, { version: SNAPSHOT_VERSION, entries: [] });
+  const loadSnapshot = (idx: number) => readJson<Snapshot | null>(join(meta, `${pad(idx)}_snapshot.json`), null);
+
+  return {
+    async lastSnapshot() {
+      const j = await journal();
+      const last = j.entries.at(-1);
+      return last ? (await loadSnapshot(last.idx)) ?? EMPTY_SNAPSHOT : EMPTY_SNAPSHOT;
+    },
+    loadSnapshot,
+    async listMigrations() {
+      const j = await journal();
+      return Promise.all(j.entries.map((e) => readJson<Migration>(join(dir, `${e.tag}.json`), { idx: e.idx, tag: e.tag, steps: [] })));
+    },
+    async write(migration, snap) {
+      await mkdir(meta, { recursive: true });
+      await writeFile(join(dir, `${migration.tag}.json`), pretty(migration));
+      await writeFile(join(meta, `${pad(snap.idx)}_snapshot.json`), pretty(snap));
+      const j = await journal();
+      j.entries.push({ idx: migration.idx, tag: migration.tag });
+      await writeFile(journalPath, pretty(j));
+    },
+    async applied() {
+      return readJson<number[]>(appliedPath, []);
+    },
+    async markApplied(idx) {
+      await mkdir(meta, { recursive: true });
+      const a = await readJson<number[]>(appliedPath, []);
+      if (!a.includes(idx)) {
+        a.push(idx);
+        await writeFile(appliedPath, pretty(a));
+      }
+    },
+  };
+}

package/src/migration.ts

@@ -0,0 +1,48 @@
+/**
+ * Migrations (C047) — drizzle-kit's `NNNN_name.sql` for infrastructure: the DELTA between two snapshots, as an ordered,
+ * human-readable list of steps (create/update/deprovision). A migration is documentable (committed JSON, reviewable in a
+ * PR) and repeatable (its snapshot replays to the same state). `diffSnapshots` computes it: creates/updates in
+ * binding-DAG order (a producer before its consumer), deprovisions in reverse (a consumer before its producer).
+ */
+import type { InstanceSpec } from "./types";
+import type { ProvisionConfig } from "./config";
+import type { Snapshot } from "./snapshot";
+import { topoOrder } from "./dag";
+import { fingerprint } from "./refs";
+
+export interface MigrationStep {
+  action: "create" | "update" | "deprovision";
+  ref: string;
+  service: string;
+  name: string;
+  /** the full spec for a create/update (so the migration is self-describing); absent for a deprovision. */
+  spec?: InstanceSpec;
+}
+
+export interface Migration {
+  idx: number;
+  /** the file stem, e.g. "0000_initial". */
+  tag: string;
+  steps: MigrationStep[];
+}
+
+/** `NNNN_name` — the zero-padded migration tag. */
+export const migrationTag = (idx: number, name = "migration"): string => `${String(idx).padStart(4, "0")}_${name}`;
+
+/** Diff the previous snapshot against the next (current) config → the ordered migration steps. Creates + updates come in
+ *  binding-DAG order (producers first); deprovisions of dropped instances come last, in reverse (consumers first). */
+export function diffSnapshots(prev: Snapshot, next: ProvisionConfig): MigrationStep[] {
+  const prevByRef = new Map(prev.instances.map((i) => [i.ref, i]));
+  const nextByRef = new Map(next.instances.map((i) => [i.ref, i]));
+  const steps: MigrationStep[] = [];
+
+  for (const spec of topoOrder(next.instances)) {
+    const before = prevByRef.get(spec.ref);
+    if (!before) steps.push({ action: "create", ref: spec.ref, service: spec.service, name: spec.name, spec });
+    else if (fingerprint(before) !== fingerprint(spec) || before.name !== spec.name) steps.push({ action: "update", ref: spec.ref, service: spec.service, name: spec.name, spec });
+  }
+  for (const prevSpec of [...prev.instances].reverse()) {
+    if (!nextByRef.has(prevSpec.ref)) steps.push({ action: "deprovision", ref: prevSpec.ref, service: prevSpec.service, name: prevSpec.name });
+  }
+  return steps;
+}

package/src/plan.ts

@@ -0,0 +1,60 @@
+/**
+ * The diff (C047) — drizzle-kit's `generate`/diff for infrastructure: desired config × live state → a reviewable plan of
+ * steps, in binding-DAG order. PURE: no provider calls, no clock. `apply` executes a plan; `check` asserts a plan is
+ * empty (no drift). The four actions mirror the OSB verbs the executor will call.
+ */
+import type { InstanceSpec, InstanceState } from "./types";
+import type { ProvisionConfig } from "./config";
+import { topoOrder } from "./dag";
+import { fingerprint } from "./refs";
+
+export type StepAction = "create" | "update" | "noop" | "deprovision";
+
+export interface PlanStep {
+  ref: string;
+  service: string;
+  name: string;
+  action: StepAction;
+  /** human-readable cause: "new" | "params changed" | "up to date" | "orphan (in state, not in config)". */
+  reason: string;
+}
+
+export interface ProvisionPlan {
+  steps: PlanStep[];
+  /** refs present in state but absent from config — deprovisioned only when pruning is on (else surfaced, not touched). */
+  orphans: string[];
+  /** true when every step is a noop and there are no (prunable) orphans — the `check` CI gate passes on this. */
+  clean: boolean;
+}
+
+/** Diff `config` against `state`. Desired instances are emitted in binding-DAG order (create/update/noop); orphans
+ *  (state − config) become `deprovision` steps only when `prune` (the config default, or an override) is on. */
+export function plan(config: ProvisionConfig, state: InstanceState[], prune = config.pruneOrphans ?? false): ProvisionPlan {
+  const byRef = new Map(state.map((s) => [s.ref, s]));
+  const declared = new Set(config.instances.map((i) => i.ref));
+  const ordered = topoOrder(config.instances);
+
+  const steps: PlanStep[] = ordered.map((spec: InstanceSpec) => {
+    const prior = byRef.get(spec.ref);
+    if (!prior) return { ref: spec.ref, service: spec.service, name: spec.name, action: "create", reason: "new" };
+    if (prior.fingerprint !== fingerprint(spec) || prior.name !== spec.name) {
+      return { ref: spec.ref, service: spec.service, name: spec.name, action: "update", reason: "params changed" };
+    }
+    return { ref: spec.ref, service: spec.service, name: spec.name, action: "noop", reason: "up to date" };
+  });
+
+  const orphans = state.filter((s) => !declared.has(s.ref)).map((s) => s.ref);
+  if (prune) {
+    for (const ref of orphans) {
+      const s = byRef.get(ref)!;
+      // a PROTECTED orphan is surfaced but NOT scheduled for destruction — the prevent-destroy safety rail.
+      if (s.protected) steps.push({ ref, service: s.service, name: s.name, action: "noop", reason: "orphan but protected — kept" });
+      else steps.push({ ref, service: s.service, name: s.name, action: "deprovision", reason: "orphan (in state, not in config)" });
+    }
+  }
+
+  // "clean" ignores protected-orphan noops (they're intentionally kept, not pending work).
+  const prunable = prune ? orphans.filter((ref) => !byRef.get(ref)?.protected) : [];
+  const clean = steps.every((s) => s.action === "noop") && prunable.length === 0;
+  return { steps, orphans, clean };
+}

package/src/poll.ts

@@ -0,0 +1,37 @@
+/**
+ * OSB last-operation polling (C047) — shared by `apply` (async provision) and `teardown` (async deprovision). The clock +
+ * sleep are injected so the loop is deterministically testable. Throws on "failed" or timeout.
+ */
+import type { Broker, OperationState } from "./types";
+
+export interface PollOptions {
+  intervalMs?: number;
+  timeoutMs?: number;
+  sleep?: (ms: number) => Promise<void>;
+  now?: () => number;
+}
+
+const sleepReal = (ms: number) => new Promise<void>((r) => setTimeout(r, ms));
+
+/** Poll an async operation to a terminal state. Throws on "failed" or after `timeoutMs`. */
+export async function pollToDone(
+  broker: Broker,
+  req: { ref: string; name: string; instanceId?: string; operation: string },
+  poll: PollOptions,
+  log: (m: string) => void,
+): Promise<void> {
+  if (!broker.lastOperation) throw new Error(`provision: ${req.ref} returned an async operation but its broker has no lastOperation()`);
+  const intervalMs = poll.intervalMs ?? 2000;
+  const timeoutMs = poll.timeoutMs ?? 600_000;
+  const now = poll.now ?? Date.now;
+  const sleep = poll.sleep ?? sleepReal;
+  const start = now();
+  for (;;) {
+    const { state, description }: { state: OperationState; description?: string } = await broker.lastOperation(req);
+    if (state === "succeeded") return;
+    if (state === "failed") throw new Error(`provision: ${req.ref} operation failed${description ? ` — ${description}` : ""}`);
+    if (now() - start > timeoutMs) throw new Error(`provision: ${req.ref} operation timed out after ${timeoutMs}ms`);
+    log(`  … ${req.ref} ${req.operation} (in progress)`);
+    await sleep(intervalMs);
+  }
+}

package/src/pull.ts

@@ -0,0 +1,92 @@
+/**
+ * Introspection (C047) — drizzle-kit's `pull` for infrastructure, over OSB's "Fetching a Service Instance". `plan`
+ * compares the config to the JOURNAL (what we believe is live); `pull` compares the journal to the PROVIDER (what's
+ * actually live), catching EXTERNAL drift — a database dropped in the dashboard, a token revoked out of band, an id that
+ * changed behind the config's back. `reconcile` folds a report back into the journal; `discover` finds untracked
+ * resources to adopt. All read-only against the journal — the caller persists the reconciled state.
+ */
+import type { Broker, InstanceState, OperationRequest } from "./types";
+
+export type PullStatus = "live" | "missing" | "drifted" | "unknown";
+
+export interface PullEntry {
+  ref: string;
+  service: string;
+  name: string;
+  instanceId: string;
+  /** live = present + matches · missing = gone from the provider · drifted = present but outputs changed · unknown = the
+   *  broker has no `fetch`, so we couldn't check. */
+  status: PullStatus;
+  liveOutputs?: Record<string, string>;
+}
+
+export interface PullReport {
+  entries: PullEntry[];
+  /** journaled refs whose live resource is GONE (deleted outside the config) — the next `apply` re-creates them. */
+  missing: string[];
+  /** journaled refs whose live outputs differ from the journal. */
+  drifted: string[];
+  /** nothing missing or drifted (unknowns don't count — we couldn't verify them). */
+  clean: boolean;
+}
+
+/** Compare only the keys the live fetch reported (it may return a subset of the journal's outputs). */
+function outputsMatch(live: Record<string, string>, journal: Record<string, string>): boolean {
+  return Object.keys(live).every((k) => live[k] === journal[k]);
+}
+
+/** Fetch each journaled instance's live state via its broker (OSB fetch) → an external-drift report. Read-only. */
+export async function pull(state: InstanceState[], brokers: Record<string, Broker>): Promise<PullReport> {
+  const entries: PullEntry[] = [];
+  for (const s of state) {
+    const broker = brokers[s.service];
+    const base = { ref: s.ref, service: s.service, name: s.name, instanceId: s.instanceId };
+    if (!broker?.fetch) {
+      entries.push({ ...base, status: "unknown" });
+      continue;
+    }
+    const req: OperationRequest = { ref: s.ref, name: s.name, instanceId: s.instanceId, operation: "fetch" };
+    const live = await broker.fetch(req);
+    if (!live.exists) {
+      entries.push({ ...base, status: "missing" });
+      continue;
+    }
+    const drifted = !!live.outputs && !outputsMatch(live.outputs, s.outputs);
+    entries.push({ ...base, status: drifted ? "drifted" : "live", liveOutputs: live.outputs });
+  }
+  const missing = entries.filter((e) => e.status === "missing").map((e) => e.ref);
+  const drifted = entries.filter((e) => e.status === "drifted").map((e) => e.ref);
+  return { entries, missing, drifted, clean: missing.length === 0 && drifted.length === 0 };
+}
+
+/** Fold a pull report into the journal: DROP externally-deleted instances (so the next `apply` re-creates them) + MERGE
+ *  live outputs over drifted ones (never dropping a bound value the provider doesn't know, e.g. a minted token). Pure —
+ *  returns the reconciled state; the caller saves it. */
+export function reconcile(state: InstanceState[], report: PullReport): InstanceState[] {
+  const missing = new Set(report.missing);
+  const liveByRef = new Map(report.entries.filter((e) => e.liveOutputs).map((e) => [e.ref, e.liveOutputs!]));
+  return state
+    .filter((s) => !missing.has(s.ref))
+    .map((s) => (liveByRef.has(s.ref) ? { ...s, outputs: { ...s.outputs, ...liveByRef.get(s.ref)! } } : s));
+}
+
+export interface DiscoveredInstance {
+  service: string;
+  name: string;
+  instanceId: string;
+  outputs?: Record<string, string>;
+}
+
+/** Discover live instances (via `broker.list`) that AREN'T in the journal — untracked resources to adopt (`pull
+ *  --discover`). Skips services whose broker has no `list`. */
+export async function discover(state: InstanceState[], brokers: Record<string, Broker>): Promise<DiscoveredInstance[]> {
+  const known = new Set(state.map((s) => `${s.service}:${s.instanceId}`));
+  const found: DiscoveredInstance[] = [];
+  for (const [service, broker] of Object.entries(brokers)) {
+    if (!broker.list) continue;
+    for (const inst of await broker.list()) {
+      if (!known.has(`${service}:${inst.instanceId}`)) found.push({ service, name: inst.name, instanceId: inst.instanceId, outputs: inst.outputs });
+    }
+  }
+  return found;
+}

package/src/refs.ts

@@ -0,0 +1,60 @@
+/**
+ * Binding references + fingerprints (C047) — the wiring under the provisioning DAG. A param string of the form
+ * `@<ref>.<key>` names another instance's binding OUTPUT (e.g. `@db.database_id`): it's an EDGE (this instance depends on
+ * `db`) and a substitution (resolved from `db`'s outputs at apply time). Pure + deterministic.
+ */
+import type { InstanceSpec } from "./types";
+
+/** Matches a whole-string binding reference `@<ref>.<key>` (refs are dotted-handle → output-key). */
+const REF_RE = /^@([A-Za-z0-9_-]+)\.([A-Za-z0-9_.-]+)$/;
+
+/** Parse a single value: a `@ref.key` string → its parts, else null (not a reference). */
+export function parseRef(value: unknown): { ref: string; key: string } | null {
+  if (typeof value !== "string") return null;
+  const m = REF_RE.exec(value);
+  return m ? { ref: m[1], key: m[2] } : null;
+}
+
+/** Every instance ref a spec's params depend on (deduped) — the spec's in-edges in the DAG. */
+export function depsOf(spec: InstanceSpec): string[] {
+  const out = new Set<string>();
+  for (const v of Object.values(spec.params ?? {})) {
+    const r = parseRef(v);
+    if (r) out.add(r.ref);
+  }
+  return [...out];
+}
+
+/** Resolve a spec's params against the accumulated outputs (ref → its output map). Throws if a referenced output is
+ *  missing (a producer that didn't emit the key) — fail-closed, never silently substitute undefined into a provider call. */
+export function resolveParams(spec: InstanceSpec, outputsByRef: Record<string, Record<string, string>>): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(spec.params ?? {})) {
+    const r = parseRef(v);
+    if (!r) {
+      out[k] = v;
+      continue;
+    }
+    const producer = outputsByRef[r.ref];
+    if (!producer || !(r.key in producer)) {
+      throw new Error(`provision: ${spec.ref}.params.${k} references @${r.ref}.${r.key}, but ${r.ref} has no output "${r.key}"`);
+    }
+    out[k] = producer[r.key];
+  }
+  return out;
+}
+
+/** A stable JSON string (recursively sorted keys) — order-independent so a fingerprint is reproducible. */
+export function stableStringify(value: unknown): string {
+  if (value === null || typeof value !== "object") return JSON.stringify(value) ?? "null";
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
+  const keys = Object.keys(value as Record<string, unknown>).sort();
+  return `{${keys.map((k) => `${JSON.stringify(k)}:${stableStringify((value as Record<string, unknown>)[k])}`).join(",")}}`;
+}
+
+/** The drift fingerprint of a desired instance = a stable hash of (name + plan + params). A change flips it → an `update`
+ *  step; an unchanged spec matches its stored fingerprint → a `noop`. (Refs are fingerprinted as their literal `@ref.key`
+ *  text — a producer's VALUE changing is the producer's own drift, surfaced on its own step.) */
+export function fingerprint(spec: InstanceSpec): string {
+  return stableStringify({ name: spec.name, plan: spec.plan ?? null, params: spec.params ?? {} });
+}

package/src/snapshot.ts

@@ -0,0 +1,25 @@
+/**
+ * Snapshots (C047) — drizzle-kit's `meta/NNNN_snapshot.json` for infrastructure. A snapshot is the point-in-time DESIRED
+ * state (the config's instances) at a given migration index. `generate` diffs the last snapshot against the current
+ * config to compute the next migration; `migrate` replays a snapshot as the desired state. Committed to git, snapshots
+ * make every infra change a repeatable, reviewable record — the same discipline as SQL migration snapshots.
+ */
+import type { InstanceSpec } from "./types";
+import type { ProvisionConfig } from "./config";
+
+export const SNAPSHOT_VERSION = "1";
+
+export interface Snapshot {
+  version: string;
+  /** the migration index this snapshot represents (−1 = the empty pre-history state). */
+  idx: number;
+  instances: InstanceSpec[];
+}
+
+/** The empty baseline — the "before the first migration" state, so the first `generate` diffs against nothing. */
+export const EMPTY_SNAPSHOT: Snapshot = { version: SNAPSHOT_VERSION, idx: -1, instances: [] };
+
+/** A snapshot of `config` at migration `idx`. */
+export function snapshot(idx: number, config: ProvisionConfig): Snapshot {
+  return { version: SNAPSHOT_VERSION, idx, instances: config.instances };
+}

package/src/teardown.ts

@@ -0,0 +1,69 @@
+/**
+ * Teardown (C047) — the destructive op: deprovision EVERY journaled instance, CONSUMERS-FIRST (reverse of the journal's
+ * provision order), so a producer is never removed while a consumer still references it. The careful rails: a `protected`
+ * instance (a database, a bucket — a resource whose loss is unrecoverable) is SKIPPED unless `force`; a broker with no
+ * `deprovision` is skipped (kept); an async teardown is polled to done. The CLI additionally gates this behind an explicit
+ * confirmation — `teardown` alone previews, `teardown --yes` executes. Returns what was torn down + what was kept.
+ */
+import type { Broker, InstanceState, StateStore } from "./types";
+import { pollToDone, type PollOptions } from "./poll";
+
+export interface TeardownOptions {
+  brokers: Record<string, Broker>;
+  store: StateStore;
+  /** override the `protected` rail — required to destroy a protected instance. */
+  force?: boolean;
+  /** preview only: compute the order + honour the rails, but call NO provider + don't save. The confirmation default. */
+  dryRun?: boolean;
+  log?: (msg: string) => void;
+  poll?: PollOptions;
+}
+
+export interface TeardownResult {
+  /** refs deprovisioned (or, under dryRun, that WOULD be). */
+  torn: string[];
+  /** refs kept + why: protected (no force) or the broker can't deprovision. */
+  kept: { ref: string; reason: string }[];
+  /** the remaining journal after teardown (the kept instances). */
+  state: InstanceState[];
+}
+
+/** Deprovision the whole journal, consumers-first, honouring `protected`. Destructive — gate it behind confirmation. */
+export async function teardown(opts: TeardownOptions): Promise<TeardownResult> {
+  const log = opts.log ?? (() => {});
+  const poll = opts.poll ?? {};
+  const state = await opts.store.load();
+  const torn: string[] = [];
+  const kept: { ref: string; reason: string }[] = [];
+  const keptState: InstanceState[] = [];
+
+  // reverse journal order ≈ consumers before producers (the journal is written in provision/DAG order).
+  for (const s of [...state].reverse()) {
+    if (s.protected && !opts.force) {
+      kept.push({ ref: s.ref, reason: "protected" });
+      keptState.push(s);
+      log(`• kept ${s.ref} (protected — pass --force to destroy)`);
+      continue;
+    }
+    const broker = opts.brokers[s.service];
+    if (!broker?.deprovision) {
+      kept.push({ ref: s.ref, reason: "no deprovision" });
+      keptState.push(s);
+      log(`• kept ${s.ref} (${s.service} has no deprovision)`);
+      continue;
+    }
+    if (opts.dryRun) {
+      torn.push(s.ref);
+      log(`  - would tear down ${s.ref} (${s.name})`);
+      continue;
+    }
+    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);
+    torn.push(s.ref);
+    log(`✗ torn down ${s.ref} (${s.name})`);
+  }
+
+  const finalState = keptState.reverse(); // restore journal (provision) order
+  if (!opts.dryRun) await opts.store.save(finalState);
+  return { torn, kept, state: finalState };
+}