@homeflare/alchemy 0.19.0 → 0.20.0

package/docs/provider-standard.md

@@ -0,0 +1,138 @@
+# The provider standard
+
+Status: in force. Verified 2026-09-22 against `alchemy@2.0.0-beta.79` (tag
+`v2.0.0-beta.79`, commit `473c3959`) and the distilled commit that tag pins (`c2a78002`).
+
+This page is the kit-side statement of the house standard for a custom Alchemy provider.
+The full rule set is the `alchemy-provider-standard` skill in the estate's workflow plugin.
+It has 46 numbered rules (S1–S46) and 14 house differences (H1–H14), and every rule cites
+`alchemy-run/alchemy` as `<path>@v2.0.0-beta.79#<section>`. This page keeps the rule numbers
+so that a review comment can name the rule a change breaks. How each family measures up is
+in [upstream-conformance.md](./upstream-conformance.md).
+
+★ **Why this package holds itself to upstream's bar.** Everything in `@homeflare/alchemy`
+should be good enough to contribute to Alchemy. So the kit builds only what upstream lacks,
+and builds it the way upstream would. A house re-implementation of something Alchemy
+already ships is a finding, even when it works.
+
+## Three questions before any code
+
+1. **Does upstream ship the resource?** Look under `packages/alchemy/src/<Cloud>/` at the
+   pinned tag. If it does, use it. `github/` does exactly this: it composes
+   `GitHub.Repository` and `GitHub.Ruleset`. `website.ts` does it too, over
+   `Website.Astro` and `Website.Vite`. A missing prop means an upstream PR, never a fork
+   (S1).
+2. **Does `@distilled.cloud/<vendor>` exist?** If it does, every call goes through it,
+   with its typed error unions and Credentials layer. A second SDK or a hand-rolled client
+   is a finding. On 2026-09-22 npm had distilled packages for Forgejo, GitHub, Kubernetes
+   and Docker, among others, and none for Proxmox, OpenBao, Caddy, Talos, NetBox or UniFi
+   (S23).
+3. **Does Alchemy ship the helper?** Hashing (`alchemy/Util/sha256`), polling
+   (`alchemy/Util/poll`), atomic writes (`alchemy/Util/AtomicFile`), equality
+   (`deepEqual` in `alchemy/Diff`), names (`alchemy/PhysicalName`), tags (`alchemy/Tags`),
+   ownership (`alchemy/AdoptPolicy`), credentials (`alchemy/Auth`) and the test harness
+   (`alchemy/Test/Bun`) all exist. Use them.
+
+## The contract, in brief
+
+- **Shape (S2, S3).** Declare the interface as
+  `Resource<"Vendor.Service.Type", Props, Attrs, never, Providers>`, and the constructor as
+  `const X = Resource<X>(…)`. The type string starts with the vendor's own name. The
+  contract and its provider share a file, and helpers go in sibling files that `index.ts`
+  does not export.
+- **Props (S5).** Props are plain types, never `Input<T>`, and every field has JSDoc.
+- **Diff (S6).** `diff` narrows with `isResolved`. It returns `undefined` for an ordinary
+  update and `replace` only for identity changes.
+- **Read (S7, S8).** `read` works with `output: undefined`. It answers `undefined`, plain
+  attributes or `Unowned(attrs)`. This package answers `Unowned` for any live object this
+  stack cannot prove it made (H1; [ownership.md](./ownership.md)).
+- **Reconcile (S9, S10).** `reconcile` is one flow: observe, ensure, sync, return. It
+  never trusts `output` as proof, and it makes zero writes when nothing drifted.
+- **Delete (S11, S14).** `delete` is idempotent and bounded. A family whose deletion
+  breaks its consumers defaults to `retain`, and still implements `delete` in full.
+- **List (S12).** `list` enumerates every object of the type in its scope, or returns `[]`
+  with the reason written down. A family whose objects carry ownership marks filters to
+  owned ones, as upstream's third-party providers do; the core contract does not ask for it. `nuke` is declared wherever nuke must never reach the object.
+- **Scope (S15).** The account, zone and region are resolved inside each operation. They
+  are never props.
+
+## Code, errors, credentials
+
+- **Effect only (S19).** Provider code, helpers and tests use `FileSystem`, `Path`,
+  `HttpClient` and `ChildProcessSpawner`. They never use `async`/`await`, a raw `Promise`,
+  `node:fs`, `node:fs/promises`, `node:os`, `node:path` or bare `fetch`. A synchronous,
+  CPU-only Node call (`node:crypto` `createHash`, `Buffer`) goes inside `Effect.sync`, which
+  is upstream's own example. When a promise cannot be avoided, use `Effect.tryPromise`,
+  never `Effect.promise`.
+- **No defects (S20).** Lifecycle operations contain no `Effect.orDie` and no
+  `Effect.die`. A refusal is a typed error.
+- **Typed errors (S21, S22).** Handle errors with `Effect.catchTag` over the SDK's union.
+  Where the kit generates its own client from a vendor schema, the status-to-tag mapping
+  lives in that client, once, and never in a resource.
+- **Credentials (S24).** Credentials come from an `alchemy/Auth` provider and a lazy
+  Credentials service. Short-lived credentials are minted per call, never reused, and never
+  taken as props.
+- **Secrets (S25).** A secret value is never a prop or an attribute. Alchemy persists
+  `Redacted` values in plaintext, and only one state store encrypts them.
+- **Bounded waits (S26).** A retry stops after at most 8 to 10 attempts and under about a
+  minute. A poll never runs past about 90 seconds.
+
+## The Bun line for this package (S42–S45)
+
+★ This package is Bun to author and runtime-neutral to consume. It builds with
+`bun build --target node`, and consumers run `dist/` on Node.
+
+- **`src/**` provider code** (resources, providers, clients, and helpers a provider calls)
+  never calls `Bun.*` and never imports `bun:*` or the `node:*` modules S19 names. A Node
+  consumer calling an exported helper that uses `Bun.YAML` fails with
+  `ReferenceError: Bun is not defined` at the call site. `node:crypto`, `node:http` and
+  `node:child_process` all load on Node. Where they break the standard, they break the
+  Effect-only rule, not the runtime.
+- **Tests, fakes, scripts and codegen** are Bun-native. That means `bun:test` (never
+  `node:test`, never vitest), `Bun.serve` fakes on loopback, `Bun.YAML`, `Bun.file()`,
+  `Bun.Glob` and `Bun.CryptoHasher`. Upstream runs its scripts and its test runner on Bun
+  too.
+- **A module that truly needs Bun** is named for Bun, sits behind its own subpath, or
+  guards on `typeof globalThis.Bun`. The package root never reaches it.
+
+The files currently on the wrong side of the line are listed in
+[upstream-conformance.md](./upstream-conformance.md#the-bun-line).
+
+## Versions (S37–S41)
+
+- **One aligned set.** `effect`, `@distilled.cloud/*` and `@effect/platform-*` are pinned
+  exactly to what the pinned `alchemy` release was built and tested against. They move only
+  in the same PR as the `alchemy` bump.
+- **Every family records the vendor version it was walked against, in code.**
+  - For a generated client, the record is the schema manifest entry and the generated
+    header. `codegen/manifest.json` holds the product, version, sha256, fetch date and
+    source role for PVE, PBS, UniFi and NetBox.
+  - For a distilled-backed family, it is the chain: `alchemy` version, distilled package
+    version, distilled commit, spec-mirror commit and date, and Smithy service version.
+  - For a CLI or OS-service family, it is the binary or OS version, the command that
+    reports it, and the date, in that family's docs page.
+- **And in its changeset.** A provider change names the vendor version it was walked
+  against. A pin move names every link, old and new.
+
+| family              | vendor version walked against          | recorded in                       |
+| ------------------- | -------------------------------------- | --------------------------------- |
+| `proxmox` (PVE)     | pve-manager 9.2.11                     | `codegen/manifest.json` + headers |
+| `proxmox` (PBS)     | proxmox-backup-server 4.2.6-1          | `codegen/manifest.json` + headers |
+| `netbox`            | NetBox 4.7.0 OpenAPI                   | `codegen/manifest.json` + headers |
+| `cloudflare`        | distilled 1.0.0-rc.12 (API v4)         | `package.json` pins only          |
+| `openbao`           | OpenBao 2.6.2                          | source comments only ⚠️           |
+| `caddy`             | Caddy 2.11.4                           | source comments only ⚠️           |
+| `forgejo`           | Forgejo 16.0.3                         | source comments only ⚠️           |
+| `talos`             | Talos v1.13 docs (never measured live) | source comments only ⚠️           |
+| `launchd` / `linux` | macOS 27 / systemd 257                 | source comments only ⚠️           |
+
+⚠️ These rows record a version only in prose, so no test catches a drift. `schemas/manifest.json`
+also repeats the PVE, PBS and UniFi entries, which means there are two manifests for one
+fact.
+
+## Where this package differs from upstream on purpose
+
+Each difference is written down with its reason. H1 is strict `Unowned`. H2 is the
+apply-time ownership re-check in `ownership/`. H4 is `retain` by default. H5 is `adopt(true)`
+on each resource. H6 is `hf-adopt-verify`. [upstream-conformance.md](./upstream-conformance.md)
+marks each one justified or a gap. Anything not listed there is a gap by definition.

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.0",
+  "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,