@homeflare/alchemy 0.19.1 → 0.20.0

package/docs/upstream-conformance.md

@@ -0,0 +1,164 @@
+# Upstream conformance, family by family
+
+Status: open ledger. Verified 2026-09-22 by reading `origin/main` `925454b` against
+[provider-standard.md](./provider-standard.md) (`alchemy@2.0.0-beta.79`). Nothing in any
+family was changed by this audit. Each row names the rule it breaks and the upstream
+replacement or fix. A row is crossed off in the PR that fixes it, with that PR's evidence.
+A decision marked **maintainer** is not an agent's to make.
+
+## Ranked findings
+
+Findings are ranked by what they can break: runtime safety first, then contributability,
+then tidiness.
+
+1. **`cloudflare/R2BucketLock` diverges on four rules.**
+   - `readLock` ends in `Effect.orDie` (S20).
+   - `reconcileLock` and `deleteLock` use `Effect.promise` (S19).
+   - `reconcileLock` skips the PUT whenever `output.rules` equals the declaration, without
+     reading the live lock (S10). So neither `--force` nor `drift --repair` can restore
+     lock rules that were removed out of band. ⚠️ Reasoned from the source, not measured
+     live.
+   - `accountId` is a prop (S15).
+
+   It is built on a second Cloudflare SDK, `cloudflare@4.5.0` (S23). Upstream
+   `Cloudflare.R2.Bucket` has lifecycle and CORS rules but no lock, so this is a real gap.
+   **Fix:** move to `@distilled.cloud/cloudflare/r2` `getBucketLock`/`putBucketLock`,
+   observe before the PUT, and resolve the account from `CloudflareEnvironment`. Then drop
+   the `cloudflare` peer. That makes it contributable as `lockRules` on `R2.Bucket`, or as
+   `Cloudflare.R2.BucketLock`. **Decision:** maintainer, on the upstream shape.
+
+2. **`forgejo/*` duplicates an upstream building block.** `client.ts` is a hand-rolled
+   Effect `HttpClient` client with a status-carrying `ForgejoError`, while
+   `@distilled.cloud/forgejo@1.0.0-rc.12` exists. That package's Smithy service version is
+   16.0.3, the version this family measured (S21, S23). Credentials come from
+   `FORGEJO_TOKEN` at call time instead of an Auth provider (S24). `read` never answers
+   `Unowned` (H1). **Replacement:** the distilled SDK plus an `alchemy/Auth` provider.
+   Untyped errors become distilled patches. **Decision:** maintainer, because it changes
+   the error surface.
+3. **`cloudflare/MeshNode` duplicates `Cloudflare.Tunnel.WarpConnector`.** The divergence is
+   deliberate and documented in [mesh-node.md](./mesh-node.md): upstream persists the
+   connector token in state as a `Redacted` attribute, and it cannot create an HA node. The
+   type string `Cloudflare.MeshNode` sits inside upstream's own namespace (H14).
+   **Options:** contribute `ha` upstream and raise the token-in-state concern, then switch;
+   or keep the house resource as a recorded divergence. **Decision:** maintainer.
+4. **Unguarded `Bun.*`, and the `node:*` modules upstream names, in shipped provider code**
+   (S42). This is listed in [the Bun line](#the-bun-line). The exported `Bun.*` paths crash
+   under Node, which is the runtime this package promises its consumers. The `node:*` paths
+   load on Node but break the Effect-only rule.
+5. **`launchd`, `linux` and `caddy` have promise-based seams (H3).** `HostRunner` and
+   `CaddyAdmin` are plain `async` interfaces, with `node:child_process`, `node:fs/promises`
+   and `node:http` behind them, and failures are untyped `Error` (S19, S21). The stated
+   reason is that a consumer implements plain async functions. Upstream meets the same need
+   by letting a caller provide `FileSystem`, `ChildProcessSpawner` or `CommandExecutor`
+   layers, and `alchemy/Util/AtomicFile.writeFileAtomic` covers the temp-and-rename write.
+   ⚠️ Only in part. `local-runner.ts` creates its temp file with `O_EXCL`, mode 0600 and
+   `chown` before `chmod`, and it refuses a planted symlink. `writeFileAtomic` writes with
+   default flags and mode, `chmod`s afterwards, and never `chown`s.
+   **Decision:** maintainer. These families are also host-specific, so "house-only" is a
+   valid answer.
+6. **`openbao/*` has no upstream equivalent, and it conforms on the contract** (Effect
+   `HttpClient`, strict `Unowned`, retain). It diverges in three ways:
+   - 30 `Effect.die` sites in non-test source, several of them on `diff` and
+     `reconcile` paths (S20);
+   - 42 test files on `node:test` (S43);
+   - `Bao.*` type strings, where the vendor name is `OpenBao` (H14).
+
+   No distilled SDK exists. OpenBao serves an OpenAPI document, so a generated SDK in
+   distilled's shape is the S23 path. **Decision:** maintainer, on whether the kit authors
+   a distilled package.
+
+7. **`proxmox/*` is the model for S38.** Its types and constraints are generated from the
+   vendor schema, and a manifest records the version and sha256. It diverges in four ways:
+   - the generic factory's `read` returns plain attributes, so every family except `Lxc`
+     adopts silently, against the house's own H1;
+   - 27 `Effect.die` sites in non-test source (S20);
+   - 7 test files on `node:test`;
+   - `Pbs.*` type strings (H14).
+8. **`talos/*`.** Its `talosctl` calls go through `ChildProcessSpawner`, as upstream's Docker
+   provider does, which conforms. Its file handling uses `Bun.file`, `Bun.write`,
+   `Bun.YAML` and `node:fs` (S42), and it uses `Effect.promise` in 3 files (S19). The
+   kubeconfig it writes is meant to be consumed through upstream's
+   `Kubernetes.KubeConfig({ path })`.
+9. **`netbox/*` conforms mostly.** Its constraints are generated from NetBox 4.7.0's
+   OpenAPI, and it uses Effect `HttpClient`. Adopting first is documented as deliberate.
+   It diverges in its credentials: `NETBOX_TOKEN` is read at call time (S24).
+10. **Every family repeats `list: () => Effect.succeed([])`**, 30 times, and only
+    `R2BucketLock` and `MeshNode` declare `nuke`. The constructor already defaults `list`
+    (S12). **Fix:** write the reason where it differs, and declare `nuke: { skip: true }`
+    where nuke must never reach the object.
+11. **Resource JSDoc is not in upstream's generator format.** Zero files use `@resource`,
+    `**Example:**` or `### Section` (S31, H10). **Decision:** maintainer, because it moves
+    the house's glyph rationale into `//` comments.
+12. **Tests never use `alchemy/Test/Bun`.** Every lifecycle is proven against loopback
+    fakes (S28, H12). Live suites need a place to run, and that is a maintainer decision.
+
+## Conforms
+
+- **`github/declareRepoPolicy`** composes upstream `GitHub.Repository` and
+  `GitHub.Ruleset`. Its one hazard is upstream's own: `Ruleset.read` returns `undefined`
+  without prior output, so a first deploy creates a duplicate
+  ([repo-policy.md](./repo-policy.md)). The fix belongs upstream: read by name and answer
+  `Unowned`.
+- **`cloudflare/website.ts`** sets house defaults over upstream `Website.Astro` and
+  `Website.Vite`.
+- **`ownership/*`** is built only on `AdoptPolicy`, `Stack`, `State` and `Artifacts`. Its
+  apply-time re-check (H2) exists because beta.79 skips the adoption probe while props hold
+  an Output. That fix also belongs in the engine upstream.
+- **`verify/*`** (`hf-adopt-verify`) runs Alchemy's own planner. It exists because beta.79
+  labels every cold adoption as an update (H6).
+
+## The Bun line
+
+These are non-test files under `src/` that the standard (S42) says must be portable. "Exp"
+marks files exported from a subpath `index.ts`. `git grep` on `origin/main` finds 23 non-test
+files under `src/` that call `Bun.*` or import `node:*`/`bun:*`. Six of them are outside
+S42's scope:
+
+- four loopback fakes (`caddy/fake-caddy.ts`, `openbao/fake-bao.ts`, `proxmox/fake-pve.ts`,
+  `proxmox/fake-pve-lxc.ts`), which are test-side under S44;
+- `proxmox/provision-cli-fake.ts`, which is used only by tests;
+- `verify/args.ts`, which belongs to the CLI and so is tooling under S43.
+
+That leaves 17 files. The table lists them, plus `provision-cli-fake.ts`, which should move
+out of `src/`. The six out-of-scope files still ship in the tarball's `src/`, but no export
+reaches them.
+⚠️ The first version of this table said 16 files and left out `launchd/job-form.ts`.
+⚠️ Corrected 2026-09-22: 14 of the 17 break upstream's rule. `launchd/job-form.ts`,
+`proxmox/write-only.ts` and `proxmox/pbs-notification-target-wire.ts` use only synchronous
+`node:crypto` or `Buffer`. Upstream allows those inside `Effect.sync`
+(`AGENTS.md@v2.0.0-beta.79#Workflow`), and 40 upstream `src/` files import `node:crypto`,
+among them `Fly/Secret.ts` and `Railway/Variable.ts`. They were listed under a blanket
+`node:*` ban that upstream does not have.
+
+| file                                                       | API                                          | exp | portable replacement                         |
+| ---------------------------------------------------------- | -------------------------------------------- | --- | -------------------------------------------- |
+| `openbao/cloudflare-roles-config.ts`                       | `Bun.YAML`                                   | yes | parse on the tooling side; pass data in      |
+| `openbao/digest.ts` (14 importers)                         | `Bun.CryptoHasher`                           | —   | `Crypto.digest` + hex; keep `canonical()` ⚠️ |
+| `openbao/cloudflare-parity-snapshot.ts`                    | `Bun.file`, `Bun.Glob`                       | —   | `FileSystem` + `Path`                        |
+| `openbao/approle-login-form.ts`                            | `Bun.file`                                   | —   | `FileSystem.readFileString`                  |
+| `openbao/approle-login-result.ts`                          | `Bun.inspect`                                | —   | a plain formatter                            |
+| `openbao/forgejo-bootstrap.ts`                             | `Bun.spawn`                                  | —   | unreferenced; `ChildProcessSpawner` or drop  |
+| `talos/credentials.ts`                                     | `Bun.write/file/env/randomUUIDv7`, `node:fs` | —   | `FileSystem.makeTempFileScoped`              |
+| `talos/kubeconfig.ts`                                      | `Bun.file`                                   | yes | `FileSystem`                                 |
+| `talos/talos-machine-config.ts`                            | `Bun.file`                                   | yes | `FileSystem`                                 |
+| `talos/values.ts`                                          | `Bun.YAML`, `node:crypto`                    | —   | tooling-side parse; hash may stay            |
+| `launchd/local-runner.ts`                                  | `node:child_process`, `node:fs/promises`     | yes | H3 above                                     |
+| `launchd/sudo-stage.ts`                                    | `node:fs/promises`, `node:os`, `node:path`   | —   | `FileSystem`, `Path`                         |
+| `launchd/job-form.ts`                                      | `node:crypto` (`createHash`)                 | —   | allowed in `Effect.sync`                     |
+| `linux/ssh-runner.ts`                                      | `node:child_process`, `node:crypto`          | yes | H3 above                                     |
+| `caddy/local-admin.ts`                                     | `node:http` (unix socket)                    | yes | H3 above                                     |
+| `proxmox/write-only.ts`, `pbs-notification-target-wire.ts` | `node:crypto`, `node:buffer`                 | —   | allowed in `Effect.sync` ⚠️                  |
+| `proxmox/provision-cli-fake.ts`                            | `Bun.spawn`, `node:fs`                       | —   | test-only; move out of `src/`                |
+
+The ⚠️ rows:
+
+- `openbao/digest.ts`: every `Bao.*` family persists this digest in state, so a swap must
+  hash the same bytes (`canonical()`, lowercase hex), or every row plans an update.
+  `Crypto.digest` from `effect/Crypto` is in every stack's services and fails with a typed
+  error; `alchemy/Util/sha256` wraps WebCrypto in `Effect.promise`.
+- `proxmox/write-only.ts`: a salted scrypt seal with `timingSafeEqual`. No Alchemy helper
+  replaces it. A plain `sha256` would make a write-only secret cheap to brute-force from
+  state, and it would change the persisted seal format.
+
+Test runners: 51 files import `node:test`/`node:assert` (openbao 42, proxmox 7, forgejo 1,
+talos 1), and 126 import `bun:test`. S43 says `bun:test`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homeflare/alchemy",
-  "version": "0.19.1",
+  "version": "0.20.0",
   "description": "Custom Alchemy providers for Cloudflare, Proxmox, OpenBao, Forgejo, Talos, launchd and Caddy, and a verifier that proves adoptions are no-ops.",
   "homepage": "https://github.com/taslabs-net/homeflare-kit/tree/main/packages/alchemy#readme",
   "bugs": "https://github.com/taslabs-net/homeflare-kit/issues",

package/src/linux/region.ts

@@ -34,6 +34,21 @@ const tokens = (spec: RegionSpec) => {
   };
 };
 
+/**
+ * Whether two declarations name the SAME block.
+ *
+ * ⛔ THE COMMENT TOKEN IS PART OF THE IDENTITY, not a formatting preference. The markers are
+ *   matched as literal whole lines, so `# BEGIN pf` and `// BEGIN pf` are two different blocks:
+ *   changing the token leaves the old block invisible to every later read, exactly as renaming
+ *   does. A resource that treated either as a mere content change would splice a second block in
+ *   and never be able to find the first one again.
+ * ★ Whole-file mode is its own identity: `undefined` equals only `undefined`.
+ */
+export const sameRegion = (a: RegionSpec | undefined, b: RegionSpec | undefined): boolean =>
+  a === undefined || b === undefined
+    ? a === undefined && b === undefined
+    : a.name === b.name && (a.comment ?? DEFAULT_COMMENT) === (b.comment ?? DEFAULT_COMMENT);
+
 export const regionProblems = (spec: RegionSpec): string[] => {
   const found: string[] = [];
   const comment = spec.comment ?? DEFAULT_COMMENT;

package/src/linux/remote-file-lifecycle.test.ts

@@ -4,7 +4,6 @@
  */
 import { describe, expect, test } from 'bun:test';
 import { fakeLinuxHost } from './fake-linux-host.ts';
-import { fileProblems } from './remote-file-form.ts';
 import {
   deleteFile,
   diffFile,
@@ -89,93 +88,6 @@ describe('whole-file mode', () => {
   });
 });
 
-describe('region mode', () => {
-  const VENDOR = '# vendor ruleset\nanchor "system"\nrule one\n';
-  const region = { name: 'homeflare' };
-  const block = { content: 'anchor "declared"\n', path: '/etc/vendor.conf', region };
-
-  const withVendor = () => {
-    const fake = host();
-    fake.files.set('/etc/vendor.conf', {
-      bytes: new TextEncoder().encode(VENDOR),
-      gid: 0,
-      kind: 'file',
-      mode: 0o600,
-      uid: 0,
-    });
-    return fake;
-  };
-
-  test('editing the block leaves the rest of the file byte-identical', async () => {
-    const fake = withVendor();
-    const output = await reconcileFile(fake.runner, block);
-    const after = decode(fake.files.get('/etc/vendor.conf')?.bytes);
-    expect(after.startsWith(VENDOR)).toBe(true);
-    await reconcileFile(fake.runner, { ...block, content: 'anchor "changed"\n' }, output);
-    expect(decode(fake.files.get('/etc/vendor.conf')?.bytes).startsWith(VENDOR)).toBe(true);
-  });
-
-  test("the other owner's mode and uid are preserved, never re-declared", async () => {
-    const fake = withVendor();
-    await reconcileFile(fake.runner, block);
-    expect(fake.files.get('/etc/vendor.conf')?.mode).toBe(0o600);
-  });
-
-  test('a change anywhere else in the file is not this resource’s drift', async () => {
-    const fake = withVendor();
-    const output = await reconcileFile(fake.runner, block);
-    const edited = `${decode(fake.files.get('/etc/vendor.conf')?.bytes)}rule two\n`;
-    fake.files.set('/etc/vendor.conf', {
-      bytes: new TextEncoder().encode(edited),
-      gid: 0,
-      kind: 'file',
-      mode: 0o600,
-      uid: 0,
-    });
-    expect(await diffFile(fake.runner, block, output)).toEqual({ action: 'noop' });
-  });
-
-  test('delete removes only the block', async () => {
-    const fake = withVendor();
-    const output = await reconcileFile(fake.runner, block);
-    await deleteFile(fake.runner, output);
-    expect(decode(fake.files.get('/etc/vendor.conf')?.bytes)).toBe(VENDOR);
-  });
-
-  test('a missing file is a refusal, because a typo is likelier than an intention', async () => {
-    const fake = host();
-    await expect(
-      reconcileFile(fake.runner, { ...block, path: '/etc/example/absent.conf' }),
-    ).rejects.toThrow(/does not create the file it lives in/);
-    const created = await reconcileFile(fake.runner, {
-      ...block,
-      create: true,
-      path: '/etc/example/absent.conf',
-    });
-    expect(created.region).toEqual(region);
-  });
-
-  test('mode and owner without create are refused at validation', () => {
-    expect(fileProblems({ ...block, mode: 0o600 })).toHaveLength(1);
-    expect(fileProblems({ ...block, create: true, mode: 0o600 })).toEqual([]);
-  });
-
-  test('a block already there with other content needs --adopt', async () => {
-    const fake = withVendor();
-    fake.files.set('/etc/vendor.conf', {
-      bytes: new TextEncoder().encode(
-        `${VENDOR}# BEGIN homeflare\nsomething else\n# END homeflare\n`,
-      ),
-      gid: 0,
-      kind: 'file',
-      mode: 0o600,
-      uid: 0,
-    });
-    await expect(reconcileFile(fake.runner, block)).rejects.toThrow(/managed region/);
-    await expect(reconcileFile(fake.runner, block, undefined, true)).resolves.toBeDefined();
-  });
-});
-
 describe('a failed read refuses', () => {
   test('a stat that throws is never read as “nothing is there”', async () => {
     const fake = host();

package/src/linux/remote-file-lifecycle.ts

@@ -28,6 +28,7 @@ import {
   planWrite,
   readFileAttributes,
   refuse,
+  relocation,
 } from './remote-file-plan.ts';
 
 export { readFileAttributes } from './remote-file-plan.ts';
@@ -42,7 +43,8 @@ export const diffFile = async (
   output: RemoteFileAttributes,
 ): Promise<Diff> => {
   const want = await identity(runner, news);
-  if (news.path !== output.path) {
+  // ⛔ A mode flip throws HERE, at plan time, before anything is written (remote-file-plan.ts).
+  if (relocation(news, output) === 'path') {
     // ★ Create-before-delete: two paths hold two files at once, so nothing forces deleteFirst.
     await runner.checkWrite?.(news.path, { mode: news.mode ?? DEFAULT_MODE, ...want });
     return { action: 'replace' };
@@ -80,8 +82,13 @@ export const reconcileFile = async (
         'a root destination or a privileged HostRunner. This provider never calls sudo itself.',
     );
   }
-  const moved = output !== undefined && output.path !== props.path;
-  const prior = moved ? undefined : output;
+  /**
+   * ⛔ WHAT WE OWNED LAST TIME MAY NOT BE WHAT WE OWN NOW. A new path, or a new region name or
+   *   comment token, means the old block or file is still out there and must be taken back — and
+   *   a flip between the two modes is refused outright (remote-file-plan.ts relocation).
+   */
+  const move = output === undefined ? 'none' : relocation(props, output);
+  const prior = move === 'none' ? output : undefined;
   const planned = await planWrite(runner, props, want);
   const live = ownedDigest(planned.before, props.region);
   const declared = digestOf(props.content);
@@ -127,10 +134,21 @@ export const reconcileFile = async (
       'the write returned but the file on disk does not match the declaration',
     );
   }
-  // ★ Create-before-delete, as the replace would have been: the old path goes once the new one is
-  //   written and verified.
-  if (moved && output !== undefined) await deleteFile(runner, output);
-  return after;
+  // ★ Create-before-delete, as the replace would have been: the old path — or, for a rename inside
+  //   one file, the old block — goes once the new one is written and verified.
+  if (move === 'none' || output === undefined) return after;
+  await deleteFile(runner, output);
+  if (move === 'path') return after;
+  /**
+   * ⛔ A REGION RENAME TOOK THE OLD BLOCK OUT OF THIS SAME FILE, so `after` — read before that
+   *   removal — describes bytes that no longer exist. Storing it would make the whole-file digest
+   *   wrong from the moment it was written and every later plan would read it as drift.
+   */
+  const settled = await readFileAttributes(runner, props.path, props.region);
+  if (settled === undefined || settled.contentSha256 !== declared) {
+    throw refuse(props.path, 'removing the previous managed block did not leave ours intact');
+  }
+  return settled;
 };
 
 /**

package/src/linux/remote-file-plan.ts

@@ -8,7 +8,7 @@
  */
 import { sha256Hex } from '../launchd/job-form.ts';
 import type { FileStat, HostRunner, WriteOptions } from '../launchd/runner.ts';
-import { type RegionSpec, readRegion, spliceRegion } from './region.ts';
+import { type RegionSpec, readRegion, sameRegion, spliceRegion } from './region.ts';
 import {
   DEFAULT_MODE,
   type RemoteFileAttributes,
@@ -46,6 +46,42 @@ export const identity = async (runner: HostRunner, props: RemoteFileProps): Prom
 
 export const digestOf = (text: string): string => sha256Hex(encoder.encode(text));
 
+/** What this declaration now owns, compared with what the last deploy owned. */
+export type Move = 'none' | 'path' | 'region';
+
+/**
+ * Has the thing this resource owns MOVED since the last deploy — and if so, how?
+ *
+ * 🔴 WHY THIS EXISTS (found by review, reproduced against the fake host, 2026-09-22). Without it,
+ *   only `path` was identity and both of these read as a routine `update`:
+ *   - RENAMING THE REGION left the old block in the file FOREVER. The new markers were spliced in,
+ *     the old ones were never touched, and `delete` — which can only look for the name in state,
+ *     now the new one — could never remove them. Two `anchor` lines in a packet filter, two
+ *     entries in a host table, and nothing in the stack able to take either back.
+ *   - DROPPING `region` TOOK OVER THE WHOLE FILE. The plan said `update`; the apply replaced every
+ *     byte of a file belonging to a vendor package with this resource's four lines. That is the
+ *     one thing the managed-region design exists to make impossible.
+ * ⛔ A FLIP BETWEEN THE TWO MODES IS A REFUSAL, NOT A MOVE. Neither order is safe: writing the
+ *   whole file first destroys the other owner's bytes before anything can be undone, and removing
+ *   the block first destroys our own claim and then refuses. The operator destroys the resource
+ *   and declares a new one, which is the only sequence with a reviewable diff at each step.
+ * ★ A region-to-region rename IS safe as a move, because both blocks can exist at once: write the
+ *   new one, verify it, then take the old one out (remote-file-lifecycle.ts reconcileFile).
+ */
+export const relocation = (props: RemoteFileProps, output: RemoteFileAttributes): Move => {
+  if (props.path !== output.path) return 'path';
+  if (sameRegion(props.region, output.region)) return 'none';
+  if (props.region === undefined || output.region === undefined) {
+    throw refuse(
+      props.path,
+      `changes between owning the whole file and owning the managed region ` +
+        `${JSON.stringify((props.region ?? output.region)?.name ?? '')} at the same path. Those ` +
+        'are two different claims on one file: destroy this resource and declare a new one.',
+    );
+  }
+  return 'region';
+};
+
 /** The digest of the part this resource owns, or `undefined` when that part is not there. */
 export const ownedDigest = (
   file: string | undefined,

package/src/linux/remote-file-region.test.ts

@@ -0,0 +1,181 @@
+/**
+ * RemoteFile in MANAGED REGION mode against the fake Linux host: the promise that every byte
+ * outside the markers survives, and the identity rules that keep it true when a declaration
+ * changes. Split from remote-file-lifecycle.test.ts, which covers whole-file mode.
+ */
+import { describe, expect, test } from 'bun:test';
+import { fakeLinuxHost } from './fake-linux-host.ts';
+import { fileProblems } from './remote-file-form.ts';
+import {
+  deleteFile,
+  diffFile,
+  readFileAttributes,
+  reconcileFile,
+} from './remote-file-lifecycle.ts';
+
+const decode = (bytes: Uint8Array | undefined) => new TextDecoder().decode(bytes);
+
+const host = (euid = 0) =>
+  fakeLinuxHost({
+    dirs: { '/etc': 0, '/etc/example': 0, '/home/someone': 1001 },
+    euid,
+    groups: { root: 0, staff: 50 },
+    users: {
+      root: { gid: 0, home: '/root', uid: 0 },
+      someone: { gid: 1001, home: '/home/someone', uid: 1001 },
+    },
+  });
+
+describe('region mode', () => {
+  const VENDOR = '# vendor ruleset\nanchor "system"\nrule one\n';
+  const region = { name: 'homeflare' };
+  const block = { content: 'anchor "declared"\n', path: '/etc/vendor.conf', region };
+
+  const withVendor = () => {
+    const fake = host();
+    fake.files.set('/etc/vendor.conf', {
+      bytes: new TextEncoder().encode(VENDOR),
+      gid: 0,
+      kind: 'file',
+      mode: 0o600,
+      uid: 0,
+    });
+    return fake;
+  };
+
+  test('editing the block leaves the rest of the file byte-identical', async () => {
+    const fake = withVendor();
+    const output = await reconcileFile(fake.runner, block);
+    const after = decode(fake.files.get('/etc/vendor.conf')?.bytes);
+    expect(after.startsWith(VENDOR)).toBe(true);
+    await reconcileFile(fake.runner, { ...block, content: 'anchor "changed"\n' }, output);
+    expect(decode(fake.files.get('/etc/vendor.conf')?.bytes).startsWith(VENDOR)).toBe(true);
+  });
+
+  test("the other owner's mode and uid are preserved, never re-declared", async () => {
+    const fake = withVendor();
+    await reconcileFile(fake.runner, block);
+    expect(fake.files.get('/etc/vendor.conf')?.mode).toBe(0o600);
+  });
+
+  test('a change anywhere else in the file is not this resource’s drift', async () => {
+    const fake = withVendor();
+    const output = await reconcileFile(fake.runner, block);
+    const edited = `${decode(fake.files.get('/etc/vendor.conf')?.bytes)}rule two\n`;
+    fake.files.set('/etc/vendor.conf', {
+      bytes: new TextEncoder().encode(edited),
+      gid: 0,
+      kind: 'file',
+      mode: 0o600,
+      uid: 0,
+    });
+    expect(await diffFile(fake.runner, block, output)).toEqual({ action: 'noop' });
+  });
+
+  test('delete removes only the block', async () => {
+    const fake = withVendor();
+    const output = await reconcileFile(fake.runner, block);
+    await deleteFile(fake.runner, output);
+    expect(decode(fake.files.get('/etc/vendor.conf')?.bytes)).toBe(VENDOR);
+  });
+
+  test('a missing file is a refusal, because a typo is likelier than an intention', async () => {
+    const fake = host();
+    await expect(
+      reconcileFile(fake.runner, { ...block, path: '/etc/example/absent.conf' }),
+    ).rejects.toThrow(/does not create the file it lives in/);
+    const created = await reconcileFile(fake.runner, {
+      ...block,
+      create: true,
+      path: '/etc/example/absent.conf',
+    });
+    expect(created.region).toEqual(region);
+  });
+
+  /**
+   * 🔴 BOTH OF THESE SHIPPED AS `update` AND WERE FOUND BY REVIEW (2026-09-22). They are the two
+   *   ways the region promise could be broken from an ordinary edit to a stack file.
+   */
+  test('renaming the region moves the block; the old markers do not survive', async () => {
+    const fake = withVendor();
+    const output = await reconcileFile(fake.runner, block);
+    const renamed = { ...block, region: { name: 'homeflare-mcp' } };
+    // ⛔ An update, not a noop: the new block is not in the file yet.
+    expect(await diffFile(fake.runner, renamed, output)).toEqual({ action: 'update' });
+    const moved = await reconcileFile(fake.runner, renamed, output);
+    const after = decode(fake.files.get('/etc/vendor.conf')?.bytes);
+    expect(after.startsWith(VENDOR)).toBe(true);
+    expect(after).not.toContain('BEGIN homeflare\n');
+    expect(after).toContain('BEGIN homeflare-mcp');
+    // ⛔ The stored digest must describe the file AFTER the old block was taken out.
+    const live = await readFileAttributes(fake.runner, '/etc/vendor.conf', renamed.region);
+    expect(moved.sha256).toBe(live?.sha256 ?? '');
+    await deleteFile(fake.runner, moved);
+    expect(decode(fake.files.get('/etc/vendor.conf')?.bytes)).toBe(VENDOR);
+  });
+
+  test('changing the comment token is a rename, not a reformat', async () => {
+    const fake = withVendor();
+    const output = await reconcileFile(fake.runner, block);
+    const retokened = { ...block, region: { comment: '//', name: 'homeflare' } };
+    await reconcileFile(fake.runner, retokened, output);
+    const after = decode(fake.files.get('/etc/vendor.conf')?.bytes);
+    expect(after).toContain('// BEGIN homeflare');
+    expect(after).not.toContain('# BEGIN homeflare');
+  });
+
+  test('a file this resource borrowed is never taken over by dropping the region', async () => {
+    const fake = withVendor();
+    const output = await reconcileFile(fake.runner, block);
+    const whole = { content: block.content, path: block.path };
+    // ⛔ At plan time, before a single byte moves.
+    await expect(diffFile(fake.runner, whole, output)).rejects.toThrow(/two different claims/);
+    await expect(reconcileFile(fake.runner, whole, output)).rejects.toThrow(/two different claims/);
+    expect(decode(fake.files.get('/etc/vendor.conf')?.bytes).startsWith(VENDOR)).toBe(true);
+  });
+
+  test('adding a region to a file this resource owned whole is refused the same way', async () => {
+    const fake = host();
+    const whole = { content: 'a = 1\n', path: '/etc/example/whole.conf' };
+    const output = await reconcileFile(fake.runner, whole);
+    await expect(
+      diffFile(fake.runner, { ...whole, region: { name: 'homeflare' } }, output),
+    ).rejects.toThrow(/two different claims/);
+  });
+
+  test('a rename onto a block someone else already owns is refused', async () => {
+    const fake = withVendor();
+    const output = await reconcileFile(fake.runner, block);
+    const taken = `${decode(fake.files.get('/etc/vendor.conf')?.bytes)}# BEGIN other\nnot ours\n# END other\n`;
+    fake.files.set('/etc/vendor.conf', {
+      bytes: new TextEncoder().encode(taken),
+      gid: 0,
+      kind: 'file',
+      mode: 0o600,
+      uid: 0,
+    });
+    await expect(
+      reconcileFile(fake.runner, { ...block, region: { name: 'other' } }, output),
+    ).rejects.toThrow(/already carries that managed region/);
+  });
+
+  test('mode and owner without create are refused at validation', () => {
+    expect(fileProblems({ ...block, mode: 0o600 })).toHaveLength(1);
+    expect(fileProblems({ ...block, create: true, mode: 0o600 })).toEqual([]);
+  });
+
+  test('a block already there with other content needs --adopt', async () => {
+    const fake = withVendor();
+    fake.files.set('/etc/vendor.conf', {
+      bytes: new TextEncoder().encode(
+        `${VENDOR}# BEGIN homeflare\nsomething else\n# END homeflare\n`,
+      ),
+      gid: 0,
+      kind: 'file',
+      mode: 0o600,
+      uid: 0,
+    });
+    await expect(reconcileFile(fake.runner, block)).rejects.toThrow(/managed region/);
+    await expect(reconcileFile(fake.runner, block, undefined, true)).resolves.toBeDefined();
+  });
+});

package/src/linux/remote-file.ts

@@ -6,10 +6,13 @@
  *   the host already says what we declare; then read back and compared.
  * - read — lstat plus the SHA-256 of the file and of the part this resource owns.
  * - diff — the declared digest against the stored AND the on-disk one, plus mode and owner.
- * - replace — only when `path` changes; create-before-delete.
+ * - replace — only when `path` changes; create-before-delete. A region renamed inside one file
+ *   is an update that writes the new block, verifies it, then takes the old one out.
  * - delete — removes the file, or in region mode only the block.
  *
  * ⛔ NEVER A SECRET — see remote-file-form.ts.
+ * ⛔ THE REGION IS PART OF THE IDENTITY. Renaming it, or changing its comment token, moves the block;
+ *   swapping between owning the whole file and owning a block is refused (remote-file-plan.ts).
  * ⚠️ NOTHING IS ADOPTED WITHOUT `--adopt` (docs/ownership.md): a file already at the path, or a
  *   block already carrying the markers, reads as `Unowned`.
  * ★ IT IS A SEPARATE RESOURCE FROM `Host.File`, not a flag on it: the two have different attributes

package/src/linux/unit-handlers.ts

@@ -17,6 +17,7 @@ import { adoptsAtApply } from '../ownership/adopt.ts';
 import { noteUnfinished } from '../ownership/resume.ts';
 import type { SystemdUnitAttributes, SystemdUnitProps } from './unit-form.ts';
 import { deleteUnit, diffUnit, readUnit, reconcileUnit } from './unit-lifecycle.ts';
+import { assertRenameTarget } from './unit-preflight.ts';
 
 export const readHandler = (
   runner: HostRunner,
@@ -46,11 +47,17 @@ export const diffHandler = (
    *   when a rendered config file's digest is templated into the same deploy.
    */
   const name = resolvedString(news, 'name');
-  return Effect.succeed(
-    name !== undefined && name !== output.name
-      ? { action: 'replace' as const, deleteFirst: true }
-      : undefined,
-  );
+  if (name === undefined || name === output.name) return Effect.succeed(undefined);
+  /**
+   * ⛔ THE NAME IS ENOUGH TO REFUSE A MASKED TARGET, and the refusal has to happen here: the old
+   *   unit is removed before the new one is reconciled. The unit file cannot be compared while
+   *   `content` is still an Output, so this is the name-only half of assertReplaceable
+   *   (unit-preflight.ts).
+   */
+  return lift(async () => {
+    await assertRenameTarget(runner, output, name);
+    return { action: 'replace' as const, deleteFirst: true };
+  });
 };
 
 export const reconcileHandler = (