@homeflare/alchemy 0.6.0 → 0.8.0

package/src/launchd/sudo-runner.ts

@@ -0,0 +1,235 @@
+/**
+ * sudoRunner(): the kit's one elevating HostRunner. The deploy runs as the operator, and only the
+ * calls that need root go through `sudo -n`, in the exact shapes sudo-allowlist.ts names:
+ *
+ * - `launchctl bootstrap | bootout | kickstart` in the system domain;
+ * - a file under a prefix the stack declared: staged in a private temp file as the operator, then
+ *   `sudo -n install -S -m <mode> [-o <uid>] [-g <gid>] <staged> <path>`; removed with
+ *   `sudo -n rm -f -- <path>`.
+ *
+ * Everything else (reads, lookups, the operator's own files and gui domain) goes to localRunner().
+ *
+ * ★ DECIDED 2026-09-21. A host stack deploys as the operator rather than as root, so a provider bug
+ *   or a wrong declaration can do no more than this list. It is an explicit opt-in,
+ *   `launchdProviders(sudoRunner({ prefixes }))`, and nothing ever falls back to it: localRunner()
+ *   stays the default and never elevates.
+ * ⛔ `sudo -n`, NEVER A PROMPT. A deploy that stops mid-apply to ask for a password is the failure
+ *   "no silent sudo" exists to prevent. With -n, sudo fails at once, and that failure becomes an
+ *   error saying what to do.
+ * ⛔ EVERY PRIVILEGED ARGV IS LOGGED BEFORE IT RUNS, and it is only ever an argv: a file's bytes
+ *   travel through the staged file, never through argv, so a log line cannot carry content.
+ * ★ `install -S`: install(1) on macOS 27.2 (read 2026-09-21) always writes a temp file in the
+ *   target directory and renames it, so the file is never torn, and -S adds the fsync that
+ *   localRunner's `handle.sync()` does.
+ * ⚠️ REASONED, NOT MEASURED: sudo's failure text. The kit never runs sudo. The strings below follow
+ *   sudoers(5) for sudo 1.9.17p2 on macOS 27.2 ("a password is required": -n was given but a
+ *   password was needed) and sudo(8) (sudo exits 1 when it fails itself).
+ */
+import { type LocalRunnerOptions, errnoCode, localRunner } from './local-runner.ts';
+import type { ExecResult, HostRunner } from './runner.ts';
+import {
+  INSTALL,
+  RM,
+  SUDO,
+  SudoRefusedError,
+  checkPrefixes,
+  octalMode,
+  prefixOf,
+  privilegedProblem,
+  routeExec,
+} from './sudo-allowlist.ts';
+import { assertPlainPath, assertReadableBack, operatorGroups } from './sudo-guard.ts';
+import { type Staged, stageFile } from './sudo-stage.ts';
+
+export { SudoRefusedError };
+
+export type SudoRunnerOptions = LocalRunnerOptions & {
+  /**
+   * The directories root may install into and remove from: `/Library/LaunchDaemons` for system
+   * jobs (bootstrap and bootout are refused without it), plus wherever the stack's root-owned
+   * HostFiles live. ⛔ Required: absolute, normalised, never `/`; and at every privileged call a
+   * real directory that root owns and only root may write (sudo-guard.ts). Outside every prefix a
+   * file is written as the deploying user, or refused when that needs root.
+   */
+  readonly prefixes: readonly string[];
+  /** Receives one line per privileged argv, before it runs. @default a line on stderr */
+  readonly log?: (line: string) => void;
+};
+
+/** What a sudo runner is built from. ★ Split out so the tests swap the host, never the logic. */
+export type SudoDeps = {
+  /** Runs everything, including `sudo` itself. localRunner() for the real one. */
+  readonly base: HostRunner;
+  readonly stage: (bytes: Uint8Array) => Promise<Staged>;
+  /** The deploying user's groups, for the read-back check; `undefined` when unknown. */
+  readonly groups: () => Promise<readonly number[] | undefined>;
+  readonly log: (line: string) => void;
+};
+
+/**
+ * ⚠️ ANCHORED TO sudo'S OWN MESSAGE FORMS (`sudo: …` lines, `Sorry, user …`), so a launchctl or
+ *   install error that happens to say "not allowed" is never reported as "the command did not run".
+ *   The refusals are the three a sudoers denial prints: the command not allowed, the user not in
+ *   sudoers, and the user not allowed on this host (`<user> is not allowed to run sudo on <host>.`).
+ *   REASONED from sudo 1.9's sudoers plugin, like the rest (header).
+ */
+const PASSWORD =
+  /^sudo: (?:a password is required|a terminal is required|sorry, you must have a tty)/m;
+const NOT_ALLOWED =
+  /^(?:Sorry, user \S+ (?:is not allowed to execute|may not run sudo)|\S+ is not (?:in the sudoers file|allowed to run sudo on ))/m;
+
+/** ★ An EACCES outside every prefix is almost always a directory the stack forgot to declare. */
+const undeclared =
+  (path: string, prefixes: readonly string[]) =>
+  (cause: unknown): never => {
+    const code = errnoCode(cause);
+    if (code !== 'EACCES' && code !== 'EPERM') throw cause;
+    throw new Error(
+      `sudoRunner ${path}: ${code} as the deploying user, and the path is under no declared prefix ` +
+        `(${prefixes.join(', ')}). If root owns its directory, declare that directory as a prefix.`,
+      { cause },
+    );
+  };
+
+export const makeSudoRunner = (prefixList: readonly string[], deps: SudoDeps): HostRunner => {
+  const prefixes = checkPrefixes(prefixList);
+  const { base } = deps;
+
+  /**
+   * ⛔ THE ONE PLACE `sudo` IS SPAWNED: allowlist, then any host check (`before`), then the log
+   *   line, then `sudo -n -- argv`.
+   */
+  const elevate = async (
+    argv: readonly string[],
+    { before, staged }: { before?: () => Promise<unknown>; staged?: string } = {},
+  ): Promise<ExecResult> => {
+    const shown = JSON.stringify(argv);
+    const problem = privilegedProblem(argv, {
+      prefixes,
+      ...(staged === undefined ? {} : { staged }),
+    });
+    if (problem !== undefined)
+      throw new SudoRefusedError(`sudoRunner refused ${shown}: ${problem}`);
+    await before?.();
+    deps.log(`homeflare/launchd sudo -n ${shown}`);
+    const result = await base.exec([SUDO, '-n', '--', ...argv]);
+    if (result.exitCode !== 1) return result;
+    if (PASSWORD.test(result.stderr)) {
+      throw new SudoRefusedError(
+        `sudo -n ${shown}: a password is required, and this runner never prompts. Run \`sudo -v\` ` +
+          'in the deploying terminal just before the deploy, or grant exactly these commands ' +
+          'NOPASSWD (docs/launchd-sudo.md). The command did not run.',
+      );
+    }
+    if (NOT_ALLOWED.test(result.stderr)) {
+      throw new SudoRefusedError(
+        `sudo -n ${shown}: sudoers does not let the deploying user run this. The command did not run.`,
+      );
+    }
+    return result;
+  };
+
+  /** A privileged file operation: anything but exit 0 is an error. ⚠️ stderr names paths only. */
+  const mustSucceed = async (argv: readonly string[], staged?: string): Promise<void> => {
+    const result = await elevate(argv, staged === undefined ? {} : { staged });
+    if (result.exitCode !== 0) {
+      const stderr = result.stderr.trim().slice(0, 300);
+      throw new Error(`sudo -n ${JSON.stringify(argv)} -> ${String(result.exitCode)}: ${stderr}`);
+    }
+  };
+
+  return {
+    effectiveUid: () => base.effectiveUid(),
+    exec: async (argv) => {
+      const route = routeExec(argv, base.effectiveUid());
+      if ('refuse' in route) throw new SudoRefusedError(`sudoRunner: ${route.refuse}`);
+      if (route.as === 'operator') return base.exec(argv);
+      // ⛔ bootstrap makes root read the plist: it must be a plain file exactly where argv says.
+      //   The allowlist has already put it under a prefix by the time `before` runs.
+      const plist = argv[1] === 'bootstrap' ? argv[3] : undefined;
+      const prefix = plist === undefined ? undefined : prefixOf(plist, prefixes);
+      return elevate(argv, {
+        before: async () => {
+          if (plist !== undefined && prefix !== undefined) {
+            await assertPlainPath(base, prefix, plist, 'file');
+          }
+        },
+      });
+    },
+    lookupGroup: (nameOrId) => base.lookupGroup(nameOrId),
+    lookupUser: (nameOrId) => base.lookupUser(nameOrId),
+    // ★ True, so the providers let a system-domain job through to this runner (canActAsRoot).
+    privileged: true,
+    readFile: (path) => base.readFile(path),
+    removeFile: async (path) => {
+      const prefix = prefixOf(path, prefixes);
+      if (prefix === undefined) return base.removeFile(path).catch(undeclared(path, prefixes));
+      /**
+       * ★ Nothing there is success without a privileged call, so an idempotent delete logs nothing.
+       * ⚠️ lstat the path FIRST: a directory on the way that is already gone means nothing is there
+       *   (HostRunner.removeFile is idempotent, and localRunner treats ENOENT/ENOTDIR so), where the
+       *   guard alone would refuse it as a missing directory.
+       */
+      if ((await base.stat(path)) === undefined) return;
+      await assertPlainPath(base, prefix, path, 'file');
+      await mustSucceed([RM, '-f', '--', path]);
+    },
+    sleep: (ms) => base.sleep(ms),
+    stat: (path) => base.stat(path),
+    writeFileAtomic: async (path, bytes, options) => {
+      const prefix = prefixOf(path, prefixes);
+      const operator = base.effectiveUid();
+      if (prefix === undefined) {
+        if (options.uid !== undefined && options.uid !== operator && operator !== 0) {
+          throw new SudoRefusedError(
+            `sudoRunner ${path}: owner ${String(options.uid)} needs root, and the path is under no ` +
+              `declared prefix (${prefixes.join(', ')}). Declare its directory, or deploy as root. ` +
+              'Nothing was written.',
+          );
+        }
+        return base.writeFileAtomic(path, bytes, options).catch(undeclared(path, prefixes));
+      }
+      const mode = octalMode(options.mode);
+      if (mode === undefined)
+        throw new SudoRefusedError(`sudoRunner ${path}: mode must be 0–0o7777`);
+      await assertPlainPath(base, prefix, path, 'file-or-absent');
+      await assertReadableBack(base, path, options, await deps.groups());
+      const staged = await deps.stage(bytes);
+      try {
+        await mustSucceed(
+          [
+            INSTALL,
+            '-S',
+            '-m',
+            mode,
+            ...(options.uid === undefined ? [] : ['-o', String(options.uid)]),
+            ...(options.gid === undefined ? [] : ['-g', String(options.gid)]),
+            staged.path,
+            path,
+          ],
+          staged.path,
+        );
+      } finally {
+        await staged.dispose();
+      }
+    },
+  };
+};
+
+/**
+ * The real sudo runner: localRunner() for everything, `/usr/bin/sudo -n` for the allowlist.
+ * Pass it explicitly: `launchdProviders(sudoRunner({ prefixes: ['/Library/LaunchDaemons'] }))`.
+ */
+export const sudoRunner = (options: SudoRunnerOptions): HostRunner => {
+  const base = localRunner(options);
+  return makeSudoRunner(options.prefixes, {
+    base,
+    groups: () => operatorGroups(base),
+    log:
+      options.log ??
+      ((line) => {
+        process.stderr.write(`${line}\n`);
+      }),
+    stage: stageFile,
+  });
+};

package/src/launchd/sudo-stage.ts

@@ -0,0 +1,28 @@
+/**
+ * Where sudo-runner.ts puts a file's bytes before `install` copies them into place as root.
+ *
+ * ★ WHY STAGE AT ALL. The deploying user cannot write inside a root-owned directory, and the bytes
+ *   must not travel through argv (they would reach the log and `ps`). So they are written, as the
+ *   deploying user, to a private file, and `install` copies that one file.
+ * ⛔ A 0700 DIRECTORY, A 0600 FILE, O_EXCL: between the write and the install, nobody but the
+ *   deploying user and root can read the bytes or swap the file.
+ */
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+/** A file staged for `install`, and how to remove it again. */
+export type Staged = { readonly path: string; readonly dispose: () => Promise<void> };
+
+export const stageFile = async (bytes: Uint8Array): Promise<Staged> => {
+  const dir = await mkdtemp(join(tmpdir(), 'hf-sudo-'));
+  const dispose = () => rm(dir, { force: true, recursive: true });
+  try {
+    const path = join(dir, 'staged');
+    await writeFile(path, bytes, { flag: 'wx', mode: 0o600 });
+    return { dispose, path };
+  } catch (cause) {
+    await dispose();
+    throw cause;
+  }
+};

package/src/openbao/README.md

@@ -14,6 +14,11 @@ plus `FetchHttpClient.layer`.
   secret, a CA key, a plugin `env` or an OIDC client secret.
 - Every family defaults to `retain` on destroy. For what a rename does, read
   [REPLACE.md](./REPLACE.md) before you change any resource's path or name.
+- ⛔ A rename or move onto a name or path that already exists fails the plan, before anything is
+  written (every family but the mounts, whose moves are below). Move through a free name, in two
+  deploys, or remove the target first.
+- ⚠️ A NEW logical id for a live name adopts it, and under `destroy` the old id's delete then
+  removes it. Change a logical id with Alchemy's `renamedFrom` (REPLACE.md).
 
 ## assertBaoIdentity: call it first
 
@@ -70,9 +75,10 @@ export const hostRoles = Effect.gen(function* () {
 - A role is named `<class>--<host>`. Class and host names may contain only lowercase letters,
   digits and single hyphens.
 - It refuses `secretIdTtl` 0 (a secret_id that never expires), empty policies, `root`, unknown
-  classes and duplicate hosts.
+  classes and a host listed twice in one class. A host in several classes gets one role per class.
 - ⚠️ Renaming a host or class makes a new role. Under `retain` the old one stays live and keeps
-  admitting its secret_ids (REPLACE.md).
+  admitting its secret_ids (REPLACE.md). Under `destroy` its secret_ids go, but tokens it already
+  issued run to their TTL: deleting a role revokes no token.
 
 ## BaoJwtRole / BaoKubernetesRole / BaoJwtAuthConfig
 

package/src/openbao/REPLACE.md

@@ -1,7 +1,13 @@
 # Replace semantics: the `Bao.*` providers
 
-Audited 2026-09-21, against `alchemy@2.0.0-beta.79` and OpenBao v2.6.2 source. Every kit
-provider must answer `replace` correctly (vault consolidation plan, "Replace freely").
+Audited 2026-09-21, against `alchemy@2.0.0-beta.79` and OpenBao v2.6.2 source, in two batches.
+Every kit provider must answer `replace` correctly (vault consolidation plan, "Replace freely").
+
+★ **Measured, not only read.** `fake-stack.ts` runs beta.79's own `Plan.make` and `apply` over an
+in-memory state store against the fake engines in `fake-engines.ts` and `fake-engines-roles.ts`.
+`policy-rename.test.ts`, `role-rename.test.ts`, `rename-occupied.test.ts`,
+`rename-families.test.ts`, `rename-identity.test.ts` and `rename-adoption.test.ts` deploy, rename,
+and deploy again, then check the plan and every call that reached the fake.
 
 ## What Alchemy does with each answer
 
@@ -9,6 +15,12 @@ provider must answer `replace` correctly (vault consolidation plan, "Replace fre
   (its path) is unchanged.
 - **`replace`**: create-first by default. The new generation is created, dependents are updated in
   the same graph, then the old generation is deleted (`Apply.ts`, delete-first comment near :1180).
+  ★ That delete gets the **old** generation's attributes (`output: old.attr`), so a provider that
+  deletes by `output` deletes the old path. Measured: `PUT` of the new path, then `DELETE` of the
+  old one.
+- **No answer** (`undefined`, which every diff returns while `news` holds a pending Output): the
+  engine plans `update` if any prop changed (`Plan.ts`, `havePropsChanged`). ⚠️ That is the bug
+  class below whenever the identity changed too.
 - **`deleteFirst: true`**: tears the old one down first. It is only for identities that cannot
   coexist, such as a unique physical name. No `Bao.*` provider uses it. A rename is a new API
   path, which never collides with the old one. ⚠️ A mount or auth method whose `type` changes
@@ -27,24 +39,117 @@ state record, so no later plan would mention it. For a mount this meant an **emp
 beside the retained one that held every secret. For an AppRole it meant the old role's secret_ids
 kept working for their whole TTL.
 
-## Touched in this batch
-
-| Resource                  | Identity change | Answer now                                                                                                                               | Other changes                                                                               |
-| ------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
-| `Bao.Mount`               | `path`          | ⛔ **fails the plan**, unless `remountFrom` names the old path. Then it is an in-place `update` that moves the mount with `sys/remount`. | `type` → `replace` that **fails at apply** (below). Description and TTLs → `update` (tune). |
-| `Bao.AuthMethod`          | `path`          | Same as `Bao.Mount` (`auth/` prefix). The accessor survives the move.                                                                    | `type` → `replace` that **fails at apply** (below)                                          |
-| `Bao.AuthRole`            | `name`          | `replace`. Before 2026-09-21 it was `update`, and the old role was orphaned.                                                             | `update`                                                                                    |
-| `Bao.PkiRole`             | `mount`, `name` | `replace`. Before, only a `mount` change was caught; a `name` change orphaned the old role.                                              | `update` (full-replace write)                                                               |
-| `Bao.JwtRole`             | `mount`, `name` | `replace`                                                                                                                                | `update` (merge write; every managed field is sent)                                         |
-| `Bao.KubernetesRole`      | `mount`, `name` | `replace`                                                                                                                                | `update`                                                                                    |
-| `Bao.JwtAuthConfig`       | `mount`         | `replace`. The old delete is a no-op because there is no delete endpoint.                                                                | `update` (full-replace write)                                                               |
-| `Bao.MfaTotpMethod`       | `name`          | ⛔ **fails the plan**: a new id would strand every enrolled secret                                                                       | `update` (the upsert keeps the id)                                                          |
-| `Bao.MfaLoginEnforcement` | `name`          | `replace`. Its delete is **refused** (openbao#4030)                                                                                      | `update`                                                                                    |
+🔴 Reproduced through the engine on 2026-09-21 for `Bao.Policy` under `RemovalPolicy.destroy()`:
+deploy `app-old`, redeclare it as `app-new`, deploy. The plan said `update`, and both policies
+stayed live. `destroy` could not help, because nothing recorded the old one.
+
+## Answers, by resource
+
+⛔ Every family below except `Bao.Mount` and `Bao.AuthMethod` judges its identity **before**
+`isResolved(news)`, and **fails the plan** on a move onto an object that already exists
+(`rename-identity.ts`, below). Names compare as the server keys them: exact, except where a row
+says folded.
+
+| Resource                  | Identity change           | Answer now                                                                                                                                                            | Other changes                                                                               |
+| ------------------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| `Bao.Mount`               | `path`                    | ⛔ **fails the plan**, unless `remountFrom` names the old path. Then it is an in-place `update` that moves the mount with `sys/remount`.                              | `type` → `replace` that **fails at apply** (below). Description and TTLs → `update` (tune). |
+| `Bao.AuthMethod`          | `path`                    | Same as `Bao.Mount` (`auth/` prefix). The accessor survives the move.                                                                                                 | `type` → `replace` that **fails at apply** (below)                                          |
+| `Bao.AuthRole`            | `name` (folded)           | `replace`. Before 2026-09-21 it was `update`, and the old role was orphaned. Its delete clears the secret_ids; issued tokens run to their TTL (below).                | `update`                                                                                    |
+| `Bao.PkiRole`             | `mount`, `name`           | `replace`. Before, only a `mount` change was caught; a `name` change orphaned the old role.                                                                           | `update` (full-replace write)                                                               |
+| `Bao.JwtRole`             | `mount`, `name` (folded)  | `replace`. The name is folded: the server reads it lowercased (TypeLowerCaseString).                                                                                  | `update` (merge write; every managed field is sent)                                         |
+| `Bao.KubernetesRole`      | `mount`, `name` (folded)  | `replace`. The name is folded, as the server stores it.                                                                                                               | `update`                                                                                    |
+| `Bao.JwtAuthConfig`       | `mount`                   | `replace`. The old delete is a no-op because there is no delete endpoint. A move onto a mount with a config fails the plan too: it would rewrite that mount's logins. | `update` (full-replace write)                                                               |
+| `Bao.MfaTotpMethod`       | `name`                    | ⛔ **fails the plan**: a new id would strand every enrolled secret. Reconcile refuses it too, when the name was an Output.                                            | `update` (the upsert keeps the id)                                                          |
+| `Bao.MfaLoginEnforcement` | `name`                    | `replace`. Its delete is **refused** (openbao#4030)                                                                                                                   | `update`                                                                                    |
+| `Bao.SshRole`             | `mount`, `name`           | `replace`                                                                                                                                                             | `update` (full-replace write)                                                               |
+| `Bao.Plugin`              | `type`, `name`, `version` | `replace`: a version bump is a new catalog entry, and `retain` keeps the old version registered.                                                                      | `update` (full-replace register)                                                            |
+| `Bao.Policy`              | `name`                    | `replace` (batch 3A). Compared as OpenBao keys it, trimmed and lowercased, so `Admin` → `admin` is the same policy: `noop`.                                           | `update` (fragments digest)                                                                 |
+| `Bao.CloudflareRole`      | `mount`, `name`           | `replace` (batch 3A). Exact; a trailing `/` on the mount is the same path.                                                                                            | `update`                                                                                    |
+| `Bao.ProxmoxRole`         | `mount`, `name`           | `replace` (batch 3A). ⛔ **Fails the plan** if the rename also changes `mintUser`, unless `allowMintUserChange` names the old one.                                    | `update`. A `mintUser` change at the same path is refused at apply, never replaced.         |
 
 `hostAppRoles` makes no resources, but its names are identities: renaming a host or a class
 renames the role. With the logical id taken from the role name, as the README does, the old id
 leaves the stack: that is an orphan delete, not a `replace`. With a stable logical id,
-`Bao.AuthRole` plans a `replace`. Under the default `retain`, both leave the old role live.
+`Bao.AuthRole` plans a `replace`. Under the default `retain`, both leave the old role live. A
+host may sit in several classes: it gets one role per class, and only the same host twice in one
+class is refused.
+
+## When the new identity is not known at plan
+
+- **Only another prop is pending** (say `fragments` is an Output of an upstream that is also
+  changing). Every family judges the identity props before `isResolved(news)`
+  (`rename-identity.ts`), so the rename still plans `replace`. Measured for all twelve. Before
+  2026-09-21 the nine batch-2 families planned `update` here and orphaned the old object.
+- **The identity itself is pending.** Then the diff defers: it never answers `replace` on an
+  unknown identity, because under `destroy` a replace onto the same path deletes what it just
+  wrote. The engine plans `update`, and reconcile, seeing the old attributes name another
+  object, **refuses before any write**. The row is left `updating`, with the new props and the
+  old attributes. The next deploy sees both names and plans `replace`. Measured for all twelve.
+  `Bao.MfaTotpMethod` refuses there with its rename refusal, and its next plan fails the same way.
+- `Bao.ProxmoxRole` defers the same way while `mintUser` or `allowMintUserChange` is pending on a
+  rename, because the re-scope guard cannot be checked. Measured for `allowMintUserChange`.
+
+## A move onto an object that already exists fails the plan
+
+⛔ Every family in the table reads the new path at plan (`judgeMove`, `rename.ts`) and refuses the
+move if anything is there. 🔴 Measured before the guard: two policies that swapped names under
+`RemovalPolicy.destroy()` both planned `replace`. Each new generation wrote over the other's live
+policy, and each old generation's delete then removed the name the other had just written. The
+deploy was green, and both policies were gone, every grant revoked. The same swap deleted both
+objects for `Bao.AuthRole`, `Bao.PkiRole`, `Bao.JwtRole`, `Bao.KubernetesRole`, `Bao.SshRole` and
+`Bao.Plugin`. `Bao.JwtAuthConfig` (no delete) and `Bao.MfaLoginEnforcement` (delete refused) lost
+nothing, but each new generation silently rewrote the other's live object. Measured the same way:
+
+- a shift (`a → b` while `b → c`) deleted `b`, and a move onto the name of a resource leaving the
+  stack deleted the name it moved onto;
+- reverting a move whose new generation failed. The old generation still holds the name, and its
+  delete runs after the revert rewrites it. So the diff compares against the props of an
+  unfinished create or replacement when there are no attributes yet. Declaring the new name again
+  finishes the move instead.
+
+⚠️ The diff cannot see the removal policy, so this refuses under `retain` too, where a swap would
+have been harmless. So would a move back onto a retained old generation. Move in two deploys
+through a name nothing holds, or remove the target by hand first. For `Bao.Plugin` that includes a
+version bump onto a version already registered by hand. A change of case the server folds (policy,
+AppRole, JWT and Kubernetes role names), or a trailing `/` on a mount, is the same object, so it is
+not a move and is never refused (`rename-identity.test.ts`).
+
+## What `retain` means for batch 3A and AppRole
+
+Under the default `retain` the old generation is kept, and the apply says so ("Replaced resource
+retained."). It is live and unmanaged from then on:
+
+- **`Bao.Policy`**: the old policy keeps every grant, for every token, role and group that still
+  names it. Under `destroy` they lose those grants at the delete. ⚠️ Only a role that takes the
+  policy's `name` Output follows the rename in the same graph. A role that names the policy as a
+  literal string (`tokenPolicies: ['deploy']`) keeps the old name, so change it in the same PR.
+- **`Bao.CloudflareRole`**: the old role still mints, for any token whose ACL reaches its
+  `creds/<name>`. Under `destroy` every consumer still minting from the old path fails. Tokens
+  already minted are leases and live to their own expiry either way.
+- **`Bao.ProxmoxRole`**: the same, and the old role keeps minting under its old `mint_user`. The
+  plugin's delete leaves outstanding leases revocable (its own
+  `TestDeletingARoleLeavesItsOutstandingLeasesRevocable`).
+- **`Bao.AuthRole`**: the old role keeps admitting its secret_ids. Under `destroy` the delete
+  removes every secret_id and the role_id, so no new login succeeds, but it revokes no token:
+  tokens already issued live to their TTL and only fail to renew (openbao v2.6.2 approle
+  `pathRoleDelete`, path_role.go:1858-1902; `pathLoginRenew`, path_login.go:414-438). Revoke by
+  accessor to contain one.
+
+★ A stack that puts `mount` and `name` in the logical id, as homeflare-openbao's
+`declareCloudflareRoles` does, never reaches the `replace`: the old id leaves the stack as an
+orphan delete, which `retain` also keeps live.
+
+## A new declaration of a live name: the swap the guard cannot see
+
+⚠️ A NEW logical id whose name already exists takes that object over and rewrites it: these
+families' `read` never answers `Unowned`, so Alchemy silently adopts it. Nothing moved, so
+`judgeMove` never runs. 🔴 Measured (`rename-adoption.test.ts`): under `destroy` the old owner's
+delete then runs after the adoption wrote, and removes the object the new id now claims, in a
+green deploy. It happened when a logical id changed with the name kept, to each of the nine
+batch-2 families whose delete runs (a TOTP method and its enrolments included), and when a new
+`Bao.AuthRole` took a name another one moved off in the same deploy. Change a logical id with
+Alchemy's `renamedFrom('<old id>')`, which migrates the state row and plans an `update`. Take a
+freed name in the deploy after the move.
 
 ## Why the moves fail instead of replacing
 
@@ -78,10 +183,9 @@ take every secret with it. (Corrected 2026-09-21: the first audit listed this as
 3. **Unique names need `deleteFirst`.** Only a mount's `type` change keeps its unique path, and
    it fails on purpose instead (above).
 
-## Audited, not touched in this batch (open)
+## Closed
 
-- ⚠️ `Bao.Policy`, `Bao.CloudflareRole` and `Bao.ProxmoxRole` still compare only the live object
-  at the declared `name` (and `mount`). A rename plans `update` and orphans the old object, which
-  is the same bug class as above. `Bao.ProxmoxRole` deliberately never answers `replace` for a
-  `mint_user` change (its own comment), and that choice is sound. The rename case is separate.
-- `Bao.SshRole` and `Bao.Plugin` already answer `replace` on an identity change.
+- ✅ **Nine families checked the identity after `isResolved(news)`** and never read the target
+  (closed 2026-09-21 by `rename-identity.ts`, measured in `rename-families.test.ts`).
+  `Bao.Mount` and `Bao.AuthMethod` never needed it: their reconcile re-plans the move from the
+  stated path.

package/src/openbao/auth-role-form.test.ts

@@ -5,17 +5,11 @@
  *   sdk v2.6.2 framework.FieldData.Validate on the approle role fields (path_role.go:166-167,
  *   TypeDurationSecond): `secret_id_ttl: "2160h"` validates and parses to 7776000 seconds. A role
  *   read hands back that integer, which attributesOf renders as `90d` — the same role.
- * And what the diff calls a rename (a `replace`): only a change the server would not fold away.
+ * (What the diff calls a rename is pinned in rename-families.test.ts, `foldName`.)
  */
 import assert from 'node:assert/strict';
 import { describe, it } from 'node:test';
-import {
-  type BaoAuthRoleProps,
-  attributesOf,
-  isRename,
-  matches,
-  writeBody,
-} from './auth-role-form.ts';
+import { type BaoAuthRoleProps, attributesOf, matches, writeBody } from './auth-role-form.ts';
 
 const PROPS: BaoAuthRoleProps = {
   bindSecretId: true,
@@ -47,11 +41,3 @@ describe('auth role secret_id TTL', () => {
     assert.equal(matches(attributesOf(PROPS, { ...live, secret_id_ttl: 0 }), PROPS), false);
   });
 });
-
-describe('auth role rename', () => {
-  it('is a rename only when the lower-cased names differ, as the server stores them', () => {
-    assert.equal(isRename('pve-node--node-a', 'pve-node--node-b'), true);
-    assert.equal(isRename('Host-Cert', 'host-cert'), false);
-    assert.equal(isRename('host-cert', 'host-cert'), false);
-  });
-});

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

@@ -89,17 +89,6 @@ export const writeBody = (props: BaoAuthRoleProps): Record<string, string> => {
   return body;
 };
 
-/**
- * Whether a changed `name` names a DIFFERENT role — the diff's `replace` question.
- *
- * ⚠️ CASE-INSENSITIVELY, BECAUSE THE SERVER IS. AppRole stores `role/<lowercased name>` (openbao
- *   v2.6.2 builtin/credential/approle/path_role.go:1485, and roleEntry reads the same key, :1537),
- *   so `Host` → `host` is the SAME role: a `replace` there would write it, then — under `destroy` —
- *   delete the old generation, which is that same role.
- */
-export const isRename = (from: string, to: string): boolean =>
-  from.toLowerCase() !== to.toLowerCase();
-
 const samePolicies = (want: readonly string[], have: readonly string[]) =>
   want.length === have.length && want.every((policy, index) => policy === have[index]);
 

package/src/openbao/auth-role.ts

@@ -5,8 +5,9 @@
  *   are credential issuance, not configuration, and are OUT OF SCOPE. This declares the
  *   role shape an approle login inherits — policy names and TTL strings only.
  *
- * ★ `defaultRemovalPolicy: 'retain'` — deleting a role revokes every token bound to it.
- *   Opt in with `.pipe(RemovalPolicy.destroy())`; see resource.ts in house/proxmox.
+ * ★ `defaultRemovalPolicy: 'retain'` — deleting a role locks out every host that logs in with it:
+ *   its secret_ids go with it (the ⚠️ on `delete` below). Opt in with
+ *   `.pipe(RemovalPolicy.destroy())`; see resource.ts in house/proxmox.
  */
 import { Resource } from 'alchemy';
 import { isResolved } from 'alchemy/Diff';
@@ -17,12 +18,12 @@ import {
   type BaoAuthRoleAttributes,
   type BaoAuthRoleProps,
   attributesOf,
-  isRename,
   matches,
   readPath,
   writeBody,
 } from './auth-role-form.ts';
 import { baoDelete, baoRead, baoWrite } from './bao-http.ts';
+import { foldName, guardRename, judgeRename, nameIdentity } from './rename-identity.ts';
 
 export type { BaoAuthRoleAttributes, BaoAuthRoleProps };
 
@@ -38,6 +39,14 @@ export const BaoAuthRole = Resource<BaoAuthRole>('Bao.AuthRole', {
   defaultRemovalPolicy: 'retain',
 });
 
+/**
+ * ⚠️ CASE-INSENSITIVELY, BECAUSE THE SERVER IS. AppRole stores `role/<lowercased name>` (openbao
+ *   v2.6.2 builtin/credential/approle/path_role.go:1485, and roleEntry reads the same key,
+ *   :1537), so `Host` → `host` is the SAME role: a `replace` there would write it, then — under
+ *   `destroy` — delete the old generation, which is that same role.
+ */
+const IDENTITY = nameIdentity<BaoAuthRoleAttributes>('Bao.AuthRole', readPath, foldName);
+
 const readRole = (props: BaoAuthRoleProps) =>
   Effect.gen(function* () {
     const live = yield* baoRead(readPath(props.name));
@@ -65,26 +74,31 @@ export const BaoAuthRoleProvider = () =>
          * ⛔ IT COMPARES THE LIVE ROLE, NOT THE STORED DIGEST. A role edited in the OpenBao
          *   UI is exactly the drift the check-* gates exist to catch.
          */
-        diff: Effect.fn(function* ({ news, output }) {
-          if (output === undefined || !isResolved(news)) return undefined;
+        diff: Effect.fn(function* ({ news, olds, output }) {
           /**
-           * ⛔ A RENAMED ROLE IS A NEW ROLE — NEW role_id, NEW secret_ids — SO IT IS A `replace`.
-           *   Until 2026-09-21 a new `name` read nothing, planned `update` and wrote the new role,
-           *   leaving the old one live under no state record: its secret_ids kept logging in for
-           *   their whole TTL, and no plan would ever mention it again (REPLACE.md).
+           * ⛔ A RENAMED ROLE IS A NEW ROLE — NEW role_id, NEW secret_ids — SO IT IS A `replace`,
+           *   judged before `isResolved(news)` (rename-identity.ts). Until 2026-09-21 a new `name`
+           *   read nothing, planned `update` and wrote the new role, leaving the old one live
+           *   under no state record: its secret_ids kept logging in for their whole TTL, and no
+           *   plan would ever mention it again (REPLACE.md). ⛔ A rename onto a role that exists
+           *   fails the plan.
            * ⚠️ UNDER THE DEFAULT `retain` THE OLD ROLE STILL STAYS LIVE — retain keeps the old
            *   generation of a replace (Apply.ts:2164-2173). For per-host roles (host-approles.ts),
            *   opt into `RemovalPolicy.destroy()` or destroy the old role's accessors by hand.
            */
-          // ⚠️ Case-insensitively, because the server is — the ⚠️ on isRename in auth-role-form.ts.
-          if (isRename(output.name, news.name)) return { action: 'replace' } as const;
+          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;
           const live = yield* readRole(news);
           if (live === undefined) return { action: 'update' } as const;
           if (matches(live, news)) return { action: 'noop' } as const;
           return { action: 'update' } as const;
         }),
 
-        reconcile: Effect.fn(function* ({ news }) {
+        reconcile: Effect.fn(function* ({ news, output }) {
+          // ⛔ An `update` across a rename the diff could not see — refused before any write.
+          yield* guardRename(IDENTITY, news, output);
           const live = yield* readRole(news);
           if (live === undefined || !matches(live, news)) {
             yield* baoWrite('PUT', readPath(news.name), writeBody(news));
@@ -101,8 +115,15 @@ export const BaoAuthRoleProvider = () =>
         }),
 
         /**
-         * ⛔ DELETING A ROLE REVOKES EVERY TOKEN BOUND TO IT. Idempotent as Alchemy requires
-         *   — already gone is success — but retain is the default for a reason.
+         * ⚠️ DELETING A ROLE DOES NOT REVOKE THE TOKENS IT ISSUED. openbao v2.6.2 pathRoleDelete
+         *   (builtin/credential/approle/path_role.go:1858-1902) deletes every secret_id
+         *   (flushRoleSecrets, validation.go:420-446), the role_id mapping and the role, so no new
+         *   login succeeds, and it revokes nothing. A token already issued lives to its TTL; only
+         *   its renewal fails, because pathLoginRenew (path_login.go:414-438) refuses once the role
+         *   is gone. So this is not a containment action: to contain a leaked token, revoke it or
+         *   its accessor. (Corrected 2026-09-21: this said the delete revoked every token.)
+         * Idempotent as Alchemy requires — already gone is success — but retain is the default,
+         *   because every host logging in with the role is locked out at the delete.
          */
         delete: Effect.fn(function* ({ output }) {
           yield* baoDelete(readPath(output.name));