@homeflare/alchemy 0.6.0 → 0.8.0

package/src/openbao/policy-rename.test.ts

@@ -0,0 +1,112 @@
+/**
+ * Renaming a Bao.Policy, through Alchemy's own plan and apply (fake-stack.ts) against a fake policy
+ * store keyed as OpenBao keys it (fake-engines.ts). Before 2026-09-21 the second deploy of every
+ * rename below planned `update` and left the old policy live, under `destroy` too.
+ */
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import * as Output from 'alchemy/Output';
+import * as RemovalPolicy from 'alchemy/RemovalPolicy';
+import * as Effect from 'effect/Effect';
+import type { Fake } from './fake-bao.ts';
+import { aclPolicies, fakePolicyProviders } from './fake-engines.ts';
+import { type FakeStack, type StackBody, withFakeStack, writesOf as writes } from './fake-stack.ts';
+import { BaoPolicy } from './policy.ts';
+
+/** A fake policy store and a stack over it; `live` lists the policy names the store holds. */
+const withStack = (body: (stack: FakeStack, bao: Fake, live: () => string[]) => Promise<void>) => {
+  const store = aclPolicies();
+  return withFakeStack(fakePolicyProviders, store, (stack, bao) =>
+    body(stack, bao, () =>
+      [...store.live.keys()].map((path) => path.replace('sys/policies/acl/', '')).sort(),
+    ),
+  );
+};
+
+type Removal = typeof RemovalPolicy.destroy;
+const policy = (name: string, removal: Removal = RemovalPolicy.retain): StackBody =>
+  Effect.asVoid(BaoPolicy('Policy', { fragments: '/policies/app', name }).pipe(removal()));
+
+describe('Bao.Policy rename, through the engine', () => {
+  it('plans replace, writes the new name first, then deletes the OLD name under destroy', async () => {
+    await withStack(async (stack, bao, live) => {
+      assert.deepEqual(await stack.deploy(policy('app-old', RemovalPolicy.destroy)), {
+        Policy: 'create',
+      });
+      bao.seen.length = 0;
+      assert.deepEqual(await stack.deploy(policy('app-new', RemovalPolicy.destroy)), {
+        Policy: 'replace',
+      });
+      assert.deepEqual(writes(bao.seen), [
+        'PUT /v1/sys/policies/acl/app-new',
+        'DELETE /v1/sys/policies/acl/app-old',
+      ]);
+      assert.deepEqual(live(), ['app-new']);
+    });
+  });
+
+  it('still plans replace under the default retain, and keeps the old policy live', async () => {
+    await withStack(async (stack, bao, live) => {
+      await stack.deploy(policy('app-old'));
+      assert.deepEqual(await stack.deploy(policy('app-new')), { Policy: 'replace' });
+      assert.ok(!writes(bao.seen).some((each) => each.startsWith('DELETE')));
+      assert.deepEqual(live(), ['app-new', 'app-old']);
+    });
+  });
+
+  it('treats a change of case as the same policy: noop, and nothing deleted', async () => {
+    await withStack(async (stack, bao, live) => {
+      await stack.deploy(policy('App', RemovalPolicy.destroy));
+      bao.seen.length = 0;
+      assert.deepEqual(await stack.deploy(policy('app', RemovalPolicy.destroy)), {
+        Policy: 'noop',
+      });
+      assert.deepEqual(writes(bao.seen), []);
+      assert.deepEqual(live(), ['app']);
+    });
+  });
+
+  it('plans replace while `fragments` is still an Output of a changing upstream', async () => {
+    const body = (dir: string, name: string): StackBody =>
+      Effect.gen(function* () {
+        const upstream = yield* BaoPolicy('Upstream', { fragments: dir, name: 'upstream' });
+        yield* BaoPolicy('Policy', {
+          fragments: Output.interpolate`/policies/${upstream.grants}`,
+          name,
+        }).pipe(RemovalPolicy.destroy());
+      });
+    await withStack(async (stack, _bao, live) => {
+      await stack.deploy(body('/policies/one', 'app-old'));
+      const planned = await stack.deploy(body('/policies/two', 'app-new'));
+      assert.deepEqual(planned, { Policy: 'replace', Upstream: 'update' });
+      assert.deepEqual(live(), ['app-new', 'upstream']);
+    });
+  });
+
+  it('refuses an update across a rename it could not see, then replaces on the next deploy', async () => {
+    // ★ The name is an Output of an upstream that is updating, so the diff cannot see it at plan.
+    const body = (dir: string): StackBody =>
+      Effect.gen(function* () {
+        const upstream = yield* BaoPolicy('Upstream', { fragments: dir, name: 'upstream' });
+        yield* BaoPolicy('Policy', {
+          fragments: '/policies/app',
+          name: Output.interpolate`app-${upstream.grants}`,
+        }).pipe(RemovalPolicy.destroy());
+      });
+    await withStack(async (stack, bao, live) => {
+      await stack.deploy(body('/policies/one'));
+      assert.deepEqual(live(), ['app-1', 'upstream']);
+      bao.seen.length = 0;
+      await assert.rejects(
+        stack.deploy(body('/policies/two')),
+        /identity moved from app-1 to app-2/,
+      );
+      assert.deepEqual(writes(bao.seen), ['PUT /v1/sys/policies/acl/upstream']);
+      assert.deepEqual(await stack.deploy(body('/policies/two')), {
+        Policy: 'replace',
+        Upstream: 'noop',
+      });
+      assert.deepEqual(live(), ['app-2', 'upstream']);
+    });
+  });
+});

package/src/openbao/policy-wire.test.ts

@@ -1,43 +1,24 @@
 /**
- * Bao.Policy's calls against a fake that behaves like OpenBao where it matters: it STRIPS the
- * policy's trailing newline on write (measured on the live server — see digest.ts), answers 404 for
- * a policy it does not have, and 204 for a delete whether or not the policy existed.
+ * Bao.Policy's calls against a fake that behaves like OpenBao where it matters (fake-engines.ts): it
+ * STRIPS the policy's trailing newline on write (measured on the live server — see digest.ts),
+ * answers 404 for a policy it does not have, and 204 for a delete whether or not it existed.
  */
 import assert from 'node:assert/strict';
 import { describe, it } from 'node:test';
 import { BaoError } from './bao-status.ts';
 import { sha256 } from './digest.ts';
-import { type Seen, run, runFailure, withFake } from './fake-bao.ts';
+import { run, runFailure, withFake } from './fake-bao.ts';
+import { aclPolicies } from './fake-engines.ts';
 import { deletePolicy, readPolicy, writePolicy } from './policy-wire.ts';
 
 const PREFIX = '/v1/sys/policies/acl/';
 
-const policyStore = () => {
-  const policies = new Map<string, string>();
-  return (seen: Seen) => {
-    const name = seen.path.slice(PREFIX.length);
-    if (seen.method === 'PUT') {
-      const { policy } = JSON.parse(seen.body) as { policy: string };
-      policies.set(name, policy.replace(/\n+$/, ''));
-      return { status: 204 };
-    }
-    if (seen.method === 'DELETE') {
-      policies.delete(name);
-      return { status: 204 };
-    }
-    const policy = policies.get(name);
-    return policy === undefined
-      ? { json: { errors: [] }, status: 404 }
-      : { json: { data: { name, policy } }, status: 200 };
-  };
-};
-
 /** Two fragments, each followed by a newline — exactly how policy.ts assembles them. */
 const ASSEMBLED = 'path "kv/data/a" {\n  capabilities = ["read"]\n}\n' + 'path "kv/data/b" {}\n';
 
 describe('policy wire', () => {
   it('reads a policy that was never written as absent', async () => {
-    await withFake(policyStore(), async (bao) => {
+    await withFake(aclPolicies(), async (bao) => {
       assert.equal(await run({ BAO_ADDR: bao.address }, readPolicy('zz-new-policy')), '');
     });
   });
@@ -45,7 +26,7 @@ describe('policy wire', () => {
   // ⛔ THE FOREVER-DIFF. Live text comes back one newline short; the digests must still agree, or
   //    every plan says `update` and reconcile rewrites a policy that already matches.
   it('round-trips through the stripped newline with equal digests', async () => {
-    await withFake(policyStore(), async (bao) => {
+    await withFake(aclPolicies(), async (bao) => {
       const env = { BAO_ADDR: bao.address };
       await run(env, writePolicy('homeflare-llm', ASSEMBLED));
       assert.equal(bao.seen[0]?.method, 'PUT');

package/src/openbao/policy.ts

@@ -7,7 +7,9 @@ import * as Path from 'effect/Path';
 import type * as HttpClient from 'effect/unstable/http/HttpClient';
 import { sha256 } from './digest.ts';
 import { isEmptyAssembly } from './policy-assembly.ts';
-import { deletePolicy, readPolicy, writePolicy } from './policy-wire.ts';
+import { deletePolicy, policyPath, readPolicy, writePolicy } from './policy-wire.ts';
+import { policyKey } from './rename.ts';
+import { guardRename, judgeRename, nameIdentity } from './rename-identity.ts';
 
 /**
  * An OpenBao ACL policy, assembled from the HCL fragments that declare it.
@@ -91,11 +93,16 @@ export interface BaoPolicy extends Resource<
  *   orphaned resource; a caller that means it opts in with `.pipe(RemovalPolicy.destroy())`. This
  *   is Terraform's `prevent_destroy`, not a stubbed operation — a delete that silently did nothing
  *   would lie to whoever read the plan.
+ * ⚠️ `retain` ALSO KEEPS THE OLD GENERATION OF A RENAME. A new `name` plans `replace`, and under
+ *   `retain` the old policy is left live and unmanaged (rename.ts, REPLACE.md).
  */
 export const BaoPolicy = Resource<BaoPolicy>('Bao.Policy', {
   defaultRemovalPolicy: 'retain',
 });
 
+/** A policy is its name, keyed as OpenBao keys it (`policyKey`). */
+const IDENTITY = nameIdentity<BaoPolicyAttributes>('Bao.Policy', policyPath, policyKey);
+
 /** `path "..."` grant count — the same number the apply script prints. */
 const grantsOf = (hcl: string) => (hcl.match(/^path /gm) ?? []).length;
 
@@ -141,11 +148,25 @@ export const BaoPolicyProvider = () =>
          *   OpenBao UI is exactly the drift the check-* gates exist to catch, and a
          *   provider that trusted its own state would report `noop` straight through it.
          */
-        diff: Effect.fn(function* ({ news, output }) {
+        diff: Effect.fn(function* ({ news, olds, output }) {
+          /**
+           * ⛔ A RENAMED POLICY IS A `replace`, DECIDED BEFORE ANY OTHER READ (rename.ts). Until
+           *   2026-09-21 this read the new name, found nothing and planned `update`: the new policy
+           *   was written and the old one kept every grant under no state record. Names compare as
+           *   OpenBao keys them (`policyKey`), so a change of case is the same policy, never a
+           *   replace. ⛔ A rename onto a policy that already exists fails the plan (`judgeMove`).
+           * ⚠️ UNDER THE DEFAULT `retain` THE OLD POLICY STAYS LIVE, GRANTS AND ALL, for every token,
+           *   role and group that still names it. Under `destroy` they lose those grants at the
+           *   delete, so a role outside this graph that names the old policy must move in the same
+           *   PR (REPLACE.md).
+           */
+          const move = yield* judgeRename(IDENTITY, olds, news, output);
+          if (output === undefined) return undefined;
+          if (move !== undefined) return { action: 'replace' } as const;
           // ⚠️ A prop can still be an unresolved Output or Config at plan time. Docker's
           //   own providers guard with isResolved and skip rather than guess; a diff that
           //   read a Config as a string would compare a placeholder to real HCL.
-          if (output === undefined || !isResolved(news)) return undefined;
+          if (!isResolved(news)) return undefined;
           const { joined } = yield* assemble(news.fragments);
           const live = yield* readPolicy(news.name);
           return live.length > 0 && sha256(live) === sha256(joined)
@@ -153,8 +174,10 @@ export const BaoPolicyProvider = () =>
             : ({ action: 'update' } as const);
         }),
 
-        reconcile: Effect.fn(function* ({ news }) {
+        reconcile: Effect.fn(function* ({ news, output }) {
           const name = news.name;
+          // ⛔ An `update` across a rename the diff could not see — refused before any write.
+          yield* guardRename(IDENTITY, news, output);
           const { joined, parts } = yield* assemble(news.fragments);
           /**
            * ⛔ AN EMPTY ASSEMBLY IS A REFUSAL, NOT AN EMPTY POLICY. `bao policy write` with

package/src/openbao/proxmox-role-form.ts

@@ -109,7 +109,7 @@ const ttlText = (seconds: number | undefined, fallback = '0') => {
 export const rolePath = (mount: string, name: string) => `${mountPath(mount)}/roles/${name}`;
 
 export const attributesOf = (
-  props: BaoProxmoxRoleProps,
+  props: Pick<BaoProxmoxRoleProps, 'mount' | 'name'>,
   live: Record<string, unknown>,
 ): BaoProxmoxRoleAttributes => {
   const attrs = {
@@ -129,13 +129,13 @@ export const attributesOf = (
  * The body for `PUT <mount>/roles/<name>` — all strings, the `k=v` pairs `bao write` sent — or
  * the prop names whose duration would not parse.
  *
- * ⛔ A WRITE TO roles/{name} REPLACES THE ROLE, IT DOES NOT MERGE. An omitted `ttl` is written
- *   as the field's zero value, so a resource that treated undeclared TTLs as "unmanaged" — the
- *   Bao.Mount shape — would silently reset a lease ceiling every time it rewrote the role for an
- *   unrelated reason. Both TTLs are therefore required props and EVERY write carries all three
- *   fields. REASONED from the Vault secrets-framework write semantics plus this plugin's schema
- *   marking only `mint_user` required; NOT measured, because this session was read-only and
- *   proving it would have meant writing to the live engine.
+ * ⛔ EVERY WRITE CARRIES ALL THREE FIELDS, and both TTLs are required props, so `matches` covers
+ *   the whole role and no field is left unmanaged behind a green plan.
+ * ⚠️ CORRECTED 2026-09-21 FROM THE PLUGIN SOURCE. This said a write REPLACES the role and resets an
+ *   omitted TTL to zero. The port in homeflare-openbao-plugins (secrets/proxmox/path_roles.go,
+ *   pathRolesWrite, commit 0e79154) MERGES: it loads the stored role and sets only the fields
+ *   present (`d.GetOk`). An omitted TTL would keep its old value, which is still a value this
+ *   resource would not be managing. The build running live was not re-checked against that source.
  *
  * ⚠️ Seconds go on the wire as integers, not as `1h`. The schema declares both TTLs
  *   `"format": "seconds"`, and an integer is accepted unambiguously by every path that reads
@@ -167,6 +167,25 @@ const sameTtl = (want: string, have: string) => {
   return wantSeconds !== undefined && wantSeconds === haveSeconds;
 };
 
+/**
+ * Why moving the role's mint user from `before` to the declared one must be refused, or undefined.
+ * The ⛔ on reconcile in proxmox-role.ts says why a re-scope needs `allowMintUserChange`.
+ *
+ * ★ ONE DEFINITION FOR BOTH PLACES THAT ASK. Reconcile asks it of the live role at the same path.
+ *   The diff asks it across a rename, where `before` is the role being replaced: a rename writes a
+ *   brand-new role, so reconcile alone would see nothing to re-scope, and a rename would become the
+ *   way around the guard.
+ */
+export const rescopeRefusal = (
+  before: string,
+  mintUser: string,
+  allowMintUserChange: string | undefined,
+): string | undefined =>
+  before === mintUser || allowMintUserChange === before
+    ? undefined
+    : `re-scopes mint_user ${before} → ${mintUser}. Every token this role mints inherits ` +
+      `the ACL of that PVE user. To re-scope deliberately, declare allowMintUserChange: '${before}'.`;
+
 /** True when the live role already matches the declaration on every field the plugin stores. */
 export const matches = (attributes: BaoProxmoxRoleAttributes, props: BaoProxmoxRoleProps) =>
   attributes.mintUser === props.mintUser &&

package/src/openbao/proxmox-role-wire.ts

@@ -0,0 +1,24 @@
+/**
+ * The read Bao.ProxmoxRole makes of `<mount>/roles/<name>`, split from proxmox-role.ts so the diff,
+ * reconcile and the rename's re-scope check share one definition of "the live role".
+ */
+import * as Effect from 'effect/Effect';
+import { baoRead } from './bao-http.ts';
+import { type BaoProxmoxRoleProps, attributesOf, rolePath } from './proxmox-role-form.ts';
+
+/**
+ * The live role, or undefined when OpenBao answers 404.
+ *
+ * ⚠️ A missing MOUNT and a missing ROLE both read as undefined here, because both answer 404:
+ *   an absent role is a read that found nothing, and a path under no mount is OpenBao's
+ *   unsupported-path error, which is also a 404 (sdk/logical/response_util.go). They are not the
+ *   same failure — one is a typo in `mount`, the other is a role that has yet to be created — so
+ *   reconcile lets OpenBao's own `errors` through on the write rather than inventing a message.
+ *   A bad mount says "no handler for route".
+ */
+export const readRole = (props: Pick<BaoProxmoxRoleProps, 'mount' | 'name'>) =>
+  Effect.gen(function* () {
+    const live = yield* baoRead(rolePath(props.mount, props.name));
+    if (live === undefined) return undefined;
+    return attributesOf(props, live);
+  });

package/src/openbao/proxmox-role.ts

@@ -40,15 +40,18 @@ import { isResolved } from 'alchemy/Diff';
 import * as Provider from 'alchemy/Provider';
 import * as Effect from 'effect/Effect';
 import type * as HttpClient from 'effect/unstable/http/HttpClient';
-import { baoDelete, baoRead, baoWrite } from './bao-http.ts';
+import { baoDelete, baoWrite } from './bao-http.ts';
 import {
   type BaoProxmoxRoleAttributes,
   type BaoProxmoxRoleProps,
-  attributesOf,
   matches,
+  rescopeRefusal,
   rolePath,
   writeBody,
 } from './proxmox-role-form.ts';
+import { readRole } from './proxmox-role-wire.ts';
+import { declaredString, isPendingProp } from './rename.ts';
+import { guardRename, judgeRename, roleIdentity } from './rename-identity.ts';
 
 export type { BaoProxmoxRoleAttributes, BaoProxmoxRoleProps };
 
@@ -64,20 +67,8 @@ export const BaoProxmoxRole = Resource<BaoProxmoxRole>('Bao.ProxmoxRole', {
   defaultRemovalPolicy: 'retain',
 });
 
-/**
- * ⚠️ A missing MOUNT and a missing ROLE both read as undefined here, because both answer 404:
- *   an absent role is a read that found nothing, and a path under no mount is OpenBao's
- *   unsupported-path error, which is also a 404 (sdk/logical/response_util.go). They are not the
- *   same failure — one is a typo in `mount`, the other is a role that has yet to be created — so
- *   reconcile lets OpenBao's own `errors` through on the write rather than inventing a message.
- *   A bad mount says "no handler for route".
- */
-const readRole = (props: BaoProxmoxRoleProps) =>
-  Effect.gen(function* () {
-    const live = yield* baoRead(rolePath(props.mount, props.name));
-    if (live === undefined) return undefined;
-    return attributesOf(props, live);
-  });
+/** Exact: the plugin stores `roles/<name>` verbatim. */
+const IDENTITY = roleIdentity<BaoProxmoxRoleAttributes>('Bao.ProxmoxRole', rolePath);
 
 export const BaoProxmoxRoleProvider = () =>
   Provider.effect(
@@ -103,8 +94,33 @@ export const BaoProxmoxRoleProvider = () =>
          *   says everything is fine — exactly the drift the hand-written check-* gates exist to
          *   catch, and exactly what a provider that trusted its own state would walk past.
          */
-        diff: Effect.fn(function* ({ news, output }) {
-          if (output === undefined || !isResolved(news)) return undefined;
+        diff: Effect.fn(function* ({ news, olds, output }) {
+          /**
+           * ⛔ A NEW `mount` OR `name` IS A `replace` (rename.ts). It is a DIFFERENT path, so none of
+           *   the reasons below apply. Until 2026-09-21 it planned `update` and left the old role
+           *   minting under no state record. Under the default `retain` the old role still mints;
+           *   under `destroy` its consumers fail at the delete (REPLACE.md). ⛔ A move onto a role
+           *   that already exists fails the plan (`judgeMove`).
+           * ⛔ THE RE-SCOPE GUARD TRAVELS WITH THE RENAME, checked here because the new generation's
+           *   reconcile finds no live role to compare. While `mintUser` or `allowMintUserChange` is
+           *   still an Output it cannot be checked, so the diff defers, and reconcile refuses the
+           *   resulting `update`.
+           */
+          const move = yield* judgeRename(IDENTITY, olds, news, output);
+          if (output === undefined) return undefined;
+          if (move !== undefined) {
+            const mintUser = declaredString(news, 'mintUser');
+            if (mintUser === undefined || isPendingProp(news, 'allowMintUserChange'))
+              return undefined;
+            const from = (yield* readRole(output))?.mintUser ?? output.mintUser;
+            const allow = declaredString(news, 'allowMintUserChange');
+            const refusal = rescopeRefusal(from, mintUser, allow);
+            if (refusal === undefined) return { action: 'replace' } as const;
+            return yield* Effect.die(
+              new Error(`Bao.ProxmoxRole ${move.from} → ${move.to}: the rename ${refusal}`),
+            );
+          }
+          if (!isResolved(news)) return undefined;
           const live = yield* readRole(news);
           if (live === undefined) return { action: 'update' } as const;
           if (matches(live, news)) return { action: 'noop' } as const;
@@ -126,7 +142,10 @@ export const BaoProxmoxRoleProvider = () =>
           return { 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 read or write.
+          yield* guardRename(IDENTITY, news, output);
           const live = yield* readRole(news);
           /**
            * ⛔ A mint_user CHANGE RE-SCOPES EVERY CREDENTIAL THE ROLE WILL EVER MINT, SILENTLY.
@@ -137,20 +156,15 @@ export const BaoProxmoxRoleProvider = () =>
            *   move unless the declaration NAMES THE VALUE IT IS REPLACING. Creating a role never
            *   trips this — there is nothing to re-scope — and the permission expires by itself
            *   once the change lands, because live then equals the declaration.
+           * ⚠️ A RENAME CREATES A NEW ROLE, SO IT NEVER REACHES THIS CHECK. The diff asks the same
+           *   question of the role being replaced (`rescopeRefusal`, proxmox-role-form.ts).
            */
-          if (
-            live !== undefined &&
-            live.mintUser !== news.mintUser &&
-            news.allowMintUserChange !== live.mintUser
-          ) {
-            return yield* Effect.die(
-              new Error(
-                `Bao.ProxmoxRole ${rolePath(news.mount, news.name)}: live mint_user ` +
-                  `${live.mintUser} != declared ${news.mintUser}. Every token this role mints ` +
-                  'inherits the ACL of that PVE user. To re-scope deliberately, declare ' +
-                  `allowMintUserChange: '${live.mintUser}'.`,
-              ),
-            );
+          const rescope =
+            live === undefined
+              ? undefined
+              : rescopeRefusal(live.mintUser, news.mintUser, news.allowMintUserChange);
+          if (rescope !== undefined) {
+            return yield* Effect.die(new Error(`Bao.ProxmoxRole ${path}: ${rescope}`));
           }
           if (live === undefined || !matches(live, news)) {
             const write = writeBody(news);
@@ -164,18 +178,18 @@ export const BaoProxmoxRoleProvider = () =>
             if (!write.ok) {
               return yield* Effect.die(
                 new Error(
-                  `Bao.ProxmoxRole ${rolePath(news.mount, news.name)}: unparseable duration ` +
+                  `Bao.ProxmoxRole ${path}: unparseable duration ` +
                     `${write.bad.join(', ')}. Use 30s / 5m / 1h / 1d, or 0.`,
                 ),
               );
             }
-            yield* baoWrite('PUT', rolePath(news.mount, news.name), write.body);
+            yield* baoWrite('PUT', path, write.body);
           }
           const after = yield* readRole(news);
           if (after === undefined) {
             return yield* Effect.die(
               new Error(
-                `Bao.ProxmoxRole ${rolePath(news.mount, news.name)}: write returned no error ` +
+                `Bao.ProxmoxRole ${path}: write returned no error ` +
                   'but the role is still absent.',
               ),
             );
@@ -197,7 +211,9 @@ export const BaoProxmoxRoleProvider = () =>
          *   So this is an availability change for every consumer of `creds/<name>` and NOT a
          *   containment action: to contain a leaked credential, revoke the lease (which deletes
          *   the PVE token) or delete the token in PVE. Deleting the role only hides the door it
-         *   came through. REASONED from Vault lease semantics; not exercised here.
+         *   came through. The plugin's own test pins this (homeflare-openbao-plugins,
+         *   TestDeletingARoleLeavesItsOutstandingLeasesRevocable): the delete is one storage
+         *   delete, and each lease stays revocable without the role.
          *
          * ⚠️ IDEMPOTENT AS ALCHEMY REQUIRES — already gone is success. It used to get that by
          *   going through `baoReadText`, which discarded the exit code entirely, so a REFUSED

package/src/openbao/rename-adoption.test.ts

@@ -0,0 +1,82 @@
+/**
+ * The swap the plan-time guard cannot see: a NEW declaration of a name that is live. 🔴 MEASURED
+ * 2026-09-21 through Alchemy's own plan and apply (fake-stack.ts). With no state row, the engine asks
+ * `read`, which finds the object and answers plain attributes, so Alchemy silently adopts it
+ * (alchemy@2.0.0-beta.79 Plan.ts, the adoption probe; AdoptPolicy.ts). Nothing moved, so
+ * `judgeMove` never runs. Under `RemovalPolicy.destroy()` the old owner's delete then runs in
+ * Apply's phase 2, after the adoption has written, and removes the object the new declaration now
+ * claims. The deploy is green.
+ *
+ * ★ These pin that, and the two ways round it REPLACE.md gives: `renamedFrom` for a logical id that
+ *   changes, and a second deploy for a name another resource is leaving. If one of the hazards stops
+ *   reproducing, the engine changed: re-read REPLACE.md before relaxing it.
+ *
+ * ⛔ TEST-ONLY. Every value is a placeholder, not the estate's.
+ */
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import { renamedFrom } from 'alchemy';
+import * as RemovalPolicy from 'alchemy/RemovalPolicy';
+import * as Effect from 'effect/Effect';
+import { FAMILIES, rowOf, withEstate } from './fake-families.ts';
+import { writesOf } from './fake-stack.ts';
+
+const { destroy } = RemovalPolicy;
+
+/** No delete endpoint (jwt-config.ts), and a delete the provider refuses (mfa-enforcement.ts). */
+const KEEPS = new Set(['Bao.JwtAuthConfig', 'Bao.MfaLoginEnforcement']);
+const REFUSES_DELETE = /Bao\.MfaLoginEnforcement/;
+
+describe('a logical id changed without renamedFrom, under destroy', () => {
+  for (const row of FAMILIES) {
+    it(`${row.family}: the orphan delete removes what the new id just adopted`, async () => {
+      await withEstate(async (stack, estate) => {
+        await stack.deploy(row.declare('X', 'a', '15m', destroy));
+        const again = stack.deploy(row.declare('Z', 'a', '15m', destroy));
+        if (row.family === 'Bao.MfaLoginEnforcement') await assert.rejects(again, REFUSES_DELETE);
+        else assert.deepEqual(await again, { X: 'delete', Z: 'adopted' });
+        assert.equal(row.has(estate, 'a'), KEEPS.has(row.family));
+      });
+    });
+  }
+});
+
+describe('the ways round it', () => {
+  const row = rowOf('Bao.AuthRole');
+
+  it('renamedFrom migrates the state row instead: an update that deletes nothing', async () => {
+    await withEstate(async (stack, estate, seen) => {
+      await stack.deploy(row.declare('X', 'a', '15m', destroy));
+      seen.length = 0;
+      const moved = row.declare('Z', 'a', '15m', destroy).pipe(renamedFrom('X'));
+      assert.deepEqual(await stack.deploy(moved), { Z: 'update' });
+      assert.deepEqual(writesOf(seen), []);
+      assert.ok(row.has(estate, 'a'));
+    });
+  });
+
+  it('a name another resource moves off is lost when taken in the same deploy', async () => {
+    await withEstate(async (stack, estate) => {
+      await stack.deploy(row.declare('X', 'a', '15m', destroy));
+      const both = Effect.gen(function* () {
+        yield* row.declare('X', 'b', '15m', destroy);
+        yield* row.declare('Z', 'a', '30m', destroy);
+      });
+      assert.deepEqual(await stack.deploy(both), { X: 'replace', Z: 'adopted' });
+      assert.ok(row.has(estate, 'b') && !row.has(estate, 'a'));
+    });
+  });
+
+  it('and survives when taken in the deploy after the move', async () => {
+    await withEstate(async (stack, estate) => {
+      await stack.deploy(row.declare('X', 'a', '15m', destroy));
+      await stack.deploy(row.declare('X', 'b', '15m', destroy));
+      const both = Effect.gen(function* () {
+        yield* row.declare('X', 'b', '15m', destroy);
+        yield* row.declare('Z', 'a', '30m', destroy);
+      });
+      assert.deepEqual(await stack.deploy(both), { X: 'noop', Z: 'create' });
+      assert.ok(row.has(estate, 'a') && row.has(estate, 'b'));
+    });
+  });
+});