@homeflare/alchemy 0.6.0 → 0.7.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,13 @@ import {
   readCloudflareRole,
   writeCloudflareRole,
 } from './cloudflare-role-wire.ts';
+import {
+  declaredRolePath,
+  isMoved,
+  judgeMove,
+  refuseMovedUpdate,
+  triedRolePath,
+} from './rename.ts';
 
 export type { BaoCloudflareRoleAttributes, BaoCloudflareRoleProps };
 
@@ -112,14 +119,24 @@ 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 tried = triedRolePath(output, olds, rolePath);
+          const declared = declaredRolePath(news, rolePath);
+          const move = yield* judgeMove('Bao.CloudflareRole', tried, declared, (path) => path);
+          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 +150,13 @@ 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.
+          const before = output === undefined ? path : rolePath(output.mount, output.name);
+          if (isMoved(before, path) === true) {
+            return yield* refuseMovedUpdate('Bao.CloudflareRole', before, path);
+          }
           const refusal = refusalOf(news);
           if (refusal !== undefined) {
             return yield* Effect.die(new Error(`Bao.CloudflareRole ${path}: ${refusal}.`));

package/src/openbao/fake-engines.ts

@@ -0,0 +1,119 @@
+/**
+ * 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".
+ *
+ * ⛔ 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';
+
+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> };
+
+const ABSENT: Reply = { json: { errors: [] }, status: 404 };
+
+const store = (
+  write: (path: string, body: Record<string, string>, before: Stored | undefined) => Stored,
+  key: (path: string) => string = (path) => path,
+): Store => {
+  const live = new Map<string, Stored>();
+  const answer = (seen: Seen): Reply => {
+    const path = key(seen.path.replace(/^\/v1\//, ''));
+    if (seen.method === 'PUT') {
+      const body = JSON.parse(seen.body) as Record<string, string>;
+      live.set(path, write(path, body, live.get(path)));
+      return { status: 204 };
+    }
+    // ★ A delete answers 204 whether or not the object existed, as all three do.
+    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 });
+};
+
+const lastSegment = (path: 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-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}`);

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 &&