@homeflare/alchemy 0.5.0 → 0.7.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,8 @@ 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 { declaredString, isMoved, judgeMove, policyKey, refuseMovedUpdate } from './rename.ts';
 
 /**
  * An OpenBao ACL policy, assembled from the HCL fragments that declare it.
@@ -91,6 +92,8 @@ 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',
@@ -141,11 +144,27 @@ 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 tried = output?.name ?? declaredString(olds, 'name');
+          const declared = declaredString(news, 'name');
+          const move = yield* judgeMove('Bao.Policy', tried, declared, policyPath, policyKey);
+          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 +172,12 @@ 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.
+          if (output !== undefined && isMoved(output.name, name, policyKey) === true) {
+            return yield* refuseMovedUpdate(`Bao.Policy ${name}`, output.name, name);
+          }
           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,25 @@ 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 {
+  declaredRolePath,
+  declaredString,
+  isMoved,
+  isPendingProp,
+  judgeMove,
+  refuseMovedUpdate,
+  triedRolePath,
+} from './rename.ts';
 
 export type { BaoProxmoxRoleAttributes, BaoProxmoxRoleProps };
 
@@ -64,21 +74,6 @@ 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);
-  });
-
 export const BaoProxmoxRoleProvider = () =>
   Provider.effect(
     BaoProxmoxRole,
@@ -103,8 +98,35 @@ 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 tried = triedRolePath(output, olds, rolePath);
+          const declared = declaredRolePath(news, rolePath);
+          const move = yield* judgeMove('Bao.ProxmoxRole', tried, declared, (path) => path);
+          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 +148,13 @@ 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.
+          const before = output === undefined ? path : rolePath(output.mount, output.name);
+          if (isMoved(before, path) === true) {
+            return yield* refuseMovedUpdate('Bao.ProxmoxRole', before, path);
+          }
           const live = yield* readRole(news);
           /**
            * ⛔ A mint_user CHANGE RE-SCOPES EVERY CREDENTIAL THE ROLE WILL EVER MINT, SILENTLY.
@@ -137,20 +165,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 +187,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 +220,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/remount-wire.test.ts

@@ -0,0 +1,87 @@
+/**
+ * sys/remount and its status loop against a fake. The shapes pinned here are the CLI's own
+ * (api/sys_mounts.go:95-191): POST `{from, to}`, then poll until `success` or `failure`.
+ */
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import * as Effect from 'effect/Effect';
+import { type Reply, type Seen, run, withFake } from './fake-bao.ts';
+import { RemountError, remountAndWait } from './remount-wire.ts';
+
+const STARTED = { json: { data: { migration_id: 'm-1' }, warnings: ['queued'] }, status: 200 };
+const status = (value: string): Reply => ({
+  json: {
+    data: {
+      migration_id: 'm-1',
+      migration_info: { source_mount: 'kv/', status: value, target_mount: 'kv-moved/' },
+    },
+  },
+  status: 200,
+});
+const FORGOTTEN: Reply = { json: { errors: [] }, status: 404 };
+
+/** Answer the start, then each status read from `statuses` in order (the last one repeats). */
+const script = (...statuses: Reply[]) => {
+  let polls = 0;
+  return (seen: Seen): Reply => {
+    if (seen.path === '/v1/sys/remount') return STARTED;
+    const reply = statuses[Math.min(polls, statuses.length - 1)] ?? FORGOTTEN;
+    polls += 1;
+    return reply;
+  };
+};
+
+const FAST = { attempts: 3, intervalMillis: 1 };
+const moved = (confirm = Effect.succeed(true)) => remountAndWait('kv', 'kv-moved', confirm, FAST);
+
+describe('remountAndWait', () => {
+  it('posts from/to and polls until success', async () => {
+    await withFake(script(status('in-progress'), status('success')), async (bao) => {
+      await run({ BAO_ADDR: bao.address }, moved());
+      assert.deepEqual(
+        bao.seen.map((seen) => [seen.method, seen.path, seen.body]),
+        [
+          ['POST', '/v1/sys/remount', JSON.stringify({ from: 'kv', to: 'kv-moved' })],
+          ['GET', '/v1/sys/remount/status/m-1', ''],
+          ['GET', '/v1/sys/remount/status/m-1', ''],
+        ],
+      );
+    });
+  });
+
+  it('fails a migration OpenBao reports failed, naming the id', async () => {
+    await withFake(script(status('failure')), async (bao) => {
+      await assert.rejects(run({ BAO_ADDR: bao.address }, moved()), (error: unknown) => {
+        assert.ok(error instanceof RemountError);
+        assert.match(error.message, /migration m-1\) FAILED/);
+        return true;
+      });
+    });
+  });
+
+  it('settles a forgotten migration from the mount tables, both ways', async () => {
+    await withFake(script(FORGOTTEN), async (bao) => {
+      await run({ BAO_ADDR: bao.address }, moved(Effect.succeed(true)));
+    });
+    await withFake(script(FORGOTTEN), async (bao) => {
+      await assert.rejects(
+        run({ BAO_ADDR: bao.address }, moved(Effect.succeed(false))),
+        /no longer knows the migration/,
+      );
+    });
+  });
+
+  it('gives up after the bounded number of status reads', async () => {
+    await withFake(script(status('in-progress')), async (bao) => {
+      await assert.rejects(run({ BAO_ADDR: bao.address }, moved()), /still in progress after 3/);
+      assert.equal(bao.seen.length, 4);
+    });
+  });
+
+  it('fails a start that names no migration id', async () => {
+    const answer = () => ({ json: { data: {} }, status: 200 });
+    await withFake(answer, async (bao) => {
+      await assert.rejects(run({ BAO_ADDR: bao.address }, moved()), /no migration_id/);
+    });
+  });
+});