@homeflare/alchemy 0.6.0 → 0.8.0

package/src/openbao/host-approles.test.ts

@@ -80,9 +80,21 @@ describe('hostAppRoles', () => {
     }
   });
 
-  it('refuses unknown classes, duplicate hosts and names that would blur the separator', () => {
+  it('gives a host in two classes one role per class', () => {
+    const hosts = [
+      { class: 'pve-node', name: 'node-c' },
+      { class: 'operator-signer', name: 'node-c' },
+    ];
+    assert.deepEqual(
+      hostAppRoles({ ...INPUT, hosts }).map((role) => role.name),
+      ['operator-signer--node-c', 'pve-node--node-c'],
+    );
+  });
+
+  it('refuses unknown classes, a host twice in one class and names that blur the separator', () => {
     const bad = [
       { class: 'nope', name: 'node-c' },
+      { class: 'constructor', name: 'node-d' },
       { class: 'pve-node', name: 'node-a' },
       { class: 'pve-node', name: 'node-a' },
       { class: 'pve-node', name: 'node--x' },
@@ -93,7 +105,8 @@ describe('hostAppRoles', () => {
       (error: unknown) => {
         assert.ok(error instanceof Error);
         assert.match(error.message, /unknown class `nope`/);
-        assert.match(error.message, /`node-a` is listed twice/);
+        assert.match(error.message, /unknown class `constructor`/);
+        assert.match(error.message, /`node-a` is listed twice in class `pve-node`/);
         assert.match(error.message, /`node--x` is not lowercase/);
         assert.match(error.message, /`Node-Y` is not lowercase/);
         return true;

package/src/openbao/host-approles.ts

@@ -96,22 +96,37 @@ export const hostAppRoles = (input: HostAppRolesInput): readonly BaoAuthRoleProp
   const problems = Object.entries(input.classes).flatMap(([name, spec]) =>
     classProblems(name, spec),
   );
+  /**
+   * ⛔ DEDUPED ON THE ROLE NAME, NOT THE HOST NAME. A host may sit in several classes (one machine
+   *   that is both a signer and a node), and each class gives it its own role: `<class>--<host>`
+   *   differs, so nothing collides. Until 2026-09-21 this keyed on the host alone and refused that
+   *   estate outright. What it must still refuse is the same host twice in ONE class: two
+   *   declarations of one role name, so one AppRole that two resources would each claim.
+   */
   const seen = new Set<string>();
   const roles: BaoAuthRoleProps[] = [];
   for (const host of input.hosts) {
     if (!NAME.test(host.name)) {
       problems.push(`host \`${host.name}\` is not lowercase letters, digits, single hyphens`);
     }
-    if (seen.has(host.name)) problems.push(`host \`${host.name}\` is listed twice`);
-    seen.add(host.name);
-    const spec = input.classes[host.class];
+    const name = hostRoleName(host.class, host.name);
+    if (seen.has(name)) {
+      problems.push(`host \`${host.name}\` is listed twice in class \`${host.class}\``);
+    }
+    seen.add(name);
+    /**
+     * ⛔ OWN KEYS ONLY. `classes['constructor']` is Object's constructor, not undefined, so a host
+     *   naming it passed as a class with no policies and no secretIdTtl, never checked by
+     *   classProblems, and wrote a role whose secret_id never expires.
+     */
+    const spec = Object.hasOwn(input.classes, host.class) ? input.classes[host.class] : undefined;
     if (spec === undefined) {
       problems.push(`host \`${host.name}\` names unknown class \`${host.class}\``);
       continue;
     }
     roles.push({
       bindSecretId: true,
-      name: hostRoleName(host.class, host.name),
+      name,
       secretIdNumUses: spec.secretIdNumUses ?? 0,
       secretIdTtl: spec.secretIdTtl,
       tokenMaxTtl: spec.tokenMaxTtl,

package/src/openbao/jwt-config.ts

@@ -10,6 +10,11 @@
  *
  * ★ REPLACE SEMANTICS (REPLACE.md): `mount` changed → `replace`: the new mount gets the config;
  *   the old one keeps its own until that mount is disabled. There is no identity but the mount.
+ * ⛔ A MOVE ONTO A MOUNT WHOSE CONFIG EXISTS FAILS THE PLAN, like every other family's move onto an
+ *   occupied path (rename-identity.ts). With no delete, nothing is lost to a swap, which MEASURED
+ *   2026-09-21 ended with each config where it was declared. But the new generation writes over
+ *   the config it lands on, which changes who can log in on that mount: an issuer or key set
+ *   someone else manages, silently replaced. Move through a mount with no config instead.
  */
 import { Resource } from 'alchemy';
 import { isResolved } from 'alchemy/Diff';
@@ -22,11 +27,12 @@ import {
   attributesOf,
   configPath,
   matches,
-  mountOf,
   problems,
   wouldErase,
   writeBody,
 } from './jwt-config-form.ts';
+import { declaredOr } from './rename.ts';
+import { type Identity, guardRename, judgeRename } from './rename-identity.ts';
 import { type RoleSpec, planRole, readRoleAt, reconcileRole } from './role-reconcile.ts';
 
 export type { BaoJwtAuthConfigAttributes, BaoJwtAuthConfigProps } from './jwt-config-form.ts';
@@ -43,6 +49,16 @@ export const BaoJwtAuthConfig = Resource<BaoJwtAuthConfig>('Bao.JwtAuthConfig',
   defaultRemovalPolicy: 'retain',
 });
 
+/** The identity is the mount alone; a trailing `/` is the same mount (`configPath` trims it). */
+const IDENTITY: Identity<BaoJwtAuthConfigAttributes> = {
+  declared: (props) => {
+    const mount = declaredOr(props, 'mount', 'jwt');
+    return mount === undefined ? undefined : configPath({ mount });
+  },
+  family: 'Bao.JwtAuthConfig',
+  recorded: (output) => configPath(output),
+};
+
 export const jwtConfigSpec = (
   props: BaoJwtAuthConfigProps,
 ): RoleSpec<BaoJwtAuthConfigAttributes> => ({
@@ -67,14 +83,19 @@ export const BaoJwtAuthConfigProvider = () =>
           return found?.attributes;
         }),
 
-        diff: Effect.fn(function* ({ news, output }) {
-          if (output === undefined || !isResolved(news)) return undefined;
-          if (mountOf(news) !== output.mount) return { action: 'replace' } as const;
+        diff: Effect.fn(function* ({ news, olds, output }) {
+          // ⛔ The mount first, before isResolved; onto a mount with a config fails the plan.
+          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;
           return { action: yield* planRole(jwtConfigSpec(news)) } as const;
         }),
 
         /** ⛔ Refuses, before writing, a live config that carries an OIDC client (wouldErase). */
-        reconcile: Effect.fn(function* ({ news }) {
+        reconcile: Effect.fn(function* ({ news, output }) {
+          // ⛔ An `update` across a move the diff could not see — refused before any write.
+          yield* guardRename(IDENTITY, news, output);
           return yield* reconcileRole(jwtConfigSpec(news));
         }),
 

package/src/openbao/jwt-role.ts

@@ -14,7 +14,8 @@
  *
  * ★ REPLACE SEMANTICS (REPLACE.md): `mount` or `name` changed → `replace`, create-first. The new
  *   path cannot collide with the old, so no `deleteFirst`. Under the default `retain` the old role
- *   stays live, and still admits logins, until removed by hand.
+ *   stays live, and still admits logins, until removed by hand. ⛔ A move onto a role that already
+ *   exists fails the plan (rename-identity.ts).
  * ★ `defaultRemovalPolicy: 'retain'`, like every Bao.* family.
  */
 import { Resource } from 'alchemy';
@@ -28,11 +29,11 @@ import {
   type BaoJwtRoleProps,
   attributesOf,
   matches,
-  mountOf,
   problems,
   rolePath,
   writeBody,
 } from './jwt-role-form.ts';
+import { foldName, guardRename, judgeRename, roleIdentity } from './rename-identity.ts';
 import { type RoleSpec, planRole, readRoleAt, reconcileRole } from './role-reconcile.ts';
 
 export type {
@@ -54,6 +55,18 @@ export const BaoJwtRole = Resource<BaoJwtRole>('Bao.JwtRole', {
   defaultRemovalPolicy: 'retain',
 });
 
+/**
+ * The name folded, as the server keys it (`foldName`): `name` is a TypeLowerCaseString
+ * (builtin/credential/jwt/path_role.go:77), so the handler reads it lowercased before it ever builds
+ * `role/<name>` (:289). `App` → `app` is the same role, never a move; `problems` refuses the case.
+ */
+const IDENTITY = roleIdentity<BaoJwtRoleAttributes>(
+  'Bao.JwtRole',
+  (mount, name) => rolePath({ mount, name }),
+  'jwt',
+  foldName,
+);
+
 export const jwtRoleSpec = (props: BaoJwtRoleProps): RoleSpec<BaoJwtRoleAttributes> => ({
   attributesOf: (live) => attributesOf(props, live),
   body: writeBody(props),
@@ -80,15 +93,18 @@ export const BaoJwtRoleProvider = () =>
         }),
 
         /** ⛔ IT COMPARES THE LIVE ROLE, NOT THE STORED DIGEST — a hand-widened audience is drift. */
-        diff: Effect.fn(function* ({ news, output }) {
-          if (output === undefined || !isResolved(news)) return undefined;
-          if (mountOf(news) !== output.mount || news.name !== output.name) {
-            return { action: 'replace' } as const;
-          }
+        diff: Effect.fn(function* ({ news, olds, output }) {
+          // ⛔ The identity first, before isResolved; onto a role that exists fails the plan.
+          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;
           return { action: yield* planRole(jwtRoleSpec(news)) } as const;
         }),
 
-        reconcile: Effect.fn(function* ({ news }) {
+        reconcile: Effect.fn(function* ({ news, output }) {
+          // ⛔ An `update` across a move the diff could not see — refused before any write.
+          yield* guardRename(IDENTITY, news, output);
           return yield* reconcileRole(jwtRoleSpec(news));
         }),
 

package/src/openbao/kubernetes-role.ts

@@ -9,7 +9,8 @@
  *   and nothing else (path_role.go:239-256).
  *
  * ★ REPLACE SEMANTICS (REPLACE.md): `mount` or `name` changed → `replace`, create-first (the new
- *   path cannot collide). Under the default `retain` the old role stays live until removed by hand.
+ *   path cannot collide with the old). Under the default `retain` the old role stays live until
+ *   removed by hand. ⛔ A move onto a role that already exists fails the plan (rename-identity.ts).
  */
 import { Resource } from 'alchemy';
 import { isResolved } from 'alchemy/Diff';
@@ -22,11 +23,11 @@ import {
   type BaoKubernetesRoleProps,
   attributesOf,
   matches,
-  mountOf,
   problems,
   rolePath,
   writeBody,
 } from './kubernetes-role-form.ts';
+import { foldName, guardRename, judgeRename, roleIdentity } from './rename-identity.ts';
 import { type RoleSpec, planRole, readRoleAt, reconcileRole } from './role-reconcile.ts';
 
 export type {
@@ -47,6 +48,14 @@ export const BaoKubernetesRole = Resource<BaoKubernetesRole>('Bao.KubernetesRole
   defaultRemovalPolicy: 'retain',
 });
 
+/** The name folded, as the server stores it (`foldName`). */
+const IDENTITY = roleIdentity<BaoKubernetesRoleAttributes>(
+  'Bao.KubernetesRole',
+  (mount, name) => rolePath({ mount, name }),
+  'kubernetes',
+  foldName,
+);
+
 export const kubernetesRoleSpec = (
   props: BaoKubernetesRoleProps,
 ): RoleSpec<BaoKubernetesRoleAttributes> => ({
@@ -72,15 +81,18 @@ export const BaoKubernetesRoleProvider = () =>
         }),
 
         /** ⛔ IT COMPARES THE LIVE ROLE, NOT THE STORED DIGEST. */
-        diff: Effect.fn(function* ({ news, output }) {
-          if (output === undefined || !isResolved(news)) return undefined;
-          if (mountOf(news) !== output.mount || news.name !== output.name) {
-            return { action: 'replace' } as const;
-          }
+        diff: Effect.fn(function* ({ news, olds, output }) {
+          // ⛔ The identity first, before isResolved; onto a role that exists fails the plan.
+          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;
           return { action: yield* planRole(kubernetesRoleSpec(news)) } as const;
         }),
 
-        reconcile: Effect.fn(function* ({ news }) {
+        reconcile: Effect.fn(function* ({ news, output }) {
+          // ⛔ An `update` across a move the diff could not see — refused before any write.
+          yield* guardRename(IDENTITY, news, output);
           return yield* reconcileRole(kubernetesRoleSpec(news));
         }),
 

package/src/openbao/mfa-enforcement.ts

@@ -19,9 +19,12 @@
  *   default `retain` it never runs; with `destroy`, set `retain` to drop it from state and leave it
  *   live — which is what the server would do anyway.
  *
- * ★ REPLACE SEMANTICS (REPLACE.md): `name` changed → `replace`, create-first (names are per
- *   namespace; the new one cannot collide). Under `retain` BOTH enforcements then apply — fail
- *   closed. Under `destroy` the old one's delete is refused, so the deploy stops after creating.
+ * ★ REPLACE SEMANTICS (REPLACE.md): `name` changed → `replace`, create-first. Under `retain` BOTH
+ *   enforcements then apply — fail closed. Under `destroy` the old one's delete is refused, so the
+ *   deploy stops after creating. ⛔ A rename onto an enforcement that exists fails the plan
+ *   (rename-identity.ts): the upsert by name would otherwise rewrite, in place, what someone else's
+ *   enforcement demands. MEASURED 2026-09-21: a swap of two under `destroy` wrote each over the
+ *   other, then stopped on the two refused deletes.
  */
 import { Resource } from 'alchemy';
 import { isResolved } from 'alchemy/Diff';
@@ -38,7 +41,8 @@ import {
   problems,
   writeBody,
 } from './mfa-enforcement-form.ts';
-import { authAccessors, readEnforcement, writeEnforcement } from './mfa-wire.ts';
+import { authAccessors, enforcementPath, readEnforcement, writeEnforcement } from './mfa-wire.ts';
+import { guardRename, judgeRename, nameIdentity } from './rename-identity.ts';
 
 export type {
   BaoMfaLoginEnforcementAttributes,
@@ -59,6 +63,12 @@ export const BaoMfaLoginEnforcement = Resource<BaoMfaLoginEnforcement>('Bao.MfaL
 
 type Env = HttpClient.HttpClient;
 
+/** Exact: the identity store indexes enforcements by (namespace, name) as given. */
+const IDENTITY = nameIdentity<BaoMfaLoginEnforcementAttributes>(
+  'Bao.MfaLoginEnforcement',
+  enforcementPath,
+);
+
 const refuse = (name: string, message: string): Effect.Effect<never> =>
   Effect.die(new Error(`Bao.MfaLoginEnforcement ${name}: ${message}`));
 
@@ -119,13 +129,18 @@ export const BaoMfaLoginEnforcementProvider = () =>
         }),
 
         /** ⛔ IT COMPARES THE LIVE ENFORCEMENT — a target removed by hand is drift, not a noop. */
-        diff: Effect.fn(function* ({ news, output }) {
-          if (output === undefined || !isResolved(news)) return undefined;
-          if (news.name !== output.name) return { action: 'replace' } as const;
+        diff: Effect.fn(function* ({ news, olds, output }) {
+          // ⛔ The name first, before isResolved; onto an enforcement that exists fails the plan.
+          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;
           return { action: yield* planEnforcement(news) } 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);
           return yield* reconcileEnforcement(news);
         }),
 

package/src/openbao/mfa-totp.ts

@@ -31,6 +31,7 @@ import {
   writeBody,
 } from './mfa-totp-form.ts';
 import { deleteTotp, findTotp, writeTotp } from './mfa-wire.ts';
+import { declaredString } from './rename.ts';
 
 export type {
   BaoMfaTotpMethodAttributes,
@@ -50,8 +51,8 @@ export const BaoMfaTotpMethod = Resource<BaoMfaTotpMethod>('Bao.MfaTotpMethod',
   defaultRemovalPolicy: 'retain',
 });
 
-const refuse = (props: BaoMfaTotpMethodProps, message: string): Effect.Effect<never> =>
-  Effect.die(new Error(`Bao.MfaTotpMethod ${props.name}: ${message}`));
+const refuse = (name: string, message: string): Effect.Effect<never> =>
+  Effect.die(new Error(`Bao.MfaTotpMethod ${name}: ${message}`));
 
 export const readTotp = (
   props: BaoMfaTotpMethodProps,
@@ -75,13 +76,13 @@ export const reconcileTotp = (
 ): Effect.Effect<BaoMfaTotpMethodAttributes, BaoError, HttpClient.HttpClient> =>
   Effect.gen(function* () {
     const bad = problems(props);
-    if (bad.length > 0) return yield* refuse(props, bad.join('; '));
+    if (bad.length > 0) return yield* refuse(props.name, bad.join('; '));
     const live = yield* readTotp(props);
     if (live === undefined || !matches(live, props)) yield* writeTotp(writeBody(props));
     const after = yield* readTotp(props);
     if (after === undefined)
-      return yield* refuse(props, 'the write succeeded but no method has that name.');
-    if (!matches(after, props)) return yield* refuse(props, 'the method read back different.');
+      return yield* refuse(props.name, 'the write succeeded but no method has that name.');
+    if (!matches(after, props)) return yield* refuse(props.name, 'the method read back different.');
     return after;
   });
 
@@ -97,14 +98,26 @@ export const BaoMfaTotpMethodProvider = () =>
           return yield* readTotp(olds);
         }),
 
+        /**
+         * ⛔ THE NAME IS JUDGED BEFORE `isResolved(news)`. Until 2026-09-21 it came after, so a
+         *   rename landing with a pending `issuer` (or any other Output) planned `update`, and the
+         *   upsert by name wrote a SECOND method: the header's stranding, reached through a green
+         *   plan. MEASURED through the engine (rename-families.test.ts).
+         */
         diff: Effect.fn(function* ({ news, output }) {
+          const name = declaredString(news, 'name');
+          if (output !== undefined && name !== undefined) {
+            const rename = renameProblem(output.name, name);
+            if (rename !== undefined) return yield* refuse(name, rename);
+          }
           if (output === undefined || !isResolved(news)) return undefined;
-          const rename = renameProblem(output.name, news.name);
-          if (rename !== undefined) return yield* refuse(news, rename);
           return { action: yield* planTotp(news) } as const;
         }),
 
-        reconcile: Effect.fn(function* ({ news }) {
+        /** ⛔ A rename the diff could not see (the name was an Output), refused before any write. */
+        reconcile: Effect.fn(function* ({ news, output }) {
+          const rename = output === undefined ? undefined : renameProblem(output.name, news.name);
+          if (rename !== undefined) return yield* refuse(news.name, rename);
           return yield* reconcileTotp(news);
         }),
 

package/src/openbao/pki-role.ts

@@ -44,7 +44,6 @@ 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 { mountPath } from './mount-form.ts';
 import {
   type BaoPkiRoleAttributes,
   type BaoPkiRoleProps,
@@ -54,6 +53,7 @@ import {
   rolePath,
   writeBody,
 } from './pki-role-form.ts';
+import { guardRename, judgeRename, roleIdentity } from './rename-identity.ts';
 
 export type { BaoPkiRoleAttributes, BaoPkiRoleProps };
 
@@ -69,6 +69,13 @@ export const BaoPkiRole = Resource<BaoPkiRole>('Bao.PkiRole', {
   defaultRemovalPolicy: 'retain',
 });
 
+/** Exact: the engine stores `role/<name>` verbatim (builtin/logical/pki/path_roles.go:963). */
+const IDENTITY = roleIdentity<BaoPkiRoleAttributes>(
+  'Bao.PkiRole',
+  (mount, name) => rolePath({ mount, name }),
+  'pki',
+);
+
 const readRole = (props: BaoPkiRoleProps) =>
   Effect.gen(function* () {
     const live = yield* baoRead(rolePath(props));
@@ -100,18 +107,21 @@ export const BaoPkiRoleProvider = () =>
          *   fields is also what stops a field being added to props and quietly forgotten in
          *   the comparison.
          */
-        diff: Effect.fn(function* ({ news, output }) {
-          if (output === undefined || !isResolved(news)) return undefined;
+        diff: Effect.fn(function* ({ news, olds, output }) {
           /**
            * ⚠️ A ROLE IS IDENTIFIED BY MOUNT **AND** NAME. Moving a declaration to another
            *   engine is a different object under a different CA, never an in-place edit —
-           *   `replace`, so Alchemy creates the new one and retires the old.
+           *   `replace`, so Alchemy creates the new one and retires the old. Judged before
+           *   `isResolved(news)`, and ⛔ a move onto a role that exists fails the plan
+           *   (rename-identity.ts).
            * ⛔ A RENAME WAS NOT CAUGHT UNTIL 2026-09-21 (REPLACE.md): only the mount was compared,
            *   so a new `name` read nothing at the new path, planned `update`, wrote the new role,
            *   and left the old one issuing certificates under no state record at all.
            */
-          if (mountPath(news.mount ?? 'pki') !== output.mount || news.name !== output.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;
           /**
            * ⚠️ A DECLARATION reconcile WOULD REFUSE MUST NEVER PLAN AS noop. An empty
            *   allowedDomains, or a duration OpenBao cannot parse, can compare equal to a
@@ -127,8 +137,10 @@ export const BaoPkiRoleProvider = () =>
             : ({ action: 'update' } as const);
         }),
 
-        reconcile: Effect.fn(function* ({ news }) {
+        reconcile: Effect.fn(function* ({ news, output }) {
           const path = rolePath(news);
+          // ⛔ An `update` across a move the diff could not see — refused before any write.
+          yield* guardRename(IDENTITY, news, output);
           /**
            * ⛔ AN EMPTY allowedDomains IS A REFUSAL, NOT AN EMPTY ROLE. `allow_any_name` is
            *   false on every live role, so a role with no allowed domains can issue NOTHING —

package/src/openbao/plugin.ts

@@ -24,9 +24,18 @@ import { isResolved } from 'alchemy/Diff';
 import * as Provider from 'alchemy/Provider';
 import * as Effect from 'effect/Effect';
 import type * as HttpClient from 'effect/unstable/http/HttpClient';
-import { type BaoPluginAttributes, type BaoPluginProps, matches, resolve } from './plugin-form.ts';
+import {
+  type BaoPluginAttributes,
+  type BaoPluginProps,
+  type BaoPluginType,
+  matches,
+  resolve,
+  versionedPath,
+} from './plugin-form.ts';
 import { readEntry, reconcilePlugin } from './plugin-reconcile.ts';
 import { deregisterPlugin } from './plugin-wire.ts';
+import { declaredOr, declaredString } from './rename.ts';
+import { type Identity, guardRename, judgeRename } from './rename-identity.ts';
 
 export type { BaoPluginAttributes, BaoPluginProps, BaoPluginType } from './plugin-form.ts';
 
@@ -42,6 +51,24 @@ export const BaoPlugin = Resource<BaoPlugin>('Bao.Plugin', {
   defaultRemovalPolicy: 'retain',
 });
 
+/**
+ * ⛔ NAME, TYPE AND VERSION ARE THE CATALOG KEY, so the identity is the versioned path a read and a
+ *   delete address. Exact: the catalog stores `<type>/<name>/<version>` as given, and the version
+ *   is already canonical (`problems`). ⚠️ An unversioned name that is a builtin reads back as
+ *   present (plugin-wire.ts), so a move onto one fails the plan, as reconcile would refuse anyway.
+ */
+const IDENTITY: Identity<BaoPluginAttributes> = {
+  declared: (props) => {
+    const type = declaredString(props, 'type') as BaoPluginType | undefined;
+    const name = declaredString(props, 'name');
+    const version = declaredOr(props, 'version', '');
+    if (type === undefined || name === undefined || version === undefined) return undefined;
+    return versionedPath(type, name, version);
+  },
+  family: 'Bao.Plugin',
+  recorded: (output) => versionedPath(output.type, output.name, output.version),
+};
+
 export const BaoPluginProvider = () =>
   Provider.effect(
     BaoPlugin,
@@ -60,21 +87,18 @@ export const BaoPluginProvider = () =>
         }),
 
         /** ⛔ IT COMPARES THE LIVE ENTRY, NOT THE STORED DIGEST — a hand re-register is drift. */
-        diff: Effect.fn(function* ({ news, output }) {
-          if (output === undefined || !isResolved(news)) return undefined;
-          const form = resolve(news);
+        diff: Effect.fn(function* ({ news, olds, output }) {
           /**
-           * ⛔ NAME, TYPE AND VERSION ARE THE CATALOG KEY, so changing one is a different entry,
-           *   not an edit. Writing the new key would leave the old registration in place under a
-           *   state record that no longer names it.
+           * ⛔ A NEW NAME, TYPE OR VERSION IS A DIFFERENT ENTRY, not an edit: `replace`, judged
+           *   before `isResolved(news)`. Writing the new key in place would leave the old
+           *   registration under a state record that no longer names it. ⛔ A move onto an entry
+           *   that is already registered fails the plan (rename-identity.ts).
            */
-          if (
-            output.name !== form.name ||
-            output.type !== form.type ||
-            output.version !== form.version
-          ) {
-            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 form = resolve(news);
           const found = yield* readEntry(form);
           if (found === undefined) return { action: 'update' } as const;
           return matches(found.attributes, form)
@@ -83,7 +107,9 @@ export const BaoPluginProvider = () =>
         }),
 
         /** The refusals — declarative, builtin, self-reported version — live in plugin-reconcile.ts. */
-        reconcile: Effect.fn(function* ({ news }) {
+        reconcile: Effect.fn(function* ({ news, output }) {
+          // ⛔ An `update` across a move the diff could not see — refused before any write.
+          yield* guardRename(IDENTITY, news, output);
           return yield* reconcilePlugin(news);
         }),