@homeflare/alchemy 0.50.0 → 0.51.0

package/src/unifi/resource.ts

@@ -1,28 +1,27 @@
 /**
- * One shape for every UniFi Network read-only object — `Unifi.Network`, `Unifi.FirewallZone`,
- * and whatever import adds next.
+ * One shape for every UniFi Network object — `Unifi.Network`, `Unifi.FirewallZone`, and whatever
+ * import adds next. ADOPT-ONLY, except the one `update` a spec may opt into (`Unifi.Network`).
  *
  * ★ MIRRORS `../discord/resource.ts` (S7-S10, H1, H5), NOT `../netbox/resource.ts`. Both are
  *   "marker-less API" families (S8): UniFi Network objects carry no tag or metadata field this
  *   stack could stamp as ownership, so a cold read of a match is `Unowned(attrs)` exactly like
- *   `Cloudflare/Snippets/Snippet.ts@v2.0.0-beta.79#read`, the reference implementation S8 and H1
+ *   `Cloudflare/Snippets/Snippet.ts@v2.0.0-beta.81#read`, the reference implementation S8 and H1
  *   both cite. `adopt(true)`, piped on by each resource's convenience constructor (H5), turns
  *   that into a silent one-time bind instead of an `OwnedBySomeoneElse` refusal.
  *
- * ⛔ THE DIFFERENCE FROM EVERY OTHER FAMILY HERE: THERE IS NO `create`, `update` OR `destroy` IN
- *   THIS SPEC AT ALL. Tim's rule, 2026-09-24 (`policy.ts`): UniFi and OPNsense are read-only. So
- *   `reconcile` below can only ever refuse or report an exact match — it has no write path to
- *   fall into by accident, and no resource file wired through this engine can reach one either.
+ * ⛔ THE POSTURE (`policy.ts`, Tim 2026-09-24, lifted for ONE case 2026-10-10): there is no
+ *   `create` and no `destroy` in this spec at all, and `update` exists only when a spec carries an
+ *   `update` block (`update-reconcile.ts`). `reconcile` is `updateReconcile`: refuse a create,
+ *   report an exact match with zero writes, and otherwise either refuse or run the three-way PUT.
+ *   A spec without `update` (every family but Network) can only ever refuse or report a match.
  *
  * ⚠️ RECONCILE STILL HAS TO SUCCEED ON AN EXACT-MATCH ADOPTION, NOT JUST REFUSE UNCONDITIONALLY.
- *   Measured against `Plan.ts@v2.0.0-beta.79` (`forceUpdateAfterAdoption`, H6): beta.79 forces
+ *   Measured against `Plan.ts@v2.0.0-beta.81` (`forceUpdateAfterAdoption`, H6): beta.81 forces
  *   ONE reconcile call after every cold adoption, whether or not the diff said noop — so a
  *   resource whose `reconcile` always failed would break the ordinary "adopt an unchanged
  *   object" deploy, not just a real write. The fix, exactly like `discordOperations.reconcile`:
- *   read the live object again, and refuse ONLY when it is missing (would need a create) or
- *   drifted (would need a write to converge). An exact match returns the live attributes and
- *   calls nothing — S10's "zero write calls when there is no drift" holds even under the forced
- *   post-adoption call.
+ *   read the live object again and return it on a match. S10's "zero write calls when there is
+ *   no drift" holds even under the forced post-adoption call.
  *
  * ⚠️ `NotFound` IS FOLDED TO "ABSENT" INSIDE EACH RESOURCE FILE'S OWN `fetchLive`, NOT HERE —
  *   same split netbox's `resource.ts` uses and for the same reason: `Effect.catchTag`'s
@@ -30,15 +29,21 @@
  *   spec's `E` is only concrete at each resource file's own call site. Every OTHER failure (a
  *   real 5xx, a network error, `Forbidden`) is NOT folded anywhere — it fails the plan loudly,
  *   per the task's own rule: only a genuine not-found may mean absent.
+ *
+ * ★ The wire guard (`wire-guard.ts`) and the three-way reconcile (`update-reconcile.ts`) live in
+ *   their own files; `read`/`diff`/`delete` run under `GetOnlyHttpClient`, only `reconcile` gets
+ *   the per-row allow entry of a spec that declares `update`.
  */
 import { Unowned } from 'alchemy/AdoptPolicy';
 import { isResolved } from 'alchemy/Diff';
 import type { Input } from 'alchemy/Input';
-import { CredentialsFromEnv } from '@distilled.cloud/unifi-network/Credentials';
+import { Credentials, CredentialsFromEnv } from '@distilled.cloud/unifi-network/Credentials';
 import type { UnifiNetworkOpContext } from '@distilled.cloud/unifi-network/Protocol';
 import * as Effect from 'effect/Effect';
-import * as HttpClient from 'effect/http/HttpClient';
-import { UNIFI_READ_ONLY_POLICY, refuseWrite } from './policy.ts';
+import type * as HttpClient from 'effect/http/HttpClient';
+import { refuseWrite } from './policy.ts';
+import { type ReconcileArgs, type UnifiUpdate, updateReconcile } from './update-reconcile.ts';
+import { type AllowedWrite, guardedHttpClient } from './wire-guard.ts';
 
 /** What every handler needs from the caller's runtime once `CredentialsFromEnv` is baked in. */
 export type UnifiRequirements = HttpClient.HttpClient;
@@ -47,9 +52,9 @@ export type UnifiRequirements = HttpClient.HttpClient;
  * One UniFi Network object's read. `Live` is whatever the SDK decodes (a `NetworkDetails`, a
  * `FirewallZone`, …); `E` is left to each resource file to declare (its own `fetchLive`'s error
  * union, with `NotFound` already folded away) so the precise per-operation error union flows
- * through instead of being widened by hand here.
+ * through instead of being widened by hand here. `E2` is the error union of the optional write.
  */
-export type UnifiSpec<Props extends object, Live, Attributes extends object, E> = {
+export type UnifiSpec<Props extends object, Live, Attributes extends object, E, E2 = never> = {
   /** The vendor type string, e.g. `Unifi.Network` — for the refusal message only. */
   readonly type: string;
   /** Already folds a genuine not-found to `undefined`; nothing else is folded (see header). */
@@ -58,10 +63,12 @@ export type UnifiSpec<Props extends object, Live, Attributes extends object, E>
   readonly matches: (attributes: Attributes, props: Props) => boolean;
   /** For the refusal message and read-back failures. */
   readonly describe: (props: Props) => string;
+  /** Present only on a family allowed to write (`Unifi.Network`); see `update-reconcile.ts`. */
+  readonly update?: UnifiUpdate<Props, Live, E2>;
 };
 
-export const unifiOperations = <Props extends object, Live, Attributes extends object, E>(
-  spec: UnifiSpec<Props, Live, Attributes, E>,
+export const unifiOperations = <Props extends object, Live, Attributes extends object, E, E2>(
+  spec: UnifiSpec<Props, Live, Attributes, E, E2>,
 ) => {
   const read = (props: Props) =>
     spec
@@ -91,16 +98,13 @@ export const unifiOperations = <Props extends object, Live, Attributes extends o
           : ({ action: 'update' } as const);
       }),
 
-    reconcile: (news: Props) =>
-      Effect.gen(function* () {
-        const live = yield* read(news);
-        if (live === undefined) return yield* refuseWrite(spec.type, spec.describe(news), 'create');
-        if (!spec.matches(live, news)) {
-          return yield* refuseWrite(spec.type, spec.describe(news), 'update');
-        }
-        // Exact match: the object already is what is declared. Zero write calls (S10), correct
-        // whether this is a routine deploy or beta.79's forced post-adoption reconcile (H6).
-        return live;
+    /** Pre-state callers (tests, adopt-only probes) pass just `news`: `olds`/`output` unset. */
+    reconcile: (news: Props, rest: Partial<Omit<ReconcileArgs<Props>, 'news'>> = {}) =>
+      updateReconcile(spec, {
+        news,
+        olds: rest.olds,
+        output: rest.output,
+        note: rest.note ?? (() => Effect.void),
       }),
 
     destroy: (olds: Props) => refuseWrite(spec.type, spec.describe(olds), 'delete'),
@@ -108,94 +112,49 @@ export const unifiOperations = <Props extends object, Live, Attributes extends o
 };
 
 /**
- * B0a / T12 DEFENSE IN DEPTH. `policy.ts`'s `UnifiWriteRefused` stops write INTENT at
- * `reconcile`/`destroy` — every path this engine exposes already returns that refusal instead of
- * calling an SDK write op. This guard stops the same thing one layer lower, AT THE WIRE: it wraps
- * whatever `HttpClient` the caller already provides (the stack's `FetchHttpClient.layer` in
- * production, `fakeUnifiLayer` in tests — `openbao/bao-http.ts`'s header names this same
- * "wrap, don't replace" seam) so a future resource file that, by mistake, called an SDK write
- * operation directly — bypassing `unifiOperations` entirely — would still never reach the vendor
- * API. `write-op-reference.test.ts` proves no such call exists today; this is what stops one from
- * ever taking effect if one is ever added.
- *
- * ⚠️ `Effect.die`, NOT A TYPED FAILURE — classified per distilled-doctrine's "classify every
- *   die/orDie". Every generated SDK operation (`networks.getNetworkDetails`, …) declares its OWN
- *   closed error union from the pinned OpenAPI spec, and generated files are never hand-edited to
- *   add a member to it. A typed `Effect.fail` here would be a failure mode absent from every op's
- *   declared type the moment it occurred — a type-system lie. A defect is the sound way to add a
- *   NEW "this must be structurally impossible" failure underneath types this package does not
- *   own, exactly like `openbao`'s `refuse()` helpers' `Effect.die(new Error(...))` for a
- *   configuration move that should never be reachable.
- */
-export class UnifiNonGetRequest extends Error {
-  constructor(
-    readonly method: string,
-    /** PATH ONLY, never the full URL — see `requestPath` below. */
-    readonly path: string,
-  ) {
-    super(
-      `UniFi HttpClient guard: refused ${method} ${path} -- ${UNIFI_READ_ONLY_POLICY}. This is a ` +
-        'defect, not a recoverable condition: something under src/unifi tried to send a non-GET ' +
-        "request, which policy.ts's per-operation refusal should already have made impossible. " +
-        'Fix the kit code that produced this request.',
-    );
-    this.name = 'UnifiNonGetRequest';
-  }
-}
-
-/**
- * ⛔ PATH ONLY, NEVER THE HOST. A cloud connector's base URL embeds the account's Console ID
- *   (`docs/unifi.md`'s Credentials section, T3) — a defect message is still a message that can
- *   reach a log, a CI failure body or a pasted error report, so it gets the same treatment as
- *   `redactUrls` gives the import layer's own error text. Falls back to a fixed placeholder rather
- *   than the raw string on a parse failure, so a malformed URL can never leak through unredacted.
- */
-const requestPath = (url: string): string => {
-  try {
-    return new URL(url).pathname;
-  } catch {
-    return '<unparseable request url>';
-  }
-};
-
-const guardGetOnly = (client: HttpClient.HttpClient): HttpClient.HttpClient =>
-  client.pipe(
-    HttpClient.mapRequestEffect((request) =>
-      request.method === 'GET'
-        ? Effect.succeed(request)
-        : Effect.die(new UnifiNonGetRequest(request.method, requestPath(request.url))),
-    ),
-  );
-
-/**
- * A `Layer` that reads whatever `HttpClient` is already in the calling context and replaces it,
- * for everything downstream, with `guardGetOnly`'s wrapped version (`HttpClient.layerMergedContext`
- * — see the guard above). Exported so `get-only-guard.test.ts` can prove the mechanism directly,
- * against a bare `HttpClient` service, without needing `CredentialsFromEnv` or any env var at all.
- */
-export const GetOnlyHttpClient = HttpClient.layerMergedContext(
-  Effect.map(HttpClient.HttpClient, guardGetOnly),
-);
-
-/**
- * The four provider handlers for a spec'd read-only UniFi object, wired once.
+ * The four provider handlers for a spec'd UniFi object, wired once.
  *
  * ⛔ `list` ANSWERS EMPTY. `GET /v1/sites/{siteId}/networks` answers every network on the site;
  *   adoption stays explicit, the same reasoning `Proxmox.User`'s and NetBox's `list` give.
  */
-export const unifiHandlers = <Props extends object, Live, Attributes extends object, E>(
-  spec: UnifiSpec<Props, Live, Attributes, E>,
+export const unifiHandlers = <Props extends object, Live, Attributes extends object, E, E2>(
+  spec: UnifiSpec<Props, Live, Attributes, E, E2>,
 ) => {
   const ops = unifiOperations(spec);
-  const withCredentials = <A, Err>(effect: Effect.Effect<A, Err, UnifiNetworkOpContext>) =>
-    effect.pipe(Effect.provide(GetOnlyHttpClient), Effect.provide(CredentialsFromEnv));
+  const withCredentials = <A, Err>(
+    effect: Effect.Effect<A, Err, UnifiNetworkOpContext>,
+    allow: ReadonlyArray<AllowedWrite> = [],
+  ) =>
+    Effect.gen(function* () {
+      // ⛔ The guard anchors the allowed PUT to the CONFIGURED base URL (`wire-guard.ts`), so it is
+      //   read from the same credentials the SDK uses.
+      const { apiBaseUrl } = yield* yield* Credentials;
+      return yield* effect.pipe(Effect.provide(guardedHttpClient(allow, apiBaseUrl)));
+    }).pipe(Effect.provide(CredentialsFromEnv)) as Effect.Effect<A, Err, HttpClient.HttpClient>;
+
   return {
     list: () => Effect.succeed([]),
     read: (args: { olds: Props; output: Attributes | undefined }) =>
       withCredentials(ops.readHandler(args)),
     diff: (args: { news: Input<Props>; output: Attributes | undefined }) =>
       withCredentials(ops.diff(args.news, args.output)),
-    reconcile: (args: { news: Props }) => withCredentials(ops.reconcile(args.news)),
+    // ⛔ ONLY `reconcile` gets the per-row allow entry, and only when the spec declares `update`.
+    reconcile: (args: {
+      news: Props;
+      olds: Props | undefined;
+      output: Attributes | undefined;
+      session: { note: (message: string) => Effect.Effect<void, never, never> };
+    }) =>
+      withCredentials(
+        ops.reconcile(args.news, {
+          olds: args.olds,
+          output: args.output,
+          note: (message) => args.session.note(message),
+        }),
+        // ⛔ From `news` (the ids the write will use), never `olds`; reconcile also refuses when
+        //   `olds` names another object (`update-reconcile.ts`).
+        spec.update ? [spec.update.allowedWrite(args.news)] : [],
+      ),
     delete: (args: { olds: Props }) => withCredentials(ops.destroy(args.olds)),
   };
 };

package/src/unifi/update-reconcile.ts

@@ -0,0 +1,126 @@
+/**
+ * The three-way `reconcile` every updatable `Unifi.*` family shares (today: `Unifi.Network`).
+ *
+ * ⛔ THREE INPUTS, NOT TWO. `news` is the declaration now, `olds` is the declaration the LAST
+ *   DEPLOY wrote (Alchemy state), `live` is the raw object read right now. The PUT body is built
+ *   from `live` plus ONLY the fields where `news` differs from `olds` (`computePatch`) — never
+ *   from `news` alone. So (HIGH-2) a hand edit on a field the declaration never touched is carried
+ *   through unchanged instead of reverted, and a hand edit on ANY declared field is refused
+ *   outright (step 4) rather than overwritten.
+ *
+ * ★ `unset` IS WHAT MAKES A REVERT REAL (HIGH-1). Deleting an override from a declaration makes
+ *   `news[k]` absent while `olds[k]` is set; a patch that only carried `set` would see "nothing
+ *   changed" and the revert would never write. A key present in `olds` and null/absent in `news`
+ *   lands in `unset`, and the family's `write` removes it from the body.
+ *
+ * ⛔ FIRST DEPLOY IS ADOPT-ONLY BY CONSTRUCTION (F1, LOW-8). Without BOTH `olds` and `output` there
+ *   is no last-deployed baseline to patch against, so the write refuses. That also covers beta.81's
+ *   forced post-adoption reconcile (H6): on a match (step 2) it returns live with zero writes.
+ *   `olds` must also name the SAME object as `news` (`UnifiIdentityChanged`).
+ *
+ * ⛔ SCOPE (`update.checkScope`) runs before the note and any request: the family decides what a
+ *   patch may touch (`network-scope.ts`). An omitted optional block is turned OFF by a whole-object
+ *   PUT, so removing a key is allowed only for an explicit allowlist.
+ *
+ * ⚠️ NOTES AND ERRORS CARRY FIELD NAMES ONLY, NEVER VALUES.
+ */
+import { deepEqual } from 'alchemy/Diff';
+import type { UnifiNetworkOpContext } from '@distilled.cloud/unifi-network/Protocol';
+import * as Effect from 'effect/Effect';
+import type { FieldDrift } from './drift.ts';
+import {
+  UnifiIdentityChanged,
+  UnifiLiveDriftedSinceDeploy,
+  UnifiUpdateDidNotConverge,
+  refuseWrite,
+} from './policy.ts';
+import type { UnifiSpec } from './resource.ts';
+import type { AllowedWrite } from './wire-guard.ts';
+
+export type Patch<Props> = { set: Partial<Props>; unset: ReadonlyArray<keyof Props> };
+
+/** The write half of a spec: everything needed to PUT one object, and nothing to create/delete. */
+export type UnifiUpdate<Props extends object, Live, E2> = {
+  /** The one PUT the wire guard may pass for this row (path pinned to the row's own ids). */
+  readonly allowedWrite: (props: Props) => AllowedWrite;
+  /** Declarable keys; never the identity keys. */
+  readonly patchKeys: ReadonlyArray<keyof Props>;
+  readonly driftOf: (live: Live, props: Props) => ReadonlyArray<FieldDrift>;
+  /** Refuses (typed, before any note or request) a patch outside this family's write scope. */
+  readonly checkScope: (live: Live, patch: Patch<Props>, props: Props) => Effect.Effect<void, E2>;
+  readonly write: (
+    live: Live,
+    patch: Patch<Props>,
+    props: Props,
+  ) => Effect.Effect<Live, E2, UnifiNetworkOpContext>;
+};
+
+/** Keys whose `news` value differs from `olds`: set when still declared, unset when dropped. */
+export const computePatch = <Props extends object>(
+  news: Props,
+  olds: Props,
+  patchKeys: ReadonlyArray<keyof Props>,
+): Patch<Props> => {
+  const set: Partial<Props> = {};
+  const unset: Array<keyof Props> = [];
+  for (const key of patchKeys) {
+    if (deepEqual(news[key], olds[key], { stripNullish: true })) continue;
+    if (news[key] == null) unset.push(key);
+    else set[key] = news[key];
+  }
+  return { set, unset };
+};
+
+export type ReconcileArgs<Props extends object> = {
+  readonly news: Props;
+  readonly olds: Props | undefined;
+  readonly output: unknown;
+  readonly note: (message: string) => Effect.Effect<void>;
+};
+
+export const updateReconcile = <Props extends object, Live, Attributes extends object, E, E2>(
+  spec: UnifiSpec<Props, Live, Attributes, E, E2>,
+  { news, olds, output, note }: ReconcileArgs<Props>,
+) =>
+  Effect.gen(function* () {
+    const identity = spec.describe(news);
+    const live = yield* spec.fetchLive(news);
+    if (live === undefined) return yield* refuseWrite(spec.type, identity, 'create');
+    const attrs = spec.attributes(live, news);
+    // Exact match: zero writes, correct for a routine deploy and the forced post-adoption call.
+    if (spec.matches(attrs, news)) return attrs;
+    const update = spec.update;
+    if (update === undefined || olds === undefined || output === undefined) {
+      return yield* refuseWrite(spec.type, identity, 'update');
+    }
+    // ⛔ `olds` is the baseline for THIS object only; another site or network id is no baseline.
+    const previous = spec.describe(olds);
+    if (previous !== identity) {
+      return yield* new UnifiIdentityChanged({ type: spec.type, identity, previous });
+    }
+    const drifted = update.driftOf(live, olds).map((d) => d.field);
+    if (drifted.length > 0) {
+      return yield* new UnifiLiveDriftedSinceDeploy({
+        type: spec.type,
+        identity,
+        fields: drifted,
+      });
+    }
+    const patch = computePatch(news, olds, update.patchKeys);
+    if (Object.keys(patch.set).length === 0 && patch.unset.length === 0) {
+      return yield* refuseWrite(spec.type, identity, 'update');
+    }
+    yield* update.checkScope(live, patch, news);
+    yield* note(
+      `${spec.type} ${identity}: PUT changes [${Object.keys(patch.set).join(', ')}] ` +
+        `removes [${patch.unset.map(String).join(', ')}]`,
+    );
+    const written = yield* update.write(live, patch, news);
+    const writtenAttrs = spec.attributes(written, news);
+    if (spec.matches(writtenAttrs, news)) return writtenAttrs;
+    return yield* new UnifiUpdateDidNotConverge({
+      type: spec.type,
+      identity,
+      fields: update.driftOf(written, news).map((d) => d.field),
+    });
+  });

package/src/unifi/wire-guard-anchor.test.ts

@@ -0,0 +1,198 @@
+/**
+ * The wire guard's ANCHORING, redirect handling and redaction — red team round 1 on PR 377.
+ * The first block runs a real `Bun.serve` through the real `FetchHttpClient` (no fake fetch), because
+ * the redirect finding is about what real fetch does with the fiber's `RequestInit`.
+ */
+import { afterAll, describe, expect, test } from 'bun:test';
+import * as Cause from 'effect/Cause';
+import * as Effect from 'effect/Effect';
+import * as Exit from 'effect/Exit';
+import * as FetchHttpClient from 'effect/http/FetchHttpClient';
+import * as HttpClient from 'effect/http/HttpClient';
+import * as HttpClientRequest from 'effect/http/HttpClientRequest';
+import { networkAllowedWrite } from './network.ts';
+import { GetOnlyHttpClient, UnifiRefusedRequest, guardedHttpClient } from './wire-guard.ts';
+
+const hits: Array<{ method: string; path: string }> = [];
+let status = 307;
+const server = Bun.serve({
+  port: 0,
+  hostname: '127.0.0.1',
+  fetch(req) {
+    const u = new URL(req.url);
+    hits.push({ method: req.method, path: u.pathname + u.search });
+    return u.pathname.endsWith('/networks/n')
+      ? new Response(null, { status, headers: { location: '/elsewhere/v1/sites/s/networks/O' } })
+      : Response.json({ ok: true });
+  },
+});
+afterAll(() => server.stop(true));
+
+const ROOT = '/proxy/network/integration';
+const PORT = server.port as number;
+const BASE = `http://127.0.0.1:${PORT}${ROOT}`;
+const ALLOW = [networkAllowedWrite({ siteId: 's', networkId: 'n' } as never)];
+
+const call = (
+  method: string,
+  url: string,
+  base: string | null = BASE,
+  outer: FetchHttpClient.RequestInit['Service'] = {},
+) =>
+  Effect.runPromiseExit(
+    Effect.gen(function* () {
+      const client = yield* HttpClient.HttpClient;
+      return yield* client.execute(
+        HttpClientRequest.make(method as never)(url).pipe(
+          HttpClientRequest.bodyText('{"x":1}', 'application/json'),
+        ),
+      );
+    }).pipe(
+      Effect.provide(guardedHttpClient(ALLOW, base ?? undefined)),
+      // ⛔ An OUTER RequestInit on the calling fiber: `layerMergedContext` lets it replace the guard's.
+      Effect.provideService(FetchHttpClient.RequestInit, outer),
+      Effect.provide(FetchHttpClient.layer),
+    ),
+  );
+
+const refusal = (exit: Exit.Exit<unknown, unknown>) => {
+  expect(Exit.isFailure(exit)).toBe(true);
+  if (!Exit.isFailure(exit)) throw new Error('unreachable');
+  expect(Cause.hasDies(exit.cause)).toBe(true);
+  const defect = Cause.squash(exit.cause);
+  expect(defect).toBeInstanceOf(UnifiRefusedRequest);
+  return defect as UnifiRefusedRequest;
+};
+
+describe('redirect: manual survives an OUTER FetchHttpClient.RequestInit', () => {
+  test('outer RequestInit, real 307 => exactly one request, then the refusal', async () => {
+    status = 307;
+    hits.length = 0;
+    const exit = await call('PUT', `${BASE}/v1/sites/s/networks/n`, BASE, {
+      keepalive: false,
+    });
+    expect(refusal(exit).message).toContain('307 redirect');
+    expect(hits).toEqual([{ method: 'PUT', path: `${ROOT}/v1/sites/s/networks/n` }]);
+  });
+
+  // ⚠️ Mutation gap: narrowing the 3xx check to 307 only. Real fetch with redirect:manual returns
+  //   each of these as-is, and the guard must refuse every one.
+  test.each([301, 302, 303, 307, 308])('a %d answer is refused', async (code) => {
+    status = code;
+    hits.length = 0;
+    refusal(await call('PUT', `${BASE}/v1/sites/s/networks/n`));
+    expect(hits).toHaveLength(1);
+  });
+
+  test('a 3xx answer to HEAD is refused too (HEAD is not GET)', async () => {
+    status = 302;
+    // HEAD is not on the allow list, so it dies at the request guard before any redirect exists.
+    hits.length = 0;
+    refusal(await call('HEAD', `${BASE}/v1/sites/s/networks/n`));
+    expect(hits).toEqual([]);
+  });
+});
+
+describe('a 3xx answer to a GET is refused under BOTH postures (2026-10-10 symmetry fix)', () => {
+  // ⛔ ROUND-2 FINDING: `redirect: 'manual'` was scoped to a non-empty allow list, so reconcile's
+  //   OWN GETs surfaced a raw 3xx and failed the SDK decode, while read/diff's GETs silently
+  //   followed it. Both postures must behave identically — and a followed GET re-sends the request,
+  //   API-key header included, to a URL the guard never vetted — so both refuse it, never follow.
+  //   Real fetch, no fake: the point is what fetch does with the fiber's `RequestInit`.
+  test.each([
+    ['GetOnlyHttpClient (read/diff/delete)', () => GetOnlyHttpClient],
+    ['the row allow list (reconcile)', () => guardedHttpClient(ALLOW, BASE)],
+  ])('%s: refused, never followed', async (_n, layer) => {
+    status = 301;
+    hits.length = 0;
+    const exit = await Effect.runPromiseExit(
+      Effect.gen(function* () {
+        const client = yield* HttpClient.HttpClient;
+        return yield* client.execute(HttpClientRequest.get(`${BASE}/v1/sites/s/networks/n`));
+      }).pipe(Effect.provide(layer()), Effect.provide(FetchHttpClient.layer)),
+    );
+    const defect = refusal(exit);
+    expect(defect.method).toBe('GET');
+    expect(defect.message).toContain('301 redirect');
+    // Exactly ONE request reached the server: the redirect was never followed.
+    expect(hits).toEqual([{ method: 'GET', path: `${ROOT}/v1/sites/s/networks/n` }]);
+  });
+});
+
+describe('the allowed path is anchored to the configured base URL', () => {
+  test('the exact route passes', async () => {
+    status = 200;
+    hits.length = 0;
+    expect(Exit.isSuccess(await call('PUT', `${BASE}/v1/sites/s/networks/n`))).toBe(true);
+    expect(hits).toHaveLength(1);
+  });
+
+  test.each([
+    ['a query string', `${ROOT}/v1/sites/s/networks/n?force=true`],
+    ['a nested route', `${ROOT}/v1/sites/OTHER/v1/sites/s/networks/n`],
+    ['a doubled slash', `${ROOT}//v1/sites/s/networks/n`],
+    ['a doubled slash at the root', `//v1/sites/s/networks/n`],
+    ['a trailing slash', `${ROOT}/v1/sites/s/networks/n/`],
+    ['a fragment', `${ROOT}/v1/sites/s/networks/n#frag`],
+    ['a different base path', `/totally/different/v1/sites/s/networks/n`],
+  ])('%s is refused before the transport', async (_n, path) => {
+    status = 200;
+    hits.length = 0;
+    refusal(await call('PUT', `http://127.0.0.1:${PORT}${path}`));
+    expect(hits).toEqual([]);
+  });
+
+  test('another origin is refused even with the right path', async () => {
+    hits.length = 0;
+    refusal(await call('PUT', `http://127.0.0.1:${PORT + 1}${ROOT}/v1/sites/s/networks/n`));
+    expect(hits).toEqual([]);
+  });
+
+  test('no configured base URL allows nothing (fail closed)', async () => {
+    hits.length = 0;
+    refusal(await call('PUT', `${BASE}/v1/sites/s/networks/n`, null));
+    expect(hits).toEqual([]);
+  });
+
+  // ⚠️ Mutation gap: a regex-escaped id. A `.` in an id must be literal, never "any character".
+  test('an id is compared as text, never as a pattern', async () => {
+    status = 200;
+    const dotted = [networkAllowedWrite({ siteId: 's', networkId: 'a.c' } as never)];
+    const run = (id: string) =>
+      Effect.runPromiseExit(
+        Effect.gen(function* () {
+          const client = yield* HttpClient.HttpClient;
+          return yield* client.execute(
+            HttpClientRequest.put(`${BASE}/v1/sites/s/networks/${id}`).pipe(
+              HttpClientRequest.bodyText('{}', 'application/json'),
+            ),
+          );
+        }).pipe(
+          Effect.provide(guardedHttpClient(dotted, BASE)),
+          Effect.provide(FetchHttpClient.layer),
+        ),
+      );
+    expect(Exit.isSuccess(await run('a.c'))).toBe(true);
+    refusal(await run('abc'));
+  });
+});
+
+describe('refusal messages redact the cloud connector Console ID', () => {
+  test('the segment after consoles/ never reaches the message or the path field', async () => {
+    const cloud =
+      'https://api.ui.com/v1/connector/consoles/SECRET-CONSOLE-ID/proxy/network/integration';
+    const exit = await Effect.runPromiseExit(
+      Effect.gen(function* () {
+        const client = yield* HttpClient.HttpClient;
+        return yield* client.execute(HttpClientRequest.put(`${cloud}/v1/sites/s/networks/OTHER`));
+      }).pipe(
+        Effect.provide(guardedHttpClient(ALLOW, cloud)),
+        Effect.provide(FetchHttpClient.layer),
+      ),
+    );
+    const defect = refusal(exit);
+    expect(defect.message).not.toContain('SECRET-CONSOLE-ID');
+    expect(defect.path).not.toContain('SECRET-CONSOLE-ID');
+    expect(defect.path).toContain('/consoles/<redacted>/proxy/network/integration');
+  });
+});