@homeflare/alchemy 0.27.1 → 0.27.2

package/dist/forgejo/values.d.ts

@@ -1,14 +1,18 @@
 /**
  * Wire coercions shared across Forgejo resources.
  *
- * ★ GITEA/ FORGEJO JSON USES snake_case ON THE WIRE and camelCase in props — each resource
+ * ★ GITEA/FORGEJO JSON USES snake_case ON THE WIRE and camelCase in props — each resource
  *   translates at the form boundary; these helpers only normalise values for comparison.
+ *
+ * ⛔ `text`/`bool`/`int` FROM THE HAND-ROLLED CLIENT ERA ARE GONE. They coerced values out of an
+ *   untyped `Record<string, unknown>` response. `@distilled.cloud/forgejo`'s operations decode
+ *   into typed structs (`Repository`, `Label`, `BranchProtection`, …), so an optional field is
+ *   already `string | undefined` / `boolean | undefined` — a plain `live.field ?? fallback` at
+ *   the call site replaces every one of their call sites, and a malformed response now fails the
+ *   operation's decode instead of silently coercing to a fallback.
  */
-export declare const text: (value: unknown, fallback?: string) => string;
 /** Forgejo returns label colours without `#`; declarations may include it. */
-export declare const color: (value: unknown) => string;
-export declare const bool: (value: unknown, fallback?: boolean) => boolean;
-export declare const int: (value: unknown, fallback?: number) => number;
+export declare const color: (value: string) => string;
 /** Wire arrays compared in sorted order — Gitea reshuffles nothing but callers should not depend on order. */
 export declare const stringArray: (value: unknown) => string[];
 export declare const stringRecord: (value: unknown) => Record<string, string>;

package/dist/forgejo/values.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"values.d.ts","sourceRoot":"","sources":["../../src/forgejo/values.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAO,MAAM,IAAI,UAAW,OAAO,8BACW,CAAC;AAE/C,8EAA8E;AAC9E,eAAO,MAAM,KAAK,UAAW,OAAO,WAAgD,CAAC;AAErF,eAAO,MAAM,IAAI,UAAW,OAAO,gCACgE,CAAC;AAEpG,eAAO,MAAM,GAAG,UAAW,OAAO,8BAOjC,CAAC;AAEF,8GAA8G;AAC9G,eAAO,MAAM,WAAW,UAAW,OAAO,aAGlC,CAAC;AAET,eAAO,MAAM,YAAY,UAAW,OAAO,KAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAOlE,CAAC;AAEF,eAAO,MAAM,WAAW,SAAU,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,YAKtF,CAAC;AAEF,wFAAwF;AACxF,eAAO,MAAM,gBAAgB,UAAW,OAAO;;CAI9C,CAAC;AAEF,+FAA+F;AAC/F,eAAO,MAAM,eAAe,QAAS,MAAM,QAAQ,MAAM,WACyB,CAAC;AAEnF,6FAA6F;AAC7F,eAAO,MAAM,gBAAgB,UAAW,MAAM,QAAQ,MAAM,QAAQ,MAAM,WACmB,CAAC"}
+{"version":3,"file":"values.d.ts","sourceRoot":"","sources":["../../src/forgejo/values.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,8EAA8E;AAC9E,eAAO,MAAM,KAAK,UAAW,MAAM,WAA0C,CAAC;AAE9E,8GAA8G;AAC9G,eAAO,MAAM,WAAW,UAAW,OAAO,aAGlC,CAAC;AAET,eAAO,MAAM,YAAY,UAAW,OAAO,KAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAOlE,CAAC;AAEF,eAAO,MAAM,WAAW,SAAU,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,YAKtF,CAAC;AAEF,wFAAwF;AACxF,eAAO,MAAM,gBAAgB,UAAW,OAAO;;CAI9C,CAAC;AAEF,+FAA+F;AAC/F,eAAO,MAAM,eAAe,QAAS,MAAM,QAAQ,MAAM,WACyB,CAAC;AAEnF,6FAA6F;AAC7F,eAAO,MAAM,gBAAgB,UAAW,MAAM,QAAQ,MAAM,QAAQ,MAAM,WACmB,CAAC"}

package/docs/credentials.md

@@ -13,3 +13,9 @@ like a bad credential.
 
 The Proxmox subpath mints every call's token from an OpenBao mount instead; see
 [proxmox.md](./proxmox.md).
+
+The Forgejo subpath (2026-09-23, moved onto `@distilled.cloud/forgejo`) resolves credentials
+through the package's own `CredentialsFromEnv` layer, which reads `FORGEJO_URL` / `FORGEJO_TOKEN`
+— the same two variable names the retired hand-rolled client read, still resolved on the calling
+fiber per request, never captured at module scope. `Authorization: token <value>` (Forgejo's
+access-token scheme, not `Bearer`) is built by the package's protocol layer, not by this package.

package/docs/distilled-interim.md

@@ -0,0 +1,151 @@
+# The distilled interim-package route
+
+How a `@distilled.cloud/<vendor>` SDK reaches the kit before it exists on
+npm — established by `packages/distilled-netbox` (the first one); every
+later vendor (PVE, PBS, paperless, …) follows this exactly.
+
+## Why this exists
+
+★ **Upstream Alchemy only accepts a provider that calls `@distilled.cloud/<vendor>`
+operations and `catchTag`s their typed errors** (alchemy PR 1425: "We don't
+accept providers without this"). The kit wants to dogfood and test on real
+`@distilled.cloud/*` packages now, but `alchemy-run/distilled` is upstream —
+⛔ **the kit never pushes to it.** Decision 42: build inside the kit first,
+fork `alchemy-run/distilled` and go upstream only with explicit later
+sign-off. Until a vendor's package is merged and released there, it does not
+exist on npm under `@distilled.cloud/<vendor>` — so there is nothing to
+`bun add`.
+
+★ **The fix is one alias.** `package.json` can point a dependency name at any
+tarball, including one on npm under a different name:
+
+```json
+"@distilled.cloud/netbox": "npm:@homeflare/distilled-netbox@0.1.0"
+```
+
+Everything importing `@distilled.cloud/netbox` resolves to the interim
+package's code, unmodified. When the real package ships, the alias's target
+changes and nothing else does.
+
+## The five steps
+
+### 1. Build the SDK the distilled way, in its own worktree
+
+Follow `.agents/skills/distilled-sdk/SKILL.md` in the local distilled clone —
+Steps 1–8 (never Step 9, which pushes). One worktree per vendor, branch
+`homeflare/<vendor>`, off `homeflare/base`. Spec sourcing, `patches/`,
+`convert.ts`/`generate.ts`, typecheck, `pnpm format`, `pnpm specs:check`.
+Commit in the local clone only — ⛔ **never push it anywhere; no forks, no
+PRs, no issues or comments on `alchemy-run/distilled` from this route.**
+
+### 2. Copy into a kit workspace package
+
+```sh
+mkdir -p packages/distilled-<vendor>/src
+cp -R <distilled-clone>/packages/<vendor>/src/. packages/distilled-<vendor>/src/
+```
+
+⛔ **`src/` is copied, never hand-edited in the kit.** A bug found here (the
+netbox package's own history: a doubled `/api/api/` prefix, caught by its
+`scripts/smoke.ts`, not by typecheck) is fixed in the distilled clone,
+regenerated, and copied back — never patched in place in the kit. The
+package's own README says so; keep saying so for the next vendor too.
+
+`package.json` (write by hand, once, then keep almost untouched across
+regenerations):
+
+- `"name"`: `"@homeflare/distilled-<vendor>"`
+- `"dependencies"`: `{ "@distilled.cloud/core": "1.0.0-rc.12" }` — the
+  **exact** version, a real npm dependency (`@distilled.cloud/core` is
+  already published; only the vendor package is missing). Never
+  `"workspace:*"` — this package is not part of the distilled workspace.
+- `"peerDependencies"`: `{ "effect": "4.0.0-rc.115" }` — the kit's own
+  `effect` override (root `package.json` → `overrides`), pinned literally
+  (matching `packages/alchemy`'s own peer on `effect`, not the `catalog:`
+  protocol — a peerDependency is resolved by the _consumer's_ installer, and
+  `catalog:` only expands inside this workspace).
+- `"license"`: `"Apache-2.0"`, **not** the kit's usual MIT — the content is a
+  redistribution of `alchemy-run/distilled`'s own Apache-2.0 output. Ship its
+  `LICENSE` file (copied from the distilled clone root) alongside.
+- `"scripts"`: `build` (`tsc -p tsconfig.json`), `types` (same, `--noEmit`),
+  `test` (`bun test`), `smoke` (`bun run scripts/smoke.ts`) — the four every
+  kit package answers to `bun run --filter '*' <script>`.
+
+`tsconfig.json`: **self-contained**, not `packages/config`'s
+`tsconfig.lib.json` preset. That preset requires `isolatedDeclarations`,
+which the distilled generator's own output does not satisfy (its
+`as any as S.Schema<X>` cast pattern) and was never written to satisfy —
+forcing it through a different lib preset on every copy is exactly the
+friction this route exists to avoid. Copy `packages/distilled-netbox/tsconfig.json`
+and change nothing but the package name in its comment.
+
+**Formatting/linting are excluded, on purpose.** `.oxfmtrc.json` and
+`.oxlintrc.json` both ignore `packages/distilled-*/src/**` at the repo root —
+already wired for every future vendor, not just netbox. Reformatting a
+generated SDK to house style would fight the source of truth on every
+regeneration; the hand-written files alongside it (`package.json`,
+`tsconfig.json`, `scripts/smoke.ts`, `README.md`) are NOT excluded and are
+checked normally.
+
+### 3. Prove it before shipping
+
+Two checks, both real, neither skippable:
+
+1. **`bun run --filter '@homeflare/distilled-<vendor>' types`** — typechecks
+   inside the KIT's own dependency graph (real npm `@distilled.cloud/core`,
+   not the distilled workspace's local one). A green typecheck in the
+   distilled clone does not by itself prove this; the netbox package
+   typechecked in both places, which is the point of checking both.
+2. **`scripts/smoke.ts`** — packs the tarball, installs it into a scratch
+   dir under its OWN published name (never the alias — the alias is the
+   _consumer's_ concern), and builds a real request for one operation
+   against a fake `HttpClient` (`effect/unstable/http/HttpClient.make`,
+   capturing the request instead of sending it). Assert on method, URL and
+   headers, and decode a canned response. This is what caught the `/api/api/`
+   bug — a clean typecheck did not, because the bug was in a runtime string,
+   not a type.
+
+### 4. Publish through the kit's own changesets release
+
+No special-casing: add a changeset (`bun changeset`, minor — new package),
+push, merge. `scripts/publish.ts` packs with `bun pm pack` (resolves
+`workspace:`/`catalog:` the way `npm pack` cannot) and publishes with `npm
+publish --provenance` from CI. `README.md`/`LICENSE`/`scripts/smoke.ts` ship
+in `files`; nothing about the release pipeline needs to know this package is
+an interim stand-in.
+
+### 5. Alias it in, then cut over later
+
+Once the interim package is on npm (`npm view @homeflare/distilled-<vendor>
+version` — **npm's CDN lags a few minutes after release**, so don't chase an
+empty read as a failure), the FIRST consuming PR adds the alias to whichever
+kit package needs the vendor's operations:
+
+```json
+"@distilled.cloud/<vendor>": "npm:@homeflare/distilled-<vendor>@<version>"
+```
+
+in `dependencies` (not `peerDependencies` — the kit package needs it
+resolved, not left to whoever installs the kit package). Everything in that
+PR imports `@distilled.cloud/<vendor>`, never `@homeflare/distilled-<vendor>`
+directly — ⛔ **that is what makes the eventual cutover a one-line change.**
+
+When `@distilled.cloud/<vendor>` is genuinely published upstream: replace the
+alias's target version with the real one (or drop the alias for a plain
+`"@distilled.cloud/<vendor>": "<version>"`), delete `packages/distilled-<vendor>`,
+run `bun install`. No import in the kit changes. **STATE MUST NOT MOVE** —
+this is a transport swap, not a redesign; an adopted resource's plan must
+stay a no-op across the cutover, the same invariant the distilled walk-down
+itself holds everywhere else.
+
+## What NOT to do
+
+- ⛔ Don't move existing hand-written resources (e.g. the kit's own
+  `packages/alchemy/src/netbox/*`) onto the interim package in the same PR
+  that introduces it. The alias can only resolve once the package is
+  actually published — that migration is its own PR, after `npm view`
+  confirms the version is live.
+- ⛔ Don't add the alias speculatively before the interim package is
+  published — `bun install` would fail to resolve it.
+- ⛔ Don't hand-fix a bug inside `packages/distilled-<vendor>/src/`. Fix it
+  upstream (the distilled clone), regenerate, copy again.

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.1",
+  "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),
   );