@homeflare/alchemy 0.5.0 → 0.7.0

package/src/openbao/remount-wire.ts

@@ -0,0 +1,112 @@
+/**
+ * `sys/remount` — move a secrets engine or auth method to a new path WITH its data — and the status
+ * polling it needs, because the move finishes after the call returns.
+ *
+ * ★ READ FROM openbao v2.6.2, NOT RECALLED:
+ *   · api/sys_mounts.go:95-191 — the CLI's `bao secrets move` POSTs `{from, to}` to sys/remount,
+ *     takes `data.migration_id`, then GETs sys/remount/status/<id> once a second until
+ *     `migration_info.status` is `success` or `failure`. This is that loop, bounded.
+ *   · vault/logical_system.go:1257-1357 — the handler validates, records the migration and
+ *     answers AT ONCE; a goroutine does the move. So a 200 means "queued", never "moved".
+ *   · vault/mount.go:630-735 — the mount keeps its UUID, and storage lives under the UUID, so every
+ *     secret stays. ⛔ BUT EVERY LEASE UNDER THE SOURCE IS REVOKED (`RevokePrefix`, :684): a move of
+ *     a dynamic-secrets mount kills every credential it has issued. KV has no leases.
+ *   · vault/logical_system.go:67-69 — `remount` is a sudo path. The status path is not.
+ * ⚠️ THE STATUS TRACKER IS IN MEMORY (vault/mount.go:2303-2336, a sync.Map on the active node). A
+ *   restart or leader change mid-move loses it, and the status read then answers 404. That is not a
+ *   failure and not a success; `confirm` settles it from the mount tables, or the call fails.
+ * ⛔ POLICIES ARE NOT REWRITTEN. Every ACL path naming the old mount keeps naming it.
+ */
+import * as Effect from 'effect/Effect';
+import type * as HttpClient from 'effect/unstable/http/HttpClient';
+import { baoCall, baoRead } from './bao-http.ts';
+import type { BaoError } from './bao-status.ts';
+
+/** A move OpenBao reported failed, or one this could not confirm. Never carries a token. */
+export class RemountError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'RemountError';
+  }
+}
+
+export interface RemountOptions {
+  /** Milliseconds between status reads. Default 1000 — the CLI's own pace. */
+  readonly intervalMillis?: number;
+  /** Status reads before giving up. Default 120, so about two minutes. */
+  readonly attempts?: number;
+}
+
+const record = (value: unknown): Record<string, unknown> | undefined =>
+  typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+
+/** POST sys/remount and return the migration id. `from`/`to` are full paths (`auth/x` for auth). */
+export const startRemount = (
+  from: string,
+  to: string,
+): Effect.Effect<string, BaoError | RemountError, HttpClient.HttpClient> =>
+  Effect.flatMap(baoCall('write', 'POST', 'sys/remount', { from, to }), (body) => {
+    const id = record(body?.['data'])?.['migration_id'];
+    return typeof id === 'string' && id !== ''
+      ? Effect.succeed(id)
+      : Effect.fail(new RemountError(`sys/remount ${from} -> ${to} answered no migration_id.`));
+  });
+
+/** `in-progress`, `success`, `failure` — or undefined when the server no longer knows the id. */
+export const remountStatus = (
+  id: string,
+): Effect.Effect<string | undefined, BaoError, HttpClient.HttpClient> =>
+  Effect.map(baoRead(`sys/remount/status/${encodeURIComponent(id)}`), (data) => {
+    if (data === undefined) return undefined;
+    const status = record(data['migration_info'])?.['status'];
+    return typeof status === 'string' ? status : 'unknown';
+  });
+
+/**
+ * Move `from` to `to` and wait until OpenBao says it is done.
+ *
+ * @param confirm answers "does the mount table show the move finished?" — asked only when the
+ *   status tracker has forgotten the id. True is success; false fails.
+ */
+export const remountAndWait = (
+  from: string,
+  to: string,
+  confirm: Effect.Effect<boolean, BaoError, HttpClient.HttpClient>,
+  options: RemountOptions = {},
+): Effect.Effect<void, BaoError | RemountError, HttpClient.HttpClient> =>
+  Effect.gen(function* () {
+    const interval = options.intervalMillis ?? 1000;
+    const attempts = Math.max(1, options.attempts ?? 120);
+    const id = yield* startRemount(from, to);
+    const named = `sys/remount ${from} -> ${to} (migration ${id})`;
+    for (let attempt = 1; attempt <= attempts; attempt += 1) {
+      const status = yield* remountStatus(id);
+      if (status === 'success') return;
+      if (status === 'failure') {
+        return yield* Effect.fail(
+          new RemountError(
+            `${named} FAILED. The server log carries the reason, tagged with that migration_id. ` +
+              'Read sys/mounts (or sys/auth) before retrying: the source may be tainted.',
+          ),
+        );
+      }
+      if (status === undefined) {
+        if (yield* confirm) return;
+        return yield* Effect.fail(
+          new RemountError(
+            `${named}: the server no longer knows the migration (its tracker is in memory, lost ` +
+              'on a restart or leader change), and the mount table does not show the move done.',
+          ),
+        );
+      }
+      if (attempt < attempts) yield* Effect.sleep(interval);
+    }
+    return yield* Effect.fail(
+      new RemountError(
+        `${named} is still in progress after ${String(attempts)} status reads. Do not re-run ` +
+          `until sys/remount/status/${id} settles.`,
+      ),
+    );
+  });

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

@@ -0,0 +1,166 @@
+/**
+ * A move onto an object that already exists, through Alchemy's own plan and apply (fake-stack.ts).
+ * Before `judgeMove` read the target, the first test below was a GREEN deploy that deleted both
+ * policies: each new generation wrote over the other's, and each old generation's delete then
+ * removed what the other had just written (rename.ts has the measurement).
+ */
+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 * as Layer from 'effect/Layer';
+import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
+import { groupKey } from './cloudflare-group-scope.ts';
+import { CloudflarePermissionGroups } from './cloudflare-permission-groups.ts';
+import { BaoCloudflareRole, BaoCloudflareRoleProvider } from './cloudflare-role.ts';
+import { aclPolicies, cloudflareRoles, fakePolicyProviders, proxmoxRoles } from './fake-engines.ts';
+import { type StackBody, withFakeStack, writesOf } from './fake-stack.ts';
+import { BaoPolicy } from './policy.ts';
+import { BaoProxmoxRole, BaoProxmoxRoleProvider } from './proxmox-role.ts';
+
+const OCCUPIED = /would land on an object that already exists/;
+
+/** Two policies, `X` and `Y`, each with fragments named after its logical id, under destroy. */
+const pair = (x: string, y: string): StackBody =>
+  Effect.gen(function* () {
+    yield* BaoPolicy('X', { fragments: '/p/x', name: x }).pipe(RemovalPolicy.destroy());
+    yield* BaoPolicy('Y', { fragments: '/p/y', name: y }).pipe(RemovalPolicy.destroy());
+  });
+
+describe('Bao.Policy: a rename onto a policy that exists fails the plan', () => {
+  it('a swap under destroy writes nothing and deletes nothing', async () => {
+    const store = aclPolicies();
+    await withFakeStack(fakePolicyProviders, store, async (stack, bao) => {
+      await stack.deploy(pair('a', 'b'));
+      const before = new Map(store.live);
+      bao.seen.length = 0;
+      await assert.rejects(stack.deploy(pair('b', 'a')), OCCUPIED);
+      assert.deepEqual(writesOf(bao.seen), []);
+      assert.deepEqual(store.live, before);
+    });
+  });
+
+  it('a shift (a → b while b → c) is refused for the name still held', async () => {
+    const store = aclPolicies();
+    await withFakeStack(fakePolicyProviders, store, async (stack, bao) => {
+      await stack.deploy(pair('a', 'b'));
+      bao.seen.length = 0;
+      await assert.rejects(stack.deploy(pair('b', 'c')), /Bao\.Policy: a → b would land/);
+      assert.deepEqual(writesOf(bao.seen), []);
+    });
+  });
+
+  it('reverting a move whose new generation failed is refused while the old name is live', async () => {
+    const store = aclPolicies();
+    const one = (name: string, dir: string): StackBody =>
+      Effect.asVoid(BaoPolicy('X', { fragments: dir, name }).pipe(RemovalPolicy.destroy()));
+    await withFakeStack(fakePolicyProviders, store, async (stack, bao) => {
+      await stack.deploy(one('a', '/p/x'));
+      await assert.rejects(stack.deploy(one('b', '/p/empty')), /carry no path grant/);
+      bao.seen.length = 0;
+      await assert.rejects(stack.deploy(one('a', '/p/x')), /Bao\.Policy: b → a would land/);
+      assert.deepEqual(writesOf(bao.seen), []);
+      assert.ok(store.live.has('sys/policies/acl/a'));
+      // ★ Finishing the move instead replaces cleanly and deletes the old name.
+      assert.deepEqual(await stack.deploy(one('b', '/p/x')), { X: 'replace' });
+      assert.deepEqual([...store.live.keys()], ['sys/policies/acl/b']);
+    });
+  });
+});
+
+/** Every group resolves, to an id named after it. */
+const groups = Layer.succeed(CloudflarePermissionGroups, {
+  resolve: (_mount, refs) =>
+    Effect.succeed(new Map(refs.map((ref) => [groupKey(ref.name, ref.scope), `id-${ref.name}`]))),
+});
+const roleProviders = Layer.mergeAll(
+  BaoCloudflareRoleProvider().pipe(Layer.provide(groups)),
+  BaoProxmoxRoleProvider(),
+  FetchHttpClient.layer,
+);
+
+const cf = (id: string, name: string) =>
+  BaoCloudflareRole(id, {
+    description: 'Read DNS records on one zone. (zone: example.com)',
+    maxTtl: '1h',
+    mount: 'cloudflare-example',
+    name,
+    policies: [
+      {
+        effect: 'allow',
+        groupOrder: 'declared',
+        groups: ['DNS Read'],
+        resource: 'com.cloudflare.api.account.zone.z1',
+      },
+    ],
+    ttl: '5m',
+  }).pipe(RemovalPolicy.destroy());
+
+describe('the role families: a move onto a role that exists fails the plan', () => {
+  it('Bao.CloudflareRole: a swap under destroy writes nothing', async () => {
+    const store = cloudflareRoles();
+    const body = (x: string, y: string): StackBody =>
+      Effect.gen(function* () {
+        yield* cf('X', x);
+        yield* cf('Y', y);
+      });
+    await withFakeStack(roleProviders, store, async (stack, bao) => {
+      await stack.deploy(body('dns-read', 'dns-edit'));
+      bao.seen.length = 0;
+      await assert.rejects(stack.deploy(body('dns-edit', 'dns-read')), OCCUPIED);
+      assert.deepEqual(writesOf(bao.seen), []);
+      assert.equal(store.live.size, 2);
+    });
+  });
+
+  it('Bao.ProxmoxRole: a rename onto a role made by hand writes nothing', async () => {
+    const store = proxmoxRoles();
+    const role = (name: string): StackBody =>
+      Effect.asVoid(
+        BaoProxmoxRole('Role', {
+          maxTtl: '6h',
+          mintUser: 'reader@pve',
+          mount: 'proxmox-lab',
+          name,
+          ttl: '1h',
+        }),
+      );
+    await withFakeStack(roleProviders, store, async (stack, bao) => {
+      await stack.deploy(role('read'));
+      store.live.set('proxmox-lab/roles/audit', { max_ttl: 0, mint_user: 'auditor@pve', ttl: 0 });
+      bao.seen.length = 0;
+      await assert.rejects(stack.deploy(role('audit')), OCCUPIED);
+      assert.deepEqual(writesOf(bao.seen), []);
+      assert.equal(store.live.get('proxmox-lab/roles/audit')?.['mint_user'], 'auditor@pve');
+    });
+  });
+});
+
+describe('Bao.ProxmoxRole: a re-scoping rename whose allowance is still an Output', () => {
+  it('defers instead of refusing a value it cannot read yet, then checks it once resolved', async () => {
+    const store = proxmoxRoles();
+    const base = { maxTtl: '6h', mount: 'proxmox-lab', ttl: '1h' } as const;
+    const body = (ttl: string, name: string, mintUser: string): StackBody =>
+      Effect.gen(function* () {
+        const up = yield* BaoProxmoxRole('Upstream', {
+          ...base,
+          mintUser: 'up@pve',
+          name: 'up',
+          ttl,
+        });
+        const allowMintUserChange = Output.interpolate`reader-${up.ttl}@pve`;
+        yield* BaoProxmoxRole('Role', { ...base, allowMintUserChange, mintUser, name });
+      });
+    await withFakeStack(roleProviders, store, async (stack) => {
+      await stack.deploy(body('1h', 'read', 'reader@pve'));
+      // ★ Before the defer, this died at plan asking for the allowance it had been given.
+      await assert.rejects(stack.deploy(body('2h', 'reader', 'writer@pve')), /identity moved/);
+      await assert.rejects(
+        stack.deploy(body('2h', 'reader', 'writer@pve')),
+        /the rename re-scopes mint_user reader@pve/,
+      );
+      assert.ok(!store.live.has('proxmox-lab/roles/reader'));
+    });
+  });
+});

package/src/openbao/rename.ts

@@ -0,0 +1,162 @@
+/**
+ * Rename safety for the families whose identity is a name, or a mount and a name: Bao.Policy,
+ * Bao.CloudflareRole and Bao.ProxmoxRole. REPLACE.md has the audit and what each answer does.
+ *
+ * ⛔ THE BUG THIS CLOSES, REPRODUCED 2026-09-21 AGAINST alchemy@2.0.0-beta.79's OWN PLAN AND APPLY
+ *   (fake-stack.ts): a Bao.Policy deployed as `old`, then redeclared as `new` under
+ *   `RemovalPolicy.destroy()`, planned `update` and left BOTH policies live. diff read the NEW
+ *   path, found nothing, answered `update`, and reconcile wrote the new object. The old one stayed
+ *   live under no state record, so no later plan would mention it, and not even `destroy` could
+ *   remove it.
+ * ★ A CHANGED IDENTITY IS A DIFFERENT OBJECT, SO THE ANSWER IS `replace`. Create-first
+ *   (`deleteFirst` false): the new path never collides with the old, the new generation is written,
+ *   dependents are updated in the same graph, and only then is the old generation deleted. The
+ *   engine hands that delete the OLD generation's attributes (Apply.ts deleteOldGenerations and the
+ *   GC pass both pass `output: old.attr`), and every delete here reads `output`, never `news`.
+ *   ⛔ A new path that collides with ANOTHER live object is refused at plan instead (`judgeMove`).
+ * ⚠️ UNDER `retain` THE OLD OBJECT STAYS LIVE. Apply.ts:2164-2173 skips the old generation's delete
+ *   and logs "Retaining replaced resource (removal policy: retain)". The plan still says `replace`
+ *   and the apply says what it kept, so it is no longer silent, but the old object is unmanaged
+ *   from then on. Remove it by hand, or opt into `RemovalPolicy.destroy()`.
+ */
+import * as Effect from 'effect/Effect';
+import { baoRead } from './bao-http.ts';
+
+const exact = (identity: string): string => identity;
+
+/**
+ * A string prop of a diff's `news`, once that one prop is resolved; `undefined` while it is still an
+ * Output of a changing upstream (a function-typed proxy) or an Effect.
+ *
+ * ★ THE IDENTITY IS JUDGED BEFORE `isResolved(news)`. That guard returns `undefined` when ANY prop is
+ *   pending, and the engine then falls back to `update` (Plan.ts, `havePropsChanged`). A rename that
+ *   lands in the same deploy as a pending `fragments` or `policies` Output would slip through as
+ *   `update`, which is the orphan again. launchd/host-effect.ts reads its identity the same way.
+ */
+export const declaredString = (news: unknown, key: string): string | undefined => {
+  if (typeof news !== 'object' || news === null) return undefined;
+  const value: unknown = (news as Record<string, unknown>)[key];
+  return typeof value === 'string' ? value : undefined;
+};
+
+/** True while an optional prop is declared but is not yet a value: an Output of a changing upstream. */
+export const isPendingProp = (news: unknown, key: string): boolean => {
+  if (typeof news !== 'object' || news === null) return false;
+  const value: unknown = (news as Record<string, unknown>)[key];
+  return value !== undefined && typeof value !== 'string';
+};
+
+/** A role's API path from a diff's `news`, once both `mount` and `name` are resolved. */
+export const declaredRolePath = (
+  news: unknown,
+  rolePath: (mount: string, name: string) => string,
+): string | undefined => {
+  const mount = declaredString(news, 'mount');
+  const name = declaredString(news, 'name');
+  return mount === undefined || name === undefined ? undefined : rolePath(mount, name);
+};
+
+/**
+ * How OpenBao keys an ACL policy: trimmed and lowercased. openbao v2.6.2
+ * vault/policy/policy_store.go:698-700 (`sanitizeName`), applied by SetPolicy (:268), GetPolicy
+ * (:378) and DeletePolicy (:562).
+ *
+ * ⛔ SO `Admin` → `admin` IS THE SAME POLICY, NOT A RENAME. A `replace` there would write it, and then,
+ *   under `destroy`, delete the old generation, which is that same policy. Every grant it carries
+ *   would be revoked by a change of case.
+ */
+export const policyKey = (name: string): string => name.trim().toLowerCase();
+
+/**
+ * Whether the declared identity names a different object than the one in state: `true` → moved (the
+ * diff asks `judgeMove`, which also reads the target); `false` → the same object; `undefined` → not
+ * knowable yet, because the declared side is still an Output. `key` is how the SERVER keys the object (`policyKey`); the default is exact,
+ * which is right for a mount path (vault/routing/router.go folds no case) and for both plugins'
+ * roles (each stores `roles/<name>` verbatim).
+ *
+ * ⛔ NEVER `replace` ON AN UNKNOWN IDENTITY. The Output may resolve to the same path, and a replace
+ *   onto the same path deletes, under `destroy`, the object it has just written. The diff defers
+ *   instead. If the engine then plans `update` and the identity turns out to have changed,
+ *   `refuseMovedUpdate` stops reconcile before it writes anything.
+ */
+export const isMoved = (
+  stored: string,
+  declared: string | undefined,
+  key: (identity: string) => string = exact,
+): boolean | undefined => (declared === undefined ? undefined : key(stored) !== key(declared));
+
+/**
+ * The role path a resource last wrote, or last tried to: its attributes once a write finished, else
+ * the props of the create or replacement that did not (`output` is undefined for both).
+ */
+export const triedRolePath = (
+  output: { readonly mount: string; readonly name: string } | undefined,
+  olds: unknown,
+  rolePath: (mount: string, name: string) => string,
+): string | undefined =>
+  output === undefined ? declaredRolePath(olds, rolePath) : rolePath(output.mount, output.name);
+
+/**
+ * The diff's first question, asked before `isResolved(news)`: the move from the identity this
+ * resource last wrote or tried (`tried`) to the declared one, or undefined when both name the same
+ * object or either is still unknown. `pathOf` is the API path an identity is read at.
+ *
+ * ⛔ A MOVE ONTO AN OBJECT THAT ALREADY EXISTS FAILS THE PLAN. MEASURED 2026-09-21 through the engine
+ *   (rename-occupied.test.ts): two policies that swapped names under `RemovalPolicy.destroy()` each
+ *   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. A shift (a → b while b → c), and a move onto the
+ *   name of a resource leaving the stack, were measured ending the same way. So was reverting a
+ *   move whose new generation failed: the old generation still holds the name, and its delete runs
+ *   after the revert has rewritten it. That is why `tried` falls back to the props of an unfinished
+ *   write.
+ * ⚠️ THE DIFF CANNOT SEE THE REMOVAL POLICY, SO THIS REFUSES UNDER `retain` TOO, where a swap, or a
+ *   move back onto a retained old generation, would have been harmless. The cost is a move in two
+ *   deploys through a free name, or removing the target by hand. The alternative is a green deploy
+ *   that deletes what it has just written.
+ * ★ ONE PLAN-TIME READ, OF A PATH THE NEW GENERATION'S RECONCILE READS ANYWAY. A 404, a missing mount
+ *   included, is free; a refused read fails the plan, as any other diff read does.
+ */
+export const judgeMove = (
+  family: string,
+  tried: string | undefined,
+  declared: string | undefined,
+  pathOf: (identity: string) => string,
+  key: (identity: string) => string = exact,
+) =>
+  Effect.gen(function* () {
+    if (tried === undefined || declared === undefined || key(tried) === key(declared)) {
+      return undefined;
+    }
+    if ((yield* baoRead(pathOf(declared))) === undefined) return { from: tried, to: declared };
+    return yield* Effect.die(
+      new Error(
+        `${family}: ${tried} → ${declared} would land on an object that already exists at ` +
+          `${declared}. Under RemovalPolicy.destroy() a resource moving off that name (a swap, a ` +
+          'shift, or a reverted move that did not finish) deletes it after this one writes it. ' +
+          'Nothing was written. Move through a name nothing holds, in two deploys, or remove ' +
+          `${declared} by hand first.`,
+      ),
+    );
+  });
+
+/**
+ * Reconcile's guard: an `update` whose prior attributes name another object.
+ *
+ * ★ REACHED ONLY WHEN THE DIFF COULD NOT SEE THE NEW IDENTITY at plan time. A fresh create, and the
+ *   new generation of a `replace`, both reach reconcile with `output` undefined (Apply.ts passes
+ *   `output: attr`, which is empty for a new generation). An `update` reaches it with the previous
+ *   generation's attributes.
+ * ★ THE FAILED DEPLOY SETTLES ITSELF. Apply has already committed the row as `updating`, with the new
+ *   props and the OLD attributes. By the next plan the upstream Output has landed, so the diff sees
+ *   both names and answers `replace` (or refuses, if the new name is already taken: `judgeMove`).
+ *   The old object is then deleted, or retained, by the removal policy, with no hand repair.
+ */
+export const refuseMovedUpdate = (family: string, from: string, to: string) =>
+  Effect.die(
+    new Error(
+      `${family}: planned as an update, but its identity moved from ${from} to ${to}. Writing ` +
+        `${to} now would leave ${from} live with no state record. Nothing was written. Run the ` +
+        'deploy again: once the value resolves at plan time it plans as a replace.',
+    ),
+  );

package/src/openbao/role-reconcile.test.ts

@@ -0,0 +1,104 @@
+/**
+ * The shared role loop against a fake, through Bao.JwtAuthConfig — the family where `wouldErase`
+ * matters most: a live OIDC client must never be written over, because the write would erase a
+ * secret the read never shows.
+ */
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import { type Reply, type Seen, run, withFake } from './fake-bao.ts';
+import { jwtConfigSpec } from './jwt-config.ts';
+import { problems } from './jwt-config-form.ts';
+import { planRole, reconcileRole } from './role-reconcile.ts';
+
+const PROPS = {
+  boundIssuer: 'https://token.actions.example.com',
+  mount: 'jwt-github',
+  oidcDiscoveryUrl: 'https://token.actions.example.com',
+};
+
+const STORED = {
+  bound_issuer: 'https://token.actions.example.com',
+  default_role: '',
+  jwks_ca_pem: '',
+  jwks_url: '',
+  jwt_supported_algs: [],
+  jwt_validation_pubkeys: [],
+  namespace_in_state: true,
+  oidc_client_id: '',
+  oidc_discovery_ca_pem: '',
+  oidc_discovery_url: 'https://token.actions.example.com',
+  oidc_response_mode: '',
+  oidc_response_types: [],
+  override_allowed_server_names: null,
+  provider_config: {},
+  status: 'valid',
+};
+
+/** Reads answer from `reads` in order (the last repeats); writes answer 204. */
+const script = (...reads: Reply[]) => {
+  let count = 0;
+  return (seen: Seen): Reply => {
+    if (seen.method !== 'GET') return { status: 204 };
+    const reply = reads[Math.min(count, reads.length - 1)] ?? { status: 500 };
+    count += 1;
+    return reply;
+  };
+};
+const ABSENT: Reply = { json: { errors: [] }, status: 404 };
+const found = (data: Record<string, unknown>): Reply => ({ json: { data }, status: 200 });
+const writes = (seen: Seen[]) => seen.filter((each) => each.method !== 'GET');
+
+describe('role loop (Bao.JwtAuthConfig)', () => {
+  it('writes an absent config once, as PUT, and returns what it read back', async () => {
+    await withFake(script(ABSENT, found(STORED)), async (bao) => {
+      const attributes = await run({ BAO_ADDR: bao.address }, reconcileRole(jwtConfigSpec(PROPS)));
+      assert.equal(attributes.mount, 'jwt-github');
+      const [write] = writes(bao.seen);
+      assert.equal(write?.method, 'PUT');
+      assert.equal(write?.path, '/v1/auth/jwt-github/config');
+      assert.ok(!(write?.body ?? '').includes('oidc_client_secret'));
+    });
+  });
+
+  it('writes nothing and plans noop when live already matches', async () => {
+    await withFake(script(found(STORED)), async (bao) => {
+      assert.equal(await run({ BAO_ADDR: bao.address }, planRole(jwtConfigSpec(PROPS))), 'noop');
+      await run({ BAO_ADDR: bao.address }, reconcileRole(jwtConfigSpec(PROPS)));
+      assert.equal(writes(bao.seen).length, 0);
+    });
+  });
+
+  it('refuses to write over a live OIDC client, naming what would be erased', async () => {
+    const oidc = found({
+      ...STORED,
+      bound_issuer: 'https://old.example.com',
+      oidc_client_id: 'client-a',
+    });
+    await withFake(script(oidc), async (bao) => {
+      await assert.rejects(
+        run({ BAO_ADDR: bao.address }, reconcileRole(jwtConfigSpec(PROPS))),
+        /oidc_client_id \(and its unreadable secret\)/,
+      );
+      assert.equal(writes(bao.seen).length, 0);
+    });
+  });
+
+  it('refuses a write that reads back different', async () => {
+    const other = found({ ...STORED, bound_issuer: 'https://elsewhere.example.com' });
+    await withFake(script(ABSENT, other), async (bao) => {
+      await assert.rejects(
+        run({ BAO_ADDR: bao.address }, reconcileRole(jwtConfigSpec(PROPS))),
+        /read back different/,
+      );
+    });
+  });
+
+  it('plans update, never noop, for a declaration it would refuse', async () => {
+    const bad = { ...PROPS, jwksUrl: 'https://keys.example.com' };
+    assert.match(problems(bad).join(), /exactly one/);
+    await withFake(script(found(STORED)), async (bao) => {
+      assert.equal(await run({ BAO_ADDR: bao.address }, planRole(jwtConfigSpec(bad))), 'update');
+      assert.equal(bao.seen.length, 0);
+    });
+  });
+});

package/src/openbao/role-reconcile.ts

@@ -0,0 +1,84 @@
+/**
+ * The read / plan / reconcile loop the newer role families share (Bao.JwtRole, Bao.KubernetesRole,
+ * Bao.JwtAuthConfig): one path, one body, one comparison. Each family supplies its own form; this
+ * owns the order of operations, which is where the estate's providers have gone wrong before.
+ *
+ * ★ THE ORDER, AND WHY EACH STEP IS THERE:
+ *   1. Refuse a declaration the family knows is wrong, before any call (`problems`).
+ *   2. Read live. Write only when it differs — an identical write is still an audit line.
+ *   3. Before writing over a live object, refuse if the write would silently destroy something
+ *      this resource does not model (`wouldErase`, the ssh-role.ts pattern).
+ *   4. Re-read, and refuse unless live now MATCHES. A 2xx is not proof: the server can accept a
+ *      field and store something else (pki-role.ts has the history).
+ * ⛔ A DECLARATION reconcile WOULD REFUSE NEVER PLANS `noop` — `planRole` routes it to `update`,
+ *   so the refusal is seen at the next deploy instead of hiding behind a clean plan.
+ */
+import * as Effect from 'effect/Effect';
+import type * as HttpClient from 'effect/unstable/http/HttpClient';
+import { baoRead, baoWrite } from './bao-http.ts';
+import type { BaoError } from './bao-status.ts';
+
+export interface RoleSpec<A> {
+  /** `Bao.JwtRole` etc., for messages. */
+  readonly family: string;
+  /** The API path, e.g. `auth/jwt/role/humans`. */
+  readonly path: string;
+  readonly problems: readonly string[];
+  readonly attributesOf: (live: Record<string, unknown>) => A;
+  readonly matches: (attributes: A) => boolean;
+  readonly body: Readonly<Record<string, unknown>>;
+  /** Live fields a write would reset that the declaration does not model. */
+  readonly wouldErase?: (live: Record<string, unknown>) => readonly string[];
+}
+
+type Found<A> = { readonly attributes: A; readonly live: Record<string, unknown> };
+
+export const readRoleAt = <A>(
+  spec: RoleSpec<A>,
+): Effect.Effect<Found<A> | undefined, BaoError, HttpClient.HttpClient> =>
+  Effect.map(baoRead(spec.path), (live) =>
+    live === undefined ? undefined : { attributes: spec.attributesOf(live), live },
+  );
+
+/** `update` or `noop` — the part of a diff after the identity checks. */
+export const planRole = <A>(
+  spec: RoleSpec<A>,
+): Effect.Effect<'noop' | 'update', BaoError, HttpClient.HttpClient> =>
+  Effect.gen(function* () {
+    if (spec.problems.length > 0) return 'update';
+    const found = yield* readRoleAt(spec);
+    return found !== undefined && spec.matches(found.attributes) ? 'noop' : 'update';
+  });
+
+const refuse = (spec: { readonly family: string; readonly path: string }, message: string) =>
+  Effect.die(new Error(`${spec.family} ${spec.path}: ${message}`));
+
+export const reconcileRole = <A>(
+  spec: RoleSpec<A>,
+): Effect.Effect<A, BaoError, HttpClient.HttpClient> =>
+  Effect.gen(function* () {
+    if (spec.problems.length > 0) return yield* refuse(spec, spec.problems.join('; '));
+    const found = yield* readRoleAt(spec);
+    if (found === undefined || !spec.matches(found.attributes)) {
+      const lost = found === undefined ? [] : (spec.wouldErase?.(found.live) ?? []);
+      if (lost.length > 0) {
+        return yield* refuse(
+          spec,
+          `live carries ${lost.join(', ')}, which this resource does not declare and the write ` +
+            'would reset. Fold it into the declaration, or clear it by hand first.',
+        );
+      }
+      // ★ PUT, as `bao write` sends (api/logical.go); http/logical.go maps PUT and POST alike.
+      yield* baoWrite('PUT', spec.path, spec.body);
+    }
+    const after = yield* readRoleAt(spec);
+    if (after === undefined) return yield* refuse(spec, 'write reported success but it is absent.');
+    if (!spec.matches(after.attributes)) {
+      return yield* refuse(
+        spec,
+        'wrote cleanly but read back different — OpenBao stored something other than what was ' +
+          'declared. Read it by hand before retrying.',
+      );
+    }
+    return after.attributes;
+  });