@homeflare/alchemy 0.27.4 → 0.29.0

package/src/caddy/config.ts

@@ -1,6 +1,6 @@
 /**
  * `Caddy.Config` — a running Caddy's whole config, declared as Caddyfile text and applied through
- * Caddy's own admin API (decision 23).
+ * Caddy's own admin API (decision 23), via `@distilled.cloud/caddy`'s typed `admin` operations.
  *
  * - create / update — `POST /adapt` (validate), `POST /load` with `text/caddyfile` (a graceful
  *   reload; Caddy keeps the old config if it refuses the new one, and the error names why), then
@@ -20,18 +20,21 @@
  *   the deploy runs with `--adopt`. A Caddy serving nothing reads as absent: a create. Where the
  *   engine skips that probe, reconcile refuses the same takeover (config-lifecycle.ts).
  * ⛔ `caddyfile` IS NEVER A SECRET — see config-form.ts; refused before anything is sent.
- * ⚠️ WHICH CADDY is the transport's (providers.ts), not a prop: one CaddyAdmin per stack.
+ * ⚠️ WHICH CADDY is the transport's (providers.ts): `CaddyAdminService` plus the `Credentials`/
+ *   `HttpClient` layers `caddyAdminLayer` merges — one per stack, not a prop.
  */
 import { Resource } from 'alchemy';
 import { Unowned } from 'alchemy/AdoptPolicy';
 import { isResolved } from 'alchemy/Diff';
 import * as Provider from 'alchemy/Provider';
 import * as Effect from 'effect/Effect';
-import { lift, resolvedString } from '../launchd/host-effect.ts';
+import { resolvedString } from '../launchd/host-effect.ts';
 import { adoptEnabled } from '../ownership/adopt.ts';
-import { CaddyAdminService, CaddyUnreachableError } from './admin.ts';
+import { CaddyAdminService } from './admin.ts';
+import { isUnreachable } from './caddy-http-client.ts';
 import type { CaddyConfigAttributes, CaddyConfigProps } from './config-form.ts';
-import { diffConfig, probeLive, readLive, reconcileConfig } from './config-lifecycle.ts';
+import { probeLive, readLive } from './config-lifecycle.ts';
+import { diffConfig, reconcileConfig } from './config-reconcile.ts';
 
 export type { CaddyConfigAttributes, CaddyConfigProps } from './config-form.ts';
 
@@ -45,9 +48,6 @@ export const CaddyConfig = Resource<CaddyConfig>('Caddy.Config', {
   defaultRemovalPolicy: 'retain',
 });
 
-const unreachable = (error: Error): error is CaddyUnreachableError =>
-  error instanceof CaddyUnreachableError;
-
 /**
  * ⚠️ A STOPPED CADDY MUST NOT FAIL THE PLAN THAT BRINGS IT BACK. Its launchd job usually sits in the
  *   same stack; if every plan died on `ECONNREFUSED`, the fix to that job could never be deployed.
@@ -56,10 +56,11 @@ const unreachable = (error: Error): error is CaddyUnreachableError =>
  */
 const planWithoutCaddy =
   <A>(admin: { endpoint: string }, fallback: A) =>
-  (error: Error) =>
+  (error: unknown) =>
     Effect.as(
       Effect.logWarning(
-        `Caddy.Config: no Caddy at ${admin.endpoint} (${error.message}); planning without it — ` +
+        `Caddy.Config: no Caddy at ${admin.endpoint} ` +
+          `(${error instanceof Error ? error.message : String(error)}); planning without it — ` +
           'the Caddyfile is validated when the deploy reaches Caddy',
       ),
       fallback,
@@ -72,23 +73,20 @@ export const CaddyConfigProvider = () =>
       const admin = yield* CaddyAdminService;
       /** The probe, branded for the engine: plain when ours, `Unowned` otherwise. */
       const probe = (caddyfile: string | undefined, sourceFile: string | undefined) =>
-        Effect.flatMap(
-          lift(() => probeLive(admin, caddyfile, sourceFile)),
-          (found) => {
-            if (found === undefined) return Effect.succeed(undefined);
-            if (found.ours) return Effect.succeed(found.attributes);
-            const unowned = Unowned(found.attributes);
-            return found.unchecked === undefined
-              ? Effect.succeed(unowned)
-              : Effect.as(
-                  Effect.logWarning(
-                    `Caddy.Config at ${admin.endpoint}: the running config could not be compared ` +
-                      `with the declared Caddyfile (${found.unchecked}), so it is not treated as ours`,
-                  ),
-                  unowned,
-                );
-          },
-        );
+        Effect.flatMap(probeLive(caddyfile, sourceFile), (found) => {
+          if (found === undefined) return Effect.succeed(undefined);
+          if (found.ours) return Effect.succeed(found.attributes);
+          const unowned = Unowned(found.attributes);
+          return found.unchecked === undefined
+            ? Effect.succeed(unowned)
+            : Effect.as(
+                Effect.logWarning(
+                  `Caddy.Config at ${admin.endpoint}: the running config could not be compared ` +
+                    `with the declared Caddyfile (${found.unchecked}), so it is not treated as ours`,
+                ),
+                unowned,
+              );
+        });
       return CaddyConfig.Provider.of({
         /** ⛔ A Caddy has one config; there is nothing to enumerate, and nothing for nuke to delete. */
         list: () => Effect.succeed([]),
@@ -100,21 +98,20 @@ export const CaddyConfigProvider = () =>
          * loopback), but WHOSE CONFIG it runs is not: a person, another tool or another stack.
          */
         read: ({ olds, output }) =>
-          (output === undefined
-            ? probe(resolvedString(olds, 'caddyfile'), resolvedString(olds, 'sourceFile'))
-            : lift(() => readLive(admin, resolvedString(olds, 'sourceFile')))
-          ).pipe(
+          Effect.gen(function* () {
+            return output === undefined
+              ? yield* probe(resolvedString(olds, 'caddyfile'), resolvedString(olds, 'sourceFile'))
+              : yield* readLive(resolvedString(olds, 'sourceFile'));
+          }).pipe(
             // ★ Nothing to adopt from a Caddy that is down: plan a create, which is the same load.
-            Effect.catchIf(unreachable, planWithoutCaddy(admin, undefined)),
+            Effect.catchIf(isUnreachable, planWithoutCaddy(admin, undefined)),
           ),
 
         diff: ({ news, output }) => {
           if (output === undefined) return Effect.succeed(undefined);
           const update = planWithoutCaddy(admin, { action: 'update' as const });
           if (isResolved(news)) {
-            return lift(() => diffConfig(admin, news, output)).pipe(
-              Effect.catchIf(unreachable, update),
-            );
+            return diffConfig(news, output).pipe(Effect.catchIf(isUnreachable, update));
           }
           /**
            * ⚠️ `sourceFile` is an Output while its HostFile changes in the same deploy
@@ -124,10 +121,9 @@ export const CaddyConfigProvider = () =>
            */
           const caddyfile = resolvedString(news, 'caddyfile');
           if (caddyfile === undefined) return Effect.succeed(undefined);
-          return lift(async () => {
-            await diffConfig(admin, { caddyfile }, output);
-            return { action: 'update' as const };
-          }).pipe(Effect.catchIf(unreachable, update));
+          return Effect.as(diffConfig({ caddyfile }, output), { action: 'update' as const }).pipe(
+            Effect.catchIf(isUnreachable, update),
+          );
         },
 
         reconcile: ({ fqn, news, output }) =>
@@ -139,9 +135,7 @@ export const CaddyConfigProvider = () =>
             const sameCaddy = output !== undefined && output.endpoint === admin.endpoint;
             const takeOver = sameCaddy || (yield* adoptEnabled(fqn));
             const stored = output === undefined ? {} : { stored: output.configSha256 };
-            const applied = yield* lift(() =>
-              reconcileConfig(admin, news, { takeOver, ...stored }),
-            );
+            const applied = yield* reconcileConfig(news, { takeOver, ...stored });
             for (const warning of applied.warnings) {
               yield* Effect.logWarning(`Caddy.Config at ${admin.endpoint}: ${warning}`);
             }

package/src/caddy/fake-caddy.ts

@@ -17,7 +17,9 @@
  * ★ `listenPort` is the port Caddy BELIEVES it listens on — its Host check uses it — while the
  *   fake really listens on an ephemeral one: a Caddy on its default :2019 behind a forward.
  */
-import type { CaddyAdmin } from './admin.ts';
+import * as Effect from 'effect/Effect';
+import type * as Caddy from '@distilled.cloud/caddy';
+import { type CaddyAdminService, type CaddyTransport, caddyAdminLayer } from './admin.ts';
 import { localCaddyAdmin } from './local-admin.ts';
 
 export type Seen = {
@@ -128,6 +130,10 @@ export const fakeCaddy = (
     }
     if (url.pathname !== '/load') return json(404, { error: 'not found' });
     const prefix = adapted.warnings.length > 0 ? JSON.stringify(adapted.warnings) : '';
+    // ⚠️ TEST-ONLY SCENARIO, no Caddy source it reproduces: a `/load` that answers 200 with no
+    //   applied change at all (not even the embedded-error 200 the ⛔ above describes) — what
+    //   config-lifecycle.ts's read-back-and-insist check exists to catch, per its own doc.
+    if (body.includes('SWALLOW_LOAD')) return new Response('', { status: 200 });
     if (body.includes('PROVISION_ERROR')) {
       const error = JSON.stringify({
         error: 'loading config: provision http: listen tcp :443: address already in use',
@@ -168,7 +174,9 @@ export const fakeCaddy = (
  *   A Caddy reached on any other port needs `admin <address>` declared, or the first load would
  *   move it (admin-guard.ts).
  */
-export const fakeDefaultCaddy = (running?: unknown): { admin: CaddyAdmin; caddy: FakeCaddy } => {
+export const fakeDefaultCaddy = (
+  running?: unknown,
+): { admin: CaddyTransport; caddy: FakeCaddy } => {
   const caddy = fakeCaddy({ listenPort: 2019, ...(running === undefined ? {} : { running }) });
   const admin = localCaddyAdmin({
     address: caddy.address,
@@ -177,3 +185,13 @@ export const fakeDefaultCaddy = (running?: unknown): { admin: CaddyAdmin; caddy:
   });
   return { admin, caddy };
 };
+
+/**
+ * Runs an Effect that needs `CaddyAdminService` and `@distilled.cloud/caddy`'s own `Credentials`/
+ * `HttpClient` against one transport — the one line every test in this directory used to spend on
+ * `Effect.provide(caddyAdminLayer(admin))` before this helper existed.
+ */
+export const runCaddy = <A, E>(
+  effect: Effect.Effect<A, E, CaddyAdminService | Caddy.CaddyOpContext>,
+  admin: CaddyTransport,
+): Promise<A> => Effect.runPromise(effect.pipe(Effect.provide(caddyAdminLayer(admin))));

package/src/caddy/index.ts

@@ -19,14 +19,9 @@ export {
   verifierProblems,
   type AccessForwardAuthProps,
 } from './access-forward-auth.ts';
-export type {
-  CaddyAdmin,
-  CaddyAdminListener,
-  CaddyAdminRequest,
-  CaddyAdminResponse,
-} from './admin.ts';
-export { CaddyAdminService, CaddyUnreachableError, caddyAdminLayer } from './admin.ts';
-export { CaddyAdminError } from './admin-calls.ts';
+export type { CaddyAdminListener, CaddyTarget, CaddyTransport } from './admin.ts';
+export { CaddyAdminService, caddyAdminLayer } from './admin.ts';
+export { isUnreachable } from './caddy-http-client.ts';
 export type { CaddyConfigAttributes, CaddyConfigProps } from './config.ts';
 export { CaddyConfig, CaddyConfigProvider } from './config.ts';
 export type { LocalCaddyAdminOptions } from './local-admin.ts';

package/src/caddy/local-admin.test.ts

@@ -7,9 +7,10 @@ import { rmSync } from 'node:fs';
 import { createServer } from 'node:net';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { CaddyUnreachableError } from './admin.ts';
-import { readRunningConfig } from './admin-calls.ts';
-import { type FakeCaddy, fakeCaddy } from './fake-caddy.ts';
+import * as HttpClientError from 'effect/unstable/http/HttpClientError';
+import { loadCaddyfile, readRunningConfig } from './admin-calls.ts';
+import { isUnreachable } from './caddy-http-client.ts';
+import { type FakeCaddy, fakeCaddy, runCaddy } from './fake-caddy.ts';
 import { DEFAULT_ADMIN_ADDRESS, localCaddyAdmin, parseAdminAddress } from './local-admin.ts';
 
 let fake: FakeCaddy | undefined;
@@ -83,7 +84,7 @@ describe('requests', () => {
   test('over TCP: Host and Origin as the Caddy CLI sends them, so the checks pass', async () => {
     fake = fakeCaddy();
     const admin = localCaddyAdmin({ address: fake.address, retries: 0 });
-    expect(await readRunningConfig(admin)).toBeNull();
+    expect(await runCaddy(readRunningConfig(), admin)).toBeNull();
     const host = `127.0.0.1:${String(fake.port)}`;
     expect(fake.seen[0]?.headers.get('host')).toBe(host);
     expect(fake.seen[0]?.headers.get('origin')).toBe(`http://${host}`);
@@ -92,29 +93,42 @@ describe('requests', () => {
   test('a narrowed `origins` needs hostHeader — without it Caddy answers 403', async () => {
     fake = fakeCaddy({ origins: ['caddy-admin.example:2019'] });
     const plain = localCaddyAdmin({ address: fake.address, retries: 0 });
-    await expect(readRunningConfig(plain)).rejects.toThrow(/403: host not allowed/);
+    await expect(runCaddy(readRunningConfig(), plain)).rejects.toThrow(/host not allowed/);
     const named = localCaddyAdmin({
       address: fake.address,
       hostHeader: 'caddy-admin.example:2019',
       retries: 0,
     });
-    expect(await readRunningConfig(named)).toBeNull();
+    expect(await runCaddy(readRunningConfig(), named)).toBeNull();
   });
 
-  test('a caller cannot override the Host and Origin the checks depend on', async () => {
+  test("an operation's own headers never override the Host and Origin the checks depend on", async () => {
+    // ⚠️ There is no raw `.request()` anymore for a caller to hand Host/Origin to — every header
+    //   an operation sends of its own (loadConfig's Content-Type, Cache-Control, …) is set by
+    //   distilled's `buildRequest` from the SCHEMA, never by a caller, and Host/Origin are set by
+    //   `CaddyProtocol.encode` from `Credentials` alone, unconditionally, after that — so the same
+    //   invariant now holds by construction rather than by a check in this transport.
     fake = fakeCaddy();
     const admin = localCaddyAdmin({ address: fake.address, retries: 0 });
-    const headers = { Host: 'evil.example:2019', Origin: 'http://evil.example:2019' };
-    expect((await admin.request({ headers, method: 'GET', path: '/config/' })).status).toBe(200);
-    expect(fake.seen[0]?.headers.get('host')).toBe(`127.0.0.1:${String(fake.port)}`);
+    await runCaddy(loadCaddyfile('respond ok'), admin);
+    const host = `127.0.0.1:${String(fake.port)}`;
+    const load = fake.seen.find((call) => call.path === '/load');
+    expect(load?.headers.get('host')).toBe(host);
+    expect(load?.headers.get('origin')).toBe(`http://${host}`);
   });
 
-  test('over a unix socket, with no Origin', async () => {
+  test('over a unix socket', async () => {
     const path = socketPath('req');
     fake = fakeCaddy({ running: { apps: {} }, unix: path });
     const admin = localCaddyAdmin({ address: fake.address, retries: 0 });
-    expect(await readRunningConfig(admin)).toEqual({ apps: {} });
-    expect(fake.seen[0]?.headers.has('origin')).toBe(false);
+    expect(await runCaddy(readRunningConfig(), admin)).toEqual({ apps: {} });
+    // ⚠️ MEASURED 2026-09-23: `@distilled.cloud/caddy`'s `CaddyProtocol.encode` sends Host AND
+    //   Origin on every call, unconditionally — unlike the old hand-rolled transport, which sent
+    //   no Origin over a unix socket (Caddy's own CLI doesn't either). Caddy skips the Host check
+    //   entirely on unix listeners either way (admin.go allowedOrigins), so this changes nothing
+    //   the default (no `enforce_origin`) fake or a real unix-socket Caddy checks.
+    expect(fake.seen[0]?.headers.get('host')).toBe('127.0.0.1');
+    expect(fake.seen[0]?.headers.get('origin')).toBe('http://127.0.0.1');
     rmSync(path, { force: true });
   });
 
@@ -124,7 +138,7 @@ describe('requests', () => {
     const late = setTimeout(() => {
       fake = fakeCaddy({ unix: path });
     }, 60);
-    expect(await readRunningConfig(admin)).toBeNull();
+    expect(await runCaddy(readRunningConfig(), admin)).toBeNull();
     clearTimeout(late);
     rmSync(path, { force: true });
   });
@@ -143,18 +157,18 @@ describe('requests', () => {
       retries: 3,
       retryDelayMs: 1,
     });
-    const failure = admin.request({ body: 'x', method: 'POST', path: '/load' });
-    await expect(failure).rejects.toThrow(/Caddy admin POST \/load/);
-    await expect(failure).rejects.not.toBeInstanceOf(CaddyUnreachableError);
+    const failure = runCaddy(loadCaddyfile('respond ok'), admin);
+    await expect(failure).rejects.toBeInstanceOf(HttpClientError.HttpClientError);
+    await expect(failure.catch((error: unknown) => isUnreachable(error))).resolves.toBe(false);
     expect(accepted).toBe(1);
     server.close();
   });
 
-  test('gives up after the retries with CaddyUnreachableError, naming the address', async () => {
+  test('gives up after the retries, still narrowable as unreachable, naming the address', async () => {
     const path = socketPath('never');
     const admin = localCaddyAdmin({ address: `unix://${path}`, retries: 1, retryDelayMs: 1 });
-    const failure = readRunningConfig(admin);
-    await expect(failure).rejects.toBeInstanceOf(CaddyUnreachableError);
-    await expect(failure).rejects.toThrow(/Caddy admin GET \/config\/ at unix:\/\//);
+    const failure = runCaddy(readRunningConfig(), admin);
+    await expect(failure).rejects.toBeInstanceOf(HttpClientError.HttpClientError);
+    await expect(failure.catch((error: unknown) => isUnreachable(error))).resolves.toBe(true);
   });
 });

package/src/caddy/local-admin.ts

@@ -1,189 +1,82 @@
 /**
- * The real CaddyAdmin: this machine's Caddy, over loopback TCP or a unix socket.
+ * The real Caddy transport: this machine's Caddy, over loopback TCP or a unix socket — the
+ * `Credentials` and `HttpClient.HttpClient` layers `@distilled.cloud/caddy`'s typed operations run
+ * against (admin-calls.ts), plus the message/guard metadata `CaddyAdminService` carries.
  *
- * ★ node:http, NOT fetch. MEASURED 2026-09-21 on bun 1.4.0 and node 26.7.0: node:http sends a Host
- *   override and dials a unix socket on BOTH runtimes, while node's fetch silently drops a `Host`
- *   header (it sent the URL's host) and only Bun's fetch has a `unix` option. The published dist
- *   loads under node too (launchd's local-runner.ts makes the same call for the same reason).
- * ⛔ LOOPBACK OR A UNIX SOCKET, NOTHING ELSE. The admin API is unauthenticated plaintext; an
- *   address off this machine means it is reachable from the network, which decision 23 forbids.
- *   Reaching another host's Caddy means forwarding its socket or port to here (SSH), never
- *   exposing :2019.
- * ★ HOST AND ORIGIN, AS CADDY's OWN CLI SENDS THEM (cmd/commandfuncs.go AdminAPIRequest): over
- *   TCP, `Host` and `Origin: http://<host>`; over a socket, `Host: 127.0.0.1` and no Origin, because
- *   Caddy skips the Host check on unix listeners (admin.go allowedOrigins). MEASURED against the
- *   a Mac host's Caddy 2.11.4: any other Host gets 403 `host not allowed`, a forwarded port included —
- *   hence `hostHeader`.
+ * Address parsing (`parseAdminAddress`) is pure — admin-address.ts. The wire transport itself
+ * (retries, timeouts, the unix-socket dial) is caddy-http-client.ts; this file is the seam between
+ * the two and `@distilled.cloud/caddy`'s own `Credentials`.
  */
-import { request as httpRequest } from 'node:http';
-import {
-  type CaddyAdmin,
-  type CaddyAdminListener,
-  type CaddyAdminResponse,
-  CaddyUnreachableError,
-} from './admin.ts';
+import * as Layer from 'effect/Layer';
+import * as Caddy from '@distilled.cloud/caddy';
+import type { CaddyTransport } from './admin.ts';
+import { DEFAULT_ADMIN_ADDRESS, parseAdminAddress } from './admin-address.ts';
+import { type LocalHttpClientOptions, makeLocalHttpClient } from './caddy-http-client.ts';
+
+export { DEFAULT_ADMIN_ADDRESS, parseAdminAddress } from './admin-address.ts';
+export { isUnreachable } from './caddy-http-client.ts';
 
-export type LocalCaddyAdminOptions = {
+export type LocalCaddyAdminOptions = LocalHttpClientOptions & {
   /**
    * `http://<loopback>:<port>` or `unix:///absolute/path.sock`.
    * @default 'http://127.0.0.1:2019' — Caddy's default admin listener (`localhost:2019`).
    */
   readonly address?: string;
   /**
-   * The Host (and Origin) to send over TCP, when it is not the address's own: the Caddyfile
+   * The Host (and, over TCP, Origin) to send when it is not the address's own: the Caddyfile
    * narrowed `admin { origins … }`, or the port is an SSH forward of the real one (Caddy checks
-   * the Host against ITS port, not yours). Form `host:port`.
+   * the Host against ITS port, not yours). Form `host:port`. Over a unix socket this still sets
+   * the Host header `@distilled.cloud/caddy`'s protocol always sends (Caddy skips the Host check
+   * on unix listeners regardless — admin.go allowedOrigins) — defaults to `127.0.0.1`, matching
+   * the Caddy CLI's own unix-socket calls (cmd/commandfuncs.go AdminAPIRequest).
    */
   readonly hostHeader?: string;
-  /**
-   * Abort an exchange after this long. @default 60_000
-   * ⚠️ A `shutdown_delay` in the Caddyfile makes `/load` block that long (caddyhttp app.go Stop);
-   *   a timeout then fails the deploy while Caddy goes on to apply — the next plan converges.
-   */
-  readonly timeoutMs?: number;
-  /**
-   * Retries when the connection is REFUSED (nothing listening yet — a Caddy launchd job that was
-   * bootstrapped a moment ago). Only refusals: those never reached Caddy, so re-sending a
-   * `POST /load` cannot apply it twice. @default 2
-   */
-  readonly retries?: number;
-  /** @default 500 */
-  readonly retryDelayMs?: number;
-};
-
-export const DEFAULT_ADMIN_ADDRESS = 'http://127.0.0.1:2019';
-
-type Target =
-  | { readonly kind: 'tcp'; readonly host: string; readonly port: number }
-  | { readonly kind: 'unix'; readonly socketPath: string };
-
-const UNIX = 'unix://';
-const HOST_PORT = /^(?:[A-Za-z0-9.-]+|\[[0-9A-Fa-f:.]+\]):\d{1,5}$/;
-
-const refuse = (address: string, why: string): Error =>
-  new Error(`Caddy admin address ${JSON.stringify(address)}: ${why}`);
-
-const isLoopback = (hostname: string): boolean =>
-  hostname === 'localhost' || hostname === '[::1]' || /^127(?:\.\d{1,3}){3}$/.test(hostname);
-
-/** The dial target and listener for an address, or a refusal naming what is wrong with it. */
-export const parseAdminAddress = (
-  address: string,
-  hostHeader?: string,
-): { target: Target; listener: CaddyAdminListener } => {
-  if (hostHeader !== undefined && !HOST_PORT.test(hostHeader)) {
-    throw refuse(address, `hostHeader ${JSON.stringify(hostHeader)} must be host:port`);
-  }
-  if (address.startsWith(UNIX)) {
-    const socketPath = address.slice(UNIX.length);
-    if (!socketPath.startsWith('/')) throw refuse(address, 'the socket path must be absolute');
-    return { listener: { kind: 'unix', path: socketPath }, target: { kind: 'unix', socketPath } };
-  }
-  let url: URL;
-  try {
-    url = new URL(address);
-  } catch {
-    throw refuse(address, 'not a URL (http://127.0.0.1:2019 or unix:///path)');
-  }
-  // ⛔ Caddy's local admin endpoint is plaintext by design; its TLS one (`admin.remote`, mTLS on
-  //   :2021) is a different, network-facing API this transport deliberately does not speak.
-  if (url.protocol !== 'http:') throw refuse(address, 'only http:// (loopback) or unix://');
-  if (!isLoopback(url.hostname)) {
-    throw refuse(address, 'not loopback — the admin API is unauthenticated; forward it to here');
-  }
-  if (url.pathname !== '/' || url.search !== '' || url.username !== '') {
-    throw refuse(address, 'no path, query or credentials — the API lives at the root');
-  }
-  const port = url.port === '' ? 80 : Number(url.port);
-  // ⚠️ NOT `url.host`: WHATWG URL drops a default port (`http://127.0.0.1:80` has host
-  //   `127.0.0.1`), and Caddy compares the Host against `host:port` (admin.go allowedOrigins), so
-  //   a portless Host is a 403 on every call. The Caddy CLI always sends the port (JoinHostPort).
-  const host = hostHeader ?? `${url.hostname}:${String(port)}`;
-  return {
-    listener: {
-      hostHeader: host,
-      kind: 'tcp',
-      port: Number(host.slice(host.lastIndexOf(':') + 1)),
-    },
-    // ★ `hostname` keeps IPv6 brackets; node:http wants them off.
-    target: { host: url.hostname.replace(/^\[(.*)\]$/, '$1'), kind: 'tcp', port },
-  };
 };
 
-const code = (cause: unknown): string | undefined =>
-  typeof cause === 'object' && cause !== null && 'code' in cause
-    ? String((cause as { code: unknown }).code)
-    : undefined;
-
-/** Nothing accepted the connection: refused TCP, or no socket file yet. The request never left. */
-const neverConnected = (cause: unknown): boolean =>
-  code(cause) === 'ECONNREFUSED' || code(cause) === 'ENOENT';
-
-const exchange = (
-  target: Target,
-  method: string,
-  path: string,
-  headers: Record<string, string>,
-  body: string | undefined,
-  timeoutMs: number,
-): Promise<CaddyAdminResponse> =>
-  new Promise((resolve, reject) => {
-    const bytes = body === undefined ? undefined : Buffer.from(body, 'utf8');
-    const request = httpRequest(
-      {
-        ...(target.kind === 'tcp'
-          ? { host: target.host, port: target.port }
-          : { socketPath: target.socketPath }),
-        headers: bytes === undefined ? headers : { ...headers, 'Content-Length': bytes.length },
-        method,
-        path,
-        timeout: timeoutMs,
-      },
-      (response) => {
-        const chunks: Buffer[] = [];
-        response.on('data', (chunk: Buffer) => chunks.push(chunk));
-        response.on('error', reject);
-        response.on('end', () =>
-          resolve({
-            body: Buffer.concat(chunks).toString('utf8'),
-            status: response.statusCode ?? 0,
-          }),
-        );
-      },
-    );
-    request.on('timeout', () => request.destroy(new Error(`no answer in ${String(timeoutMs)} ms`)));
-    request.on('error', reject);
-    request.end(bytes);
-  });
-
-export const localCaddyAdmin = (options: LocalCaddyAdminOptions = {}): CaddyAdmin => {
+/**
+ * A transport to this machine's Caddy — feed it to `caddyProviders()`, or build the layer by hand
+ * with `CaddyConfigProvider().pipe(Layer.provideMerge(caddyAdminLayer(localCaddyAdmin())))` (never
+ * plain `Layer.provide` — admin.ts's own doc on `caddyAdminLayer` says why).
+ *
+ * ⛔ LOOPBACK OR A UNIX SOCKET, NOTHING ELSE. The admin API is unauthenticated plaintext; an
+ *   address off this machine means it is reachable from the network, which decision 23 forbids.
+ *   `parseAdminAddress` refuses anything else.
+ */
+export const localCaddyAdmin = (options: LocalCaddyAdminOptions = {}): CaddyTransport => {
   const address = options.address ?? DEFAULT_ADMIN_ADDRESS;
   const { listener, target } = parseAdminAddress(address, options.hostHeader);
-  const timeoutMs = options.timeoutMs ?? 60_000;
-  const retries = options.retries ?? 2;
-  const delay = options.retryDelayMs ?? 500;
-  const fixed: Record<string, string> =
-    listener.kind === 'tcp'
-      ? { Host: listener.hostHeader, Origin: `http://${listener.hostHeader}` }
-      : { Host: '127.0.0.1' };
+  // `@distilled.cloud/caddy`'s protocol always builds `Host`/Origin from `apiBaseUrl` (or this
+  // override) — never from the dial target, which caddy-http-client.ts ignores the URL's host/port
+  // for anyway over a unix socket. `http://localhost` is a placeholder base for the request-URL
+  // machinery (`buildRequest` needs a syntactically valid `http://` URL to join `/config/…` onto);
+  // the hostHeader default `127.0.0.1` is what actually reaches Caddy's Host check, matching what
+  // the Caddy CLI sends over a unix socket.
+  const credentials =
+    target.kind === 'unix'
+      ? Caddy.fromApiBaseUrl({
+          apiBaseUrl: 'http://localhost',
+          hostHeader: options.hostHeader ?? '127.0.0.1',
+        })
+      : Caddy.fromApiBaseUrl({
+          apiBaseUrl: address,
+          ...(options.hostHeader === undefined ? {} : { hostHeader: options.hostHeader }),
+        });
   return {
     endpoint: address,
+    // ⚠️ `Caddy.Retry.Retry` DISABLED, not left at the SDK's default. MEASURED 2026-09-23: core's
+    //   `isTransientError` treats ANY `HttpClientError` with a `TransportError` reason as transient
+    //   — including an ECONNRESET well after the connection was accepted — and every generated
+    //   operation already retries under that default (`API.make({ retry: Retry.Retry })`,
+    //   services/admin.ts). Left in place, it retried a `POST /load` that had already reached the
+    //   far side (a socket that accepted, then reset) — the exact re-send admin-calls.ts's module
+    //   doc says must never happen — NINE times over, compounding with caddy-http-client.ts's own
+    //   narrower retry below it. This transport's retry (ECONNREFUSED/ENOENT only — "nothing
+    //   accepted the connection yet") is the one retry policy Caddy's admin API gets.
+    layer: Layer.mergeAll(
+      credentials,
+      makeLocalHttpClient(target, options),
+      Layer.succeed(Caddy.Retry.Retry, { while: () => false }),
+    ),
     listener,
-    request: async ({ body, headers, method, path }) => {
-      for (let attempt = 0; ; attempt += 1) {
-        try {
-          // oxlint-disable-next-line no-await-in-loop -- sequential by design: retry after a wait
-          return await exchange(target, method, path, { ...headers, ...fixed }, body, timeoutMs);
-        } catch (cause) {
-          if (!neverConnected(cause) || attempt >= retries) {
-            const reason = cause instanceof Error ? cause.message : String(cause);
-            const message = `Caddy admin ${method} ${path} at ${address}: ${reason}`;
-            throw neverConnected(cause) ? new CaddyUnreachableError(message) : new Error(message);
-          }
-          // oxlint-disable-next-line no-await-in-loop -- the wait between attempts
-          await new Promise((resolve) => setTimeout(resolve, delay));
-        }
-      }
-    },
   };
 };

package/src/caddy/providers.test.ts

@@ -7,7 +7,8 @@ import * as Output from 'alchemy/Output';
 import { Stack } from 'alchemy/Stack';
 import * as Effect from 'effect/Effect';
 import * as Layer from 'effect/Layer';
-import { caddyAdminLayer } from './admin.ts';
+import type * as Caddy from '@distilled.cloud/caddy';
+import { type CaddyAdminService, caddyAdminLayer } from './admin.ts';
 import { CaddyConfig, CaddyConfigProvider } from './config.ts';
 import { type FakeCaddy, fakeCaddy } from './fake-caddy.ts';
 import * as barrel from './index.ts';
@@ -30,7 +31,9 @@ const handler = <F>(name: string, fn: F | undefined): F => {
 };
 
 const withProvider = <A>(
-  use: (p: Effect.Success<typeof CaddyConfig.Provider>) => Effect.Effect<A, unknown>,
+  use: (
+    p: Effect.Success<typeof CaddyConfig.Provider>,
+  ) => Effect.Effect<A, unknown, CaddyAdminService | Caddy.CaddyOpContext>,
   address?: string,
 ) => {
   // ★ A Caddy on its default :2019 behind a forward, as in config-lifecycle.test.ts.
@@ -46,7 +49,7 @@ const withProvider = <A>(
   return Effect.runPromise(
     Effect.gen(function* () {
       return yield* use(yield* CaddyConfig.Provider);
-    }).pipe(Effect.provide(CaddyConfigProvider().pipe(Layer.provide(caddyAdminLayer(admin))))),
+    }).pipe(Effect.provide(CaddyConfigProvider().pipe(Layer.provideMerge(caddyAdminLayer(admin))))),
   );
 };
 
@@ -159,7 +162,11 @@ describe('a Caddy that is down', () => {
         }),
       closedPort(),
     );
-    await expect(applying).rejects.toThrow(/Caddy admin POST \/adapt at http:\/\/127\.0\.0\.1/);
+    // ★ Reconcile never catches `isUnreachable` (config.ts): the raw, still-typed
+    //   `HttpClientError` propagates as-is, its own `.message` naming the operation and URL.
+    await expect(applying).rejects.toThrow(
+      /Transport error \(POST http:\/\/127\.0\.0\.1.*\/adapt\)/,
+    );
   });
 
   test('a bad Caddyfile still fails the plan when Caddy IS up (only unreachability is forgiven)', async () => {
@@ -214,11 +221,9 @@ describe('caddyWithFile', () => {
 describe('the barrel', () => {
   test('exports the public API and not the internals', () => {
     expect(Object.keys(barrel).sort()).toEqual([
-      'CaddyAdminError',
       'CaddyAdminService',
       'CaddyConfig',
       'CaddyConfigProvider',
-      'CaddyUnreachableError',
       'DEFAULT_ADMIN_ADDRESS',
       // Caddyfile TEXT for an Access-protected route, not a resource — see
       // access-forward-auth.ts. It pairs with @homeflare/cloudflare/access-auth.
@@ -226,6 +231,9 @@ describe('the barrel', () => {
       'caddyAdminLayer',
       'caddyProviders',
       'caddyWithFile',
+      // The type guard config.ts's plan-time escape hatch narrows unreachable failures with —
+      // exported so a consumer's own transport (an SSH forward, a remote runner) can reuse it.
+      'isUnreachable',
       'localCaddyAdmin',
       'verifierProblems',
     ]);