@homeflare/alchemy 0.50.0 → 0.52.0

package/src/linux/container-env-quote.ts

@@ -0,0 +1,126 @@
+/**
+ * The `[Container]` `Environment=` value renderer — the one place a declared env var crosses THREE
+ * parsers between `container.environment` and the container's own environment, each able to mangle
+ * a value the props held intact:
+ *
+ *   1. Quadlet's generator reads the raw line value with systemd's exec-like splitter:
+ *      `pkg/systemd/parser/unitfile.go` `LookupAllKeyVal` calls `splitString(value,
+ *      WhitespaceSeparators, SplitRelax | SplitUnquote | SplitCUnescape)` (podman v5.4.0). An
+ *      unquoted space ENDS the assignment there; a quote starts/ends a quoted region wherever it
+ *      sits; C-escapes are processed; and an unsupported escape (`\d` in a regex, say) fails the
+ *      split — `LookupAllKeyVal` then drops EVERY assignment of that line, silently.
+ *   2. Quadlet re-emits each assignment as `--env KEY=value` arguments of the generated unit's
+ *      `ExecStart=` (`podman.addEnv` → `AddCmdline` → `escapeWords`, same source), re-quoting for
+ *      the next parser but never touching `%` or `$` — both pass through verbatim.
+ *   3. systemd parses that `ExecStart=` and expands BOTH syntaxes there. `%`: `%%` folds to one
+ *      literal `%` and an unknown `%x` makes the setting invalid ("Specifiers must be known and
+ *      resolvable for the setting to be valid", systemd.unit(5) §Specifiers). `$`
+ *      (systemd.service(5) §Command lines, v257): the generated ExecStart has no `:` prefix, so
+ *      variables are always substituted — `${FOO}` is "erased and replaced by the exact value of
+ *      the environment variable", "to pass a literal dollar sign, use "$$"", and a bare `$` in
+ *      the middle of a word stays literal (unbraced expansion applies only to a whole `$FOO`
+ *      word, which a `KEY=value` word never is). So `pa$$word` arrives halved as `pa$word` and
+ *      `a${HOME}b` arrives as `ab` — the variable is resolved from the UNIT's environment, not
+ *      the one this file declares.
+ *
+ * ⛔ MEASURED 2026-10-11 (ice2/grafana-oidc.md; reproduced locally with the real podman 5.4.2
+ *   generator): the previous renderer emitted `Environment=KEY=value` UNQUOTED, so Grafana's
+ *   `ROLE_ATTRIBUTE_PATH=contains(groups[*], '…')` reached the container as
+ *   `ROLE_ATTRIBUTE_PATH=contains(groups[*],` — split at the first space — plus a bogus `--env
+ *   cn=…` variable, and every login failed `role_attribute_strict_violation`.
+ * ⛔ MEASURED 2026-10-12 (same generator dry run, plus a live systemd 257 unit): escaping `\`, `"`,
+ *   `%` and `$` is what survives all three parsers. `Environment="KEY=a b"` generates `--env
+ *   "KEY=a b"`; `Environment="D=pa$$$$word"` generates `--env D=pa$$$$word` and
+ *   `Environment="B=a$${HOME}b"` generates `--env B=a$${HOME}b` — podman passes `$` through
+ *   untouched — and the live unit folded them back to `pa$$word` and `a${HOME}b`, exactly the
+ *   declared values, while the same values UNQUOTED arrived as `pa$word` and `ab`.
+ * ⛔ NEWLINES ARE REFUSED, NOT ENCODED — a raw newline in a key or value breaks the LINE the whole
+ *   format is built on: quadlet reads the file line by line, so the assignment ends mid-value and
+ *   anything after the newline is parsed as a NEW directive (attacker-controllable key injection
+ *   when a value comes from external config). The refusal is a typed error so a caller can catch
+ *   it by tag; `containerProblems` (container-form.ts) turns it into a problem string so one plan
+ *   still shows every refusal at once.
+ */
+import * as Data from 'effect/Data';
+
+/** Same shape as container-form.ts's `UnitLine` — structural, so this module imports nothing back. */
+export type EnvironmentLine = readonly [key: string, value: string];
+
+/** The shared rule text — the typed error's message and the problem string are the same sentence. */
+const environmentValueProblem = (key: string): string =>
+  `environment key ${JSON.stringify(key)} contains a newline; a .container file is line-based, ` +
+  'so quadlet would end the assignment mid-value and parse whatever follows as a new directive. ' +
+  'Nothing was written.';
+
+/**
+ * ⛔ CARRIES THE KEY AND THE RULE, NEVER THE VALUE — an error is logged, retried and pasted into a
+ * PR, and a newline-containing value may be arbitrarily large or semi-secret; the key name (which
+ * `secretLikeEnvironment` already names in its own messages) is enough to locate the prop.
+ */
+export class QuadletEnvironmentValueError extends Data.TaggedError('QuadletEnvironmentValueError')<{
+  readonly key: string;
+}> {
+  override get message(): string {
+    return environmentValueProblem(this.key);
+  }
+}
+
+/**
+ * `Environment="KEY=value"` — the whole assignment double-quoted, with `\`, `"`, `%` and `$`
+ * escaped (in that order, over the joined `KEY=value`), so the wrapping quotes this function adds
+ * can never be confused with quotes the value contained, every `%` reaches systemd's specifier
+ * expansion as the documented `%%` literal instead of an unknown `%x` that invalidates the unit,
+ * and every `$` reaches it as `$$` — the documented literal-dollar escape (systemd.service(5)
+ * §Command lines) — instead of a `${FOO}` systemd would erase and replace with a variable of ITS
+ * choosing, or a `$$` it would fold and halve.
+ */
+export const quoteEnvironmentValue = (key: string, value: string): string => {
+  if (key.includes('\n') || value.includes('\n')) throw new QuadletEnvironmentValueError({ key });
+  // ⛔ THE `$` REPLACEMENT MUST BE A FUNCTION — measured 2026-10-12: `replaceAll`'s replacement
+  //   STRING runs its own `$`-pattern mini-language (same fold as systemd: `$$` in it IS one
+  //   literal `$`, and `$&` is the match), so a plain `'$$'` replacement silently no-ops and the
+  //   value ships bare. A function's return value is inserted verbatim, no patterns read.
+  //   The earlier `\`, `"` and `%` replacements keep string form: only `$` starts a pattern.
+  return `"${`${key}=${value}`
+    .replaceAll('\\', '\\\\')
+    .replaceAll('"', '\\"')
+    .replaceAll('%', '%%')
+    .replaceAll('$', () => '$$')}"`;
+};
+
+/**
+ * The sorted, quoted `Environment=` lines of a `[Container]` section — spliced by container-form.ts
+ * between `EnvironmentFile=` and `Volume=`, exactly where the unquoted renderer emitted them, so
+ * the render ORDER does not change (only the bytes of the Environment lines themselves do).
+ */
+export const environmentLines = (
+  environment: Readonly<Record<string, string>>,
+): readonly EnvironmentLine[] =>
+  // ★ Object.entries, not keys+index: under noUncheckedIndexedAccess an indexed read is
+  //   `string | undefined`, and the sort below reproduces the old `keys().sort()` order exactly
+  //   (both compare UTF-16 code units), so the render order does not change.
+  Object.entries(environment)
+    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+    .map(([key, value]): EnvironmentLine => ['Environment', quoteEnvironmentValue(key, value)]);
+
+/**
+ * The newline refusal as problem STRINGS (containerProblems' currency), so one plan still shows the
+ * whole list instead of aborting on the first newline — the typed error above stays the contract
+ * for anyone rendering directly.
+ */
+export const environmentValueProblems = (
+  environment: Readonly<Record<string, string>>,
+): string[] => {
+  const found: string[] = [];
+  for (const [key, value] of Object.entries(environment).sort(([a], [b]) =>
+    a < b ? -1 : a > b ? 1 : 0,
+  )) {
+    try {
+      quoteEnvironmentValue(key, value);
+    } catch (error) {
+      if (!(error instanceof QuadletEnvironmentValueError)) throw error;
+      found.push(environmentValueProblem(key));
+    }
+  }
+  return found;
+};

package/src/linux/container-fixture.test.ts

@@ -66,7 +66,9 @@ test('renders every directive CT100’s live caddy.container carries', () => {
     'ContainerName=caddy',
     'Network=host',
     'EnvironmentFile=/etc/caddy/cf-token.env',
-    'Environment=CADDY_CONFIG=/etc/caddy/Caddyfile',
+    // ⛔ Quoted, like every Environment= value now (container-env-quote.ts) — the caddy value has
+    //   no spaces, but uniform quoting is the rule; container-env-quote.test.ts has the story.
+    'Environment="CADDY_CONFIG=/etc/caddy/Caddyfile"',
     'Volume=/etc/caddy/Caddyfile:/etc/caddy/Caddyfile:ro,Z',
     'Volume=/etc/caddy/rendered:/etc/caddy/rendered:ro,Z',
     'Volume=/etc/caddy/cf-token.env:/run/cf/token.env:ro',

package/src/linux/container-form.ts

@@ -16,6 +16,15 @@
  *   `containerProblems` below. A container that needs a secret takes `EnvironmentFile=` pointing at
  *   a host path an out-of-band secret renderer (openbao-agent) maintains; this family never reads
  *   or renders that file's contents.
+ * ⛔ `Environment=` VALUES ARE ALWAYS QUOTED, VIA container-env-quote.ts — measured 2026-10-11:
+ *   unquoted, a spaced value splits at its first space, a quoted fragment re-parses into a bogus
+ *   variable, and an unknown C escape drops the line's assignments silently (ice2/grafana-oidc.md;
+ *   the live podman 5.4.2 generator reproduced all three). Quoting costs the PARSE nothing — the
+ *   generator reads a quoted line as exactly one assignment — and it also stops systemd expanding
+ *   `%` specifiers in values. It is NOT free at deploy: every Environment line's BYTES change, so
+ *   the first deploy after this bump rewrites the file and RESTARTS every container declaring
+ *   `environment` (all 13 on ct100; only grafana's values change meaning) — plan it as one window.
+ *   Newlines are refused, never encoded (same module).
  * ⛔ `[Install]` SUPPORTS ONLY `Alias=`/`WantedBy=`/`RequiredBy=` FOR A `.container` FILE (same doc,
  *   "Currently, only the Alias, WantedBy and RequiredBy keys are supported") — NOT `Also=`, which
  *   plain `systemd.unit(5)` allows and unit-text.ts's `INSTALL_KEYS` therefore lists. See
@@ -23,9 +32,14 @@
  */
 import { type UnitSection, configDigest, digestOf, renderUnit } from './unit-form.ts';
 import { podmanArgsProblems, secretLikeEnvironment, secretLikeLines } from './container-secrets.ts';
+import { environmentLines, environmentValueProblems } from './container-env-quote.ts';
+import { QUADLET_DEFAULT_DIRECTORY, QUADLET_SEARCH_DIRECTORIES } from './container-paths.ts';
 
 /** ★ Reused, not redefined: same digest and `restartOn`-join contract as Systemd.Unit. */
 export { configDigest, digestOf };
+// ★ The search path lives in container-paths.ts (file-length cap) and is re-exported here so every
+//   importer and the barrel keep one import site — the API does not move.
+export { QUADLET_DEFAULT_DIRECTORY, QUADLET_SEARCH_DIRECTORIES };
 
 export type UnitLine = readonly [key: string, value: string];
 
@@ -64,7 +78,8 @@ export type ContainerSection = {
 export type ContainerProps = {
   /** The Quadlet file's basename, WITHOUT `.container`. Written as `<name>.container`. */
   name: string;
-  /** @default QUADLET_DEFAULT_DIRECTORY. Must be one of QUADLET_SEARCH_DIRECTORIES (below). */
+  /** @default QUADLET_DEFAULT_DIRECTORY. Must be one of QUADLET_SEARCH_DIRECTORIES
+   *  (container-paths.ts, where the search path now lives). */
   directory?: string;
   /** `[Unit]` — `Description=`/`Documentation=` typed, everything else verbatim (see file header). */
   unit?: { description?: string; documentation?: string; lines?: readonly UnitLine[] };
@@ -103,25 +118,8 @@ export type ContainerAttributes = {
 };
 
 /**
- * Podman's OWN rootful search path, most specific first — `podman-systemd.unit(5)`, "Podman Unit
- * Search Path", Podman 5.4, read 2026-09-24: "Quadlet files for the root user can be placed in the
- * following directories ordered in precedence" (`/run` over `/etc` over `/usr/share`).
- * ★ CT100's `caddy.container` lives in the middle one — measured live, `cat` over `ssh ct100`,
- *   2026-09-24: `/etc/containers/systemd/caddy.container`.
- * ⛔ A directory outside this list is invisible to Quadlet: the generator only reads these three, so
- *   a file elsewhere is a `.container` file with no `.service` ever generated from it — silently,
- *   unlike `Systemd.Unit`'s directory check, which at least writes a unit systemd could load if only
- *   it were enabled. See `containerProblems`.
+ * ★ A conservative subset of what Quadlet itself accepts as a unit name: no template `@`, no `/`.
  */
-export const QUADLET_SEARCH_DIRECTORIES = [
-  '/run/containers/systemd',
-  '/etc/containers/systemd',
-  '/usr/share/containers/systemd',
-] as const;
-
-export const QUADLET_DEFAULT_DIRECTORY = '/etc/containers/systemd';
-
-/** ★ A conservative subset of what Quadlet itself accepts as a unit name: no template `@`, no `/`. */
 export const NAME = /^[A-Za-z0-9][A-Za-z0-9_.-]*$/;
 
 export const containerPathFor = (props: Pick<ContainerProps, 'name' | 'directory'>): string =>
@@ -149,13 +147,8 @@ const containerLines = (c: ContainerSection): UnitLine[] => [
   ...(c.exec === undefined ? [] : [['Exec', c.exec] as UnitLine]),
   ...(c.autoUpdate === undefined ? [] : [['AutoUpdate', c.autoUpdate] as UnitLine]),
   ...(c.environmentFile ?? []).map((file): UnitLine => ['EnvironmentFile', file]),
-  // ★ Sorted by key: a stable render for a plain object whose own key order JS does not promise.
-  ...Object.keys(c.environment ?? {})
-    .sort()
-    .map((key): UnitLine => [
-      'Environment',
-      `${key}=${(c.environment as Record<string, string>)[key]}`,
-    ]),
+  // ⛔ Always quoted, via container-env-quote.ts (see this file's header) — sorted there too.
+  ...environmentLines(c.environment ?? {}),
   ...(c.volume ?? []).map((volume): UnitLine => ['Volume', volume]),
   ...(c.publishPort ?? []).map((port): UnitLine => ['PublishPort', port]),
   ...(c.podmanArgs ?? []).map((arg): UnitLine => ['PodmanArgs', arg]),
@@ -225,19 +218,30 @@ export const containerProblems = (props: ContainerProps): string[] => {
       (problem) => `container.${problem}`,
     ),
   );
+  // ⛔ Newlines in a key or value are refused before anything renders: a .container file is read
+  //   line by line, so a raw newline ends the assignment mid-value and whatever follows parses as a
+  //   NEW directive (key injection when a value comes from external config). Strings here so one
+  //   plan shows every refusal at once; the typed error stays the contract for direct renderers.
+  const envProblems = environmentValueProblems(props.container.environment ?? {});
+  found.push(...envProblems);
   // ★ Every OTHER rendered line — `Exec=`/`PodmanArgs=` and the `unit`/`service`/`install` escape
   //   hatches — checked too, so a secret cannot reach the file through a field this typed check does
   //   not otherwise inspect. `container.environment`'s OWN lines are excluded: `secretLikeEnvironment`
   //   above already checked them, with a better error message (the actual env var name).
+  //   ⛔ The sweep renders WITHOUT the environment (a newline value cannot throw here); the NUL
+  //   check is skipped when the environment could not render — the refusals above are its result.
+  const { environment: _env, ...withoutEnvironment } = props.container;
   found.push(
     ...secretLikeLines([
       ...unitLines(props),
-      ...containerLines(props.container).filter(([key]) => key !== 'Environment'),
+      // ⛔ No `Environment` filter needed: the destructure above removed the only field whose
+      //   lines would carry it, so `containerLines` here emits none — a filter would be dead code.
+      ...containerLines(withoutEnvironment),
       ...serviceLines(props),
       ...installLines(props),
     ]),
   );
-  if (renderContainerFile(props).includes('\u0000'))
+  if (envProblems.length === 0 && renderContainerFile(props).includes('\u0000'))
     found.push('the rendered .container file contains NUL');
   return found;
 };

package/src/linux/container-paths.ts

@@ -0,0 +1,21 @@
+/**
+ * Where Quadlet looks for `.container` files — split out of container-form.ts under the file-length
+ * cap, with the measured context that justifies every entry kept intact.
+ *
+ * Podman's OWN rootful search path, most specific first — `podman-systemd.unit(5)`, "Podman Unit
+ * Search Path", Podman 5.4, read 2026-09-24: "Quadlet files for the root user can be placed in the
+ * following directories ordered in precedence" (`/run` over `/etc` over `/usr/share`).
+ * ★ CT100's `caddy.container` lives in the middle one — measured live, `cat` over `ssh ct100`,
+ *   2026-09-24: `/etc/containers/systemd/caddy.container`.
+ * ⛔ A directory outside this list is invisible to Quadlet: the generator only reads these three, so
+ *   a file elsewhere is a `.container` file with no `.service` ever generated from it — silently,
+ *   unlike `Systemd.Unit`'s directory check, which at least writes a unit systemd could load if only
+ *   it were enabled. See `containerProblems`.
+ */
+export const QUADLET_SEARCH_DIRECTORIES = [
+  '/run/containers/systemd',
+  '/etc/containers/systemd',
+  '/usr/share/containers/systemd',
+] as const;
+
+export const QUADLET_DEFAULT_DIRECTORY = '/etc/containers/systemd';

package/src/unifi/fake-unifi.ts

@@ -17,7 +17,14 @@ import * as FetchHttpClient from 'effect/http/FetchHttpClient';
 export const FAKE_BASE = 'https://unifi.example.com/proxy/network/integration';
 export const FAKE_KEY = 'placeholder-unifi-key';
 
-export type Seen = { readonly method: string; readonly path: string };
+export type Seen = {
+  readonly method: string;
+  readonly path: string;
+  /** Parsed JSON request body, when one was sent. */
+  readonly body?: unknown;
+  /** The `redirect` mode fetch was handed (`FetchHttpClient.RequestInit`), when set. */
+  readonly redirect?: NonNullable<RequestInit['redirect']>;
+};
 
 /**
  * Plain-text failure. `protocol.ts`'s `errorEnvelope` also decodes a documented JSON shape
@@ -42,7 +49,13 @@ export const fakeUnifi = (route: (method: string, url: URL) => Response) => {
     const request =
       input instanceof Request ? new Request(input, init) : new Request(String(input), init);
     const url = new URL(request.url);
-    seen.push({ method: request.method, path: `${url.pathname}${url.search}` });
+    const text = request.method === 'GET' ? '' : await request.clone().text();
+    seen.push({
+      method: request.method,
+      path: `${url.pathname}${url.search}`,
+      ...(text === '' ? {} : { body: JSON.parse(text) as unknown }),
+      ...(init?.redirect === undefined ? {} : { redirect: init.redirect }),
+    });
     return route(request.method, url);
   }) as typeof globalThis.fetch;
   return { fetch, seen };

package/src/unifi/handler-allow-news.test.ts

@@ -0,0 +1,80 @@
+/**
+ * `unifiHandlers.reconcile` builds the allowed PUT from `news`, never `olds` (red team round 1,
+ * mutation gap), and anchors it to the CONFIGURED base URL read from the credentials.
+ *
+ * ★ A probe spec whose `describe` is constant, so `updateReconcile`'s identity check passes and the
+ *   ONLY thing separating `news.id` from `olds.id` is the wire guard's allow entry.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as ConfigProvider from 'effect/ConfigProvider';
+import * as Effect from 'effect/Effect';
+import * as Exit from 'effect/Exit';
+import * as Layer from 'effect/Layer';
+import * as HttpClient from 'effect/http/HttpClient';
+import * as HttpClientRequest from 'effect/http/HttpClientRequest';
+import { FAKE_BASE, FAKE_KEY, fakeUnifi, fakeUnifiLayer } from './fake-unifi.ts';
+import { type UnifiSpec, unifiHandlers } from './resource.ts';
+
+interface Probe {
+  id: string;
+}
+interface State {
+  written: boolean;
+}
+
+const probe: UnifiSpec<Probe, State, State, unknown, never> = {
+  type: 'Test.Probe',
+  describe: () => 'probe',
+  fetchLive: () =>
+    Effect.gen(function* () {
+      const client = yield* HttpClient.HttpClient;
+      const res = yield* client.execute(HttpClientRequest.get(`${FAKE_BASE}/probe`));
+      return (yield* res.json) as unknown as State;
+    }) as never,
+  attributes: (live) => live,
+  matches: (a) => a.written,
+  update: {
+    allowedWrite: (props) => ({ method: 'PUT', tail: `/probe/${props.id}` }),
+    // `id` differs between news and olds, so the patch is non-empty and the write really runs.
+    patchKeys: ['id'],
+    driftOf: () => [],
+    checkScope: () => Effect.void,
+    write: (_live, _patch, props) =>
+      Effect.gen(function* () {
+        const client = yield* HttpClient.HttpClient;
+        const res = yield* client.execute(HttpClientRequest.put(`${FAKE_BASE}/probe/${props.id}`));
+        return (yield* res.json) as unknown as State;
+      }) as never,
+  },
+};
+
+const config = ConfigProvider.layer(
+  ConfigProvider.fromUnknown({
+    UNIFI_NETWORK_API_BASE_URL: FAKE_BASE,
+    UNIFI_NETWORK_API_KEY: FAKE_KEY,
+  }),
+);
+
+const reconcile = (news: Probe, olds: Probe) => {
+  let written = false;
+  const fake = fakeUnifi((method) => {
+    if (method === 'PUT') written = true;
+    return Response.json({ written });
+  });
+  const exit = Effect.runPromiseExit(
+    unifiHandlers(probe)
+      .reconcile({ news, olds, output: { written: false }, session: { note: () => Effect.void } })
+      .pipe(Effect.provide(Layer.mergeAll(fakeUnifiLayer(fake.fetch), config))) as never,
+  );
+  return { fake, exit };
+};
+
+describe('unifiHandlers.reconcile allow entry', () => {
+  test('is built from news: a PUT to news.id passes even though olds.id differs', async () => {
+    const { fake, exit } = reconcile({ id: 'NEW' }, { id: 'OLD' });
+    expect(Exit.isSuccess(await exit)).toBe(true);
+    expect(fake.seen.filter((s) => s.method === 'PUT').map((s) => s.path)).toEqual([
+      '/proxy/network/integration/probe/NEW',
+    ]);
+  });
+});

package/src/unifi/index.ts

@@ -1,20 +1,36 @@
 /**
- * UniFi Network providers for Alchemy — READ-ONLY, by Tim's rule (2026-09-24; `policy.ts`).
+ * UniFi Network providers for Alchemy — ADOPT-ONLY, except `Unifi.Network` update (Tim's rule of
+ * 2026-09-24 lifted for that one case on 2026-10-10; `policy.ts`).
  *
  * ⛔ THIS BARREL IS THE PUBLIC API, SMALLER THAN THE DIRECTORY. `resource.ts`'s generic engine
  *   and each `*-form.ts`'s wire helpers are internals a provider needs but a consumer should
  *   not depend on — mirrors `../netbox/index.ts`.
  */
-export { UNIFI_READ_ONLY_POLICY, UnifiWriteRefused, type UnifiWriteAction } from './policy.ts';
+export {
+  UNIFI_READ_ONLY_POLICY,
+  UNIFI_WRITE_POLICY,
+  UnifiFieldNotRemovable,
+  UnifiFieldNotSettable,
+  UnifiIdentityChanged,
+  UnifiImmutableFieldChanged,
+  UnifiLiveDriftedSinceDeploy,
+  UnifiManagementNetworkRefused,
+  UnifiUpdateDidNotConverge,
+  UnifiUpdateWouldBeNoop,
+  UnifiWriteRefused,
+  type UnifiWriteAction,
+} from './policy.ts';
 export {
   // Barrel-exported (not just internal to `unifiHandlers`) so `homeflare-network`'s own
   // import-layer guard (plan item C0) can reuse this instead of re-implementing the same
   // `HttpClient` wrap against a second copy of the SDK's `HttpClient.HttpClient` service.
+  type AllowedWrite,
   GetOnlyHttpClient,
   UnifiNonGetRequest,
-  type UnifiRequirements,
-  type UnifiSpec,
-} from './resource.ts';
+  UnifiRefusedRequest,
+  guardedHttpClient,
+} from './wire-guard.ts';
+export { type UnifiRequirements, type UnifiSpec } from './resource.ts';
 export type { FieldDrift } from './drift.ts';
 export {
   UnifiNetwork,

package/src/unifi/network-scope.test.ts

@@ -0,0 +1,224 @@
+/**
+ * `Unifi.Network`'s write SCOPE (`network-scope.ts`), identity check, no-retry PUT and message
+ * wording — red team round 1 on PR 377. Drives `unifiOperations(spec).reconcile` against `fakeUnifi`,
+ * so the real SDK `updateNetwork` assembles the request and the fake records every one.
+ */
+import { 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 { fakeFailure, fakeUnifi, fakeUnifiLayer } from './fake-unifi.ts';
+import { type NetworkProps, spec } from './network.ts';
+import { IMMUTABLE_KEYS, REMOVABLE_KEYS, SETTABLE_KEYS } from './network-scope.ts';
+import { UnifiLiveDriftedSinceDeploy, UnifiUpdateDidNotConverge } from './policy.ts';
+import { unifiOperations } from './resource.ts';
+
+const PATH = '/proxy/network/integration/v1/sites/site-1/networks/net-1';
+const IPV6 = {
+  interfaceType: 'STATIC',
+  prefixLength: 64,
+  hostIpAddress: '2602:f660:0:16::254',
+  clientAddressAssignment: { slaacEnabled: true },
+  routerAdvertisement: { priority: 'HIGH' },
+};
+const BASE: NetworkProps = {
+  siteId: 'site-1',
+  networkId: 'net-1',
+  name: 'Compute',
+  enabled: true,
+  management: 'ADVANCED',
+  vlanId: 16,
+  dhcpGuarding: { trustedDhcpServerIpAddresses: ['10.0.0.1'] },
+  ipv4Configuration: { dhcpConfiguration: { mode: 'SERVER' }, hostIpAddress: '10.20.16.254' },
+};
+const WITH_V6 = { ...BASE, ipv6Configuration: IPV6 } as NetworkProps;
+
+const live = (extra: Record<string, unknown> = {}) => ({
+  id: 'net-1',
+  default: false,
+  metadata: { origin: 'USER' },
+  ...BASE,
+  siteId: undefined,
+  networkId: undefined,
+  ...extra,
+});
+
+const run = (
+  liveBody: object,
+  news: NetworkProps,
+  olds: NetworkProps,
+  put: () => Response = () => Response.json(liveBody),
+) => {
+  const fake = fakeUnifi((method, url) =>
+    url.pathname === PATH
+      ? method === 'GET'
+        ? Response.json(liveBody)
+        : put()
+      : fakeFailure(400, 'unexpected'),
+  );
+  const exit = Effect.runPromiseExit(
+    unifiOperations(spec)
+      .reconcile(news, { olds, output: {} })
+      .pipe(Effect.provide(fakeUnifiLayer(fake.fetch))),
+  );
+  return { fake, exit };
+};
+
+const tagOf = (exit: Exit.Exit<unknown, unknown>) => {
+  if (!Exit.isFailure(exit)) return 'Success';
+  const error = Cause.squash(exit.cause) as { _tag?: string; message?: string };
+  return error._tag ?? 'defect';
+};
+const puts = (fake: { seen: ReadonlyArray<{ method: string }> }) =>
+  fake.seen.filter((s) => s.method === 'PUT');
+
+// ⛔ EXACT-CONTENTS PIN. The three allowlists are the whole write scope: a widened SETTABLE_KEYS or
+//   REMOVABLE_KEYS would let a whole-object PUT reach a key the controller reads "off" when omitted,
+//   and a narrowed IMMUTABLE_KEYS would let a patch move the network (`zoneId`/`vlanId`/`management`/
+//   `deviceId`) or the management LAN (`default` is refused separately, not listed here). A widening
+//   with a key no behaviour test below names would keep them all green, so each list is pinned to
+//   its EXACT contents — a mutation fails this test even when nothing else does.
+describe('the three key sets are pinned to their exact contents', () => {
+  test('SETTABLE_KEYS is exactly ipv6Configuration', () => {
+    expect([...SETTABLE_KEYS]).toEqual(['ipv6Configuration']);
+  });
+
+  test('REMOVABLE_KEYS is exactly ipv6Configuration', () => {
+    expect([...REMOVABLE_KEYS]).toEqual(['ipv6Configuration']);
+  });
+
+  test('IMMUTABLE_KEYS is exactly zoneId/vlanId/management/deviceId', () => {
+    expect([...IMMUTABLE_KEYS]).toEqual(['zoneId', 'vlanId', 'management', 'deviceId']);
+  });
+});
+
+describe('removable-field allowlist (omission would turn the block off)', () => {
+  test.each([
+    ['ipv4Configuration', 'ipv4Configuration'],
+    ['dhcpGuarding', 'dhcpGuarding'],
+    ['a required key (name)', 'name'],
+  ])('dropping %s => UnifiFieldNotRemovable, zero PUTs', async (_n, key) => {
+    const { [key as 'name']: _gone, ...news } = { ...WITH_V6 } as NetworkProps;
+    const { fake, exit } = run(live({ ipv6Configuration: IPV6 }), news as NetworkProps, WITH_V6);
+    const result = await exit;
+    expect(tagOf(result)).toBe('UnifiFieldNotRemovable');
+    expect(JSON.stringify(result)).toContain(key);
+    expect(puts(fake)).toHaveLength(0);
+  });
+
+  // ⚠️ Mutation gap: an explicit `null` removes a key just like absence (`== null`, not `=== undefined`).
+  test('an explicit null on ipv6Configuration removes it from the body', async () => {
+    const news = { ...BASE, ipv6Configuration: null } as unknown as NetworkProps;
+    const { fake, exit } = run(live({ ipv6Configuration: IPV6 }), news, WITH_V6, () =>
+      Response.json(live()),
+    );
+    expect(tagOf(await exit)).toBe('Success');
+    const body = puts(fake)[0] as { body?: Record<string, unknown> };
+    expect(body.body).toBeDefined();
+    expect('ipv6Configuration' in (body.body as object)).toBe(false);
+  });
+});
+
+describe('settable-field allowlist (only ipv6Configuration may be written)', () => {
+  // ⛔ Round-2 BLOCKING finding: the PR claimed this scope but sent these PUTs. Each case is a real
+  //   change to a non-ipv6 key, with live matching the prior state, so only the allowlist stops it.
+  test.each([
+    ['enabled', { enabled: false }, {}],
+    ['internetAccessEnabled', { internetAccessEnabled: false }, { internetAccessEnabled: true }],
+    [
+      'ipv4Configuration',
+      { ipv4Configuration: { dhcpConfiguration: { mode: 'NONE' }, hostIpAddress: '10.9.9.1' } },
+      {},
+    ],
+    ['dhcpGuarding', { dhcpGuarding: { trustedDhcpServerIpAddresses: ['10.0.0.9'] } }, {}],
+  ])('a patch that sets %s => UnifiFieldNotSettable, zero PUTs', async (field, change, olds) => {
+    const oldProps = { ...WITH_V6, ...olds } as NetworkProps;
+    const { fake, exit } = run(
+      live({ ipv6Configuration: IPV6, ...olds }),
+      { ...oldProps, ...change } as NetworkProps,
+      oldProps,
+    );
+    const result = await exit;
+    expect(tagOf(result)).toBe('UnifiFieldNotSettable');
+    expect(JSON.stringify(result)).toContain(field);
+    expect(puts(fake)).toHaveLength(0);
+  });
+
+  test('setting ipv6Configuration is still allowed', async () => {
+    const { fake, exit } = run(live(), WITH_V6, BASE, () =>
+      Response.json(live({ ipv6Configuration: IPV6 })),
+    );
+    expect(tagOf(await exit)).toBe('Success');
+    expect(puts(fake)).toHaveLength(1);
+  });
+});
+
+describe('write scope', () => {
+  test('a live default (management) network is refused, zero PUTs', async () => {
+    const { fake, exit } = run(live({ default: true }), WITH_V6, BASE);
+    expect(tagOf(await exit)).toBe('UnifiManagementNetworkRefused');
+    expect(puts(fake)).toHaveLength(0);
+  });
+
+  test.each([
+    ['zoneId', { zoneId: 'zone-2' }, { zoneId: 'zone-1' }],
+    ['vlanId', { vlanId: 17 }, {}],
+    ['management', { management: 'GATEWAY' }, {}],
+    ['deviceId', { deviceId: 'dev-2' }, { deviceId: 'dev-1' }],
+  ])('a patch that changes %s is refused, zero PUTs', async (field, change, olds) => {
+    const oldProps = { ...WITH_V6, ...olds } as NetworkProps;
+    const { fake, exit } = run(
+      live({ ipv6Configuration: IPV6, ...olds }),
+      { ...oldProps, ...change } as NetworkProps,
+      oldProps,
+    );
+    const result = await exit;
+    expect(tagOf(result)).toBe('UnifiImmutableFieldChanged');
+    expect(JSON.stringify(result)).toContain(field);
+    expect(puts(fake)).toHaveLength(0);
+  });
+
+  test('olds naming another network id => UnifiIdentityChanged, zero PUTs', async () => {
+    const { fake, exit } = run(live(), WITH_V6, { ...BASE, networkId: 'net-OLD' });
+    expect(tagOf(await exit)).toBe('UnifiIdentityChanged');
+    expect(puts(fake)).toHaveLength(0);
+  });
+
+  test('olds naming another site id => UnifiIdentityChanged, zero PUTs', async () => {
+    const { fake, exit } = run(live(), WITH_V6, { ...BASE, siteId: 'site-OLD' });
+    expect(tagOf(await exit)).toBe('UnifiIdentityChanged');
+    expect(puts(fake)).toHaveLength(0);
+  });
+});
+
+describe('the PUT is attempted once', () => {
+  test('a 503 on the PUT is not retried', async () => {
+    const { fake, exit } = run(live(), WITH_V6, BASE, () => fakeFailure(503, 'busy'));
+    expect((await exit)._tag).toBe('Failure');
+    expect(puts(fake)).toHaveLength(1);
+  });
+});
+
+describe('error wording', () => {
+  test('did-not-converge says the PUT landed and names re-import', () => {
+    const message = new UnifiUpdateDidNotConverge({
+      type: 'Unifi.Network',
+      identity: 'sites/s/networks/n',
+      fields: ['ipv6Configuration'],
+    }).message;
+    expect(message).toContain('LANDED');
+    expect(message).toContain('differs from the declaration');
+    expect(message).toContain('re-import');
+    expect(message).toContain('[ipv6Configuration]');
+  });
+
+  test('live-drifted names both causes, not only a hand edit', () => {
+    const message = new UnifiLiveDriftedSinceDeploy({
+      type: 'Unifi.Network',
+      identity: 'sites/s/networks/n',
+      fields: ['name'],
+    }).message;
+    expect(message).toContain('hand edit');
+    expect(message).toContain('UnifiUpdateDidNotConverge');
+  });
+});