@homeflare/alchemy 0.37.5 → 0.37.6

package/src/openbao/bao-http.ts

@@ -11,6 +11,7 @@
  * ⚠️ THE STACK MUST PROVIDE `FetchHttpClient.layer`. alchemy.run.ts does, the way
  *   <estate>/proxmox/alchemy.run.ts does.
  */
+import * as Cause from 'effect/Cause';
 import * as Context from 'effect/Context';
 import * as Effect from 'effect/Effect';
 import * as Option from 'effect/Option';
@@ -65,7 +66,7 @@ export const BaoGate = Context.Reference<Semaphore.Semaphore>('homeflare/openbao
  * ⚠️ THE CLI's DEFAULT CLIENT TIMEOUT (openbao v2.6.2 api/client.go:324). A hung agent or a server
  *   that accepts and never answers would otherwise hang the plan with no line saying why.
  */
-const TIMEOUT = '60 seconds';
+export const BAO_TIMEOUT = '60 seconds';
 
 /**
  * Mesh in front of a remote OpenBao drops connections under Alchemy's unbounded
@@ -73,11 +74,12 @@ const TIMEOUT = '60 seconds';
  * 2026-09-16 against bao.example.internal: a 585-role plan died mid-diff with
  * `no response: (no errors given)` while the vault stayed unsealed.
  */
-const retryTransport = <A, R>(effect: Effect.Effect<A, BaoError, R>) =>
+export const retryTransport = <A, E, R>(effect: Effect.Effect<A, E, R>) =>
   Effect.retry(effect, {
     schedule: Schedule.spaced('750 millis'),
     times: 2,
-    while: (error: BaoError) => error.status === 0,
+    while: (error) =>
+      (error instanceof BaoError && error.status === 0) || Cause.isTimeoutError(error),
   });
 
 /**
@@ -87,7 +89,7 @@ const retryTransport = <A, R>(effect: Effect.Effect<A, BaoError, R>) =>
  *   true). `X-Vault-Token` is not on that list, so under any tracer the token would be exported as
  *   a span attribute. It is added for every call made here.
  */
-const redactingToken = <A, E, R>(effect: Effect.Effect<A, E, R>) =>
+export const redactingToken = <A, E, R>(effect: Effect.Effect<A, E, R>) =>
   Effect.gen(function* () {
     const names = yield* Headers.CurrentRedactedNames;
     return yield* Effect.provideService(effect, Headers.CurrentRedactedNames, [
@@ -109,9 +111,9 @@ const redactingToken = <A, E, R>(effect: Effect.Effect<A, E, R>) =>
  *   the request to http://localhost:80 — a silent wrong server, which is the one outcome this
  *   package exists to prevent. It also assumes the provided `HttpClient` is the fetch one.
  */
-const overSocket =
+export const overSocket =
   (socket: string | undefined, method: string, path: string) =>
-  <A, R>(effect: Effect.Effect<A, BaoError, R>): Effect.Effect<A, BaoError, R> => {
+  <A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E | BaoError, R> => {
     if (socket === undefined) return effect;
     if (typeof Bun === 'undefined') {
       return Effect.fail(
@@ -148,7 +150,7 @@ export const baoCall = (
       Effect.flatMap((response) =>
         Effect.map(response.text, (text) => ({ status: response.status, text })),
       ),
-      Effect.timeout(TIMEOUT),
+      Effect.timeout(BAO_TIMEOUT),
       // ⛔ `.message` ONLY: the HttpClientError message is the reason, method and URL. The error
       //   object itself holds the request, whose headers hold the token.
       Effect.mapError((cause) => new BaoError(0, method, path, [cause.message])),

package/src/openbao/distilled-retry.test.ts

@@ -0,0 +1,164 @@
+import { expect, test } from 'bun:test';
+import { policiesReadAclPolicy } from '@distilled.cloud/openbao/policies';
+import * as Effect from 'effect/Effect';
+import * as HttpClient from 'effect/unstable/http/HttpClient';
+import { HttpClientError, TransportError } from 'effect/unstable/http/HttpClientError';
+import * as HttpClientResponse from 'effect/unstable/http/HttpClientResponse';
+import { readAuthRole, writeAuthRole } from './auth-role-wire.ts';
+import { BaoEnv } from './bao-http.ts';
+import { BaoError } from './bao-status.ts';
+import { runBaoRead } from './distilled.ts';
+import { deletePolicy, readPolicy, writePolicy } from './policy-wire.ts';
+
+const ROLE_PROPS = {
+  name: 'test',
+  tokenPolicies: ['default'],
+  tokenTtl: '15m',
+  tokenMaxTtl: '1h',
+  secretIdTtl: '2160h',
+};
+
+const TOKEN = 'fixture-retry-token';
+const POLICY = { policy: 'path "test" {}' };
+const ROLE = {
+  bind_secret_id: true,
+  secret_id_num_uses: 0,
+  secret_id_ttl: 0,
+  token_max_ttl: 3600,
+  token_policies: ['default'],
+  token_ttl: 900,
+};
+
+const runWith = <A, E>(
+  effect: Effect.Effect<A, E, HttpClient.HttpClient>,
+  client: HttpClient.HttpClient,
+) =>
+  Effect.runPromise(
+    effect.pipe(
+      Effect.provideService(BaoEnv, { BAO_ADDR: 'http://fake.invalid', BAO_TOKEN: TOKEN }),
+      Effect.provideService(HttpClient.HttpClient, client),
+    ),
+  );
+
+for (const [name, read, data] of [
+  ['Policy', Effect.asVoid(readPolicy('test')), POLICY],
+  ['AppRole', Effect.asVoid(readAuthRole('test')), ROLE],
+] as const) {
+  test(`${name} retries a dropped read and then returns the live object`, async () => {
+    let attempts = 0;
+    const client = HttpClient.make((request) => {
+      attempts++;
+      expect(request.method).toBe('GET');
+      return attempts === 1
+        ? Effect.fail(new HttpClientError({ reason: new TransportError({ request }) }))
+        : Effect.succeed(HttpClientResponse.fromWeb(request, Response.json({ data })));
+    });
+    await runWith(read, client);
+    expect(attempts).toBe(2);
+  });
+}
+
+test('read transport retries stop after three attempts without exposing the token', async () => {
+  let attempts = 0;
+  const client = HttpClient.make((request) => {
+    attempts++;
+    return Effect.fail(new HttpClientError({ reason: new TransportError({ request }) }));
+  });
+  const error = await runWith(Effect.flip(readPolicy('test')), client);
+  expect(attempts).toBe(3);
+  expect(error).toBeInstanceOf(BaoError);
+  expect(JSON.stringify(error)).not.toContain(TOKEN);
+});
+
+/**
+ * A FULL-REPLACE write sends the complete desired state on every attempt, so — unlike a
+ * create or a non-idempotent call — it is safe to replay after a transport-level failure.
+ * `runBaoWrite` restores the bounded retry `baoCall()` gave every call before the distilled
+ * SDK path landed with `Retry.none`.
+ */
+for (const [name, write] of [
+  ['Policy', writePolicy('test', 'path "test" {}')],
+  ['AppRole', writeAuthRole(ROLE_PROPS)],
+] as const) {
+  test(`${name} write retries a dropped transport attempt and then succeeds`, async () => {
+    let attempts = 0;
+    const client = HttpClient.make((request) => {
+      attempts++;
+      expect(request.method).toBe('POST');
+      return attempts === 1
+        ? Effect.fail(new HttpClientError({ reason: new TransportError({ request }) }))
+        : Effect.succeed(HttpClientResponse.fromWeb(request, new Response(null, { status: 204 })));
+    });
+    await runWith(write, client);
+    expect(attempts).toBe(2);
+  });
+
+  test(`${name} write transport retries stop after three attempts without exposing the token`, async () => {
+    let attempts = 0;
+    const client = HttpClient.make((request) => {
+      attempts++;
+      return Effect.fail(new HttpClientError({ reason: new TransportError({ request }) }));
+    });
+    const error = await runWith(Effect.flip(write), client);
+    expect(attempts).toBe(3);
+    expect(error).toBeInstanceOf(BaoError);
+    expect(JSON.stringify(error)).not.toContain(TOKEN);
+  });
+}
+
+test('a read timeout has a fresh bound on its next attempt', async () => {
+  let attempts = 0;
+  const client = HttpClient.make((request) => {
+    attempts++;
+    return attempts === 1
+      ? Effect.never
+      : Effect.succeed(HttpClientResponse.fromWeb(request, Response.json({ data: POLICY })));
+  });
+  await runWith(runBaoRead(policiesReadAclPolicy({ name: 'test' }), '20 millis'), client);
+  expect(attempts).toBe(2);
+});
+
+/**
+ * Delete stays single-attempt: it is idempotent (a policy or role already gone is success,
+ * per policy-wire.ts / auth-role-wire.ts), but it is not a full-replace write, and this suite
+ * scopes the restored retry to the writes that carry the complete desired state on the wire.
+ */
+test('an uncertain delete is never replayed', async () => {
+  let attempts = 0;
+  const client = HttpClient.make((request) => {
+    attempts++;
+    return Effect.fail(new HttpClientError({ reason: new TransportError({ request }) }));
+  });
+  const error = await runWith(Effect.flip(deletePolicy('test')), client);
+  expect(error).toBeInstanceOf(BaoError);
+  expect(attempts).toBe(1);
+});
+
+test('typed denied reads are returned immediately without transport retries', async () => {
+  let attempts = 0;
+  const client = HttpClient.make((request) => {
+    attempts++;
+    return Effect.succeed(
+      HttpClientResponse.fromWeb(
+        request,
+        Response.json({ errors: ['permission denied'] }, { status: 403 }),
+      ),
+    );
+  });
+  const error = await runWith(Effect.flip(readPolicy('test')), client);
+  expect(error).toMatchObject({ _tag: 'Forbidden' });
+  expect(attempts).toBe(1);
+});
+
+test('SDK normalization accepts an address that already carries the API prefix', async () => {
+  let observed = '';
+  const client = HttpClient.make((request) => {
+    observed = request.url;
+    return Effect.succeed(HttpClientResponse.fromWeb(request, Response.json({ data: POLICY })));
+  });
+  await runWith(
+    readPolicy('test').pipe(Effect.provideService(BaoEnv, { BAO_ADDR: 'http://fake.invalid/v1/' })),
+    client,
+  );
+  expect(observed).toBe('http://fake.invalid/v1/sys/policies/acl/test');
+});

package/src/openbao/distilled.test.ts

@@ -0,0 +1,146 @@
+import { expect, test } from 'bun:test';
+import { rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { policiesReadAclPolicy, policiesWriteAclPolicy } from '@distilled.cloud/openbao/policies';
+import * as Effect from 'effect/Effect';
+import * as Semaphore from 'effect/Semaphore';
+import * as Headers from 'effect/unstable/http/Headers';
+import * as HttpClient from 'effect/unstable/http/HttpClient';
+import * as HttpClientResponse from 'effect/unstable/http/HttpClientResponse';
+import { BaoEnv, BaoGate, MAX_IN_FLIGHT, baoRead } from './bao-http.ts';
+import { runBao } from './distilled.ts';
+import { fakeBao, run, runFailure, withFake } from './fake-bao.ts';
+import { BaoError } from './bao-status.ts';
+import { readPolicy } from './policy-wire.ts';
+
+const OK = { json: { data: { policy: 'path "test" {}' } }, status: 200 };
+
+test('SDK calls resolve BAO/VAULT values per call, retaining empty BAO precedence', async () => {
+  await withFake(
+    () => OK,
+    async (bao) => {
+      const env = {
+        VAULT_ADDR: bao.address,
+        VAULT_NAMESPACE: 'tenant',
+        VAULT_TOKEN: 'first',
+        BAO_TOKEN: '',
+      };
+      const read = readPolicy('test');
+      await run(env, read);
+      env.BAO_TOKEN = 'rotated';
+      await run(env, read);
+      expect(bao.seen[0]?.headers.has('x-vault-token')).toBe(false);
+      expect(bao.seen[1]?.headers.get('x-vault-token')).toBe('rotated');
+      expect(bao.seen[1]?.headers.get('x-vault-namespace')).toBe('tenant');
+      expect(bao.seen[1]?.headers.get('x-vault-request')).toBe('true');
+    },
+  );
+});
+
+test('SDK calls use the agent unix socket ahead of a direct address, without a token header', async () => {
+  const socket = join(tmpdir(), `distilled-bao-${process.pid}.sock`);
+  rmSync(socket, { force: true });
+  try {
+    await withFake(
+      () => OK,
+      async (bao) => {
+        await run(
+          { BAO_ADDR: 'http://wrong.invalid', BAO_AGENT_ADDR: bao.address },
+          readPolicy('test'),
+        );
+        expect(bao.seen[0]?.path).toBe('/v1/sys/policies/acl/test');
+        expect(bao.seen[0]?.headers.has('x-vault-token')).toBe(false);
+        expect(bao.seen[0]?.headers.has('x-vault-namespace')).toBe(false);
+      },
+      socket,
+    );
+  } finally {
+    rmSync(socket, { force: true });
+  }
+});
+
+test('legacy and SDK calls share the same eight in-flight permits', async () => {
+  let active = 0;
+  let peak = 0;
+  await withFake(
+    async () => {
+      active++;
+      peak = Math.max(peak, active);
+      await Bun.sleep(15);
+      active--;
+      return OK;
+    },
+    async (bao) => {
+      await run(
+        { BAO_ADDR: bao.address },
+        Effect.all(
+          Array.from({ length: 32 }, (_, i) =>
+            i % 2 === 0 ? Effect.asVoid(readPolicy(`p${i}`)) : Effect.asVoid(baoRead(`p${i}`)),
+          ),
+          { concurrency: 'unbounded' },
+        ),
+      );
+      expect(peak).toBe(MAX_IN_FLIGHT);
+      expect(bao.seen).toHaveLength(32);
+    },
+  );
+});
+
+test('a sent write is bounded, not retried, and releases its permit', async () => {
+  await withFake(
+    async ({ method }) => {
+      if (method === 'POST') {
+        await Bun.sleep(120);
+        return { status: 204 };
+      }
+      return OK;
+    },
+    async (bao) => {
+      const gate = Semaphore.makeUnsafe(1);
+      const write = runBao(
+        policiesWriteAclPolicy({ name: 'test', policy: 'path "test" {}' }),
+        '30 millis',
+      );
+      const error = await runFailure(
+        { BAO_ADDR: bao.address },
+        write.pipe(Effect.provideService(BaoGate, gate)),
+      );
+      expect(error).toMatchObject({ _tag: 'TimeoutError' });
+      await run(
+        { BAO_ADDR: bao.address },
+        readPolicy('test').pipe(Effect.provideService(BaoGate, gate)),
+      );
+      expect(bao.seen.filter(({ method }) => method === 'POST')).toHaveLength(1);
+    },
+  );
+});
+
+test('the SDK keeps x-vault-token in Effect trace redaction alongside default names', async () => {
+  let names: ReadonlyArray<RegExp | string> = [];
+  const client = HttpClient.make((request, _url, _signal, fiber) => {
+    names = fiber.getRef(Headers.CurrentRedactedNames);
+    return Effect.succeed(HttpClientResponse.fromWeb(request, Response.json(OK.json)));
+  });
+  await Effect.runPromise(
+    runBao(policiesReadAclPolicy({ name: 'test' })).pipe(
+      Effect.provideService(BaoEnv, {
+        BAO_ADDR: 'http://fake.invalid',
+        BAO_TOKEN: 'never-log-this',
+      }),
+      Effect.provideService(HttpClient.HttpClient, client),
+    ),
+  );
+  expect(names).toContain('x-vault-token');
+  expect(names).toContain('authorization');
+});
+
+test('transport failures cannot serialize the request token after the fiber context unwinds', async () => {
+  const gone = fakeBao(() => OK);
+  gone.stop();
+  const token = 'fixture-private-bao-token';
+  const error = await runFailure({ BAO_ADDR: gone.address, BAO_TOKEN: token }, readPolicy('test'));
+  expect(error).toBeInstanceOf(BaoError);
+  expect(JSON.stringify(error)).not.toContain(token);
+  expect(String(error)).not.toContain(token);
+});

package/src/openbao/distilled.ts

@@ -0,0 +1,88 @@
+/**
+ * The SDK shares Bao's existing call-time environment and process-wide concurrency gate.
+ * Merely supplying HttpClient does not apply that gate: legacy calls acquire it in baoCall.
+ * ⛔ `runBao` ITSELF NEVER RETRIES: an interrupted call may already have reached the vault, and
+ * replaying a non-idempotent operation (a delete whose 404-is-success path already ran, a login,
+ * a credential issuance) could repeat a side effect. `runBaoRead` and `runBaoWrite` opt specific,
+ * known-idempotent call shapes back into the bounded transport retry baoCall always had.
+ */
+import { Credentials, normalizeBaseUrl } from '@distilled.cloud/openbao/Credentials';
+import type { OpenBaoOpContext } from '@distilled.cloud/openbao/Protocol';
+import * as Retry from '@distilled.cloud/openbao/Retry';
+import type * as Cause from 'effect/Cause';
+import type * as Duration from 'effect/Duration';
+import * as Effect from 'effect/Effect';
+import * as Redacted from 'effect/Redacted';
+import * as Semaphore from 'effect/Semaphore';
+import type * as HttpClient from 'effect/unstable/http/HttpClient';
+import { isHttpClientError } from 'effect/unstable/http/HttpClientError';
+import { readBaoVariable, resolveAddress } from './bao-address.ts';
+import {
+  BAO_TIMEOUT,
+  BaoEnv,
+  BaoGate,
+  overSocket,
+  redactingToken,
+  retryTransport,
+} from './bao-http.ts';
+import { BaoError } from './bao-status.ts';
+
+export const runBao = <A, E>(
+  operation: Effect.Effect<A, E, OpenBaoOpContext>,
+  timeout: Duration.Input = BAO_TIMEOUT,
+): Effect.Effect<A, E | BaoError | Cause.TimeoutError, HttpClient.HttpClient> =>
+  Effect.gen(function* () {
+    const env = yield* BaoEnv;
+    const address = resolveAddress(env);
+    const token = readBaoVariable(env, 'BAO_TOKEN');
+    const gate = yield* BaoGate;
+    return yield* operation.pipe(
+      Effect.provideService(
+        Credentials,
+        Effect.succeed({
+          apiBaseUrl: normalizeBaseUrl(address.base),
+          ...(address.namespace === undefined ? {} : { namespace: address.namespace }),
+          ...(token === '' ? {} : { token: Redacted.make(token) }),
+        }),
+      ),
+      Retry.none,
+      // ⛔ HttpClientError holds the request, including X-Vault-Token. Trace redaction is
+      // fiber-local and gone when an error is serialized later; keep only its safe message,
+      // as baoCall does. SDK status/resource errors retain their original typed identity.
+      Effect.mapError((cause) =>
+        isHttpClientError(cause) ? new BaoError(0, 'SDK', 'operation', [cause.message]) : cause,
+      ),
+      // ★ A queued call has not reached the server: acquire the shared permit outside the timeout.
+      Effect.timeout(timeout),
+      overSocket(address.socket, 'SDK', 'operation'),
+      redactingToken,
+      Semaphore.withPermits(gate, 1),
+    );
+  });
+
+/**
+ * Reads use the existing two transport retries (750 ms between attempts). Each attempt
+ * reacquires the shared permit and its own bounded timeout. Typed SDK status and decoding
+ * failures still propagate immediately; a read is always safe to replay because it never
+ * changes vault state.
+ */
+export const runBaoRead = <A, E>(
+  operation: Effect.Effect<A, E, OpenBaoOpContext>,
+  timeout: Duration.Input = BAO_TIMEOUT,
+): Effect.Effect<A, E | BaoError | Cause.TimeoutError, HttpClient.HttpClient> =>
+  retryTransport(runBao(operation, timeout));
+
+/**
+ * The pre-PR `baoCall()` retried every call, writes included; that bound was lost when the
+ * distilled SDK path landed with `Retry.none` on `runBao`. Restore it for the writes where
+ * replaying is safe: a FULL-REPLACE, idempotent write (an OpenBao policy PUT, an AppRole
+ * write) sends the complete desired state every time, so retrying an uncertain transport
+ * failure converges on the same result rather than compounding a partial change. A create
+ * that mints a new identifier, or any operation whose second attempt could do something the
+ * first did not, must keep calling `runBao` directly and make one attempt.
+ */
+export const runBaoWrite = <A, E>(
+  operation: Effect.Effect<A, E, OpenBaoOpContext>,
+  timeout: Duration.Input = BAO_TIMEOUT,
+): Effect.Effect<A, E | BaoError | Cause.TimeoutError, HttpClient.HttpClient> =>
+  retryTransport(runBao(operation, timeout));

package/src/openbao/fake-engines-roles.ts

@@ -48,10 +48,17 @@ const typed = (body: Stored): Stored => {
   return out;
 };
 
-/** Every role engine, JWT auth config and MFA login enforcement. A write replaces the object. */
+/**
+ * Every role engine, JWT auth config and MFA login enforcement.
+ * ★ AppRole preserves omitted knobs and supplies defaults on create (OpenBao 2.6.2
+ * path_role.go:1688-1721); this fixture must not turn a correct omitted SDK field into drift.
+ */
 export const wireRoles = (): Store =>
   store<Stored>(
-    (_path, body) => typed(body),
+    (path, body, before) =>
+      path.startsWith('auth/approle/role/')
+        ? { bind_secret_id: true, secret_id_num_uses: 0, ...before, ...typed(body) }
+        : typed(body),
     (path) => keyOf(path),
   );
 

package/src/openbao/policy-distilled.test.ts

@@ -0,0 +1,98 @@
+import { expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { runFailure, withFake } from './fake-bao.ts';
+import { aclPolicies, fakePolicyProviders } from './fake-engines.ts';
+import { withFakeStack, writesOf } from './fake-stack.ts';
+import { BaoPolicy } from './policy.ts';
+import { judgePolicyRename } from './policy-identity.ts';
+import { deletePolicy, readPolicy, writePolicy } from './policy-wire.ts';
+
+for (const [status, tag] of [
+  [401, 'Unauthorized'],
+  [403, 'Forbidden'],
+  [503, 'ServiceUnavailable'],
+] as const) {
+  test(`SDK policy ${status} failures propagate on every verb without retry`, async () => {
+    await withFake(
+      () => ({ status, json: { errors: ['refused'] } }),
+      async (bao) => {
+        const env = { BAO_ADDR: bao.address };
+        for (const op of [
+          Effect.asVoid(readPolicy('test')),
+          writePolicy('test', 'path "test" {}'),
+          deletePolicy('test'),
+        ]) {
+          expect(await runFailure(env, op)).toMatchObject({ _tag: tag });
+        }
+        expect(bao.seen.map(({ method }) => method)).toEqual(['GET', 'POST', 'DELETE']);
+      },
+    );
+  });
+}
+
+test('SDK policy refuses null, non-string, and missing policy text on a successful read', async () => {
+  for (const data of [null, {}, { policy: 42 }]) {
+    await withFake(
+      () => ({ status: 200, json: { data } }),
+      async (bao) => {
+        const error = await runFailure({ BAO_ADDR: bao.address }, readPolicy('test'));
+        expect(String(error)).toContain('no data.policy');
+      },
+    );
+  }
+});
+
+test('rename checks preserve an occupied empty policy and propagate denied SDK reads', async () => {
+  await withFake(
+    () => ({ status: 200, json: { data: { policy: '' } } }),
+    async (bao) => {
+      await expect(
+        runFailure(
+          { BAO_ADDR: bao.address },
+          judgePolicyRename({ name: 'old' }, { name: 'new' }, undefined),
+        ),
+      ).rejects.toThrow('already exists');
+    },
+  );
+  await withFake(
+    () => ({ status: 403, json: { errors: ['refused'] } }),
+    async (bao) => {
+      expect(
+        await runFailure(
+          { BAO_ADDR: bao.address },
+          judgePolicyRename({ name: 'old' }, { name: 'new' }, undefined),
+        ),
+      ).toMatchObject({ _tag: 'Forbidden' });
+    },
+  );
+});
+
+test('policy adoption and next deploy write nothing, while live drift writes one SDK POST', async () => {
+  const store = aclPolicies();
+  const path = 'sys/policies/acl/test';
+  store.live.set(path, {
+    name: 'test',
+    policy: 'path "/policies/test/a.hcl" {\n  capabilities = ["read"]\n}',
+  });
+  await withFakeStack(fakePolicyProviders, store, async (stack, bao) => {
+    const body = BaoPolicy('Policy', { name: 'test', fragments: '/policies/test' });
+    expect(await stack.deploy(body, { adopt: true })).toEqual({ Policy: 'adopted' });
+    expect(writesOf(bao.seen)).toEqual([]);
+    expect(await stack.deploy(body)).toEqual({ Policy: 'noop' });
+    store.live.set(path, { name: 'test', policy: 'path "drift" {}' });
+    bao.seen.length = 0;
+    expect(await stack.deploy(body)).toEqual({ Policy: 'update' });
+    expect(writesOf(bao.seen)).toEqual(['POST /v1/sys/policies/acl/test']);
+  });
+});
+
+test('a real empty policy is an existing unowned object, never a first-time create', async () => {
+  const store = aclPolicies();
+  store.live.set('sys/policies/acl/test', { name: 'test', policy: '' });
+  await withFakeStack(fakePolicyProviders, store, async (stack, bao) => {
+    await expect(
+      stack.deploy(BaoPolicy('Policy', { name: 'test', fragments: '/policies/test' })),
+    ).rejects.toThrow('not owned');
+    expect(writesOf(bao.seen)).toEqual([]);
+  });
+});

package/src/openbao/policy-identity.ts

@@ -0,0 +1,24 @@
+import { policyExists, policyPath } from './policy-wire.ts';
+import { declaredString, judgeMoveWith, policyKey } from './rename.ts';
+import { nameIdentity } from './rename-identity.ts';
+
+/** A policy is its name, keyed as OpenBao keys it (`policyKey`). */
+export const policyIdentity = nameIdentity<{ readonly name: string }>(
+  'Bao.Policy',
+  policyPath,
+  policyKey,
+);
+
+/** The occupied-name guard must use the same SDK and refusal semantics as every other read. */
+export const judgePolicyRename = (
+  olds: unknown,
+  news: unknown,
+  output: { readonly name: string } | undefined,
+) =>
+  judgeMoveWith(
+    'Bao.Policy',
+    output === undefined ? declaredString(olds, 'name') : output.name,
+    declaredString(news, 'name'),
+    policyExists,
+    policyKey,
+  );

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

@@ -38,7 +38,7 @@ describe('Bao.Policy rename, through the engine', () => {
         Policy: 'replace',
       });
       assert.deepEqual(writes(bao.seen), [
-        'PUT /v1/sys/policies/acl/app-new',
+        'POST /v1/sys/policies/acl/app-new',
         'DELETE /v1/sys/policies/acl/app-old',
       ]);
       assert.deepEqual(live(), ['app-new']);
@@ -101,7 +101,7 @@ describe('Bao.Policy rename, through the engine', () => {
         stack.deploy(body('/policies/two')),
         /identity moved from app-1 to app-2/,
       );
-      assert.deepEqual(writes(bao.seen), ['PUT /v1/sys/policies/acl/upstream']);
+      assert.deepEqual(writes(bao.seen), ['POST /v1/sys/policies/acl/upstream']);
       assert.deepEqual(await stack.deploy(body('/policies/two')), {
         Policy: 'replace',
         Upstream: 'noop',

package/src/openbao/policy-wire.test.ts

@@ -5,7 +5,7 @@
  */
 import assert from 'node:assert/strict';
 import { describe, it } from 'node:test';
-import { BaoError } from './bao-status.ts';
+import { Forbidden } from '@distilled.cloud/openbao/Errors';
 import { sha256 } from './digest.ts';
 import { run, runFailure, withFake } from './fake-bao.ts';
 import { aclPolicies } from './fake-engines.ts';
@@ -19,7 +19,7 @@ const ASSEMBLED = 'path "kv/data/a" {\n  capabilities = ["read"]\n}\n' + 'path "
 describe('policy wire', () => {
   it('reads a policy that was never written as absent', async () => {
     await withFake(aclPolicies(), async (bao) => {
-      assert.equal(await run({ BAO_ADDR: bao.address }, readPolicy('zz-new-policy')), '');
+      assert.equal(await run({ BAO_ADDR: bao.address }, readPolicy('zz-new-policy')), undefined);
     });
   });
 
@@ -29,10 +29,11 @@ describe('policy wire', () => {
     await withFake(aclPolicies(), async (bao) => {
       const env = { BAO_ADDR: bao.address };
       await run(env, writePolicy('app-llm', ASSEMBLED));
-      assert.equal(bao.seen[0]?.method, 'PUT');
+      assert.equal(bao.seen[0]?.method, 'POST');
       assert.equal(bao.seen[0]?.path, `${PREFIX}app-llm`);
       assert.deepEqual(JSON.parse(bao.seen[0]?.body ?? ''), { policy: ASSEMBLED });
       const live = await run(env, readPolicy('app-llm'));
+      assert.ok(live !== undefined);
       assert.notEqual(live, ASSEMBLED, 'the fake strips the newline, as OpenBao does');
       assert.equal(sha256(live), sha256(ASSEMBLED));
     });
@@ -43,8 +44,7 @@ describe('policy wire', () => {
       () => ({ json: { errors: ['permission denied'] }, status: 403 }),
       async (bao) => {
         const error = await runFailure({ BAO_ADDR: bao.address }, readPolicy('homeflare-admin'));
-        assert.ok(error instanceof BaoError);
-        assert.equal(error.status, 403);
+        assert.ok(error instanceof Forbidden);
       },
     );
   });