@homeflare/alchemy 0.39.0 → 0.41.0

package/src/talos/talos-machine-config.test.ts

@@ -0,0 +1,189 @@
+/**
+ * `Talos.MachineConfig` acceptance tests from docs/plans/2026-09-26-talos-secrets-flow.md — fully
+ * offline, fake `bao`/`talosctl` (fake-process.ts via machine-config-fixtures.ts), no real
+ * process ever spawns. Bounded-poll-per-mode tests live in machine-config-poll.test.ts.
+ */
+import assert from 'node:assert/strict';
+import { existsSync, statSync } from 'node:fs';
+import { describe, it } from 'node:test';
+import { Unowned } from 'alchemy/AdoptPolicy';
+import {
+  CONFIG_TEXT,
+  PIN,
+  dispatcher,
+  hasTag,
+  props,
+  run,
+  wrapperFor,
+} from './machine-config-fixtures.ts';
+import type { FakeCall } from './fake-process.ts';
+import { diffMachineConfig, readMachineConfig } from './machine-config-read.ts';
+import { type MachineConfigAttributes, reconcileMachineConfig } from './talos-machine-config.ts';
+import { extractMachineConfigSpec } from './values.ts';
+
+describe('reconcileMachineConfig — digest gate', () => {
+  it('fails closed on a mismatch and never spawns talosctl', async () => {
+    const calls: FakeCall[] = [];
+    await assert.rejects(
+      run(
+        reconcileMachineConfig(props(), undefined),
+        dispatcher({ configText: 'not the pinned text' }),
+        calls,
+      ),
+      hasTag('TalosConfigDigestMismatch'),
+    );
+    assert.ok(
+      calls.every((c) => c.command !== 'talosctl'),
+      'no talosctl call on a digest mismatch',
+    );
+  });
+});
+
+describe('reconcileMachineConfig — apply argv and --insecure', () => {
+  it('CREATE (output undefined) passes --insecure; argv never carries --dry-run', async () => {
+    const calls: FakeCall[] = [];
+    await run(reconcileMachineConfig(props(), undefined), dispatcher({}), calls);
+    const apply = calls.find((c) => c.command === 'talosctl' && c.args[0] === 'apply-config');
+    assert.ok(apply);
+    assert.ok(apply.args.includes('--insecure'));
+    assert.ok(!calls.some((c) => c.args.includes('--dry-run')));
+  });
+
+  it('UPDATE (output defined) never passes --insecure; base argv is exactly apply-config/--file/--mode', async () => {
+    const calls: FakeCall[] = [];
+    const output: MachineConfigAttributes = {
+      configDigest: PIN,
+      converged: 'read-back',
+      mode: 'auto',
+      node: props().node,
+    };
+    await run(reconcileMachineConfig(props(), output), dispatcher({}), calls);
+    const apply = calls.find((c) => c.command === 'talosctl' && c.args[0] === 'apply-config');
+    assert.ok(apply);
+    assert.ok(!apply.args.includes('--insecure'));
+    const filePath = apply.args[apply.args.indexOf('--file') + 1];
+    assert.deepEqual(apply.args.slice(0, 5), [
+      'apply-config',
+      '--file',
+      filePath,
+      '--mode',
+      'auto',
+    ]);
+  });
+
+  it('the machine-config temp file exists (0600) exactly when talosctl spawns, and is gone after', async () => {
+    let seenAtSpawn: { existed: boolean; mode: number } | undefined;
+    let path = '';
+    const handler = (call: FakeCall) => {
+      if (call.command === 'talosctl' && call.args[0] === 'apply-config') {
+        path = call.args[call.args.indexOf('--file') + 1] ?? '';
+        seenAtSpawn = { existed: existsSync(path), mode: statSync(path).mode & 0o777 };
+      }
+      return dispatcher({})(call);
+    };
+    await run(reconcileMachineConfig(props(), undefined), handler);
+    assert.ok(seenAtSpawn?.existed, 'temp file must exist the instant talosctl spawns');
+    assert.equal(seenAtSpawn?.mode, 0o600);
+    assert.equal(existsSync(path), false, 'temp file must be gone once reconcile returns');
+  });
+});
+
+describe('readMachineConfig — extracted spec only, no swallowing', () => {
+  it('converges even when wrapper metadata differs, since only spec is hashed', async () => {
+    const result = await run(
+      readMachineConfig(props()),
+      dispatcher({ liveWrapper: () => ({ stdout: wrapperFor(CONFIG_TEXT, '999') }) }),
+    );
+    assert.ok(result);
+    assert.equal(result.converged, 'read-back');
+  });
+
+  it('reports false (not an error), branded Unowned, when a successful read genuinely differs', async () => {
+    const result = await run(
+      readMachineConfig(props()),
+      dispatcher({
+        liveWrapper: () => ({ stdout: wrapperFor('machine:\n  type: controlplane\n') }),
+      }),
+    );
+    assert.ok(result);
+    assert.equal(result.converged, false);
+    // ⛔ fix-first #1c — a digest mismatch on the engine's cold-start adoption probe must never
+    //   read as plain (silently-owned) attrs, or a mistyped node pointing at a sibling row's
+    //   configured node gets `apply-config` run onto it with no `adopt()` in sight.
+    assert.equal(Unowned.is(result), true);
+  });
+
+  it('propagates the AUTHENTICATED failure when the maintenance probe also fails, never converged: false', async () => {
+    await assert.rejects(
+      run(
+        readMachineConfig(props()),
+        dispatcher({ liveWrapper: () => ({ exitCode: 1, stderr: 'unreachable' }) }),
+      ),
+      (error: unknown) => error instanceof Error && error.message.includes('unreachable'),
+    );
+  });
+});
+
+describe('readMachineConfig — cold-start adoption answer (fix-first #1)', () => {
+  it('returns undefined (not created) when the authenticated read fails but the node answers insecurely', async () => {
+    const result = await run(
+      readMachineConfig(props()),
+      dispatcher({
+        liveWrapper: () => ({
+          exitCode: 1,
+          stderr: 'x509: certificate signed by unknown authority',
+        }),
+        maintenanceReachable: true,
+      }),
+    );
+    assert.equal(result, undefined);
+  });
+});
+
+describe('diffMachineConfig', () => {
+  it('plans noop when the live digest matches, update when it does not', async () => {
+    const output: MachineConfigAttributes = {
+      configDigest: PIN,
+      converged: 'read-back',
+      mode: 'auto',
+      node: props().node,
+    };
+    const noop = await run(diffMachineConfig(props(), output), dispatcher({}));
+    assert.equal(noop?.action, 'noop');
+    const update = await run(
+      diffMachineConfig(props(), output),
+      dispatcher({
+        liveWrapper: () => ({ stdout: wrapperFor('machine:\n  type: controlplane\n') }),
+      }),
+    );
+    assert.equal(update?.action, 'update');
+  });
+
+  it('plans update when the live resource is gone (node reverted to maintenance mode)', async () => {
+    const output: MachineConfigAttributes = {
+      configDigest: PIN,
+      converged: 'read-back',
+      mode: 'auto',
+      node: props().node,
+    };
+    const result = await run(
+      diffMachineConfig(props(), output),
+      dispatcher({
+        liveWrapper: () => ({
+          exitCode: 1,
+          stderr: 'x509: certificate signed by unknown authority',
+        }),
+        maintenanceReachable: true,
+      }),
+    );
+    assert.equal(result?.action, 'update');
+  });
+});
+
+// Sanity: the wrapper fixture itself round-trips through extractMachineConfigSpec (belt & suspenders
+// with values.test.ts, which owns the exhaustive shape tests).
+describe('fixture sanity', () => {
+  it('wrapperFor embeds exactly CONFIG_TEXT under spec', () => {
+    assert.equal(extractMachineConfigSpec(wrapperFor(CONFIG_TEXT)), CONFIG_TEXT);
+  });
+});

package/src/talos/talos-machine-config.ts

@@ -2,38 +2,51 @@
  * `Talos.MachineConfig` — apply one machine configuration document to one node.
  *
  * ★ REASONED FROM talosctl apply-config (Talos v1.13 CLI reference): `-f/--file`, `-n/--nodes`,
- *   `-m/--mode`, `-i/--insecure` for maintenance mode, `--dry-run` for planning without a write.
+ *   `-m/--mode`, `-i/--insecure` for maintenance mode.
  *
- * ⛔ THE CONFIG BODY IS NEVER AN ATTRIBUTE. Machine configs can embed cluster tokens; only a digest
- *   of the repo file is persisted. Read `configFile` from disk at reconcile time.
+ * ⛔ THE CONFIG BODY IS NEVER AN ATTRIBUTE, A PROP, OR ARGV — ONLY ITS DIGEST. K-A3
+ *   (docs/plans/2026-09-26-talos-secrets-flow.md, option O-A) moved the source of truth from a
+ *   repo file (the shipped `configFile` + `STACK_DIR`, gone with this rewrite) to OpenBao: props
+ *   carry a `configKey` (a vault path) and a `configDigest` PINNED IN GIT, never the bytes. The
+ *   source is write-only from Alchemy's point of view — content is read once per reconcile,
+ *   verified against the pin, written to a session-temp file, and never returned from any
+ *   handler.
+ * ⛔ NEVER `--dry-run`. Talos's dry-run prints a full, unredacted old/new config diff — with an
+ *   empty old config (the first apply) that diff IS the whole config, CA private key and
+ *   bootstrap token included (REASONED, `internal/app/machined/.../v1alpha1_server.go:258-272` +
+ *   `configdiff.go`; docs/plans/2026-09-26-talos-stack-first-boot.md). This file never builds
+ *   that flag.
+ * ⛔ `insecure` IS NOT A PROP. A fixed value fails in both directions — `true` breaks every later
+ *   update, `false` breaks the very first apply against a node with no talosconfig auth yet — so
+ *   CREATE (`output === undefined`) applies `--insecure` and UPDATE never does (resource.ts).
  */
 import { Resource } from 'alchemy';
-import { isResolved } from 'alchemy/Diff';
 import type { Input } from 'alchemy/Input';
 import * as Provider from 'alchemy/Provider';
 import * as Effect from 'effect/Effect';
-import { mintTalosconfig } from './credentials.ts';
-import type { TalosRequirements, WithTarget } from './resource.ts';
+import { mintKvTempFile, mintTalosconfig, readKvValue } from './credentials.ts';
+import { diffMachineConfig, liveSpecDigest, readMachineConfig } from './machine-config-read.ts';
+import { type PollPolicy, confirmConverged } from './machine-config-poll.ts';
+import type { ApplyMode, TalosRequirements, WithTarget } from './resource.ts';
+import { TalosConfigDigestMismatch } from './talos-errors.ts';
 import { talosctl } from './talosctl.ts';
-import { configDigest, resolveConfigPath } from './values.ts';
+import { configDigest } from './values.ts';
 
-const STACK_DIR = new URL('..', import.meta.url).pathname;
-
-export type ApplyMode = 'auto' | 'no-reboot' | 'reboot' | 'staged' | 'try';
+export type { ApplyMode } from './resource.ts';
 
 export interface MachineConfigProps extends WithTarget {
   /** Node IP or hostname — the `-n` target. */
   node: string;
-  /** Repo-relative or absolute path to the YAML file passed to `-f`. */
-  configFile: string;
-  /** talosctl `-m` mode. Default `auto` per published CLI. */
-  mode?: ApplyMode;
+  /** OpenBao KV path under `target.mount` holding this node's rendered config, e.g. `nodes/10001`. */
+  configKey: string;
   /**
-   * Maintenance-mode apply only (`-i`). Default false — post-bootstrap applies use talosconfig auth.
-   *
-   * ⚠️ REASONED: docs describe `--insecure` for the first apply before talosconfig exists.
+   * sha256(canonicalText(content)) of the seeded KV value (values.ts `configDigest`), pinned in
+   * git by the operator. ⛔ Verified against the live KV content before ANY talosctl spawn — a
+   * mismatch fails closed (`TalosConfigDigestMismatch`), nothing is applied.
    */
-  insecure?: boolean;
+  configDigest: string;
+  /** talosctl `-m` mode. Default `auto` per published CLI. */
+  mode?: ApplyMode;
   /** Ordering edge — e.g. wait for Proxmox.Vm. */
   after?: readonly unknown[];
 }
@@ -42,8 +55,13 @@ export interface MachineConfigAttributes {
   node: string;
   configDigest: string;
   mode: ApplyMode;
-  /** True when the node's reported config digest matches the declared file. */
-  converged: boolean;
+  /**
+   * Which convergence claim was made. `'read-back'`/`'accepted'` only come from `reconcile` (see
+   * machine-config-poll.ts); `false` only comes from `read`, meaning a live digest was
+   * successfully fetched and genuinely differs — never a stand-in for a failed read, which
+   * propagates as its own error instead (docs/plans/2026-09-26-talos-stack-first-boot.md).
+   */
+  converged: 'read-back' | 'accepted' | false;
 }
 
 export interface TalosMachineConfig extends Resource<
@@ -56,77 +74,67 @@ export interface TalosMachineConfig extends Resource<
 
 export const TalosMachineConfig = Resource<TalosMachineConfig>('Talos.MachineConfig');
 
-const loadDigest = (props: MachineConfigProps) =>
-  Effect.gen(function* () {
-    const path = resolveConfigPath(STACK_DIR, props.configFile);
-    const text = yield* Effect.tryPromise({
-      try: () => Bun.file(path).text(),
-      catch: (cause) => new Error(`reading ${props.configFile}: ${String(cause)}`),
-    });
-    return configDigest(text);
-  });
+/**
+ * The read path (`readMachineConfig`, `diffMachineConfig`, `liveSpecDigest`) lives in
+ * machine-config-read.ts — see that file's own header for the ownership-aware three-way answer
+ * `read` now gives (fix-first #1/#2, PR 307 red team).
+ */
+
+/** `pollPolicies` is a test seam only — see machine-config-poll.ts's `confirmConverged`. */
+export const reconcileMachineConfig = (
+  props: MachineConfigProps,
+  output: MachineConfigAttributes | undefined,
+  pollPolicies?: { readonly immediate: PollPolicy; readonly rebootish: PollPolicy },
+) =>
+  Effect.scoped(
+    Effect.gen(function* () {
+      const mode = props.mode ?? 'auto';
 
-/** REASONED: `talosctl get machineconfig -o yaml` returns the live document. */
-const liveDigest = (props: MachineConfigProps, talosconfigPath: string) =>
-  talosctl(['get', 'machineconfig', '-o', 'yaml'], {
-    nodes: [props.node],
-    talosconfigPath,
-  }).pipe(
-    Effect.map((yaml) => configDigest(yaml)),
-    Effect.orElseSucceed(() => undefined),
-  );
+      // ⛔ VERIFY BEFORE ANY talosctl SPAWN. A mismatch fails closed — see talos-errors.ts.
+      const raw = yield* readKvValue(props.target.mount, props.configKey, ['config']);
+      const gotDigest = configDigest(raw);
+      if (gotDigest !== props.configDigest) {
+        return yield* Effect.fail(
+          new TalosConfigDigestMismatch({
+            expected: props.configDigest,
+            got: gotDigest,
+            key: props.configKey,
+            mount: props.target.mount,
+          }),
+        );
+      }
 
-const read = (props: MachineConfigProps) =>
-  Effect.gen(function* () {
-    const wanted = yield* loadDigest(props);
-    const credential = yield* mintTalosconfig(props.target);
-    const live = yield* liveDigest(props, credential.talosconfigPath);
-    return {
-      configDigest: wanted,
-      converged: live === wanted,
-      mode: props.mode ?? 'auto',
-      node: props.node,
-    };
-  });
+      const credential = yield* mintTalosconfig(props.target);
+      const { path } = yield* mintKvTempFile(raw, `${props.target.cluster}-${props.node}-config`);
 
-const diff = (news: Input<MachineConfigProps>, output: MachineConfigAttributes | undefined) =>
-  Effect.gen(function* () {
-    if (output === undefined || !isResolved(news)) return undefined;
-    const live = yield* read(news);
-    if (live.converged) return { action: 'noop' } as const;
-    return { action: 'update' } as const;
-  });
+      const isCreate = output === undefined;
+      const args = [
+        'apply-config',
+        '--file',
+        path,
+        '--mode',
+        mode,
+        ...(isCreate ? ['--insecure'] : []),
+      ];
+      yield* talosctl(args, { nodes: [props.node], talosconfigPath: credential.talosconfigPath });
 
-const reconcile = (props: MachineConfigProps) =>
-  Effect.gen(function* () {
-    const path = resolveConfigPath(STACK_DIR, props.configFile);
-    const wanted = yield* loadDigest(props);
-    const credential = yield* mintTalosconfig(props.target);
-    const args = [
-      'apply-config',
-      '--file',
-      path,
-      '--mode',
-      props.mode ?? 'auto',
-      ...(props.insecure === true ? ['--insecure'] : []),
-    ];
-    yield* talosctl(args, { nodes: [props.node], talosconfigPath: credential.talosconfigPath });
-    const live = yield* liveDigest(props, credential.talosconfigPath);
-    if (live !== wanted) {
-      return yield* Effect.die(
-        new Error(
-          `${props.node}: apply-config returned no error but machineconfig digest still differs. ` +
-            'Read back rather than trusting the exit code alone.',
+      const converged = yield* confirmConverged(
+        props.node,
+        mode,
+        liveSpecDigest(props, credential.talosconfigPath).pipe(
+          Effect.map((live) => live === props.configDigest),
         ),
+        pollPolicies,
       );
-    }
-    return {
-      configDigest: wanted,
-      converged: true,
-      mode: props.mode ?? 'auto',
-      node: props.node,
-    };
-  });
+
+      return {
+        configDigest: props.configDigest,
+        converged,
+        mode,
+        node: props.node,
+      } satisfies MachineConfigAttributes;
+    }),
+  );
 
 const handlers = {
   delete: () => Effect.void,
@@ -136,10 +144,16 @@ const handlers = {
   }: {
     news: Input<MachineConfigProps>;
     output: MachineConfigAttributes | undefined;
-  }) => diff(news, output),
+  }) => diffMachineConfig(news, output),
   list: () => Effect.succeed([]),
-  read: ({ olds }: { olds: MachineConfigProps }) => read(olds),
-  reconcile: ({ news }: { news: MachineConfigProps }) => reconcile(news),
+  read: ({ olds }: { olds: MachineConfigProps }) => readMachineConfig(olds),
+  reconcile: ({
+    news,
+    output,
+  }: {
+    news: MachineConfigProps;
+    output: MachineConfigAttributes | undefined;
+  }) => reconcileMachineConfig(news, output),
 };
 
 export const TalosMachineConfigProvider = () =>

package/src/talos/talosctl.ts

@@ -30,6 +30,13 @@ export type TalosRunOptions = {
   readonly talosconfigPath: string;
   readonly nodes?: readonly string[];
   readonly endpoints?: readonly string[];
+  /**
+   * `-i/--insecure` — a maintenance-mode node has no established PKI yet. Used by the CREATE apply
+   * (resource.ts's own header) and by talos-machine-config.ts's maintenance-mode probe (fix-first
+   * #1, PR 307 red team): `--talosconfig` is still passed alongside it, matching the CREATE path,
+   * since insecure mode ignores the file's certs rather than requiring their absence.
+   */
+  readonly insecure?: boolean;
 };
 
 /** Run `talosctl <args…>`. Returns trimmed stdout, or '' when empty. */
@@ -42,6 +49,7 @@ export const talosctl = (args: readonly string[], options: TalosRunOptions) =>
       options.talosconfigPath,
       ...(options.nodes === undefined ? [] : ['--nodes', options.nodes.join(',')]),
       ...(options.endpoints === undefined ? [] : ['--endpoints', options.endpoints.join(',')]),
+      ...(options.insecure === true ? ['--insecure'] : []),
     ];
     const result = yield* ChildProcess.make('talosctl', argv, {
       detached: false,

package/src/talos/values.test.ts

@@ -12,7 +12,7 @@
  */
 import assert from 'node:assert/strict';
 import { describe, it } from 'node:test';
-import { configDigest, kubeconfigMetadata, resolveConfigPath, sha256 } from './values.ts';
+import { configDigest, extractMachineConfigSpec, kubeconfigMetadata, sha256 } from './values.ts';
 
 /** Plain words, base64-encoded here rather than in the source. See the ⛔ above. */
 const b64 = (words: string) => Buffer.from(words).toString('base64');
@@ -69,12 +69,40 @@ describe('kubeconfigMetadata', () => {
   });
 });
 
-describe('resolveConfigPath', () => {
-  it('passes absolute paths through', () => {
-    assert.equal(resolveConfigPath('/stack', '/etc/talos/cp.yaml'), '/etc/talos/cp.yaml');
+describe('extractMachineConfigSpec', () => {
+  /** Shape REASONED from talosctl's `get machineconfig -o yaml` — see values.ts's own header. */
+  const wrapper = (version: string) =>
+    `node: 192.0.2.10\nmetadata:\n  version: "${version}"\nspec: "machine:\\n  type: worker\\n"\n`;
+
+  it('hashes only the spec text, not the wrapper metadata', () => {
+    const specA = extractMachineConfigSpec(wrapper('7'));
+    const specB = extractMachineConfigSpec(wrapper('9')); // metadata differs, spec does not
+    assert.ok(specA !== undefined && specB !== undefined);
+    assert.equal(specA, specB);
+    assert.equal(configDigest(specA), configDigest(specB));
+  });
+
+  it('unwraps a single-element array response the same way', () => {
+    const asArrayYaml =
+      '- node: 192.0.2.10\n  metadata:\n    version: "7"\n  spec: "machine:\\n  type: worker\\n"\n';
+    const asDoc = extractMachineConfigSpec(wrapper('7'));
+    const asArray = extractMachineConfigSpec(asArrayYaml);
+    assert.ok(asDoc !== undefined && asArray !== undefined);
+    assert.equal(asDoc, asArray);
+  });
+
+  it('returns undefined for unparsable YAML or a missing/non-string spec', () => {
+    assert.equal(extractMachineConfigSpec(':::not yaml:::'), undefined);
+    assert.equal(extractMachineConfigSpec('node: 192.0.2.10\n'), undefined);
+    assert.equal(extractMachineConfigSpec('spec:\n  nested: true\n'), undefined);
   });
 
-  it('joins relative paths to the stack directory', () => {
-    assert.equal(resolveConfigPath('/stack', 'configs/cp.yaml'), '/stack/configs/cp.yaml');
+  it('refuses more than one document rather than guessing which one (fix-first #2)', () => {
+    // Shape of an unfiltered `get machineconfig`: `persistent` then `v1alpha1`, sorted by id — a
+    // bare `doc[0]` here would silently pick `persistent`, the shipped bug this guard replaces.
+    const twoDocs =
+      '- node: 192.0.2.10\n  metadata:\n    id: persistent\n  spec: "not the applied config"\n' +
+      '- node: 192.0.2.10\n  metadata:\n    id: v1alpha1\n  spec: "machine:\\n  type: worker\\n"\n';
+    assert.equal(extractMachineConfigSpec(twoDocs), undefined);
   });
 });

package/src/talos/values.ts

@@ -1,8 +1,9 @@
 /**
  * Coercions and digests for Talos resources — every function here exists because a trap does.
  *
- * ⚠️ NOTHING IN THIS FILE TOUCHES A LIVE CLUSTER. Digests are computed from repo files or from
- *   kubeconfig YAML already on disk at reconcile time; tests use fixtures only.
+ * ⚠️ NOTHING IN THIS FILE TOUCHES A LIVE CLUSTER OR OpenBao. Digests are computed from KV content
+ *   or talosctl output already fetched by the caller, and kubeconfig YAML already on disk at
+ *   reconcile time; tests use fixtures only.
  */
 import { createHash } from 'node:crypto';
 
@@ -13,9 +14,46 @@ export const canonicalText = (text: string) => text.trimEnd();
 export const sha256 = (text: string) =>
   createHash('sha256').update(canonicalText(text)).digest('hex');
 
-/** Digest of a machine config file read from the repo. ⛔ Never persist the file body itself. */
+/** Digest of a machine config's canonical text. ⛔ Never persist the text itself. */
 export const configDigest = (text: string) => sha256(text);
 
+/**
+ * Extract the raw config text under `spec` from `talosctl get machineconfig -o yaml`'s wrapper.
+ *
+ * ⛔ THE WHOLE WRAPPER CAN NEVER MATCH THE PINNED DIGEST, AND HASHING IT WAS THE SHIPPED BUG.
+ *   REASONED from talosctl source (`cmd/talosctl/.../output/yaml.go:63`,
+ *   `resources/config/machine_config.go:40-50`): the resource envelope nests a `node:` line and
+ *   resource metadata (version, timestamps) around the config, which is itself a raw YAML STRING
+ *   under `spec`. Metadata changes on every observation, so `configDigest(wrapper)` never equals
+ *   `configDigest(seededConfigText)` even when nothing changed — every reconcile would die, every
+ *   diff would plan `update`, verify would never go quiet (all three MEASURED against the shipped
+ *   code's shape, docs/plans/2026-09-26-talos-stack-first-boot.md).
+ * ⚠️ Returns `undefined` for any shape without a string `spec`, so a caller cannot mistake
+ *   "unparsable wrapper" for "empty config" — those must fail differently (the caller's job).
+ * ⛔ MORE THAN ONE DOCUMENT IS REFUSED, NEVER `doc[0]` (fix-first #2, PR 307 red team). An unfiltered
+ *   `get machineconfig` lists BOTH the `persistent` and `v1alpha1` resources, sorted by id
+ *   (REASONED, cosi-project/runtime `inmem/collection.go:122-124`), so a bare `doc[0]` is always
+ *   `persistent` — never the config this package applies. The caller (machine-config-read.ts) now
+ *   always requests the single named resource (`get machineconfig v1alpha1`); a second document
+ *   showing up here means that request shape changed without this guard changing with it, and
+ *   silently picking one would repeat the exact shipped bug.
+ */
+export const extractMachineConfigSpec = (wrapperYaml: string): string | undefined => {
+  let doc: unknown;
+  try {
+    doc = Bun.YAML.parse(wrapperYaml);
+  } catch {
+    return undefined;
+  }
+  if (Array.isArray(doc)) {
+    if (doc.length !== 1) return undefined;
+    doc = doc[0];
+  }
+  if (doc === null || typeof doc !== 'object') return undefined;
+  const spec = (doc as { spec?: unknown }).spec;
+  return typeof spec === 'string' ? spec : undefined;
+};
+
 type KubeconfigDoc = {
   clusters?: {
     cluster?: { server?: string; 'certificate-authority-data'?: string };
@@ -64,7 +102,3 @@ export const kubeconfigMetadata = (
     endpoint,
   };
 };
-
-/** Resolve a config file path relative to the declaring stack file. */
-export const resolveConfigPath = (stackDir: string, configFile: string) =>
-  configFile.startsWith('/') ? configFile : `${stackDir}/${configFile}`;

package/src/unifi/acl-rule-drift.ts

@@ -0,0 +1,57 @@
+/**
+ * `Unifi.AclRule`'s `matches` AND `driftOf` (B6) — both built on the ONE field list below, the
+ * same `fieldDrift`-is-the-only-comparison shape `network-drift.ts`'s header explains (MEDIUM-4,
+ * red team, 2026-09-26): `matches(attrs, props) === (driftOf(live, props).length === 0)` is true
+ * BY CONSTRUCTION.
+ *
+ * ⚠️ `stripNullish: true` ON EVERY FIELD BY DEFAULT (`drift.ts`'s `defaultEqual`) — same "UniFi's
+ *   JSON answers `null`, a declaration omits" tolerance `network-drift.ts` documents.
+ * ⛔ `enforcingDeviceFilter`/`protocolFilter` RUN THROUGH `acl-rule-form.ts`'s normalizers on BOTH
+ *   sides before comparing — never applied to only `live` or only `declared` (that specific gap is
+ *   what MEDIUM-4's own mutant found in `network-drift.ts`; see its header).
+ */
+import type * as aclRules from '@distilled.cloud/unifi-network/access_control_acl_rules';
+import { makeDriftOf } from './drift.ts';
+import {
+  type AclRuleAttributes,
+  type AclRuleProps,
+  attributesOf,
+  normalizeDeviceFilter,
+  normalizeProtocolFilter,
+} from './acl-rule-form.ts';
+
+const fieldDrift = makeDriftOf<AclRuleAttributes, AclRuleProps>([
+  { field: 'action', live: (a) => a.action, declared: (p) => p.action },
+  { field: 'description', live: (a) => a.description, declared: (p) => p.description },
+  {
+    field: 'destinationFilter',
+    live: (a) => a.destinationFilter,
+    declared: (p) => p.destinationFilter,
+  },
+  { field: 'enabled', live: (a) => a.enabled, declared: (p) => p.enabled },
+  {
+    field: 'enforcingDeviceFilter',
+    live: (a) => normalizeDeviceFilter(a.enforcingDeviceFilter),
+    declared: (p) => normalizeDeviceFilter(p.enforcingDeviceFilter),
+  },
+  { field: 'name', live: (a) => a.name, declared: (p) => p.name },
+  { field: 'sourceFilter', live: (a) => a.sourceFilter, declared: (p) => p.sourceFilter },
+  { field: 'type', live: (a) => a.type, declared: (p) => p.type },
+  {
+    field: 'protocolFilter',
+    live: (a) => normalizeProtocolFilter(a.protocolFilter),
+    declared: (p) => normalizeProtocolFilter(p.protocolFilter),
+  },
+  { field: 'networkIdFilter', live: (a) => a.networkIdFilter, declared: (p) => p.networkIdFilter },
+]);
+
+export const matches = (attributes: AclRuleAttributes, props: AclRuleProps): boolean =>
+  fieldDrift(attributes, props).length === 0;
+
+/**
+ * Per-field live-vs-declared drift straight from one live read — the task's own API
+ * (`driftOf(live, props)`), so `homeflare-network`'s pre-import drift check never has to derive
+ * `attributesOf` itself just to call this.
+ */
+export const driftOf = (live: aclRules.ACLRule, props: AclRuleProps) =>
+  fieldDrift(attributesOf(live, props), props);