@homeflare/alchemy 0.28.0 → 0.29.0

package/src/caddy/config-lifecycle.test.ts

@@ -1,12 +1,13 @@
 /**
- * CaddyConfig's lifecycle against the fake admin API (fake-caddy.ts): apply, a refused config
- * rolled back, drift, and the refusals that must happen before anything is sent.
+ * CaddyConfig's read / diff / reconcile against the fake admin API (fake-caddy.ts) — a real HTTP
+ * server, so this drives the real distilled wire protocol: apply, a refused config rolled back,
+ * drift, and the refusals that must happen before anything is sent.
  */
 import { afterEach, describe, expect, test } from 'bun:test';
-import type { CaddyAdmin } from './admin.ts';
-import { type FakeCaddy, fakeDefaultCaddy } from './fake-caddy.ts';
+import { type FakeCaddy, fakeDefaultCaddy, runCaddy } from './fake-caddy.ts';
 import { configDigest } from './digest.ts';
-import { diffConfig, readLive, reconcileConfig } from './config-lifecycle.ts';
+import { readLive } from './config-lifecycle.ts';
+import { diffConfig, reconcileConfig } from './config-reconcile.ts';
 
 const SITE = 'app.example.com reverse_proxy 127.0.0.1:8080';
 const OTHER = 'www.example.com respond <hello> & bye';
@@ -32,7 +33,7 @@ const loads = (caddy: FakeCaddy) => caddy.seen.filter((call) => call.path === '/
 describe('apply', () => {
   test('loads the Caddyfile, reads it back, and stores the digest Caddy reports', async () => {
     const { admin, caddy } = setup();
-    const applied = await reconcileConfig(admin, { caddyfile: OTHER }, OWNED);
+    const applied = await runCaddy(reconcileConfig({ caddyfile: OTHER }, OWNED), admin);
     expect(applied.loaded).toBe(true);
     // ★ The fake's /config/ is sorted and escaped differently from /adapt; the digests still agree.
     expect(applied.attributes.configSha256).toBe(configDigest(caddy.adapt(OTHER)));
@@ -44,8 +45,8 @@ describe('apply', () => {
 
   test('a Caddy already running this config is not reloaded', async () => {
     const { admin, caddy } = setup();
-    await reconcileConfig(admin, { caddyfile: SITE }, OWNED);
-    const again = await reconcileConfig(admin, { caddyfile: SITE }, OWNED);
+    await runCaddy(reconcileConfig({ caddyfile: SITE }, OWNED), admin);
+    const again = await runCaddy(reconcileConfig({ caddyfile: SITE }, OWNED), admin);
     expect(again.loaded).toBe(false);
     expect(loads(caddy)).toHaveLength(1);
   });
@@ -53,7 +54,10 @@ describe('apply', () => {
   test('sourceFile rides as the headers `caddy reload` sends, and lands in the attributes', async () => {
     const { admin, caddy } = setup();
     const path = '/usr/local/etc/Caddyfile';
-    const applied = await reconcileConfig(admin, { caddyfile: SITE, sourceFile: path }, OWNED);
+    const applied = await runCaddy(
+      reconcileConfig({ caddyfile: SITE, sourceFile: path }, OWNED),
+      admin,
+    );
     expect(loads(caddy)[0]?.headers.get('caddy-config-source-file')).toBe(path);
     expect(loads(caddy)[0]?.headers.get('caddy-config-source-adapter')).toBe('caddyfile');
     expect(applied.attributes.sourceFile).toBe(path);
@@ -61,7 +65,7 @@ describe('apply', () => {
 
   test('adapter warnings are returned, not refused', async () => {
     const { admin } = setup();
-    const applied = await reconcileConfig(admin, { caddyfile: `${SITE}\t` }, OWNED);
+    const applied = await runCaddy(reconcileConfig({ caddyfile: `${SITE}\t` }, OWNED), admin);
     expect(applied.warnings).toEqual(['Caddyfile:1: Caddyfile input is not formatted']);
   });
 });
@@ -69,43 +73,39 @@ describe('apply', () => {
 describe('a config Caddy refuses', () => {
   test('surfaces Caddy’s reason and confirms the previous config is still running', async () => {
     const { admin, caddy } = setup();
-    await reconcileConfig(admin, { caddyfile: SITE }, OWNED);
+    await runCaddy(reconcileConfig({ caddyfile: SITE }, OWNED), admin);
     const before = caddy.running;
     await expect(
-      reconcileConfig(admin, { caddyfile: `${SITE}\nPROVISION_ERROR` }, OWNED),
+      runCaddy(reconcileConfig({ caddyfile: `${SITE}\nPROVISION_ERROR` }, OWNED), admin),
     ).rejects.toThrow(/address already in use.*kept the previous config/);
     expect(caddy.running).toEqual(before);
   });
 
   test('a refusal that came back as a 200 (warnings first) is still a refusal', async () => {
     const { admin, caddy } = setup();
-    await reconcileConfig(admin, { caddyfile: SITE }, OWNED);
+    await runCaddy(reconcileConfig({ caddyfile: SITE }, OWNED), admin);
     await expect(
-      reconcileConfig(admin, { caddyfile: `${SITE}\t\nPROVISION_ERROR` }, OWNED),
-    ).rejects.toThrow(/→ 200: loading config.*error in a 200 body.*kept the previous/);
+      runCaddy(reconcileConfig({ caddyfile: `${SITE}\t\nPROVISION_ERROR` }, OWNED), admin),
+    ).rejects.toThrow(/address already in use.*LoadRefused.*200.*kept the previous/);
     expect(configDigest(caddy.running)).toBe(configDigest(caddy.adapt(SITE)));
   });
 
   test('a load answered 200 that Caddy did not apply fails the deploy (the read-back)', async () => {
     const { admin, caddy } = setup();
-    await reconcileConfig(admin, { caddyfile: SITE }, OWNED);
+    await runCaddy(reconcileConfig({ caddyfile: SITE }, OWNED), admin);
     // ⚠️ A concurrent writer, or a 200 that carried no change: state must not record OTHER.
-    const swallowing: CaddyAdmin = {
-      ...admin,
-      request: (call) =>
-        call.path === '/load' ? Promise.resolve({ body: '', status: 200 }) : admin.request(call),
-    };
-    await expect(reconcileConfig(swallowing, { caddyfile: OTHER }, OWNED)).rejects.toThrow(
-      /after the load Caddy runs config \w+, not the \w+ this Caddyfile adapts to/,
-    );
+    // fake-caddy.ts's SWALLOW_LOAD keyword answers `/load` 200 without applying anything.
+    await expect(
+      runCaddy(reconcileConfig({ caddyfile: `${OTHER}\nSWALLOW_LOAD` }, OWNED), admin),
+    ).rejects.toThrow(/after the load Caddy runs config \w+, not the \w+ this Caddyfile adapts to/);
     expect(configDigest(caddy.running)).toBe(configDigest(caddy.adapt(SITE)));
   });
 
   test('a Caddyfile that does not adapt is refused before any load', async () => {
     const { admin, caddy } = setup();
-    await expect(reconcileConfig(admin, { caddyfile: 'SYNTAX_ERROR' }, OWNED)).rejects.toThrow(
-      /\/adapt → 400: Caddyfile:1 - Error during parsing/,
-    );
+    await expect(
+      runCaddy(reconcileConfig({ caddyfile: 'SYNTAX_ERROR' }, OWNED), admin),
+    ).rejects.toThrow(/POST \/adapt failed.*Caddyfile:1 - Error during parsing/);
     expect(loads(caddy)).toHaveLength(0);
   });
 });
@@ -116,7 +116,7 @@ describe('refused before anything is sent', () => {
     ['an empty Caddyfile', '  \n'],
   ])('%s', async (_, caddyfile) => {
     const { admin, caddy } = setup();
-    await expect(reconcileConfig(admin, { caddyfile }, OWNED)).rejects.toThrow(
+    await expect(runCaddy(reconcileConfig({ caddyfile }, OWNED), admin)).rejects.toThrow(
       /Caddy\.Config at http/,
     );
     expect(caddy.seen).toHaveLength(0);
@@ -127,14 +127,16 @@ describe('refused before anything is sent', () => {
     ['only global options', 'admin localhost:2019'],
   ])('a Caddyfile of %s adapts to no apps, and is never loaded', async (_, caddyfile) => {
     const { admin, caddy } = setup();
-    await expect(reconcileConfig(admin, { caddyfile }, OWNED)).rejects.toThrow(/adapts to no apps/);
+    await expect(runCaddy(reconcileConfig({ caddyfile }, OWNED), admin)).rejects.toThrow(
+      /adapts to no apps/,
+    );
     expect(loads(caddy)).toHaveLength(0);
   });
 
   test('a Caddyfile that would turn the admin API off is never loaded', async () => {
     const { admin, caddy } = setup();
     await expect(
-      reconcileConfig(admin, { caddyfile: `admin off\n${SITE}` }, OWNED),
+      runCaddy(reconcileConfig({ caddyfile: `admin off\n${SITE}` }, OWNED), admin),
     ).rejects.toThrow(/admin off/);
     expect(loads(caddy)).toHaveLength(0);
   });
@@ -143,53 +145,64 @@ describe('refused before anything is sent', () => {
 describe('drift', () => {
   const applied = async () => {
     const { admin, caddy } = setup();
-    const { attributes } = await reconcileConfig(admin, { caddyfile: SITE }, OWNED);
+    const { attributes } = await runCaddy(reconcileConfig({ caddyfile: SITE }, OWNED), admin);
     return { admin, attributes, caddy };
   };
 
   test('converged: declared, live and stored agree → noop', async () => {
     const { admin, attributes } = await applied();
-    expect(await diffConfig(admin, { caddyfile: SITE }, attributes)).toEqual({ action: 'noop' });
+    expect(await runCaddy(diffConfig({ caddyfile: SITE }, attributes), admin)).toEqual({
+      action: 'noop',
+    });
   });
 
   test('a changed declaration → update', async () => {
     const { admin, attributes } = await applied();
-    expect(await diffConfig(admin, { caddyfile: OTHER }, attributes)).toEqual({ action: 'update' });
+    expect(await runCaddy(diffConfig({ caddyfile: OTHER }, attributes), admin)).toEqual({
+      action: 'update',
+    });
   });
 
   test('a hand edit through the API → update, and the apply puts the declaration back', async () => {
     const { admin, attributes, caddy } = await applied();
     caddy.running = { apps: { http: { servers: {} } } };
-    expect(await diffConfig(admin, { caddyfile: SITE }, attributes)).toEqual({ action: 'update' });
-    const again = await reconcileConfig(admin, { caddyfile: SITE }, OWNED);
+    expect(await runCaddy(diffConfig({ caddyfile: SITE }, attributes), admin)).toEqual({
+      action: 'update',
+    });
+    const again = await runCaddy(reconcileConfig({ caddyfile: SITE }, OWNED), admin);
     expect(again.attributes.configSha256).toBe(attributes.configSha256);
   });
 
   test('a restart with a different file → update', async () => {
     const { admin, attributes, caddy } = await applied();
     caddy.running = JSON.parse(JSON.stringify(caddy.adapt(OTHER))) as unknown;
-    expect((await readLive(admin)).configSha256).not.toBe(attributes.configSha256);
-    expect(await diffConfig(admin, { caddyfile: SITE }, attributes)).toEqual({ action: 'update' });
+    expect((await runCaddy(readLive(), admin)).configSha256).not.toBe(attributes.configSha256);
+    expect(await runCaddy(diffConfig({ caddyfile: SITE }, attributes), admin)).toEqual({
+      action: 'update',
+    });
   });
 
   test('state that lags the live config → update, so the stored digest is refreshed', async () => {
     const { admin, attributes } = await applied();
     const stale = { ...attributes, configSha256: configDigest({ apps: { before: true } }) };
-    expect(await diffConfig(admin, { caddyfile: SITE }, stale)).toEqual({ action: 'update' });
+    expect(await runCaddy(diffConfig({ caddyfile: SITE }, stale), admin)).toEqual({
+      action: 'update',
+    });
   });
 
   test('the transport now reaches Caddy at another endpoint → update (load there)', async () => {
     const { admin, attributes } = await applied();
     const moved = { ...attributes, endpoint: 'unix:///run/caddy/admin.sock' };
-    expect(await diffConfig(admin, { caddyfile: SITE }, moved)).toEqual({ action: 'update' });
+    expect(await runCaddy(diffConfig({ caddyfile: SITE }, moved), admin)).toEqual({
+      action: 'update',
+    });
   });
 
   test('a new sourceFile → update, so state records the file this config mirrors', async () => {
     const { admin, attributes } = await applied();
-    const diff = await diffConfig(
+    const diff = await runCaddy(
+      diffConfig({ caddyfile: SITE, sourceFile: '/etc/Caddyfile' }, attributes),
       admin,
-      { caddyfile: SITE, sourceFile: '/etc/Caddyfile' },
-      attributes,
     );
     expect(diff).toEqual({ action: 'update' });
   });

package/src/caddy/config-lifecycle.ts

@@ -1,26 +1,21 @@
 /**
- * CaddyConfig's read / diff / reconcile as plain async functions over a CaddyAdmin, so the
- * lifecycle runs against a fake admin server in tests.
+ * CaddyConfig's validate / read / probe as Effects over `@distilled.cloud/caddy`'s typed `admin`
+ * operations (admin-calls.ts), so the lifecycle runs against a fake admin server in tests — and,
+ * since fake-caddy.ts is a real HTTP server, against the real distilled wire protocol too.
+ * config-reconcile.ts covers `diff`/`reconcile`, the other half of the same lifecycle.
  *
  * The comparison is always between DIGESTS OF ADAPTED JSON (digest.ts): what `POST /adapt` makes
- * of the declared Caddyfile, what `GET /config/` reports, and what was stored after the last
- * apply. Three digests, because they answer different questions:
- *   · declared ≠ stored — the declaration changed.
- *   · live ≠ stored — DRIFT: a hand `curl` to the API, or a restart that loaded a different file
- *     (or an `autosave.json` holding someone else's change, under `--resume`).
- *   · declared = live — nothing to load, whatever the state says.
- * With NO state there is no stored digest, and the question is whose config is running: see
- * `claimable` below, which both the adoption probe and the apply ask.
+ * of the declared Caddyfile and what `GET /config/` reports — `claimable` below asks whether a
+ * running config is provably the declared one, which both the adoption probe and the apply need.
  */
-import type { Diff } from 'alchemy/Diff';
-import { type CaddyAdmin, CaddyUnreachableError } from './admin.ts';
-import {
-  CaddyAdminError,
-  adaptCaddyfile,
-  loadCaddyfile,
-  readRunningConfig,
-} from './admin-calls.ts';
+import * as Effect from 'effect/Effect';
+import * as Result from 'effect/Result';
+import type * as Caddy from '@distilled.cloud/caddy';
+import { CaddyAdminService } from './admin.ts';
+import { adaptCaddyfile, readRunningConfig } from './admin-calls.ts';
 import { adminProblems } from './admin-guard.ts';
+import { isUnreachable } from './caddy-http-client.ts';
+import { refuse, wrapOperation } from './config-errors.ts';
 import {
   type CaddyConfigAttributes,
   type CaddyConfigProps,
@@ -28,11 +23,6 @@ import {
 } from './config-form.ts';
 import { configDigest } from './digest.ts';
 
-const refuse = (admin: CaddyAdmin, message: string): Error =>
-  new Error(`Caddy.Config at ${admin.endpoint}: ${message}`);
-
-const short = (digest: string): string => digest.slice(0, 12);
-
 type Desired = { readonly digest: string; readonly warnings: readonly string[] };
 
 /**
@@ -41,7 +31,7 @@ type Desired = { readonly digest: string; readonly warnings: readonly string[] }
  *   2026-09-21 on a throwaway Caddy 2.11.4 — and loading it stops every server: the same outage,
  *   from the same templating bug, that the empty check exists to prevent.
  */
-const servesNothing = (config: unknown): boolean => {
+export const servesNothing = (config: unknown): boolean => {
   const apps =
     typeof config === 'object' && config !== null ? (config as { apps?: unknown }).apps : undefined;
   return typeof apps !== 'object' || apps === null || Object.keys(apps).length === 0;
@@ -53,37 +43,49 @@ const servesNothing = (config: unknown): boolean => {
  *   Caddyfile that does not adapt, carries a literal secret, or would strand the admin API fails the
  *   PLAN, before any resource (a HostFile holding the same text included) is applied.
  */
-export const desiredConfig = async (
-  admin: CaddyAdmin,
+export const desiredConfig = (
   props: CaddyConfigProps,
-): Promise<Desired> => {
-  const found = configProblems(props);
-  if (found.length > 0) throw refuse(admin, found.join('; '));
-  const adapted = await adaptCaddyfile(admin, props.caddyfile);
-  if (servesNothing(adapted.config)) {
-    throw refuse(admin, 'the Caddyfile adapts to no apps — loading it would stop every site');
-  }
-  const guard = adminProblems(adapted.config, admin.listener);
-  if (guard.length > 0) throw refuse(admin, guard.join('; '));
-  return { digest: configDigest(adapted.config), warnings: adapted.warnings };
-};
+): Effect.Effect<Desired, Error | Caddy.CaddyOpError, CaddyAdminService | Caddy.CaddyOpContext> =>
+  Effect.gen(function* () {
+    const { endpoint, listener } = yield* CaddyAdminService;
+    const found = configProblems(props);
+    if (found.length > 0) return yield* Effect.fail(refuse(endpoint, found.join('; ')));
+    const adapted = yield* adaptCaddyfile(props.caddyfile).pipe(
+      wrapOperation(endpoint, 'POST /adapt'),
+    );
+    if (servesNothing(adapted.config)) {
+      return yield* Effect.fail(
+        refuse(endpoint, 'the Caddyfile adapts to no apps — loading it would stop every site'),
+      );
+    }
+    const guard = adminProblems(adapted.config, listener);
+    if (guard.length > 0) return yield* Effect.fail(refuse(endpoint, guard.join('; ')));
+    return { digest: configDigest(adapted.config), warnings: adapted.warnings };
+  });
 
-const attributesOf = (
-  admin: CaddyAdmin,
+export const attributesOf = (
+  endpoint: string,
   running: unknown,
   sourceFile?: string,
 ): CaddyConfigAttributes => ({
   configSha256: configDigest(running),
-  endpoint: admin.endpoint,
+  endpoint,
   ...(sourceFile === undefined ? {} : { sourceFile }),
 });
 
 /** What is running now, as attributes. `sourceFile` is carried over, never discovered. */
-export const readLive = async (
-  admin: CaddyAdmin,
+export const readLive = (
   sourceFile?: string,
-): Promise<CaddyConfigAttributes> =>
-  attributesOf(admin, await readRunningConfig(admin), sourceFile);
+): Effect.Effect<
+  CaddyConfigAttributes,
+  Error | Caddy.CaddyOpError,
+  CaddyAdminService | Caddy.CaddyOpContext
+> =>
+  Effect.gen(function* () {
+    const { endpoint } = yield* CaddyAdminService;
+    const running = yield* readRunningConfig().pipe(wrapOperation(endpoint, 'GET /config/'));
+    return attributesOf(endpoint, running, sourceFile);
+  });
 
 /**
  * ⛔ WITH NO STATE, A RUNNING CONFIG IS THIS STACK'S ONLY IF IT IS THE DECLARED ONE (decision,
@@ -112,128 +114,36 @@ export type Probe = {
  *   adapt then would fail every later plan, the one carrying the fix included. What cannot be
  *   compared is "not proven ours", with the reason; the next diff or apply validates the Caddyfile.
  */
-export const probeLive = async (
-  admin: CaddyAdmin,
+export const probeLive = (
   caddyfile: string | undefined,
   sourceFile?: string,
-): Promise<Probe | undefined> => {
-  const running = await readRunningConfig(admin);
-  if (servesNothing(running)) return undefined;
-  const attributes = attributesOf(admin, running, sourceFile);
-  if (caddyfile === undefined) {
-    return { attributes, ours: false, unchecked: 'the stored Caddyfile is not plain text' };
-  }
-  try {
-    const want = await desiredConfig(admin, { caddyfile });
-    return { attributes, ours: claimable(running, want.digest) };
-  } catch (cause) {
-    // ⚠️ Unreachable mid-probe is still "no Caddy" (config.ts plans without it), not "not ours".
-    if (cause instanceof CaddyUnreachableError) throw cause;
+): Effect.Effect<Probe | undefined, Caddy.CaddyOpError, CaddyAdminService | Caddy.CaddyOpContext> =>
+  Effect.gen(function* () {
+    const { endpoint } = yield* CaddyAdminService;
+    // ⚠️ NOT wrapOperation here: an unreachable Caddy must still raise the raw, narrowable
+    //   HttpClientError (config.ts's plan-time escape hatch), and every OTHER failure reading the
+    //   running config mid-probe is "not proven ours" below, never a thrown refusal.
+    const running = yield* readRunningConfig();
+    if (servesNothing(running)) return undefined;
+    const attributes = attributesOf(endpoint, running, sourceFile);
+    if (caddyfile === undefined) {
+      return { attributes, ours: false, unchecked: 'the stored Caddyfile is not plain text' };
+    }
+    // ⚠️ Unreachable mid-probe is still "no Caddy" (config.ts plans without it), not "not ours" —
+    //   re-failed with the raw, still-narrowable error, never swallowed into `unchecked`. Every
+    //   OTHER refusal desiredConfig raises mid-probe (a bad admin block, a Caddyfile that will not
+    //   adapt) is "not proven ours", with the reason — never a thrown refusal over the DECLARATION
+    //   (the ⛔ above). `Effect.result`, per S20, rather than a `catchAll` this Effect version
+    //   does not export.
+    const desired = yield* Effect.result(desiredConfig({ caddyfile }));
+    if (Result.isSuccess(desired)) {
+      return { attributes, ours: claimable(running, desired.success.digest) };
+    }
+    if (isUnreachable(desired.failure)) return yield* Effect.fail(desired.failure);
+    const cause = desired.failure;
     return {
       attributes,
       ours: false,
       unchecked: cause instanceof Error ? cause.message : String(cause),
     };
-  }
-};
-
-/**
- * ★ NEVER `replace`. Nothing in the props names a different object: a new Caddyfile is a reload of
- *   the same Caddy, and `sourceFile` is a header. (Which Caddy is the transport's business — see
- *   the ⚠️ on `endpoint` in the diff.)
- */
-export const diffConfig = async (
-  admin: CaddyAdmin,
-  news: CaddyConfigProps,
-  output: CaddyConfigAttributes,
-): Promise<Diff> => {
-  const want = await desiredConfig(admin, news);
-  const live = await readLive(admin);
-  const converged =
-    want.digest === live.configSha256 &&
-    live.configSha256 === output.configSha256 &&
-    news.sourceFile === output.sourceFile &&
-    // ⚠️ A stack whose transport now reaches ANOTHER Caddy (a new address) must load there; the
-    //   old one keeps what it has — the same as a delete, which never unloads (see config.ts).
-    //   Planned as an update, but the state does not vouch for that Caddy: see Authority.
-    admin.endpoint === output.endpoint;
-  return converged ? { action: 'noop' } : { action: 'update' };
-};
-
-export type Applied = {
-  readonly attributes: CaddyConfigAttributes;
-  /** The adapter's warnings (e.g. "Caddyfile input is not formatted") — log them, never refuse. */
-  readonly warnings: readonly string[];
-  /** Whether a `POST /load` was sent (false when Caddy already ran this config). */
-  readonly loaded: boolean;
-};
-
-/**
- * What this apply may load over — config.ts decides from the state and the adopt setting:
- *   · `takeOver` — any running config: the state was applied to THIS Caddy (an update, drift
- *     correction, or a create the engine adopted), or adoption is on (`--adopt`, or the
- *     resource's own `adopt(true)` — ownership/adopt.ts adoptEnabled).
- *   · otherwise only a claimable one — plus, as `stored`, the digest the state last recorded: a
- *     Caddy reached at a NEW endpoint that runs exactly that is the same config under another name.
- */
-export type Authority = { readonly takeOver: boolean; readonly stored?: string };
-
-/**
- * Load the Caddyfile unless Caddy already runs it, then read it back and insist it matches.
- * ⛔ WITHOUT `takeOver`, A CONFIG THE STACK CANNOT CLAIM IS NEVER LOADED OVER. The engine's adoption
- *   probe cannot guard every create: it is skipped while `news` holds an Output — ALWAYS on
- *   caddyWithFile's first deploy (`sourceFile` is its HostFile's path) — and a Caddy that was down at
- *   plan time read as nothing. Nor does state vouch for a Caddy the transport NOW reaches at another
- *   endpoint (diff plans that as an update). Refused here, before any `/load`, like HostFile's.
- */
-export const reconcileConfig = async (
-  admin: CaddyAdmin,
-  props: CaddyConfigProps,
-  authority: Authority,
-): Promise<Applied> => {
-  const want = await desiredConfig(admin, props);
-  const running = await readRunningConfig(admin);
-  const before = configDigest(running);
-  const known = before === authority.stored || claimable(running, want.digest);
-  if (!authority.takeOver && !known) {
-    throw refuse(
-      admin,
-      `Caddy runs config ${short(before)}, which this stack did not load, and the Caddyfile adapts ` +
-        `to ${short(want.digest)} — loading it would replace every site that config serves. ` +
-        'Deploy with --adopt (or wrap the resource in adopt(true)) to take this Caddy over, or ' +
-        'point caddyProviders() at the Caddy you meant.',
-    );
-  }
-  let warnings = want.warnings;
-  const loaded = before !== want.digest;
-  if (loaded) {
-    try {
-      warnings = await loadCaddyfile(admin, props.caddyfile, props.sourceFile);
-    } catch (cause) {
-      if (!(cause instanceof CaddyAdminError)) throw cause;
-      // ★ SAY WHAT IS RUNNING NOW. Caddy restores the previous config on a failed load (caddy.go
-      //   changeConfig); confirm it rather than promise it, because the deploy log is where the
-      //   person decides whether sites are down.
-      const after = await readLive(admin).catch(() => undefined);
-      const state =
-        after === undefined
-          ? 'and the running config could not be read back'
-          : after.configSha256 === before
-            ? 'Caddy kept the previous config (still serving)'
-            : `and the running config is now ${short(after.configSha256)}, not the previous ${short(before)}`;
-      throw refuse(admin, `Caddy refused the Caddyfile — ${cause.message}; ${state}`);
-    }
-  }
-  // ⚠️ READ BACK, never echo the declaration: a concurrent writer, or a load Caddy answered 200 but
-  //   did not apply (admin-calls.ts), shows up here as a refusal instead of as stored state that is
-  //   already wrong.
-  const attributes = await readLive(admin, props.sourceFile);
-  if (attributes.configSha256 !== want.digest) {
-    throw refuse(
-      admin,
-      `after the load Caddy runs config ${short(attributes.configSha256)}, not the ` +
-        `${short(want.digest)} this Caddyfile adapts to — another writer changed it, or it was not applied`,
-    );
-  }
-  return { attributes, loaded, warnings };
-};
+  });

package/src/caddy/config-reconcile.ts

@@ -0,0 +1,138 @@
+/**
+ * CaddyConfig's diff / reconcile — the apply half of the lifecycle config-lifecycle.ts's
+ * `desiredConfig`/`readLive`/`probeLive` compute the inputs for. Split out at the 250-line file
+ * cap; the two files together are one lifecycle, read config-lifecycle.ts's module doc first.
+ */
+import * as Effect from 'effect/Effect';
+import * as Result from 'effect/Result';
+import type * as Diff from 'alchemy/Diff';
+import type * as Caddy from '@distilled.cloud/caddy';
+import { CaddyAdminService } from './admin.ts';
+import { loadCaddyfile, readRunningConfig } from './admin-calls.ts';
+import { isUnreachable } from './caddy-http-client.ts';
+import { messageOf, refuse, short, wrapOperation } from './config-errors.ts';
+import type { CaddyConfigAttributes, CaddyConfigProps } from './config-form.ts';
+import { claimable, desiredConfig, readLive } from './config-lifecycle.ts';
+import { configDigest } from './digest.ts';
+
+/**
+ * ★ NEVER `replace`. Nothing in the props names a different object: a new Caddyfile is a reload of
+ *   the same Caddy, and `sourceFile` is a header. (Which Caddy is the transport's business — see
+ *   the ⚠️ on `endpoint` in the diff.)
+ */
+export const diffConfig = (
+  news: CaddyConfigProps,
+  output: CaddyConfigAttributes,
+): Effect.Effect<Diff.Diff, Error | Caddy.CaddyOpError, CaddyAdminService | Caddy.CaddyOpContext> =>
+  Effect.gen(function* () {
+    const { endpoint } = yield* CaddyAdminService;
+    const want = yield* desiredConfig(news);
+    const live = yield* readLive();
+    const converged =
+      want.digest === live.configSha256 &&
+      live.configSha256 === output.configSha256 &&
+      news.sourceFile === output.sourceFile &&
+      // ⚠️ A stack whose transport now reaches ANOTHER Caddy (a new address) must load there; the
+      //   old one keeps what it has — the same as a delete, which never unloads (see config.ts).
+      //   Planned as an update, but the state does not vouch for that Caddy: see Authority.
+      endpoint === output.endpoint;
+    return converged ? { action: 'noop' } : { action: 'update' };
+  });
+
+export type Applied = {
+  readonly attributes: CaddyConfigAttributes;
+  /** The adapter's warnings (e.g. "Caddyfile input is not formatted") — log them, never refuse. */
+  readonly warnings: readonly string[];
+  /** Whether a `POST /load` was sent (false when Caddy already ran this config). */
+  readonly loaded: boolean;
+};
+
+/**
+ * What this apply may load over — config.ts decides from the state and the adopt setting:
+ *   · `takeOver` — any running config: the state was applied to THIS Caddy (an update, drift
+ *     correction, or a create the engine adopted), or adoption is on (`--adopt`, or the
+ *     resource's own `adopt(true)` — ownership/adopt.ts adoptEnabled).
+ *   · otherwise only a claimable one — plus, as `stored`, the digest the state last recorded: a
+ *     Caddy reached at a NEW endpoint that runs exactly that is the same config under another name.
+ */
+export type Authority = { readonly takeOver: boolean; readonly stored?: string };
+
+/**
+ * Load the Caddyfile unless Caddy already runs it, then read it back and insist it matches.
+ * ⛔ WITHOUT `takeOver`, A CONFIG THE STACK CANNOT CLAIM IS NEVER LOADED OVER. The engine's adoption
+ *   probe cannot guard every create: it is skipped while `news` holds an Output — ALWAYS on
+ *   caddyWithFile's first deploy (`sourceFile` is its HostFile's path) — and a Caddy that was down at
+ *   plan time read as nothing. Nor does state vouch for a Caddy the transport NOW reaches at another
+ *   endpoint (diff plans that as an update). Refused here, before any `/load`, like HostFile's.
+ */
+export const reconcileConfig = (
+  props: CaddyConfigProps,
+  authority: Authority,
+): Effect.Effect<Applied, Error | Caddy.CaddyOpError, CaddyAdminService | Caddy.CaddyOpContext> =>
+  Effect.gen(function* () {
+    const { endpoint } = yield* CaddyAdminService;
+    const want = yield* desiredConfig(props);
+    const running = yield* readRunningConfig().pipe(wrapOperation(endpoint, 'GET /config/'));
+    const before = configDigest(running);
+    const known = before === authority.stored || claimable(running, want.digest);
+    if (!authority.takeOver && !known) {
+      return yield* Effect.fail(
+        refuse(
+          endpoint,
+          `Caddy runs config ${short(before)}, which this stack did not load, and the Caddyfile ` +
+            `adapts to ${short(want.digest)} — loading it would replace every site that config ` +
+            'serves. Deploy with --adopt (or wrap the resource in adopt(true)) to take this Caddy ' +
+            'over, or point caddyProviders() at the Caddy you meant.',
+        ),
+      );
+    }
+    let warnings = want.warnings;
+    const loaded = before !== want.digest;
+    if (loaded) {
+      const outcome = yield* Effect.result(loadCaddyfile(props.caddyfile, props.sourceFile));
+      if (Result.isFailure(outcome)) {
+        const error = outcome.failure;
+        // ⚠️ Caddy going unreachable MID-load is not a refusal — nothing to "say what's running
+        //   now" about, and re-sending it is unsafe (admin-calls.ts's module doc). Propagated raw,
+        //   still narrowable, matching every other unreachable path in this file.
+        if (isUnreachable(error)) return yield* Effect.fail(error);
+        // ★ SAY WHAT IS RUNNING NOW. Caddy restores the previous config on a failed load (caddy.go
+        //   changeConfig); confirm it rather than promise it, because the deploy log is where the
+        //   person decides whether sites are down.
+        const afterRead = yield* Effect.result(readLive());
+        const after = Result.isSuccess(afterRead) ? afterRead.success : undefined;
+        const state =
+          after === undefined
+            ? 'and the running config could not be read back'
+            : after.configSha256 === before
+              ? 'Caddy kept the previous config (still serving)'
+              : `and the running config is now ${short(after.configSha256)}, not the previous ${short(before)}`;
+        // ⚠️ SAY SO WHEN THE STATUS LIED, or a bare "refused" reads like a normal 4xx/5xx.
+        //   `LoadRefused` IS the 200-embedded-error trap (admin-calls.ts's module doc): Caddy
+        //   answered 200, and the failure was only in the body.
+        const reason =
+          error._tag === 'LoadRefused'
+            ? `${error.message} (LoadRefused: a 200 whose body carried the error, not a failure status)`
+            : messageOf(error);
+        return yield* Effect.fail(
+          refuse(endpoint, `Caddy refused the Caddyfile — ${reason}; ${state}`),
+        );
+      }
+      warnings = outcome.success;
+    }
+    // ⚠️ READ BACK, never echo the declaration: a concurrent writer, or a load Caddy answered 200 but
+    //   did not apply (admin-calls.ts), shows up here as a refusal instead of as stored state that is
+    //   already wrong.
+    const attributes = yield* readLive(props.sourceFile);
+    if (attributes.configSha256 !== want.digest) {
+      return yield* Effect.fail(
+        refuse(
+          endpoint,
+          `after the load Caddy runs config ${short(attributes.configSha256)}, not the ` +
+            `${short(want.digest)} this Caddyfile adapts to — another writer changed it, or it was ` +
+            'not applied',
+        ),
+      );
+    }
+    return { attributes, loaded, warnings };
+  });