@homeflare/alchemy 0.27.0 → 0.27.2

package/docs/launchd-ports.md

@@ -36,18 +36,13 @@ right before the jobs it describes), and fails the **plan** — nothing is fetch
 
 ## Why it keys on the port number alone
 
-`house/nix/homeflare-config/hosts/macmini/modules/lib-ports.nix` (a different repo —
-`homeflare/homeflare`, read at `92cff7f`, 2026-09-23) is the check this replaces for a
-kit-declared job. Its `assertNoCollision` is:
-
-```nix
-dupes = lib.subtractLists (lib.unique vals) vals;  # vals = lib.attrValues ports
-```
-
-— every port **value** in the registry, address and protocol never read. `portClaimProblems`
-reproduces that rule rather than a looser one, because that is the strictness the registry already
-enforces across the whole estate, and a kit-side check that disagreed with it would be a second,
-inconsistent source of truth.
+A stack's jobs share one estate, and a kit-side check that disagreed with the estate's existing
+port-collision convention — every port **value**, address and protocol never read — would be a
+second, looser source of truth rather than a replacement for the stricter one. So
+`portClaimProblems` reproduces that same strictness deliberately, keyed on the port number alone,
+rather than inventing a narrower rule of its own. (A host still on Nix keeps that convention
+enforced by its own port registry until the job migrates — see "What it cannot see" below; this
+doc states the kit's rule on its own terms and does not depend on that registry's file.)
 
 ### The measured bind table
 
@@ -88,15 +83,17 @@ refuses that pairing anyway — the port number is the key, exactly like the reg
 - **A job the stack does not pass.** `claimPorts` takes exactly the array a stack builds and
   hands it; there is no argv-parsing, no config-file reading and no host inspection here to
   recover a port a stack forgot to include. Leaving a job's claim out of the list is invisible to
-  this check, the same way a port left out of `lib-ports.nix` was invisible on 2026-09-02.
+  this check, the same way a port left out of a host's own Nix-based port registry was invisible
+  on 2026-09-02.
 - **A daemon still on Nix**, unless the migrating stack also passes that daemon's port as a claim
   of its own (owner naming the Nix job, so the message is legible during a cutover). Until a job
-  moves off Nix, `lib-ports.nix` is still the thing keeping it collision-free; `claimPorts` only
-  starts covering a port once a kit stack declares the job that binds it.
+  moves off Nix, that host's Nix-based port registry is still the thing keeping it
+  collision-free; `claimPorts` only starts covering a port once a kit stack declares the job that
+  binds it.
 - **Two protocols of the same port number.** Keying on the port alone means a daemon on `tcp/9094`
   and another on `udp/9094` would be refused as a collision, same as the Nix registry. No mini job
-  does that today (checked against the registry at `92cff7f`); if one needs to, the key widens
-  deliberately, in its own change — not silently here.
+  does that today; if one needs to, the key widens deliberately, in its own change — not silently
+  here.
 
 ## The error is a defect, not a typed channel
 

package/docs/peers.md

@@ -6,8 +6,9 @@ The install line for `@homeflare/alchemy`, and why every peer on it and every en
 
 ```sh
 bun add @homeflare/alchemy alchemy@2.0.0-beta.79 effect@4.0.0-rc.115 \
-        @effect/platform-node@4.0.0-rc.115 cloudflare@4.5.0 mime@4.1.0 \
-        @distilled.cloud/cloudflare@1.0.0-rc.12 @effect/sql-pg@4.0.0-rc.115
+        @effect/platform-node@4.0.0-rc.115 mime@4.1.0 \
+        @distilled.cloud/cloudflare@1.0.0-rc.12 @distilled.cloud/forgejo@1.0.0-rc.12 \
+        @effect/sql-pg@4.0.0-rc.115
 ```
 
 🔴 **Why, measured 2026-09-16 on 0.1.0 and re-checked 2026-09-17 against Alchemy 78.**
@@ -33,10 +34,18 @@ import the Proxmox subpath.
 declaring it (measured 2026-09-17). 79 declares it; the peer stays so a consumer
 that followed the 78 README does not drop a required line.
 
-⚠️ So is `cloudflare`. It was marked optional in 0.1.1, which claimed the `/cloudflare`
-subpath would degrade without it — measured 2026-09-16, the subpath does not load at all:
-`Cannot find package 'cloudflare'`. An optional peer should mean a feature is absent, not
-that an import fails.
+★ `cloudflare` **is gone, not merely tolerated.** It was a required peer (marked optional in
+0.1.1, which claimed the `/cloudflare` subpath would degrade without it — measured 2026-09-16,
+the subpath did not load at all: `Cannot find package 'cloudflare'`) until 2026-09-23, when
+`R2BucketLock` moved off the `cloudflare` npm SDK onto `@distilled.cloud/cloudflare/r2`, the same
+one `MeshNode` already called. Nothing else in this package imported it, so the peer — and the
+`client.ts` wrapper it existed for — were dropped rather than left declared and unused.
+
+⚠️ **`@distilled.cloud/forgejo` (added 2026-09-23, moving `/forgejo` off a hand-rolled
+`HttpClient` client) is required for the same reason `@distilled.cloud/cloudflare` is: it is
+a plain dependency of this package, not something a hoisting installer can hide from a strict
+one.** Pinned to `1.0.0-rc.12` — the distilled release's own lockstep version, not alchemy's,
+since alchemy does not bundle a Forgejo SDK the way it bundles Cloudflare's.
 
 ⚠️ **`@effect/sql-pg` (added for `/postgres`, 2026-09-23) is required too, for the same
 reason, not because every subpath imports it.** This package has one flat peer set for the

package/docs/upstream-conformance.md

@@ -11,30 +11,54 @@ A decision marked **maintainer** is not an agent's to make.
 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
+1. **`cloudflare/R2BucketLock` diverges on three rules.**
+
+   ✅ **S23 fixed 2026-09-23** (branch `claude2/distilled-r2-bucket-lock`, an agent task
+   scoped to exactly this SDK swap): it now calls `@distilled.cloud/cloudflare/r2`'s
+   `getBucketLock`/`putBucketLock`, the same package `MeshNode` uses, with
+   `catchTag('NoSuchBucket', …)` in place of the old `instanceof NotFoundError` status
+   check. The `cloudflare` peer and `client.ts` are gone from the package — nothing else
+   imported either. As a side effect this also cleared the `Effect.promise` calls in
+   `reconcileLock`/`deleteLock` (S19): distilled's operations are already Effects, so there
+   is nothing left to promise-wrap.
+
+   Still open, and out of scope for that task (props/attributes were required to stay
+   byte-identical, so neither touches the wire contract):
+   - `readLock`, and now `reconcileLock`/`deleteLock` too, end in `Effect.orDie` for the
+     error channel distilled leaves after `NoSuchBucket` (S20). A full fix means a typed
+     refusal error for `InvalidRoute`/`CloudflareRateLimited`/`CloudflareError`, which is a
+     separate, larger change than the transport swap.
+   - `reconcileLock` still skips the PUT whenever `output.rules` equals the declaration,
+     without reading the live lock (S10). Neither `--force` nor `drift --repair` can
+     restore lock rules removed out of band. ⚠️ Reasoned from the source, not measured live.
+   - `accountId` is still a prop (S15).
+
+   Upstream `Cloudflare.R2.Bucket` has lifecycle and CORS rules but no lock, so this is
+   still a real gap. **Remaining fix:** observe before the PUT, and resolve the account
+   from `CloudflareEnvironment` — the same shape change `MeshNode` uses instead of a prop.
+   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.
+2. **`forgejo/*` duplicates an upstream building block.**
+   - ✅ **S23 fixed 2026-09-23** (branch `claude2/distilled-forgejo`, PR #180 — Tim, decision
+     42, "build inside the kit first, dogfood and test"; an agent task scoped to exactly this
+     SDK swap). Every call now goes through
+     `@distilled.cloud/forgejo@1.0.0-rc.12`'s typed operations, `catchTag('NotFound', ...)`
+     replaced the status-carrying `ForgejoError`, and `client.ts` is deleted. Verified
+     operation by operation against the package before relying on it (every operation this
+     family calls exists, every error it handles has a tag) — nothing was missing, so no
+     distilled patch was needed. State did not move: every prop and attribute stays
+     byte-identical, proven by keeping the family's existing tests unchanged plus new tests
+     against a fake Forgejo exercising the real distilled protocol. No stack in this estate
+     currently imports `@homeflare/alchemy/forgejo` (measured 2026-09-23 across
+     homeflare-landscape and the house monorepo), so there is no live plan to re-run —
+     `house/forgejo` in the house monorepo declares the same seven resource types but against
+     its OWN independent hand-rolled copy under `house/forgejo/src/`, not this package; this
+     PR does not touch it.
+   - ⛔ **`read` still never answers `Unowned` (H1), open.** Credentials still come from
+     `FORGEJO_TOKEN` at call time rather than an `alchemy/Auth` provider (S24). Both need a
+     maintainer decision on the ownership-check shape before a distilled-backed
+     implementation is worth writing — the client swap did not attempt either.
 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homeflare/alchemy",
-  "version": "0.27.0",
+  "version": "0.27.2",
   "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",
@@ -95,10 +95,10 @@
   },
   "peerDependencies": {
     "@distilled.cloud/cloudflare": "1.0.0-rc.12",
+    "@distilled.cloud/forgejo": "1.0.0-rc.12",
     "@effect/platform-node": "4.0.0-rc.115",
     "@effect/sql-pg": "4.0.0-rc.115",
     "alchemy": "2.0.0-beta.79",
-    "cloudflare": ">=4.5.0",
     "effect": "4.0.0-rc.115",
     "mime": "4.1.0"
   }

package/src/cloudflare/fake-r2-lock.ts

@@ -0,0 +1,120 @@
+/**
+ * A fake Cloudflare R2 bucket-lock API for r2-bucket-lock.test.ts — an in-memory `fetch` handed to
+ * Effect's real FetchHttpClient through its `Fetch` reference, so the tests exercise distilled's
+ * real path assembly, header encoding, envelope decoding and error matching. Same idiom as
+ * fake-mesh.ts, for the route `GET`/`PUT /accounts/<FAKE_ACCOUNT>/r2/buckets/<name>/lock`.
+ *
+ * ⛔ TEST-ONLY, AND NO NETWORK. No provider imports this file. The base URL is RFC 2606
+ *   `api.example.com`, and any request outside that route throws, so a mis-wired test fails
+ *   instead of reaching a real API.
+ * ★ `existingBuckets` MODELS THE VENDOR'S OWN DISTINCTION. A bucket not in the set answers
+ *   `NoSuchBucket` (code 10006) on both verbs, matching the 404 the doc comment in
+ *   r2-bucket-lock.ts measured. A bucket in the set with no rules answers `{}` on GET, matching
+ *   "never locked" — both collapse to "absent" in `readLock`, but the fake keeps them distinct so
+ *   a test can put a bucket in either state on purpose.
+ * ★ `onRoute` OVERRIDES ONE REQUEST. A test uses it to answer a request with an arbitrary
+ *   `Response` — a non-404 status carrying code 10006 (proves matching is by code, not status), or
+ *   a different tagged error entirely (`InvalidRoute`, code 7003) to prove it does NOT fall into
+ *   `readLock`'s `NoSuchBucket` catch.
+ */
+import { type Credentials, fromApiToken } from '@distilled.cloud/cloudflare/Credentials';
+import * as Layer from 'effect/Layer';
+import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
+import type { R2LockRule } from './lock-rules.ts';
+
+export const FAKE_BASE = 'https://api.example.com/client/v4';
+export const FAKE_ACCOUNT = '00000000000000000000000000000002';
+/** ⚠️ A placeholder, not a credential. */
+export const FAKE_API_TOKEN = 'placeholder-api-token';
+
+export type Seen = {
+  readonly method: string;
+  readonly path: string;
+  readonly headers: Record<string, string>;
+  readonly body: unknown;
+};
+
+const ok = (result: unknown) => Response.json({ success: true, errors: [], messages: [], result });
+
+export const fakeFailure = (status: number, code: number, message: string) =>
+  Response.json(
+    { success: false, errors: [{ code, message }], messages: [], result: null },
+    { status },
+  );
+
+/** The response `NoSuchBucket` matches: code 10006, conventionally at 404. */
+export const noSuchBucket = (status = 404) =>
+  fakeFailure(status, 10006, 'The specified bucket does not exist.');
+
+export type FakeOptions = {
+  /** Buckets the account has. Any other name is `NoSuchBucket` on both GET and PUT. */
+  readonly existingBuckets?: readonly string[];
+  /** Override one request's response. `undefined` falls through to the default route. */
+  readonly onRoute?: (method: string, bucketName: string) => Response | undefined;
+};
+
+export const fakeR2Lock = (options: FakeOptions = {}) => {
+  const existing = new Set(options.existingBuckets ?? []);
+  const locks = new Map<string, readonly R2LockRule[]>();
+  const seen: Seen[] = [];
+
+  const route = (method: string, url: URL, body: Record<string, unknown>): Response => {
+    const prefix = `/client/v4/accounts/${FAKE_ACCOUNT}/r2/buckets/`;
+    if (url.host !== 'api.example.com' || !url.pathname.startsWith(prefix)) {
+      throw new Error(`fake-r2-lock: unexpected request ${method} ${url.href}`);
+    }
+    const rest = url.pathname.slice(prefix.length).split('/');
+    const bucketName = rest[0];
+    if (bucketName === undefined || rest[1] !== 'lock' || rest.length !== 2) {
+      throw new Error(`fake-r2-lock: unexpected path ${url.pathname}`);
+    }
+    const override = options.onRoute?.(method, bucketName);
+    if (override !== undefined) return override;
+    if (!existing.has(bucketName)) return noSuchBucket();
+    if (method === 'GET') return ok({ rules: locks.get(bucketName) ?? [] });
+    if (method === 'PUT') {
+      const rules = (body['rules'] as readonly R2LockRule[] | undefined) ?? [];
+      if (rules.length === 0) locks.delete(bucketName);
+      else locks.set(bucketName, rules);
+      return ok({});
+    }
+    throw new Error(`fake-r2-lock: unexpected ${method} ${url.pathname}`);
+  };
+
+  const fetch = (async (input: string | URL | Request, init?: RequestInit) => {
+    const request =
+      input instanceof Request ? new Request(input, init) : new Request(String(input), init);
+    const url = new URL(request.url);
+    const text = await request.text();
+    const body = text.length === 0 ? {} : (JSON.parse(text) as Record<string, unknown>);
+    seen.push({
+      method: request.method,
+      path: `${url.pathname}${url.search}`,
+      headers: Object.fromEntries(request.headers.entries()),
+      body,
+    });
+    return route(request.method, url, body);
+  }) as typeof globalThis.fetch;
+
+  return { existing, fetch, locks, seen };
+};
+
+export type FakeR2Lock = ReturnType<typeof fakeR2Lock>;
+
+/** distilled Credentials + the real FetchHttpClient over the fake — `CloudflareOpContext`. */
+export const fakeR2LockLayer = (
+  fake: FakeR2Lock,
+  credentials: Layer.Layer<Credentials> = fromApiToken({
+    apiToken: FAKE_API_TOKEN,
+    apiBaseUrl: FAKE_BASE,
+  }),
+) =>
+  Layer.mergeAll(
+    credentials,
+    FetchHttpClient.layer,
+    Layer.succeed(FetchHttpClient.Fetch, fake.fetch),
+  );
+
+/** The writes the fake saw, in order: `['PUT', 'GET', …]`. */
+export const writes = (fake: FakeR2Lock) =>
+  fake.seen.filter((s) => s.method !== 'GET').map((s) => s.method);

package/src/cloudflare/index.ts

@@ -1,11 +1,10 @@
 /**
  * Cloudflare providers for Alchemy — the gaps the vendor SDK leaves.
  *
- * ★ Built on vendor SDKs, not hand-rolled HTTP. `R2BucketLock` uses the official `cloudflare`
- *   SDK, which already has `r2.buckets.locks.update/get` over the documented endpoints.
- *   `MeshNode` uses `@distilled.cloud/cloudflare`, the SDK Alchemy's own Cloudflare providers
- *   use, because `cloudflare@4.5.0` cannot create an HA node (mesh-node-api.ts). Either way
- *   there is no path string this package invents.
+ * ★ Built on vendor SDKs, not hand-rolled HTTP. Both `R2BucketLock` and `MeshNode` call
+ *   `@distilled.cloud/cloudflare`, the SDK Alchemy's own Cloudflare providers use — R2BucketLock
+ *   over `/r2` (`getBucketLock`/`putBucketLock`), MeshNode over `/zero-trust`, because
+ *   `cloudflare@4.5.0` cannot create an HA node (mesh-node-api.ts). Neither invents a path string.
  */
 export type { R2LockRule } from './lock-rules.ts';
 export { R2BucketLock, type R2BucketLockProps } from './r2-bucket-lock.ts';

package/src/cloudflare/mesh-node-api.ts

@@ -6,8 +6,9 @@
  *   `GET …/warp_connector/{id}/token` (developers.cloudflare.com/mesh/get-started, read
  *   2026-09-21). There is no separate "mesh node" endpoint.
  *
- * ★ OVER `@distilled.cloud/cloudflare`, THE SDK ALCHEMY'S OWN CLOUDFLARE PROVIDERS USE, not the
- *   `cloudflare` npm SDK the R2 lock uses. Measured 2026-09-21: `cloudflare@4.5.0`'s
+ * ★ OVER `@distilled.cloud/cloudflare`, THE SDK ALCHEMY'S OWN CLOUDFLARE PROVIDERS USE — and, as
+ *   of 2026-09-23, the same one `R2BucketLock` calls too (r2-bucket-lock.ts), not the `cloudflare`
+ *   npm SDK either used before that. Measured 2026-09-21: `cloudflare@4.5.0`'s
  *   `WARPConnectorCreateParams` has only `account_id` and `name`, so it cannot create an HA node.
  *   distilled `1.0.0-rc.12` (the version alchemy@2.0.0-beta.79 pins) has `ha?: boolean` on
  *   `CreateTunnelWarpConnectorRequest`, typed errors (`TunnelNotFound` code 1002 / 404,

package/src/cloudflare/providers.ts

@@ -1,41 +1,38 @@
 /**
  * The HomeFlare Cloudflare provider collection, in the shape `LiteLLM.providers()` has.
  *
- * ★ ONE LAYER, BUILT ONCE, so the single `Config.Redacted('CLOUDFLARE_API_TOKEN')` read is shared
- *   by every resource in the stack rather than repeated per resource.
- *
  * ⚠️ THIS IS NOT `alchemy/Cloudflare`'s COLLECTION AND DOES NOT REPLACE IT. A stack that declares
  *   both a `Cloudflare.R2.Bucket` and this lock merges the two:
  *   `Layer.mergeAll(Cloudflare.providers(), HomeflareCloudflare.providers())` — the shape
  *   a consuming stack names for one talking to more than one account.
  *
- * ★ TWO CREDENTIAL PATHS, ONE PER SDK. `R2BucketLock` uses the `cloudflare` SDK through
- *   `CloudflareApiLive` (`CLOUDFLARE_API_TOKEN`, fail-closed). `MeshNode` uses Alchemy's own SDK
- *   and resolves credentials and the account through `Cloudflare.CloudflareApiLive()` — the same
- *   source `Cloudflare.providers()` uses (an Alchemy profile, or `CLOUDFLARE_API_TOKEN` +
- *   `CLOUDFLARE_ACCOUNT_ID` in CI), so a node lands in the account its Gateway rules do.
- * ⚠️ That second layer is built again here even when the stack also merges
- *   `Cloudflare.providers()`. `Layer.provide`, not `provideMerge`: it feeds MeshNode only and adds
- *   nothing to the stack's context.
+ * ★ ONE CREDENTIAL PATH NOW, NOT TWO. Until 2026-09-23 `R2BucketLock` ran over the `cloudflare`
+ *   npm SDK with its own `CLOUDFLARE_API_TOKEN` read (`client.ts`, since deleted) while `MeshNode`
+ *   ran over `@distilled.cloud/cloudflare` through `Cloudflare.CloudflareApiLive()`. Both
+ *   providers now call distilled, so both resolve credentials and the account the same way
+ *   `Cloudflare.providers()` does (an Alchemy profile, or `CLOUDFLARE_API_TOKEN` +
+ *   `CLOUDFLARE_ACCOUNT_ID` in CI) — a lock and the Gateway rules that reference the same bucket
+ *   land in the same account.
+ * ⚠️ THE LAYER IS BUILT TWICE ON PURPOSE, once per provider, even when the stack also merges
+ *   `Cloudflare.providers()`. `Layer.provide`, not `provideMerge`: each feeds its own provider
+ *   only and adds nothing to the stack's context.
  */
 import * as Cloudflare from 'alchemy/Cloudflare';
 import * as Provider from 'alchemy/Provider';
 import * as Layer from 'effect/Layer';
-import { CloudflareApiLive } from './client.ts';
 import { MeshNode, MeshNodeProvider } from './mesh-node.ts';
 import { R2BucketLock, R2BucketLockProvider } from './r2-bucket-lock.ts';
 
 export class Providers extends Provider.ProviderCollection<Providers>()('HomeflareCloudflare') {}
 
+// ⛔ `orDie` ON BOTH, as `Cloudflare.providers()` ends with: a stack's providers layer must not
+//   fail, and a profile that cannot resolve is a defect carrying Alchemy's own sentence.
 export const providers = () =>
   Layer.effect(Providers, Provider.collection([R2BucketLock, MeshNode])).pipe(
     Layer.provide(
       Layer.mergeAll(
-        R2BucketLockProvider(),
-        // ⛔ `orDie`, as `Cloudflare.providers()` ends with: a stack's providers layer must not
-        //   fail, and a profile that cannot resolve is a defect carrying Alchemy's own sentence.
+        R2BucketLockProvider().pipe(Layer.provide(Cloudflare.CloudflareApiLive()), Layer.orDie),
         MeshNodeProvider().pipe(Layer.provide(Cloudflare.CloudflareApiLive()), Layer.orDie),
       ),
     ),
-    Layer.provideMerge(CloudflareApiLive),
   );

package/src/cloudflare/r2-bucket-lock.test.ts

@@ -0,0 +1,139 @@
+/**
+ * `readLock` / `reconcileLock` / `deleteLock` against the fake Cloudflare in fake-r2-lock.ts, the
+ * same direct style mesh-node-token.test.ts uses for `fetchMeshNodeToken`: run the plain Effect
+ * under `fakeR2LockLayer`, no Provider or engine harness needed.
+ *
+ * ★ THE POINT OF THIS FILE IS THE TAGGED-ERROR PATHS, per the transport swap onto
+ *   `@distilled.cloud/cloudflare/r2`: `NoSuchBucket` is matched by Cloudflare's own error code
+ *   (10006), never by HTTP status, and only `readLock` treats it as "nothing to adopt" —
+ *   `reconcileLock`/`deleteLock` let it die like any other tagged error.
+ */
+import type { CloudflareOpContext } from '@distilled.cloud/cloudflare/r2';
+import { Unowned } from 'alchemy/AdoptPolicy';
+import { describe, expect, test } from 'bun:test';
+import * as Cause from 'effect/Cause';
+import * as Effect from 'effect/Effect';
+import * as Exit from 'effect/Exit';
+import {
+  FAKE_ACCOUNT,
+  type FakeR2Lock,
+  fakeFailure,
+  fakeR2Lock,
+  fakeR2LockLayer,
+  writes,
+} from './fake-r2-lock.ts';
+import type { R2LockRule } from './lock-rules.ts';
+import { type R2BucketLockProps, deleteLock, readLock, reconcileLock } from './r2-bucket-lock.ts';
+
+const run = <A, E>(fake: FakeR2Lock, effect: Effect.Effect<A, E, CloudflareOpContext>) =>
+  Effect.runPromise(effect.pipe(Effect.provide(fakeR2LockLayer(fake))));
+
+const dies = <A, E>(fake: FakeR2Lock, effect: Effect.Effect<A, E, CloudflareOpContext>) =>
+  Effect.runPromiseExit(effect.pipe(Effect.provide(fakeR2LockLayer(fake))));
+
+const rule: R2LockRule = {
+  id: 'keep-30d',
+  enabled: true,
+  condition: { type: 'Age', maxAgeSeconds: 2_592_000 },
+};
+
+const props = (over: Partial<R2BucketLockProps> = {}): R2BucketLockProps => ({
+  accountId: FAKE_ACCOUNT,
+  bucketName: 'my-backups',
+  rules: [rule],
+  ...over,
+});
+
+describe('readLock', () => {
+  test('a bucket that does not exist (NoSuchBucket, code 10006) reads as absent', async () => {
+    const fake = fakeR2Lock();
+    expect(await run(fake, readLock(props(), false))).toBeUndefined();
+  });
+
+  test('a bucket that exists but was never locked reads as absent', async () => {
+    const fake = fakeR2Lock({ existingBuckets: ['my-backups'] });
+    expect(await run(fake, readLock(props(), false))).toBeUndefined();
+  });
+
+  test('a locked bucket, written by this stack, reads as plain attributes', async () => {
+    const fake = fakeR2Lock({ existingBuckets: ['my-backups'] });
+    await run(fake, reconcileLock(props(), undefined));
+    const attrs = await run(fake, readLock(props(), true));
+    expect(Unowned.is(attrs)).toBe(false);
+    expect(attrs).toEqual({ bucketName: 'my-backups', jurisdiction: 'default', rules: [rule] });
+  });
+
+  test('a locked bucket, not yet written by this stack, reads Unowned', async () => {
+    const fake = fakeR2Lock({ existingBuckets: ['my-backups'] });
+    await run(fake, reconcileLock(props(), undefined));
+    const attrs = await run(fake, readLock(props(), false));
+    expect(Unowned.is(attrs)).toBe(true);
+  });
+
+  test('NoSuchBucket is matched by code, not by HTTP status', async () => {
+    // ⛔ THE PROOF THAT THIS IS catchTag, NOT A STATUS CHECK: code 10006 at a non-404 status is
+    //   still caught. The old `cloudflare` SDK's `instanceof NotFoundError` could only ever match
+    //   a 404; distilled's error matcher does not look at status at all for this tag.
+    const fake = fakeR2Lock({
+      onRoute: () => fakeFailure(400, 10006, 'The specified bucket does not exist.'),
+    });
+    expect(await run(fake, readLock(props(), false))).toBeUndefined();
+  });
+
+  test('a different tagged error at 404 is NOT swallowed as NoSuchBucket', async () => {
+    // ⛔ code 7003 is `InvalidRoute`, not `NoSuchBucket` — even at the same 404 status a plain
+    //   status check would have treated as "no bucket". `catchTag('NoSuchBucket', …)` leaves it
+    //   alone, and `Effect.orDie` turns it into a defect.
+    const fake = fakeR2Lock({ onRoute: () => fakeFailure(404, 7003, 'Invalid route') });
+    const exit = await dies(fake, readLock(props(), false));
+    expect(Exit.isFailure(exit)).toBe(true);
+    expect(Exit.isFailure(exit) && Cause.hasDies(exit.cause)).toBe(true);
+  });
+});
+
+describe('reconcileLock', () => {
+  test('writes nothing when the declared rules already match', async () => {
+    const fake = fakeR2Lock({ existingBuckets: ['my-backups'] });
+    const output = await run(fake, reconcileLock(props(), undefined));
+    fake.seen.length = 0;
+    const again = await run(fake, reconcileLock(props(), output));
+    expect(again).toEqual(output);
+    expect(writes(fake)).toEqual([]);
+  });
+
+  test('PUTs the whole rule set when it differs from output', async () => {
+    const fake = fakeR2Lock({ existingBuckets: ['my-backups'] });
+    await run(fake, reconcileLock(props(), undefined));
+    expect(writes(fake)).toEqual(['PUT']);
+    expect(fake.locks.get('my-backups')).toEqual([rule]);
+  });
+
+  test('NoSuchBucket is NOT caught here: a genuinely missing bucket dies', async () => {
+    const fake = fakeR2Lock();
+    const exit = await dies(fake, reconcileLock(props(), undefined));
+    expect(Exit.isFailure(exit)).toBe(true);
+    expect(Exit.isFailure(exit) && Cause.hasDies(exit.cause)).toBe(true);
+  });
+});
+
+describe('deleteLock', () => {
+  test('PUTs an empty rule set, unlocking the bucket', async () => {
+    const fake = fakeR2Lock({ existingBuckets: ['my-backups'] });
+    const output = await run(fake, reconcileLock(props(), undefined));
+    fake.seen.length = 0;
+    await run(fake, deleteLock(output, FAKE_ACCOUNT));
+    expect(writes(fake)).toEqual(['PUT']);
+    expect(fake.locks.has('my-backups')).toBe(false);
+  });
+
+  test('NoSuchBucket is NOT caught here either: a genuinely missing bucket dies', async () => {
+    const fake = fakeR2Lock();
+    const output = await run(
+      fakeR2Lock({ existingBuckets: ['my-backups'] }),
+      reconcileLock(props(), undefined),
+    );
+    const exit = await dies(fake, deleteLock(output, FAKE_ACCOUNT));
+    expect(Exit.isFailure(exit)).toBe(true);
+    expect(Exit.isFailure(exit) && Cause.hasDies(exit.cause)).toBe(true);
+  });
+});