@homeflare/alchemy 0.7.0 → 0.10.0

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

@@ -0,0 +1,235 @@
+/**
+ * Ownership with no state — decision 2026-09-21: CaddyConfig never adopts silently. The adoption
+ * probe (`read` with no output) and the apply of a create the engine never probed must agree on
+ * what is claimable: the declared config itself, or a Caddy serving nothing. Anything else is
+ * `Unowned` at plan time and refused at apply, unless the deploy runs with `--adopt` — and state
+ * lends authority only over the Caddy it was applied to.
+ */
+import { afterEach, describe, expect, test } from 'bun:test';
+import { AdoptPolicy, Unowned } from 'alchemy/AdoptPolicy';
+import { AlchemyContext } from 'alchemy/AlchemyContext';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import { type CaddyAdmin, CaddyUnreachableError, caddyAdminLayer } from './admin.ts';
+import { CaddyConfig, CaddyConfigProvider } from './config.ts';
+import { probeLive, reconcileConfig } from './config-lifecycle.ts';
+import { configDigest } from './digest.ts';
+import { type FakeCaddy, fakeDefaultCaddy } from './fake-caddy.ts';
+
+const SITE = 'app.example.com reverse_proxy 127.0.0.1:8080';
+/** A config someone else loaded: it serves a site, and it is not what the stack declares. */
+const FOREIGN = { apps: { http: { servers: { legacy: { listen: [':80'] } } } } };
+const ids = { fqn: 'stack/caddy', id: 'caddy', instanceId: 'i-1' };
+
+let fake: FakeCaddy | undefined;
+afterEach(() => {
+  fake?.stop();
+  fake = undefined;
+});
+
+const setup = (running?: unknown) => {
+  const made = fakeDefaultCaddy(running);
+  fake = made.caddy;
+  return made;
+};
+
+/** A Caddy already running the declared config — as one started from caddyWithFile's file is. */
+const runningDeclared = () => {
+  const made = setup();
+  made.caddy.running = made.caddy.adapt(SITE);
+  return made;
+};
+
+const loads = (caddy: FakeCaddy) => caddy.seen.filter((call) => call.path === '/load');
+
+describe('the probe: read with no state', () => {
+  test('a Caddy already running the declared config is ours — adopting it changes nothing', async () => {
+    const { admin, caddy } = runningDeclared();
+    const probe = await probeLive(admin, SITE);
+    expect(probe).toMatchObject({ attributes: { configSha256: configDigest(caddy.adapt(SITE)) } });
+    expect(probe?.ours).toBe(true);
+    expect(loads(caddy)).toHaveLength(0);
+  });
+
+  test('a Caddy running any other config is not ours', async () => {
+    const { admin } = setup(FOREIGN);
+    const probe = await probeLive(admin, SITE, '/usr/local/etc/Caddyfile');
+    expect(probe?.ours).toBe(false);
+    expect(probe?.unchecked).toBeUndefined();
+    expect(probe?.attributes).toEqual({
+      configSha256: configDigest(FOREIGN),
+      endpoint: fake?.address ?? '',
+      sourceFile: '/usr/local/etc/Caddyfile',
+    });
+  });
+
+  test.each([
+    ['no config at all', null],
+    ['only an admin block', { admin: { listen: 'localhost:2019' } }],
+  ])('a Caddy serving nothing (%s) reads as absent: a create', async (_, running) => {
+    const { admin } = setup(running);
+    expect(await probeLive(admin, SITE)).toBeUndefined();
+  });
+
+  test.each([
+    ['does not adapt', 'SYNTAX_ERROR', /Error during parsing/],
+    ['is not plain text (a stripped Output)', undefined, /not plain text/],
+  ])('a declaration that %s is not ours — and never fails the read', async (_, text, reason) => {
+    // ⛔ The engine replays this read with an interrupted create's props: a throw here would fail
+    //   every later plan, the one carrying the fix included.
+    const { admin } = setup(FOREIGN);
+    const probe = await probeLive(admin, text);
+    expect(probe?.ours).toBe(false);
+    expect(probe?.unchecked).toMatch(reason);
+  });
+
+  test('Caddy vanishing mid-probe stays "no Caddy", never "not ours"', async () => {
+    const { admin } = setup(FOREIGN);
+    const flaky: CaddyAdmin = {
+      ...admin,
+      request: (call) =>
+        call.path === '/adapt'
+          ? Promise.reject(new CaddyUnreachableError('gone'))
+          : admin.request(call),
+    };
+    await expect(probeLive(flaky, SITE)).rejects.toThrow('gone');
+  });
+});
+
+/** A create the engine never probed, or state from another endpoint (config.ts decides which). */
+describe('the apply without authority over the running config', () => {
+  test('without authority, a config the stack cannot claim is refused before any load', async () => {
+    const { admin, caddy } = setup(FOREIGN);
+    await expect(reconcileConfig(admin, { caddyfile: SITE }, { takeOver: false })).rejects.toThrow(
+      /which this stack did not load.*Deploy with --adopt/,
+    );
+    expect(loads(caddy)).toHaveLength(0);
+    expect(caddy.running).toEqual(FOREIGN);
+  });
+
+  test('the declared config already running is taken as it is — no load', async () => {
+    const { admin, caddy } = runningDeclared();
+    const applied = await reconcileConfig(admin, { caddyfile: SITE }, { takeOver: false });
+    expect(applied.loaded).toBe(false);
+    expect(loads(caddy)).toHaveLength(0);
+  });
+
+  test('a Caddy serving nothing is loaded — there is nothing to take over', async () => {
+    const { admin, caddy } = setup();
+    const applied = await reconcileConfig(admin, { caddyfile: SITE }, { takeOver: false });
+    expect(applied.loaded).toBe(true);
+    expect(configDigest(caddy.running)).toBe(configDigest(caddy.adapt(SITE)));
+  });
+
+  test('the config the state last stored is known — the same Caddy at a new endpoint', async () => {
+    const { admin } = setup(FOREIGN);
+    const authority = { stored: configDigest(FOREIGN), takeOver: false };
+    expect((await reconcileConfig(admin, { caddyfile: SITE }, authority)).loaded).toBe(true);
+  });
+
+  test('with authority, the foreign config is replaced', async () => {
+    const { admin, caddy } = setup(FOREIGN);
+    const applied = await reconcileConfig(admin, { caddyfile: SITE }, { takeOver: true });
+    expect(applied.loaded).toBe(true);
+    expect(configDigest(caddy.running)).toBe(configDigest(caddy.adapt(SITE)));
+  });
+});
+
+type Deploy = { readonly adopt?: boolean; readonly contextAdopt?: boolean };
+
+/** The provider over `admin`, run under the services a deploy provides (the CLI's `--adopt`). */
+const withProvider = <A>(
+  admin: CaddyAdmin,
+  deploy: Deploy,
+  use: (p: Effect.Success<typeof CaddyConfig.Provider>) => Effect.Effect<A, unknown>,
+) => {
+  let program = Effect.gen(function* () {
+    return yield* use(yield* CaddyConfig.Provider);
+  }).pipe(Effect.provide(CaddyConfigProvider().pipe(Layer.provide(caddyAdminLayer(admin)))));
+  if (deploy.adopt !== undefined) {
+    program = program.pipe(Effect.provideService(AdoptPolicy, deploy.adopt));
+  }
+  if (deploy.contextAdopt !== undefined) {
+    const context = { adopt: deploy.contextAdopt, dev: false, dotAlchemy: '.alchemy' };
+    program = program.pipe(Effect.provideService(AlchemyContext, context));
+  }
+  return Effect.runPromise(program);
+};
+
+const read = (admin: CaddyAdmin, caddyfile: unknown, output?: object) =>
+  withProvider(admin, {}, (provider) => {
+    if (provider.read === undefined) throw new Error('provider has no read handler');
+    return provider.read({ ...ids, olds: { caddyfile } as never, output: output as never });
+  });
+
+/** Apply, then check that exactly the expected loads reached Caddy — or none, and why. */
+const expectApply = async (applying: Promise<unknown>, caddy: FakeCaddy, loaded: boolean) => {
+  if (loaded) await applying;
+  else await expect(applying).rejects.toThrow(/Deploy with --adopt/);
+  expect(loads(caddy)).toHaveLength(loaded ? 1 : 0);
+};
+
+const reconcile = (admin: CaddyAdmin, deploy: Deploy, output?: object) =>
+  withProvider(admin, deploy, (provider) =>
+    provider.reconcile({
+      ...ids,
+      bindings: [] as never,
+      news: { caddyfile: SITE },
+      olds: undefined,
+      output: output as never,
+      session: undefined as never,
+    }),
+  );
+
+describe('CaddyConfigProvider', () => {
+  test('read: Unowned with no state, plain with state, plain when it is the declared config', async () => {
+    const { admin, caddy } = setup(FOREIGN);
+    const probe = await read(admin, SITE);
+    expect(Unowned.is(probe)).toBe(true);
+    expect(probe).toMatchObject({ configSha256: configDigest(FOREIGN) });
+    const owned = await read(admin, SITE, { configSha256: 'stored', endpoint: caddy.address });
+    expect(owned).toBeDefined();
+    expect(Unowned.is(owned)).toBe(false);
+    caddy.running = caddy.adapt(SITE);
+    const same = await read(admin, SITE);
+    expect(same).toBeDefined();
+    expect(Unowned.is(same)).toBe(false);
+  });
+
+  test('read with no state: nothing served is a create; an unreadable declaration is Unowned', async () => {
+    expect(await read(setup().admin, SITE)).toBeUndefined();
+    fake?.stop();
+    const { admin } = setup(FOREIGN);
+    expect(Unowned.is(await read(admin, 'SYNTAX_ERROR'))).toBe(true);
+    expect(Unowned.is(await read(admin, {}))).toBe(true);
+  });
+
+  test.each([
+    ['no adopt setting at all', {}, false],
+    ['AdoptPolicy off', { adopt: false }, false],
+    ['--adopt (AdoptPolicy)', { adopt: true }, true],
+    ['--adopt reaching only AlchemyContext', { contextAdopt: true }, true],
+    ['AdoptPolicy off over AlchemyContext on', { adopt: false, contextAdopt: true }, false],
+  ] as const)('reconcile with no state, %s', async (_, deploy, loaded) => {
+    const { admin, caddy } = setup(FOREIGN);
+    await expectApply(reconcile(admin, deploy), caddy, loaded);
+  });
+
+  test('reconcile with state for this Caddy loads over anything, without --adopt', async () => {
+    // ★ An update correcting drift (a hand edit since the stored digest), or an adopted create.
+    const { admin, caddy } = setup(FOREIGN);
+    const output = { configSha256: 'before-a-hand-edit', endpoint: caddy.address };
+    await expectApply(reconcile(admin, {}, output), caddy, true);
+  });
+
+  test.each([
+    ['a config it never stored, without --adopt', 'stored-elsewhere', {}, false],
+    ['a config it never stored, with --adopt', 'stored-elsewhere', { adopt: true }, true],
+    ['the config it last stored (the same Caddy, renamed)', configDigest(FOREIGN), {}, true],
+  ] as const)('reconcile with state from another endpoint: %s', async (_, sha, deploy, loaded) => {
+    // ⛔ State vouches for the Caddy it was applied to — not for whatever the transport now reaches.
+    const { admin, caddy } = setup(FOREIGN);
+    const output = { configSha256: sha, endpoint: 'unix:///run/elsewhere.sock' };
+    await expectApply(reconcile(admin, deploy, output), caddy, loaded);
+  });
+});

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

@@ -4,10 +4,9 @@
  */
 import { afterEach, describe, expect, test } from 'bun:test';
 import type { CaddyAdmin } from './admin.ts';
-import { type FakeCaddy, fakeCaddy } from './fake-caddy.ts';
+import { type FakeCaddy, fakeDefaultCaddy } from './fake-caddy.ts';
 import { configDigest } from './digest.ts';
 import { diffConfig, readLive, reconcileConfig } from './config-lifecycle.ts';
-import { localCaddyAdmin } from './local-admin.ts';
 
 const SITE = 'app.example.com reverse_proxy 127.0.0.1:8080';
 const OTHER = 'www.example.com respond <hello> & bye';
@@ -18,27 +17,22 @@ afterEach(() => {
   fake = undefined;
 });
 
-/**
- * ★ Addressed as a Caddy on its DEFAULT :2019 behind a forward (`hostHeader`), so a Caddyfile with
- *   no `admin` line — the common case — passes the guard. A Caddy reached on any other port needs
- *   `admin <address>` declared, or the first load would move it (admin-guard.ts).
- */
+/** A Caddy on its default :2019 (fake-caddy.ts fakeDefaultCaddy), stopped after each test. */
 const setup = (running?: unknown) => {
-  fake = fakeCaddy({ listenPort: 2019, ...(running === undefined ? {} : { running }) });
-  const admin = localCaddyAdmin({
-    address: fake.address,
-    hostHeader: '127.0.0.1:2019',
-    retries: 0,
-  });
-  return { admin, caddy: fake };
+  const made = fakeDefaultCaddy(running);
+  fake = made.caddy;
+  return made;
 };
 
+/** ★ These are the resource's own applies (it has state); config-adopt.test.ts covers a create. */
+const OWNED = { takeOver: true } as const;
+
 const loads = (caddy: FakeCaddy) => caddy.seen.filter((call) => call.path === '/load');
 
 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 });
+    const applied = await reconcileConfig(admin, { caddyfile: OTHER }, OWNED);
     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)));
@@ -50,8 +44,8 @@ describe('apply', () => {
 
   test('a Caddy already running this config is not reloaded', async () => {
     const { admin, caddy } = setup();
-    await reconcileConfig(admin, { caddyfile: SITE });
-    const again = await reconcileConfig(admin, { caddyfile: SITE });
+    await reconcileConfig(admin, { caddyfile: SITE }, OWNED);
+    const again = await reconcileConfig(admin, { caddyfile: SITE }, OWNED);
     expect(again.loaded).toBe(false);
     expect(loads(caddy)).toHaveLength(1);
   });
@@ -59,7 +53,7 @@ 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 });
+    const applied = await reconcileConfig(admin, { caddyfile: SITE, sourceFile: path }, OWNED);
     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);
@@ -67,7 +61,7 @@ describe('apply', () => {
 
   test('adapter warnings are returned, not refused', async () => {
     const { admin } = setup();
-    const applied = await reconcileConfig(admin, { caddyfile: `${SITE}\t` });
+    const applied = await reconcileConfig(admin, { caddyfile: `${SITE}\t` }, OWNED);
     expect(applied.warnings).toEqual(['Caddyfile:1: Caddyfile input is not formatted']);
   });
 });
@@ -75,33 +69,33 @@ 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 });
+    await reconcileConfig(admin, { caddyfile: SITE }, OWNED);
     const before = caddy.running;
-    await expect(reconcileConfig(admin, { caddyfile: `${SITE}\nPROVISION_ERROR` })).rejects.toThrow(
-      /address already in use.*kept the previous config/,
-    );
+    await expect(
+      reconcileConfig(admin, { caddyfile: `${SITE}\nPROVISION_ERROR` }, OWNED),
+    ).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 });
+    await reconcileConfig(admin, { caddyfile: SITE }, OWNED);
     await expect(
-      reconcileConfig(admin, { caddyfile: `${SITE}\t\nPROVISION_ERROR` }),
+      reconcileConfig(admin, { caddyfile: `${SITE}\t\nPROVISION_ERROR` }, OWNED),
     ).rejects.toThrow(/→ 200: loading config.*error in a 200 body.*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 });
+    await reconcileConfig(admin, { caddyfile: SITE }, OWNED);
     // ⚠️ 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 })).rejects.toThrow(
+    await expect(reconcileConfig(swallowing, { caddyfile: OTHER }, OWNED)).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)));
@@ -109,7 +103,7 @@ describe('a config Caddy refuses', () => {
 
   test('a Caddyfile that does not adapt is refused before any load', async () => {
     const { admin, caddy } = setup();
-    await expect(reconcileConfig(admin, { caddyfile: 'SYNTAX_ERROR' })).rejects.toThrow(
+    await expect(reconcileConfig(admin, { caddyfile: 'SYNTAX_ERROR' }, OWNED)).rejects.toThrow(
       /\/adapt → 400: Caddyfile:1 - Error during parsing/,
     );
     expect(loads(caddy)).toHaveLength(0);
@@ -122,7 +116,9 @@ describe('refused before anything is sent', () => {
     ['an empty Caddyfile', '  \n'],
   ])('%s', async (_, caddyfile) => {
     const { admin, caddy } = setup();
-    await expect(reconcileConfig(admin, { caddyfile })).rejects.toThrow(/Caddy\.Config at http/);
+    await expect(reconcileConfig(admin, { caddyfile }, OWNED)).rejects.toThrow(
+      /Caddy\.Config at http/,
+    );
     expect(caddy.seen).toHaveLength(0);
   });
 
@@ -131,15 +127,15 @@ 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 })).rejects.toThrow(/adapts to no apps/);
+    await expect(reconcileConfig(admin, { caddyfile }, OWNED)).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}` })).rejects.toThrow(
-      /admin off/,
-    );
+    await expect(
+      reconcileConfig(admin, { caddyfile: `admin off\n${SITE}` }, OWNED),
+    ).rejects.toThrow(/admin off/);
     expect(loads(caddy)).toHaveLength(0);
   });
 });
@@ -147,7 +143,7 @@ describe('refused before anything is sent', () => {
 describe('drift', () => {
   const applied = async () => {
     const { admin, caddy } = setup();
-    const { attributes } = await reconcileConfig(admin, { caddyfile: SITE });
+    const { attributes } = await reconcileConfig(admin, { caddyfile: SITE }, OWNED);
     return { admin, attributes, caddy };
   };
 
@@ -165,7 +161,7 @@ describe('drift', () => {
     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 });
+    const again = await reconcileConfig(admin, { caddyfile: SITE }, OWNED);
     expect(again.attributes.configSha256).toBe(attributes.configSha256);
   });
 
@@ -198,21 +194,3 @@ describe('drift', () => {
     expect(diff).toEqual({ action: 'update' });
   });
 });
-
-describe('adopt', () => {
-  test('a running Caddy reads as its live config; the first apply replaces it', async () => {
-    const { admin, caddy } = setup({
-      apps: { http: { servers: { legacy: { listen: [':80'] } } } },
-    });
-    const adopted = await readLive(admin);
-    expect(adopted.configSha256).toBe(configDigest(caddy.running));
-    expect(await diffConfig(admin, { caddyfile: SITE }, adopted)).toEqual({ action: 'update' });
-    await reconcileConfig(admin, { caddyfile: SITE });
-    expect(configDigest(caddy.running)).toBe(configDigest(caddy.adapt(SITE)));
-  });
-
-  test('an empty Caddy (config null) is adoptable too', async () => {
-    const { admin } = setup();
-    expect((await readLive(admin)).configSha256).toBe(configDigest(null));
-  });
-});

package/src/caddy/config-lifecycle.ts

@@ -9,9 +9,11 @@
  *   · 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.
  */
 import type { Diff } from 'alchemy/Diff';
-import type { CaddyAdmin } from './admin.ts';
+import { type CaddyAdmin, CaddyUnreachableError } from './admin.ts';
 import {
   CaddyAdminError,
   adaptCaddyfile,
@@ -66,16 +68,75 @@ export const desiredConfig = async (
   return { digest: configDigest(adapted.config), warnings: adapted.warnings };
 };
 
-/** What is running now, as attributes. `sourceFile` is carried over, never discovered. */
-export const readLive = async (
+const attributesOf = (
   admin: CaddyAdmin,
+  running: unknown,
   sourceFile?: string,
-): Promise<CaddyConfigAttributes> => ({
-  configSha256: configDigest(await readRunningConfig(admin)),
+): CaddyConfigAttributes => ({
+  configSha256: configDigest(running),
   endpoint: admin.endpoint,
   ...(sourceFile === undefined ? {} : { sourceFile }),
 });
 
+/** What is running now, as attributes. `sourceFile` is carried over, never discovered. */
+export const readLive = async (
+  admin: CaddyAdmin,
+  sourceFile?: string,
+): Promise<CaddyConfigAttributes> =>
+  attributesOf(admin, await readRunningConfig(admin), sourceFile);
+
+/**
+ * ⛔ WITH NO STATE, A RUNNING CONFIG IS THIS STACK'S ONLY IF IT IS THE DECLARED ONE (decision,
+ *   2026-09-21: CaddyConfig must not adopt silently — the house rule HostFile and LaunchdJob keep).
+ *   Anything else was put there by a person, another tool or another stack, and loading over it
+ *   replaces every site it serves. ★ A config that serves nothing (`null`, or no apps) is claimable
+ *   too: there is nothing to take over, as an empty R2 lock rule set reads as no lock.
+ */
+export const claimable = (running: unknown, declaredDigest: string): boolean =>
+  servesNothing(running) || configDigest(running) === declaredDigest;
+
+export type Probe = {
+  readonly attributes: CaddyConfigAttributes;
+  /** The live config IS the declared one: adopting it changes nothing. */
+  readonly ours: boolean;
+  /** Why the declaration could not be compared, when it could not — the Caddy is then not ours. */
+  readonly unchecked?: string;
+};
+
+/**
+ * The adoption probe — `read` with no state: `undefined` when Caddy serves nothing (plan a create),
+ * else the live attributes and whether they are provably ours (the provider brands the rest
+ * `Unowned`, and the plan refuses them without `--adopt`).
+ * ⛔ IT NEVER THROWS OVER THE DECLARATION. The engine also runs this read to recover an interrupted
+ *   create, with THAT deploy's props (Plan.ts, `status: "creating"`) — so a Caddyfile that failed to
+ *   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,
+  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;
+    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
@@ -94,6 +155,7 @@ export const diffConfig = async (
     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' };
 };
@@ -106,13 +168,42 @@ export type Applied = {
   readonly loaded: boolean;
 };
 
-/** Load the Caddyfile unless Caddy already runs it, then read it back and insist it matches. */
+/**
+ * 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 before = configDigest(await readRunningConfig(admin));
+  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) {