@homeflare/alchemy 0.6.0 → 0.8.0

package/src/openbao/cloudflare-role-wire.test.ts

@@ -1,7 +1,8 @@
 /**
- * Bao.CloudflareRole's calls against a fake that behaves like the Cloudflare engine where it matters:
- * a write parses the duration text into seconds and re-marshals `policies` (path_roles.go:117-146,
- * :199-210), a role never written is a 404, and a delete answers 204 whether or not it existed.
+ * Bao.CloudflareRole's calls against a fake that behaves like the Cloudflare engine where it matters
+ * (fake-engines.ts): a write parses the duration text into seconds and re-marshals `policies`
+ * (path_roles.go:117-146, :199-210), a role never written is a 404, and a delete answers 204
+ * whether or not it existed.
  */
 import assert from 'node:assert/strict';
 import { describe, it } from 'node:test';
@@ -13,8 +14,8 @@ import {
   readCloudflareRole,
   writeCloudflareRole,
 } from './cloudflare-role-wire.ts';
-import { type Reply, type Seen, run, runFailure, withFake } from './fake-bao.ts';
-import { parseDuration } from './mount-form.ts';
+import { run, runFailure, withFake } from './fake-bao.ts';
+import { cloudflareRoles } from './fake-engines.ts';
 
 const PROPS: BaoCloudflareRoleProps = {
   description: 'Read DNS records on one zone. (zone: example.com)',
@@ -34,36 +35,9 @@ const PROPS: BaoCloudflareRoleProps = {
 
 const PATH = '/v1/cloudflare-acme-dns/roles/example-com-dns-read';
 
-/** The engine's role store, reduced to what these calls can observe. */
-const roleStore = () => {
-  const roles = new Map<string, Record<string, unknown>>();
-  return (seen: Seen): Reply => {
-    if (seen.method === 'PUT') {
-      const body = JSON.parse(seen.body) as Record<string, string>;
-      roles.set(seen.path, {
-        description: body['description'],
-        max_ttl: parseDuration(body['max_ttl'] ?? ''),
-        name: seen.path.split('/').at(-1),
-        // ★ Re-marshalled, as json.Marshal of the stored structs would be.
-        policies: JSON.stringify(JSON.parse(body['policies'] ?? 'null')),
-        ttl: parseDuration(body['ttl'] ?? ''),
-      });
-      return { status: 204 };
-    }
-    if (seen.method === 'DELETE') {
-      roles.delete(seen.path);
-      return { status: 204 };
-    }
-    const role = roles.get(seen.path);
-    return role === undefined
-      ? { json: { errors: [] }, status: 404 }
-      : { json: { data: role }, status: 200 };
-  };
-};
-
 describe('Cloudflare role wire', () => {
   it('reads a role that was never written as absent', async () => {
-    await withFake(roleStore(), async (bao) => {
+    await withFake(cloudflareRoles(), async (bao) => {
       const env = { BAO_ADDR: bao.address };
       assert.equal(await run(env, readCloudflareRole(PROPS.mount, PROPS.name)), undefined);
       assert.deepEqual([bao.seen[0]?.method, bao.seen[0]?.path], ['GET', PATH]);
@@ -71,7 +45,7 @@ describe('Cloudflare role wire', () => {
   });
 
   it('writes the four fields and reads them back with no difference', async () => {
-    await withFake(roleStore(), async (bao) => {
+    await withFake(cloudflareRoles(), async (bao) => {
       const env = { BAO_ADDR: bao.address };
       const { policies } = resolvePolicies(
         PROPS.policies,

package/src/openbao/cloudflare-role.ts

@@ -38,6 +38,7 @@ import {
   readCloudflareRole,
   writeCloudflareRole,
 } from './cloudflare-role-wire.ts';
+import { guardRename, judgeRename, roleIdentity } from './rename-identity.ts';
 
 export type { BaoCloudflareRoleAttributes, BaoCloudflareRoleProps };
 
@@ -59,6 +60,9 @@ export const BaoCloudflareRole = Resource<BaoCloudflareRole>('Bao.CloudflareRole
   defaultRemovalPolicy: 'retain',
 });
 
+/** Exact: a trailing `/` on the mount is the same path (`rolePath` trims it). */
+const IDENTITY = roleIdentity<BaoCloudflareRoleAttributes>('Bao.CloudflareRole', rolePath);
+
 export const BaoCloudflareRoleProvider = () =>
   Provider.effect(
     BaoCloudflareRole,
@@ -112,14 +116,22 @@ export const BaoCloudflareRoleProvider = () =>
          *   OpenBao UI changes what every future token can do while the digest in Postgres still
          *   says everything is fine.
          *
-         * ⚠️ NO `replace`, EVEN FOR A NAME OR MOUNT CHANGE. A different path is a different object,
-         *   so diff reads the new path, finds it absent and plans `update`; reconcile creates it and
-         *   the old role is left live, retained and unmanaged — the same outcome apply-roles.py's
-         *   UNTRACKED report had. declareCloudflareRoles puts mount and name in the resource id, so
-         *   a rename there is a new resource anyway.
+         * ⛔ A NEW `mount` OR `name` IS A `replace`, DECIDED BEFORE ANY OTHER READ (rename.ts). Until
+         *   2026-09-21 this read the new path, found it absent and planned `update`: reconcile wrote
+         *   the new role and the old one stayed live and mintable under no state record. ⛔ A move
+         *   onto a role that already exists fails the plan (`judgeMove`).
+         * ⚠️ UNDER THE DEFAULT `retain` THE OLD ROLE STILL MINTS for any token whose policy reaches its
+         *   `creds/<name>`. Under `destroy` every consumer still minting from the old path fails at
+         *   the delete, so move them in the same PR (REPLACE.md).
+         * ★ A STACK THAT PUTS mount AND name IN THE LOGICAL ID never reaches this branch
+         *   (homeflare-openbao's declareCloudflareRoles does). There a rename is a new logical id,
+         *   and the old id leaves the stack as an orphan delete, which `retain` keeps live.
          */
-        diff: Effect.fn(function* ({ news, output }) {
-          if (output === undefined || !isResolved(news)) return undefined;
+        diff: Effect.fn(function* ({ news, olds, output }) {
+          const move = yield* judgeRename(IDENTITY, olds, news, output);
+          if (output === undefined) return undefined;
+          if (move !== undefined) return { action: 'replace' } as const;
+          if (!isResolved(news)) return undefined;
           /**
            * ⚠️ A DECLARATION reconcile WOULD REFUSE MUST NEVER PLAN AS noop — route it to reconcile,
            *   which says why (pki-role.ts has the same guard).
@@ -133,8 +145,10 @@ export const BaoCloudflareRoleProvider = () =>
             : ({ action: 'update' } as const);
         }),
 
-        reconcile: Effect.fn(function* ({ news }) {
+        reconcile: Effect.fn(function* ({ news, output }) {
           const path = rolePath(news.mount, news.name);
+          // ⛔ An `update` across a move the diff could not see — refused before any write.
+          yield* guardRename(IDENTITY, news, output);
           const refusal = refusalOf(news);
           if (refusal !== undefined) {
             return yield* Effect.die(new Error(`Bao.CloudflareRole ${path}: ${refusal}.`));

package/src/openbao/fake-engines-roles.ts

@@ -0,0 +1,114 @@
+/**
+ * Fakes of the stores behind the batch-2 families, for fake-bao: every role engine, JWT auth config
+ * and login-MFA enforcements (`wireRoles`), the TOTP method table (`totpMethods`) and the plugin
+ * catalog (`pluginCatalog`), behind one answer (`fakeEstate`). As in fake-engines.ts, each keys its
+ * objects the way the real server does, because a rename test is only as good as the fake's idea of
+ * "the same object".
+ *
+ * ⛔ TEST-ONLY — see fake-bao.ts. No provider imports this file.
+ */
+import type { Reply, Seen } from './fake-bao.ts';
+import { ABSENT, type Store, type Stored, lastSegment, store } from './fake-engines.ts';
+
+/**
+ * The role stores whose server lowercases the name: AppRole (openbao v2.6.2
+ * builtin/credential/approle/path_role.go:1485 and :1893), Kubernetes
+ * (builtin/credential/kubernetes backend.go:362, path_role.go:250 and :396) and JWT, whose `name`
+ * field is a TypeLowerCaseString (builtin/credential/jwt/path_role.go:77; sdk v2.6.2
+ * framework/field_data.go:250-255 lowercases it on read). PKI and SSH store the name verbatim. The
+ * tests mount all three at their default paths.
+ */
+const FOLDED = /^auth\/(approle|jwt|kubernetes)\/role\/[^/]+$/;
+
+const keyOf = (path: string): string =>
+  FOLDED.test(path) ? path.replace(/[^/]+$/, (name) => name.toLowerCase()) : path;
+
+/** Fields a write sends comma-joined that the server reads back as a list. */
+const LISTS = new Set([
+  'allowed_domains',
+  'cn_validations',
+  'ext_key_usage',
+  'key_usage',
+  'token_policies',
+]);
+
+/**
+ * The server's typed view of a `k=v` body: `true`, `false` and digit strings become values, and the
+ * LISTS split. Arrays, objects and duration strings pass through, and every reader here takes a
+ * duration string as well as seconds (`ttlSeconds`).
+ */
+const typed = (body: Stored): Stored => {
+  const out: Stored = {};
+  for (const [field, value] of Object.entries(body)) {
+    if (typeof value !== 'string') out[field] = value;
+    else if (LISTS.has(field)) out[field] = value.split(',').filter((part) => part !== '');
+    else if (value === 'true' || value === 'false') out[field] = value === 'true';
+    else out[field] = /^\d+$/.test(value) ? Number(value) : value;
+  }
+  return out;
+};
+
+/** Every role engine, JWT auth config and MFA login enforcement. A write replaces the object. */
+export const wireRoles = (): Store =>
+  store<Stored>(
+    (_path, body) => typed(body),
+    (path) => keyOf(path),
+  );
+
+/**
+ * `sys/plugins/catalog/<type>/<name>`. A register names its version in the body; a read or a delete
+ * names it in `?version=` (plugin-form.ts versionedPath).
+ */
+export const pluginCatalog = (): Store =>
+  store<Stored>(
+    (path, body) => ({ ...body, builtin: false, name: lastSegment(path.split('?')[0] ?? '') }),
+    (path, body) => {
+      const version = body?.['version'];
+      return typeof version === 'string' && version !== '' ? `${path}?version=${version}` : path;
+    },
+  );
+
+/**
+ * `identity/mfa/method/totp`: an upsert by `method_name` (identity/mfa.go:159-230), listed with
+ * every other type under `identity/mfa/method?list=true` (mfa-wire.ts). Keyed by the server-made
+ * id.
+ */
+export const totpMethods = (): Store => {
+  const live = new Map<string, Stored>();
+  let made = 0;
+  const answer = (seen: Seen): Reply => {
+    const path = seen.path.replace(/^\/v1\//, '');
+    if (seen.method === 'POST') {
+      const body = JSON.parse(seen.body) as Stored;
+      const name = body['method_name'];
+      const found = [...live].find(([, method]) => method['name'] === name)?.[0];
+      made += found === undefined ? 1 : 0;
+      const id = found ?? `method-${String(made)}`;
+      live.set(id, { ...body, id, name, namespace_path: '', type: 'totp' });
+      return { json: { data: { method_id: id } }, status: 200 };
+    }
+    if (seen.method === 'DELETE') {
+      live.delete(lastSegment(path));
+      return { status: 204 };
+    }
+    if (path !== 'identity/mfa/method?list=true' || live.size === 0) return ABSENT;
+    const info = Object.fromEntries(live);
+    return { json: { data: { key_info: info, keys: [...live.keys()] } }, status: 200 };
+  };
+  return Object.assign(answer, { live });
+};
+
+/** All three behind one answer, routed by path, for a stack that mixes the families. */
+export const fakeEstate = () => {
+  const roles = wireRoles();
+  const plugins = pluginCatalog();
+  const totp = totpMethods();
+  const answer = (seen: Seen): Reply => {
+    if (seen.path.startsWith('/v1/identity/mfa/method')) return totp(seen);
+    if (seen.path.startsWith('/v1/sys/plugins/catalog/')) return plugins(seen);
+    return roles(seen);
+  };
+  return Object.assign(answer, { plugins, roles, totp });
+};
+
+export type Estate = ReturnType<typeof fakeEstate>;

package/src/openbao/fake-engines.ts

@@ -0,0 +1,126 @@
+/**
+ * Fakes of the three stores behind Bao.Policy, Bao.CloudflareRole and Bao.ProxmoxRole, for fake-bao,
+ * plus Bao.Policy's provider over fake fragment directories. Each store keys its objects the way the
+ * real server does. That is the point: a rename test is only as good as the fake's idea of "the
+ * same object". `store` is shared with fake-engines-roles.ts, which fakes the batch-2 families.
+ *
+ * ⛔ TEST-ONLY — see fake-bao.ts. No provider imports this file.
+ */
+import * as Effect from 'effect/Effect';
+import * as FileSystem from 'effect/FileSystem';
+import * as Layer from 'effect/Layer';
+import * as Path from 'effect/Path';
+import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
+import type { Reply, Seen } from './fake-bao.ts';
+import { parseDuration } from './mount-form.ts';
+import { trimTrailing } from './mount-path.ts';
+import { BaoPolicyProvider } from './policy.ts';
+import { policyKey } from './rename.ts';
+
+export type Stored = Record<string, unknown>;
+
+/** An answer for fake-bao that also exposes what it holds, keyed by API path (no `/v1/`). */
+export type Store = ((seen: Seen) => Reply) & { readonly live: Map<string, Stored> };
+
+export const ABSENT: Reply = { json: { errors: [] }, status: 404 };
+
+/**
+ * A store of objects by API path. `key` turns a request path (and a write's body) into the key the
+ * server would store it under.
+ */
+export const store = <B extends Stored = Record<string, string>>(
+  write: (path: string, body: B, before: Stored | undefined) => Stored,
+  key: (path: string, body?: B) => string = (path) => path,
+): Store => {
+  const live = new Map<string, Stored>();
+  const answer = (seen: Seen): Reply => {
+    const raw = seen.path.replace(/^\/v1\//, '');
+    // ★ `bao write` sends PUT, and the identity endpoints are called with POST. Both write.
+    if (seen.method === 'PUT' || seen.method === 'POST') {
+      const body = JSON.parse(seen.body) as B;
+      const path = key(raw, body);
+      live.set(path, write(path, body, live.get(path)));
+      return { status: 204 };
+    }
+    const path = key(raw);
+    // ★ A delete answers 204 whether or not the object existed, as every engine here does.
+    if (seen.method === 'DELETE') {
+      live.delete(path);
+      return { status: 204 };
+    }
+    const data = live.get(path);
+    return data === undefined ? ABSENT : { json: { data }, status: 200 };
+  };
+  return Object.assign(answer, { live });
+};
+
+export const lastSegment = (path: string): string => path.split('/').at(-1) ?? '';
+
+/**
+ * `sys/policies/acl/<name>`. It strips the policy's trailing newline on write (measured on the live
+ * server — digest.ts), and keys the name as OpenBao does: trimmed and lowercased (`policyKey`).
+ */
+export const aclPolicies = (): Store =>
+  store(
+    (path, body) => ({
+      name: lastSegment(path),
+      policy: trimTrailing(body['policy'] ?? '', '\n'),
+    }),
+    (path) =>
+      path.startsWith('sys/policies/acl/')
+        ? `sys/policies/acl/${policyKey(decodeURIComponent(lastSegment(path)))}`
+        : path,
+  );
+
+/**
+ * `<mount>/roles/<name>` on the Cloudflare engine. A write parses the duration text into seconds and
+ * re-marshals `policies` (path_roles.go:117-146, :199-210). Names are stored verbatim.
+ */
+export const cloudflareRoles = (): Store =>
+  store((path, body) => ({
+    description: body['description'],
+    max_ttl: parseDuration(body['max_ttl'] ?? ''),
+    name: lastSegment(path),
+    // ★ Re-marshalled, as json.Marshal of the stored structs would be.
+    policies: JSON.stringify(JSON.parse(body['policies'] ?? 'null')),
+    ttl: parseDuration(body['ttl'] ?? ''),
+  }));
+
+/**
+ * `<mount>/roles/<name>` on the proxmox engine. A write MERGES into the stored role, and TTLs go over
+ * as seconds (homeflare-openbao-plugins secrets/proxmox/path_roles.go, pathRolesWrite).
+ */
+export const proxmoxRoles = (): Store =>
+  store((path, body, before) => ({
+    max_ttl: 0,
+    name: lastSegment(path),
+    ttl: 0,
+    ...before,
+    ...(body['mint_user'] === undefined ? {} : { mint_user: body['mint_user'] }),
+    ...(body['ttl'] === undefined ? {} : { ttl: Number(body['ttl']) }),
+    ...(body['max_ttl'] === undefined ? {} : { max_ttl: Number(body['max_ttl']) }),
+  }));
+
+/**
+ * Bao.Policy's provider over fragment directories that exist only here: `…/empty` holds no file,
+ * `…/two` holds two, and any other directory one. Each file is one grant named after its own path,
+ * so a directory's content is its name.
+ */
+export const fakePolicyProviders = Layer.mergeAll(
+  BaoPolicyProvider().pipe(
+    Layer.provide(
+      Layer.mergeAll(
+        FileSystem.layerNoop({
+          readDirectory: (dir) =>
+            Effect.succeed(
+              dir.endsWith('/empty') ? [] : dir.endsWith('/two') ? ['a.hcl', 'b.hcl'] : ['a.hcl'],
+            ),
+          readFileString: (path) =>
+            Effect.succeed(`path "${path}" {\n  capabilities = ["read"]\n}`),
+        }),
+        Path.layer,
+      ),
+    ),
+  ),
+  FetchHttpClient.layer,
+);

package/src/openbao/fake-families.ts

@@ -0,0 +1,182 @@
+/**
+ * The nine batch-2 families as rows of one table, so a rename test can run each of them through
+ * Alchemy's own plan and apply (fake-stack.ts) against one fake (fake-engines-roles.ts). Every row
+ * declares a resource whose identity is `name` (for Bao.JwtAuthConfig, the mount), with `knob`, a
+ * duration, in a prop that is NOT its identity: the pending Output in "a rename lands with another
+ * pending prop".
+ *
+ * ⛔ TEST-ONLY. Every value is a placeholder, not the estate's.
+ */
+import * as RemovalPolicy from 'alchemy/RemovalPolicy';
+import type * as Output from 'alchemy/Output';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
+import { BaoAuthRole, BaoAuthRoleProvider } from './auth-role.ts';
+import type { Seen } from './fake-bao.ts';
+import { type Estate, fakeEstate } from './fake-engines-roles.ts';
+import { type FakeStack, type StackBody, withFakeStack } from './fake-stack.ts';
+import { BaoJwtAuthConfig, BaoJwtAuthConfigProvider } from './jwt-config.ts';
+import { BaoJwtRole, BaoJwtRoleProvider } from './jwt-role.ts';
+import { BaoKubernetesRole, BaoKubernetesRoleProvider } from './kubernetes-role.ts';
+import { BaoMfaLoginEnforcement, BaoMfaLoginEnforcementProvider } from './mfa-enforcement.ts';
+import { BaoMfaTotpMethod, BaoMfaTotpMethodProvider } from './mfa-totp.ts';
+import { BaoPkiRole, BaoPkiRoleProvider } from './pki-role.ts';
+import { BaoPlugin, BaoPluginProvider } from './plugin.ts';
+import { BaoSshRole, BaoSshRoleProvider } from './ssh-role.ts';
+
+export const familyProviders = Layer.mergeAll(
+  BaoAuthRoleProvider(),
+  BaoJwtAuthConfigProvider(),
+  BaoJwtRoleProvider(),
+  BaoKubernetesRoleProvider(),
+  BaoMfaLoginEnforcementProvider(),
+  BaoMfaTotpMethodProvider(),
+  BaoPkiRoleProvider(),
+  BaoPluginProvider(),
+  BaoSshRoleProvider(),
+  FetchHttpClient.layer,
+);
+
+/** One stack over a fresh estate: every family's provider, and every call the fake saw. */
+export const withEstate = (
+  body: (stack: FakeStack, estate: Estate, seen: Seen[]) => Promise<void>,
+): Promise<void> => {
+  const estate = fakeEstate();
+  return withFakeStack(familyProviders, estate, (stack, bao) => body(stack, estate, bao.seen));
+};
+
+/** The row for one family, by name. */
+export const rowOf = (family: string): Family => {
+  const row = FAMILIES.find((each) => each.family === family);
+  if (row === undefined) throw new Error(`no fake-families row for ${family}`);
+  return row;
+};
+
+type Text = string | Output.Output<string>;
+type Removal = typeof RemovalPolicy.destroy;
+
+export interface Family {
+  readonly family: string;
+  /** One resource, logical id `id`, whose identity is `name`. */
+  readonly declare: (id: string, name: Text, knob: Text, removal?: Removal) => StackBody;
+  /** Whether the fake holds the object `name` names. */
+  readonly has: (estate: Estate, name: string) => boolean;
+}
+
+const role = (path: (name: string) => string) => (estate: Estate, name: string) =>
+  estate.roles.live.has(path(name));
+
+const APPROLE = { secretIdTtl: '24h', tokenMaxTtl: '1h', tokenPolicies: ['default'] } as const;
+const SHA = 'a'.repeat(64);
+
+export const FAMILIES: readonly Family[] = [
+  {
+    declare: (id, name, knob, removal = RemovalPolicy.retain) =>
+      BaoAuthRole(id, { ...APPROLE, name, tokenTtl: knob }).pipe(removal()),
+    family: 'Bao.AuthRole',
+    has: role((name) => `auth/approle/role/${name}`),
+  },
+  {
+    declare: (id, name, knob, removal = RemovalPolicy.retain) =>
+      BaoPkiRole(id, { allowedDomains: ['example.com'], maxTtl: '8760h', name, ttl: knob }).pipe(
+        removal(),
+      ),
+    family: 'Bao.PkiRole',
+    has: role((name) => `pki/roles/${name}`),
+  },
+  {
+    declare: (id, name, knob, removal = RemovalPolicy.retain) =>
+      BaoJwtRole(id, {
+        boundAudiences: ['https://example.com'],
+        name,
+        roleType: 'jwt',
+        tokenPolicies: ['ci'],
+        tokenTtl: knob,
+        userClaim: 'sub',
+      }).pipe(removal()),
+    family: 'Bao.JwtRole',
+    has: role((name) => `auth/jwt/role/${name}`),
+  },
+  {
+    declare: (id, name, knob, removal = RemovalPolicy.retain) =>
+      BaoKubernetesRole(id, {
+        aliasNameSource: 'serviceaccount_uid',
+        boundServiceAccountNames: ['app'],
+        boundServiceAccountNamespaces: ['apps'],
+        name,
+        tokenPolicies: ['app'],
+        tokenTtl: knob,
+      }).pipe(removal()),
+    family: 'Bao.KubernetesRole',
+    has: role((name) => `auth/kubernetes/role/${name}`),
+  },
+  {
+    declare: (id, mount, knob, removal = RemovalPolicy.retain) =>
+      BaoJwtAuthConfig(id, {
+        boundIssuer: knob,
+        jwksUrl: 'https://issuer.example.com/keys',
+        mount,
+      }).pipe(removal()),
+    family: 'Bao.JwtAuthConfig',
+    has: role((mount) => `auth/${mount}/config`),
+  },
+  {
+    declare: (id, name, knob, removal = RemovalPolicy.retain) =>
+      BaoMfaTotpMethod(id, { issuer: knob, name }).pipe(removal()),
+    family: 'Bao.MfaTotpMethod',
+    has: (estate, name) => [...estate.totp.live.values()].some((each) => each['name'] === name),
+  },
+  {
+    declare: (id, name, knob, removal = RemovalPolicy.retain) =>
+      BaoMfaLoginEnforcement(id, {
+        authMethodTypes: ['jwt'],
+        mfaMethodIds: [knob],
+        name,
+      }).pipe(removal()),
+    family: 'Bao.MfaLoginEnforcement',
+    has: role((name) => `identity/mfa/login-enforcement/${name}`),
+  },
+  {
+    declare: (id, name, knob, removal = RemovalPolicy.retain) =>
+      BaoSshRole(id, {
+        allowUserCertificates: true,
+        allowedUsers: ['ops'],
+        maxTtl: '8h',
+        name,
+        ttl: knob,
+      }).pipe(removal()),
+    family: 'Bao.SshRole',
+    has: role((name) => `ssh/roles/${name}`),
+  },
+  {
+    declare: (id, name, knob, removal = RemovalPolicy.retain) =>
+      BaoPlugin(id, {
+        args: [knob],
+        command: 'plugin-example',
+        name,
+        sha256: SHA,
+        type: 'secret',
+        version: 'v1.0.0',
+      }).pipe(removal()),
+    family: 'Bao.Plugin',
+    has: (estate, name) =>
+      estate.plugins.live.has(`sys/plugins/catalog/secret/${name}?version=v1.0.0`),
+  },
+];
+
+/**
+ * Two of one family, `X` and `Y`, under destroy: the shape a swap or a shift needs. Their knobs
+ * differ, so a generation that lands on the other's name has to write over it.
+ */
+export const pairOf =
+  (row: Family) =>
+  (x: string, y: string): StackBody =>
+    Effect.gen(function* () {
+      yield* row.declare('X', x, '15m', RemovalPolicy.destroy);
+      yield* row.declare('Y', y, '30m', RemovalPolicy.destroy);
+    });
+
+/** An AppRole whose `tokenTtl` attribute is the Output the other rows are fed. */
+export const upstream = (ttl: string) =>
+  BaoAuthRole('Upstream', { ...APPROLE, name: 'upstream', tokenTtl: ttl });

package/src/openbao/fake-stack.ts

@@ -0,0 +1,112 @@
+/**
+ * Alchemy's own Plan and Apply, run in-process over an in-memory state store, so a test can deploy a
+ * declaration, change it, deploy again, and see what the ENGINE did with a provider's answers: which
+ * action it planned, and which calls reached the fake.
+ *
+ * ★ WHY THE ENGINE AND NOT THE HANDLERS ALONE. A diff that answers `replace` proves nothing by itself.
+ *   What matters is that Apply then creates the new generation, deletes the OLD one with the OLD
+ *   attributes, and keeps it under `retain`. Those are claims about alchemy@2.0.0-beta.79, and this
+ *   harness measures them instead of restating them (REPLACE.md).
+ * ★ NOT alchemy/Test/Bun. Its runtime builds the CLI's profile and credentials stores, which read
+ *   files under the home directory, plus a file logger. This needs none of that: the providers, an
+ *   in-memory state store, a stage, and the stack's own services. It is the composition
+ *   alchemy/src/Deploy.ts uses, minus the platform layer.
+ *
+ * ⛔ TEST-ONLY, AND NEVER A REAL VAULT. `BaoEnv` is provided explicitly, so a BAO_ADDR or BAO_TOKEN
+ *   in the shell running the tests is never read. No provider imports this file.
+ */
+import * as Alchemy from 'alchemy';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import type { BaoEnvironment } from './bao-address.ts';
+import { BaoEnv } from './bao-http.ts';
+import { type Fake, type Reply, type Seen, fakeBao } from './fake-bao.ts';
+
+/** The planned action for each resource, deletions included, keyed by FQN. */
+export type Planned = Readonly<Record<string, string>>;
+
+/** A stack body: resource declarations, as an `alchemy.run.ts` would write them. */
+export type StackBody = Effect.Effect<unknown, unknown, unknown>;
+
+export interface FakeStack {
+  /** Plan, then apply, `body`. Resolves to the plan; rejects with the apply's failure. */
+  readonly deploy: (body: StackBody) => Promise<Planned>;
+}
+
+type Node = { readonly action: string };
+type PlanView = {
+  readonly resources: Readonly<Record<string, Node>>;
+  readonly deletions: Readonly<Record<string, Node | undefined>>;
+};
+
+const actionsOf = (plan: PlanView): Planned => {
+  const out: Record<string, string> = {};
+  for (const [fqn, node] of Object.entries(plan.resources)) out[fqn] = node.action;
+  for (const [fqn, node] of Object.entries(plan.deletions)) {
+    if (node !== undefined) out[fqn] = node.action;
+  }
+  return out;
+};
+
+/**
+ * One stack over one state store, shared by every `deploy`, so the second deploy plans against what
+ * the first one recorded.
+ *
+ * ⚠️ THE CASTS ARE AT THE ENGINE'S TYPED BOUNDARY, NOT IN THE PROVIDERS. `Alchemy.Stack` types its body
+ *   against every service a CLI run provides. Here the body needs only the providers given, and a
+ *   missing one fails the test by name ("Provider not found for …").
+ */
+export const fakeStack = <ROut, E, RIn>(
+  providers: Layer.Layer<ROut, E, RIn>,
+  env: BaoEnvironment,
+  name = 'RenameStack',
+): FakeStack => {
+  const state = Alchemy.inMemoryState();
+  const stack = Alchemy.Stack as unknown as (
+    stackName: string,
+    options: { providers: typeof providers; state: typeof state },
+    body: StackBody,
+  ) => Effect.Effect<{ readonly services: never }, unknown, never>;
+  const plan = Alchemy.Plan.make as unknown as (
+    compiled: unknown,
+  ) => Effect.Effect<PlanView, unknown, never>;
+  const apply = Alchemy.apply as unknown as (planned: PlanView) => Effect.Effect<unknown, unknown>;
+
+  const deploy = (body: StackBody) =>
+    Effect.gen(function* () {
+      const compiled = yield* stack(name, { providers, state }, body);
+      return yield* Effect.gen(function* () {
+        const planned = yield* plan(compiled);
+        yield* apply(planned);
+        return actionsOf(planned);
+      }).pipe(Effect.provide(Layer.succeedContext(compiled.services)));
+    }).pipe(
+      Effect.provideService(Alchemy.Stage, 'test'),
+      Effect.provideService(BaoEnv, env),
+      Effect.provide(state),
+      Effect.scoped,
+    );
+
+  return { deploy: (body) => Effect.runPromise(deploy(body) as Effect.Effect<Planned>) };
+};
+
+/**
+ * A fake engine answering with `answer`, and one stack over it, for one test. The fake stops however
+ * `body` ends.
+ */
+export const withFakeStack = async <ROut, E, RIn>(
+  providers: Layer.Layer<ROut, E, RIn>,
+  answer: (seen: Seen) => Reply,
+  body: (stack: FakeStack, bao: Fake) => Promise<void>,
+): Promise<void> => {
+  const bao = fakeBao(answer);
+  try {
+    await body(fakeStack(providers, { BAO_ADDR: bao.address }), bao);
+  } finally {
+    bao.stop();
+  }
+};
+
+/** Every call that changed something, as `METHOD /v1/path`, in order. */
+export const writesOf = (seen: readonly Seen[]): string[] =>
+  seen.filter((each) => each.method !== 'GET').map((each) => `${each.method} ${each.path}`);