@homeflare/alchemy 0.37.4 → 0.37.6

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);
       },
     );
   });

package/src/openbao/policy-wire.ts

@@ -2,15 +2,20 @@
  * The three OpenBao calls Bao.Policy makes — read, write and delete of `sys/policies/acl/<name>`.
  * Split from policy.ts so the trailing-newline round trip can be tested against a fake server.
  */
+import {
+  policiesDeleteAclPolicy,
+  policiesReadAclPolicy,
+  policiesWriteAclPolicy,
+} from '@distilled.cloud/openbao/policies';
 import * as Effect from 'effect/Effect';
-import { baoDelete, baoRead, baoWrite } from './bao-http.ts';
 import { BaoError } from './bao-status.ts';
+import { runBao, runBaoRead, runBaoWrite } from './distilled.ts';
 
 /** The endpoint the CLI's policy commands used — openbao v2.6.2 api/sys_policy.go:60, :100, :122. */
 export const policyPath = (name: string) => `sys/policies/acl/${name}`;
 
 /**
- * The live policy text, or '' when the policy is genuinely absent. Anything else FAILS.
+ * The live policy text, or undefined only when the SDK reports PolicyNotFound. Other errors FAIL.
  *
  * 🔴 THE ABSENCE WORDING WAS THE POLICY COMMAND'S OWN, AND ASSUMING OTHERWISE MADE A NEW POLICY
  *   UNCREATABLE. `No value found at` was measured for `bao read`; `bao policy read` never printed
@@ -33,21 +38,36 @@ export const policyPath = (name: string) => `sys/policies/acl/${name}`;
  *   ("no policy found in response", api/sys_policy.go:81-85).
  */
 export const readPolicy = (name: string) =>
-  Effect.flatMap(baoRead(policyPath(name)), (data) => {
-    if (data === undefined) return Effect.succeed('');
-    const text = data['policy'];
-    return typeof text === 'string'
-      ? Effect.succeed(text)
-      : Effect.fail(new BaoError(200, 'GET', policyPath(name), ['no data.policy in the response']));
-  });
+  runBaoRead(policiesReadAclPolicy({ name })).pipe(
+    Effect.flatMap((data) => {
+      const text = data['policy'];
+      return typeof text === 'string'
+        ? Effect.succeed(text)
+        : Effect.fail(
+            new BaoError(200, 'GET', policyPath(name), ['no data.policy in the response']),
+          );
+    }),
+    Effect.catchTag('PolicyNotFound', () => Effect.succeed(undefined)),
+  );
+
+/** Even a live empty policy occupies its name; rename guards must not overwrite it. */
+export const policyExists = (name: string) =>
+  Effect.map(readPolicy(name), (policy) => policy !== undefined);
 
 /**
  * ★ THE HCL TRAVELS IN THE REQUEST BODY (`{"policy": …}`, api/sys_policy.go:96-101). The CLI path
  *   needed a scoped temp file because passing HCL on argv would have put every grant in the process
  *   list; a JSON body never reaches argv, so the temp file is gone with it.
+ * ★ A FULL-REPLACE WRITE: the whole policy text is sent every time, so it is safe to retry a
+ *   transport failure through `runBaoWrite` — a replayed attempt converges on the same policy
+ *   rather than compounding a partial one.
  */
 export const writePolicy = (name: string, hcl: string) =>
-  baoWrite('PUT', policyPath(name), { policy: hcl });
+  runBaoWrite(policiesWriteAclPolicy({ name, policy: hcl })).pipe(Effect.asVoid);
 
 /** Deleting a policy that is already gone answers success (handlePoliciesDelete returns nothing). */
-export const deletePolicy = (name: string) => baoDelete(policyPath(name));
+export const deletePolicy = (name: string) =>
+  runBao(policiesDeleteAclPolicy({ name })).pipe(
+    Effect.catchTag('NotFound', () => Effect.void),
+    Effect.asVoid,
+  );

package/src/openbao/policy.ts

@@ -10,9 +10,9 @@ import { ownedRead } from '../ownership/probe.ts';
 import { provingResumes } from '../ownership/resume.ts';
 import { sha256 } from './digest.ts';
 import { isEmptyAssembly } from './policy-assembly.ts';
-import { deletePolicy, policyPath, readPolicy, writePolicy } from './policy-wire.ts';
-import { policyKey } from './rename.ts';
-import { guardRename, judgeRename, nameIdentity } from './rename-identity.ts';
+import { judgePolicyRename, policyIdentity } from './policy-identity.ts';
+import { deletePolicy, readPolicy, writePolicy } from './policy-wire.ts';
+import { guardRename } from './rename-identity.ts';
 
 /**
  * An OpenBao ACL policy, assembled from the HCL fragments that declare it.
@@ -103,9 +103,6 @@ export const BaoPolicy = Resource<BaoPolicy>('Bao.Policy', {
   defaultRemovalPolicy: 'retain',
 });
 
-/** A policy is its name, keyed as OpenBao keys it (`policyKey`). */
-const IDENTITY = nameIdentity<BaoPolicyAttributes>('Bao.Policy', policyPath, policyKey);
-
 /** `path "..."` grant count — the same number the apply script prints. */
 const grantsOf = (hcl: string) => (hcl.match(/^path /gm) ?? []).length;
 
@@ -140,12 +137,12 @@ export const BaoPolicyProvider = () =>
          */
         list: () => Effect.succeed([]),
 
-        // ★ '' means genuinely absent (a 404); a refusal fails. policy-wire.ts has the history.
+        // ★ Only undefined means absent (a typed 404); even a live empty policy occupies its name.
         // ⛔ With no attributes in state, a live policy is `Unowned` unless it is the one our own
         //   interrupted create wrote: these fragments, byte for byte (ownership/probe.ts).
         read: Effect.fn(function* ({ fqn, instanceId, olds, output }) {
           const live = yield* readPolicy(olds.name);
-          const found = live.length === 0 ? undefined : attributesOf(olds.name, live, 0);
+          const found = live === undefined ? undefined : attributesOf(olds.name, live, 0);
           const ours = Effect.map(
             assemble(olds.fragments),
             (a) => sha256(a.joined) === found?.digest,
@@ -170,7 +167,7 @@ export const BaoPolicyProvider = () =>
            *   delete, so a role outside this graph that names the old policy must move in the same
            *   PR (REPLACE.md).
            */
-          const move = yield* judgeRename(IDENTITY, olds, news, output);
+          const move = yield* judgePolicyRename(olds, news, output);
           // ★ No attributes: an unfinished generation, proven ours or not by provingResumes.
           if (output === undefined) return undefined;
           if (move !== undefined) return { action: 'replace' } as const;
@@ -180,7 +177,7 @@ export const BaoPolicyProvider = () =>
           if (!isResolved(news)) return undefined;
           const { joined } = yield* assemble(news.fragments);
           const live = yield* readPolicy(news.name);
-          return live.length > 0 && sha256(live) === sha256(joined)
+          return live !== undefined && sha256(live) === sha256(joined)
             ? ({ action: 'noop' } as const)
             : ({ action: 'update' } as const);
         }),
@@ -188,7 +185,7 @@ export const BaoPolicyProvider = () =>
         reconcile: Effect.fn(function* ({ fqn, instanceId, news, output }) {
           const name = news.name;
           // ⛔ An `update` across a rename the diff could not see — refused before any write.
-          yield* guardRename(IDENTITY, news, output);
+          yield* guardRename(policyIdentity, news, output);
           const { joined, parts } = yield* assemble(news.fragments);
           /**
            * ⛔ AN EMPTY ASSEMBLY IS A REFUSAL, NOT AN EMPTY POLICY. `bao policy write` with
@@ -218,9 +215,9 @@ export const BaoPolicyProvider = () =>
            *   sibling PVE provider does exactly this in pveOperations.reconcile.
            */
           const current = yield* readPolicy(name);
-          if (current.length > 0)
+          if (current !== undefined)
             yield* refuseTakeover({ fqn, instanceId, output }, `Bao.Policy ${name}`);
-          if (current.length > 0 && sha256(current) === sha256(joined)) {
+          if (current !== undefined && sha256(current) === sha256(joined)) {
             return attributesOf(name, joined, parts);
           }
           // ⚠️ In the request body, never on argv — see `writePolicy` for why the temp file went.

package/src/openbao/rename.ts

@@ -127,12 +127,28 @@ export const judgeMove = (
   declared: string | undefined,
   pathOf: (identity: string) => string,
   key: (identity: string) => string = exact,
+) =>
+  judgeMoveWith(
+    family,
+    tried,
+    declared,
+    (identity) => Effect.map(baoRead(pathOf(identity)), (value) => value !== undefined),
+    key,
+  );
+
+/** SDK families supply their own typed read so a rename cannot fall back to raw HTTP. */
+export const judgeMoveWith = <E, R>(
+  family: string,
+  tried: string | undefined,
+  declared: string | undefined,
+  occupied: (identity: string) => Effect.Effect<boolean, E, R>,
+  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 };
+    if (!(yield* occupied(declared))) return { from: tried, to: declared };
     return yield* Effect.die(
       new Error(
         `${family}: ${tried} → ${declared} would land on an object that already exists at ` +

package/src/proxmox/node-network-read-failure.test.ts

@@ -139,6 +139,30 @@ describe('only the measured "interface does not exist" 400 means absent', () =>
     });
   });
 
+  /**
+   * ⛔ THE RETAG REGRESSION'S OWN TEST — RED-TEAM FINDING, 2026-09-25: `@distilled.cloud/proxmox`
+   *   retagged this exact 400 from the generic `ParameterVerificationFailed` to a specific
+   *   `NetworkInterfaceNotFound` (`nodes.ts`), and `readInterfaceOrFail`'s `catchTag` still named
+   *   the OLD tag — so on an already-adopted row (this is `diff`'s and `verify --all`'s `read`'s
+   *   `output !== undefined` branch, the non-folding one) the absence signal went UNCAUGHT and
+   *   threw straight through `engine.verify`, instead of resolving a `diff`/`missing` report.
+   *   Proven by temporarily reverting the `catchTag` to `'ParameterVerificationFailed'`: only this
+   *   test fails, with an unhandled `NetworkInterfaceNotFound`.
+   */
+  test('an already-adopted interface whose live GET now answers genuinely absent resolves via diff as missing, never throws', async () => {
+    const fake = clusterOverInterface('n2', 'vmbr0', live);
+    await withoutBao(async () => {
+      const engine = engineOver(ProxmoxNodeNetworkProvider().pipe(Layer.provideMerge(fake.layer)));
+      expect(await engine.deploy(declare())).toEqual({ 'n2-vmbr0': 'adopted' });
+      fake.setAnswer('genuinely-absent');
+      const report = await engine.verify(declare(), { all: true });
+      // ⛔ `update` IS THE RIGHT ANSWER HERE, NOT A THROW: this resource's `diff` treats a
+      //   vanished interface as something `reconcile` recreates (node-network.ts's `diff`,
+      //   `live === undefined` branch), the same as any other drifted-away row.
+      expect(report.rows[0]).toMatchObject({ diff: 'update' });
+    });
+  });
+
   /**
    * ★ WHY `read` FOLDS AT ALL, SPELLED OUT ON A BRAND NEW DECLARATION. Plan.ts's cold-start
    *   adoption probe (no prior Alchemy state for this declaration) calls `provider.read` with no

package/src/proxmox/node-network-wire.ts

@@ -156,14 +156,17 @@ const attributesOf = (
  *   `{"errors":{"iface":"interface does not exist"},"data":null,"message":"Parameter verification
  *   failed.\n"}` at HTTP 400 — a THIRD shape, different from every other migrated family's
  *   measured 500. `@distilled.cloud/proxmox` types this as a genuine typed error,
- *   `ParameterVerificationFailed` (`errors.ts`), carrying the per-field `errors` object rather
- *   than collapsing it to an opaque `BadRequest` — PVE's OWN 400 is never one shape (it is
- *   whatever the endpoint's parameter verification rejected), so `errors.ts`'s own header spells
- *   out why this ONE typed error is global rather than per-operation.
- * ⛔ ONLY THIS EXACT SIGNAL MEANS ABSENT, EVEN WITH THE FOLD BELOW. A different 400 reason, a
- *   permission gap, a network blip, or ANY OTHER `ParameterVerificationFailed` reason is never
- *   read as "this interface is not there" — `diff` calls this directly and propagates every one
- *   of them loudly.
+ *   `NetworkInterfaceNotFound` (`nodes.ts`, generated from `patches/nodes/network-errors.json`),
+ *   attached ONLY to `getNodeNetwork`'s error union and matched by the SDK's own
+ *   `errorEnvelope`/`matchTypedError` against the EXACT sole-field body `errors.iface ===
+ *   "interface does not exist"` — the precision the code here used to check by hand
+ *   (`error.errors['iface'] === '…'`) is now the SDK's own matcher contract, not this file's.
+ *   Any 400 that fails that exact match (a different field, a different message, more than one
+ *   field) decodes as the generic `ParameterVerificationFailed` instead, never this tag.
+ * ⛔ ONLY THIS EXACT SIGNAL MEANS ABSENT, EVEN WITH THE FOLD BELOW. A different 400 reason
+ *   (`ParameterVerificationFailed`), a permission gap, a network blip, or any other failure is
+ *   never read as "this interface is not there" — `diff` calls this directly and propagates
+ *   every one of them loudly.
  */
 export const readInterfaceOrFail = (props: NodeNetworkProps) =>
   readOrUnreadable(
@@ -172,13 +175,7 @@ export const readInterfaceOrFail = (props: NodeNetworkProps) =>
       'read',
       false,
       nodes.getNodeNetwork({ iface: props.iface, node: props.node }),
-    ).pipe(
-      Effect.catchTag('ParameterVerificationFailed', (error) =>
-        error.errors['iface'] === 'interface does not exist'
-          ? Effect.succeed(undefined)
-          : Effect.fail(error),
-      ),
-    ),
+    ).pipe(Effect.catchTag('NetworkInterfaceNotFound', () => Effect.succeed(undefined))),
   ).pipe(
     Effect.map((live) => {
       if (live === UNREADABLE) return UNREADABLE;
@@ -198,8 +195,9 @@ export const readInterfaceOrFail = (props: NodeNetworkProps) =>
  *   interrupted-create recovery, and Apply.ts's delete recovery, all call `read` with
  *   `output: undefined` and NO catch of their own (`Plan.ts` v2.0.0-beta.79 ~line 1308) — and
  *   Plan.ts fails the WHOLE PLAN, every other resource included, if that call throws. A malformed
- *   `iface` in ONE brand-new declaration (a DIFFERENT `ParameterVerificationFailed` than the
- *   absence one) would abort `bun run plan` for the entire stack under the precise-only design,
+ *   `iface` in ONE brand-new declaration (a `ParameterVerificationFailed`, DIFFERENT from the
+ *   `NetworkInterfaceNotFound` absence tag) would abort `bun run plan` for the entire stack under
+ *   the precise-only design,
  *   where every other migrated family instead defers that same malformed declaration to a scoped,
  *   loud refusal at apply. This restores that same fold for those three call sites.
  */