@homeflare/alchemy 0.8.0 → 0.10.1

package/src/openbao/pki-role.ts

@@ -43,6 +43,9 @@ import { isResolved } from 'alchemy/Diff';
 import * as Provider from 'alchemy/Provider';
 import * as Effect from 'effect/Effect';
 import type * as HttpClient from 'effect/unstable/http/HttpClient';
+import { refuseTakeover } from '../ownership/adopt.ts';
+import { ownedRead } from '../ownership/probe.ts';
+import { provingResumes } from '../ownership/resume.ts';
 import { baoDelete, baoRead, baoWrite } from './bao-http.ts';
 import {
   type BaoPkiRoleAttributes,
@@ -95,8 +98,13 @@ export const BaoPkiRoleProvider = () =>
          */
         list: () => Effect.succeed([]),
 
-        read: Effect.fn(function* ({ olds }) {
-          return yield* readRole(olds);
+        /** ⛔ Stateless: `Unowned` unless our own interrupted create made it (ownership/probe.ts). */
+        read: Effect.fn(function* ({ fqn, instanceId, olds, output }) {
+          const found = yield* readRole(olds);
+          const ours = Effect.sync(
+            () => found !== undefined && problems(olds).length === 0 && matches(found, olds),
+          );
+          return yield* ownedRead({ fqn, instanceId, output }, found, ours);
         }),
 
         /**
@@ -119,6 +127,7 @@ export const BaoPkiRoleProvider = () =>
            *   and left the old one issuing certificates under no state record at all.
            */
           const move = yield* judgeRename(IDENTITY, olds, news, output);
+          // ★ No attributes: an unfinished generation, proven ours or not by provingResumes.
           if (output === undefined) return undefined;
           if (move !== undefined) return { action: 'replace' } as const;
           if (!isResolved(news)) return undefined;
@@ -137,7 +146,7 @@ export const BaoPkiRoleProvider = () =>
             : ({ action: 'update' } as const);
         }),
 
-        reconcile: Effect.fn(function* ({ news, output }) {
+        reconcile: Effect.fn(function* ({ fqn, instanceId, news, output }) {
           const path = rolePath(news);
           // ⛔ An `update` across a move the diff could not see — refused before any write.
           yield* guardRename(IDENTITY, news, output);
@@ -153,6 +162,8 @@ export const BaoPkiRoleProvider = () =>
             return yield* Effect.die(new Error(`Bao.PkiRole ${path}: ${bad.join(' ')}`));
           }
           const live = yield* readRole(news);
+          if (live !== undefined)
+            yield* refuseTakeover({ fqn, instanceId, output }, `Bao.PkiRole ${path}`);
           if (live === undefined || !matches(live, news)) {
             yield* baoWrite('PUT', path, writeBody(news));
           }
@@ -195,5 +206,5 @@ export const BaoPkiRoleProvider = () =>
           return undefined;
         }),
       }),
-    ),
+    ).pipe(Effect.map(provingResumes)),
   );

package/src/openbao/plugin-reconcile.ts

@@ -4,6 +4,7 @@
  */
 import * as Effect from 'effect/Effect';
 import type * as HttpClient from 'effect/unstable/http/HttpClient';
+import type { Claim } from '../ownership/adopt.ts';
 import type { BaoError } from './bao-status.ts';
 import {
   type BaoPluginAttributes,
@@ -39,18 +40,25 @@ const refuse = (form: BaoPluginForm, message: string) =>
  *   nothing, or finds an OLDER genuinely-unversioned entry. The Cloudflare engine reports one
  *   (`framework.Backend.RunningVersion`). REASONED FROM SOURCE, not measured against a server.
  * ⚠️ THE WRITE HAS ALREADY LANDED when this fires, so the catalog holds a registration no state
- *   record names. Declaring the reported version adopts it on the next deploy (same sha256 and
- *   command, so reconcile matches and writes nothing); declaring a DIFFERENT version is refused by
- *   the server itself (setInternal :1219-1221, "plugin version mismatch").
+ *   record names. Declaring the reported version and deploying once with `--adopt` adopts it (same
+ *   sha256 and command, so reconcile matches and writes nothing); declaring a DIFFERENT version is
+ *   refused by the server itself (setInternal :1219-1221, "plugin version mismatch").
+ * ⚠️ `--adopt`, NOT A SILENT RESUME (2026-09-21): the row this create left names the UNVERSIONED
+ *   entry, so it cannot prove the versioned one ours (docs/ownership.md).
  */
 const SELF_REPORTED =
   'the write succeeded but the read-back does not match. If the binary reports its own version, ' +
   'OpenBao filed the registration under it (plugin_catalog.go setInternal) — declare `version` ' +
-  'as exactly the version the binary reports; that adopts the entry this write just made.';
+  'as exactly the version the binary reports, and deploy once with --adopt: that adopts the ' +
+  'entry this write just made.';
 
-/** Register when the live entry differs, then prove it by reading back. Dies on a refusal. */
+/**
+ * Register when the live entry differs, then prove it by reading back. Dies on a refusal.
+ * ⛔ `claim` (the provider passes it): a create never takes over an entry already registered.
+ */
 export const reconcilePlugin = (
   props: BaoPluginProps,
+  claim?: Claim,
 ): Effect.Effect<BaoPluginAttributes, BaoError, HttpClient.HttpClient> =>
   Effect.gen(function* () {
     const form = resolve(props);
@@ -58,6 +66,9 @@ export const reconcilePlugin = (
     if (bad.length > 0) return yield* refuse(form, bad.join('; '));
 
     const found = yield* readEntry(form);
+    if (found !== undefined && claim !== undefined) {
+      yield* claim(`Bao.Plugin ${versionedPath(form.type, form.name, form.version)}`);
+    }
     if (found !== undefined && !matches(found.attributes, form)) {
       /**
        * ⛔ A DECLARATIVE OR OCI ENTRY BELONGS TO THE SERVER'S CONFIG FILE (`plugin` stanzas with

package/src/openbao/plugin.ts

@@ -24,11 +24,15 @@ import { isResolved } from 'alchemy/Diff';
 import * as Provider from 'alchemy/Provider';
 import * as Effect from 'effect/Effect';
 import type * as HttpClient from 'effect/unstable/http/HttpClient';
+import { claimFor } from '../ownership/adopt.ts';
+import { ownedRead } from '../ownership/probe.ts';
+import { provingResumes } from '../ownership/resume.ts';
 import {
   type BaoPluginAttributes,
   type BaoPluginProps,
   type BaoPluginType,
   matches,
+  problems,
   resolve,
   versionedPath,
 } from './plugin-form.ts';
@@ -81,9 +85,15 @@ export const BaoPluginProvider = () =>
          */
         list: () => Effect.succeed([]),
 
-        read: Effect.fn(function* ({ olds }) {
-          const found = yield* readEntry(resolve(olds));
-          return found?.attributes;
+        /** ⛔ Stateless: `Unowned` unless our own interrupted create made it (ownership/probe.ts). */
+        read: Effect.fn(function* ({ fqn, instanceId, olds, output }) {
+          const form = resolve(olds);
+          const found = yield* readEntry(form);
+          const ours = Effect.sync(
+            () =>
+              found !== undefined && problems(form).length === 0 && matches(found.attributes, form),
+          );
+          return yield* ownedRead({ fqn, instanceId, output }, found?.attributes, ours);
         }),
 
         /** ⛔ IT COMPARES THE LIVE ENTRY, NOT THE STORED DIGEST — a hand re-register is drift. */
@@ -95,6 +105,7 @@ export const BaoPluginProvider = () =>
            *   that is already registered fails the plan (rename-identity.ts).
            */
           const move = yield* judgeRename(IDENTITY, olds, news, output);
+          // ★ No attributes: an unfinished generation, proven ours or not by provingResumes.
           if (output === undefined) return undefined;
           if (move !== undefined) return { action: 'replace' } as const;
           if (!isResolved(news)) return undefined;
@@ -107,10 +118,10 @@ export const BaoPluginProvider = () =>
         }),
 
         /** The refusals — declarative, builtin, self-reported version — live in plugin-reconcile.ts. */
-        reconcile: Effect.fn(function* ({ news, output }) {
+        reconcile: Effect.fn(function* ({ fqn, instanceId, news, output }) {
           // ⛔ An `update` across a move the diff could not see — refused before any write.
           yield* guardRename(IDENTITY, news, output);
-          return yield* reconcilePlugin(news);
+          return yield* reconcilePlugin(news, claimFor({ fqn, instanceId, output }));
         }),
 
         /**
@@ -122,5 +133,5 @@ export const BaoPluginProvider = () =>
           return undefined;
         }),
       }),
-    ),
+    ).pipe(Effect.map(provingResumes)),
   );

package/src/openbao/policy.ts

@@ -5,6 +5,9 @@ import * as Effect from 'effect/Effect';
 import * as FileSystem from 'effect/FileSystem';
 import * as Path from 'effect/Path';
 import type * as HttpClient from 'effect/unstable/http/HttpClient';
+import { refuseTakeover } from '../ownership/adopt.ts';
+import { ownedRead } from '../ownership/probe.ts';
+import { provingResumes } from '../ownership/resume.ts';
 import { sha256 } from './digest.ts';
 import { isEmptyAssembly } from './policy-assembly.ts';
 import { deletePolicy, policyPath, readPolicy, writePolicy } from './policy-wire.ts';
@@ -138,9 +141,16 @@ export const BaoPolicyProvider = () =>
         list: () => Effect.succeed([]),
 
         // ★ '' means genuinely absent (a 404); a refusal fails. policy-wire.ts has the history.
-        read: Effect.fn(function* ({ olds }) {
+        // ⛔ With no attributes in state, a live policy is `Unowned` unless it is the one our own
+        //   interrupted create wrote: these fragments, byte for byte (ownership/probe.ts).
+        read: Effect.fn(function* ({ fqn, instanceId, olds, output }) {
           const live = yield* readPolicy(olds.name);
-          return live.length === 0 ? undefined : attributesOf(olds.name, live, 0);
+          const found = live.length === 0 ? undefined : attributesOf(olds.name, live, 0);
+          const ours = Effect.map(
+            assemble(olds.fragments),
+            (a) => sha256(a.joined) === found?.digest,
+          );
+          return yield* ownedRead({ fqn, instanceId, output }, found, ours);
         }),
 
         /**
@@ -161,6 +171,7 @@ export const BaoPolicyProvider = () =>
            *   PR (REPLACE.md).
            */
           const move = yield* judgeRename(IDENTITY, olds, news, output);
+          // ★ No attributes: an unfinished generation, proven ours or not by provingResumes.
           if (output === undefined) return undefined;
           if (move !== undefined) return { action: 'replace' } as const;
           // ⚠️ A prop can still be an unresolved Output or Config at plan time. Docker's
@@ -174,7 +185,7 @@ export const BaoPolicyProvider = () =>
             : ({ action: 'update' } as const);
         }),
 
-        reconcile: Effect.fn(function* ({ news, output }) {
+        reconcile: Effect.fn(function* ({ fqn, instanceId, news, output }) {
           const name = news.name;
           // ⛔ An `update` across a rename the diff could not see — refused before any write.
           yield* guardRename(IDENTITY, news, output);
@@ -207,6 +218,8 @@ export const BaoPolicyProvider = () =>
            *   sibling PVE provider does exactly this in pveOperations.reconcile.
            */
           const current = yield* readPolicy(name);
+          if (current.length > 0)
+            yield* refuseTakeover({ fqn, instanceId, output }, `Bao.Policy ${name}`);
           if (current.length > 0 && sha256(current) === sha256(joined)) {
             return attributesOf(name, joined, parts);
           }
@@ -231,5 +244,5 @@ export const BaoPolicyProvider = () =>
           return undefined;
         }),
       });
-    }),
+    }).pipe(Effect.map(provingResumes)),
   );

package/src/openbao/proxmox-role.ts

@@ -40,6 +40,9 @@ import { isResolved } from 'alchemy/Diff';
 import * as Provider from 'alchemy/Provider';
 import * as Effect from 'effect/Effect';
 import type * as HttpClient from 'effect/unstable/http/HttpClient';
+import { refuseTakeover } from '../ownership/adopt.ts';
+import { ownedRead } from '../ownership/probe.ts';
+import { provingResumes } from '../ownership/resume.ts';
 import { baoDelete, baoWrite } from './bao-http.ts';
 import {
   type BaoProxmoxRoleAttributes,
@@ -84,8 +87,11 @@ export const BaoProxmoxRoleProvider = () =>
          */
         list: () => Effect.succeed([]),
 
-        read: Effect.fn(function* ({ olds }) {
-          return yield* readRole(olds);
+        /** ⛔ Stateless: `Unowned` unless our own interrupted create made it (ownership/probe.ts). */
+        read: Effect.fn(function* ({ fqn, instanceId, olds, output }) {
+          const found = yield* readRole(olds);
+          const ours = Effect.sync(() => found !== undefined && matches(found, olds));
+          return yield* ownedRead({ fqn, instanceId, output }, found, ours);
         }),
 
         /**
@@ -107,6 +113,7 @@ export const BaoProxmoxRoleProvider = () =>
            *   resulting `update`.
            */
           const move = yield* judgeRename(IDENTITY, olds, news, output);
+          // ★ No attributes: an unfinished generation, proven ours or not by provingResumes.
           if (output === undefined) return undefined;
           if (move !== undefined) {
             const mintUser = declaredString(news, 'mintUser');
@@ -142,11 +149,13 @@ export const BaoProxmoxRoleProvider = () =>
           return { action: 'update' } as const;
         }),
 
-        reconcile: Effect.fn(function* ({ news, output }) {
+        reconcile: Effect.fn(function* ({ fqn, instanceId, news, output }) {
           const path = rolePath(news.mount, news.name);
           // ⛔ An `update` across a move the diff could not see — refused before any read or write.
           yield* guardRename(IDENTITY, news, output);
           const live = yield* readRole(news);
+          if (live !== undefined)
+            yield* refuseTakeover({ fqn, instanceId, output }, `Bao.ProxmoxRole ${path}`);
           /**
            * ⛔ A mint_user CHANGE RE-SCOPES EVERY CREDENTIAL THE ROLE WILL EVER MINT, SILENTLY.
            *   The minted token inherits that PVE user's standing ACL and nothing else, so
@@ -226,5 +235,5 @@ export const BaoProxmoxRoleProvider = () =>
           return undefined;
         }),
       }),
-    ),
+    ).pipe(Effect.map(provingResumes)),
   );

package/src/openbao/rename-adoption.test.ts

@@ -1,15 +1,15 @@
 /**
- * The swap the plan-time guard cannot see: a NEW declaration of a name that is live. 🔴 MEASURED
- * 2026-09-21 through Alchemy's own plan and apply (fake-stack.ts). With no state row, the engine asks
- * `read`, which finds the object and answers plain attributes, so Alchemy silently adopts it
- * (alchemy@2.0.0-beta.79 Plan.ts, the adoption probe; AdoptPolicy.ts). Nothing moved, so
- * `judgeMove` never runs. Under `RemovalPolicy.destroy()` the old owner's delete then runs in
- * Apply's phase 2, after the adoption has written, and removes the object the new declaration now
- * claims. The deploy is green.
- *
- * ★ These pin that, and the two ways round it REPLACE.md gives: `renamedFrom` for a logical id that
- *   changes, and a second deploy for a name another resource is leaving. If one of the hazards stops
- *   reproducing, the engine changed: re-read REPLACE.md before relaxing it.
+ * The swap the plan-time rename guard cannot see: a NEW declaration of a name that is live.
+ * 🔴 MEASURED 2026-09-21 through Alchemy's own plan and apply (fake-stack.ts), before the ownership
+ * rule: with no state row the engine asked `read`, which answered plain attributes, so Alchemy
+ * silently adopted the object (alchemy@2.0.0-beta.79 Plan.ts, the adoption probe; AdoptPolicy.ts).
+ * Under `RemovalPolicy.destroy()` the old owner's delete then ran in Apply's phase 2 and removed the
+ * object the new declaration claimed — in a green deploy.
+ * ★ NOW (decided 2026-09-21): the probe answers `Unowned` for any live object (ownership/probe.ts),
+ *   so that plan FAILS before anything is written, and the takeover happens only when asked for —
+ *   which is exactly the old hazard, on purpose. These pin both, and the two ways round it
+ *   REPLACE.md gives: `renamedFrom` for a logical id that changes, and a second deploy for a name
+ *   another resource is leaving.
  *
  * ⛔ TEST-ONLY. Every value is a placeholder, not the estate's.
  */
@@ -25,14 +25,25 @@ const { destroy } = RemovalPolicy;
 
 /** No delete endpoint (jwt-config.ts), and a delete the provider refuses (mfa-enforcement.ts). */
 const KEEPS = new Set(['Bao.JwtAuthConfig', 'Bao.MfaLoginEnforcement']);
-const REFUSES_DELETE = /Bao\.MfaLoginEnforcement/;
+const REFUSES_DELETE = /Bao\.MfaLoginEnforcement a: REFUSING to delete/;
+const NOT_OWNED = /Cannot adopt resource 'Z'.*--adopt/s;
 
 describe('a logical id changed without renamedFrom, under destroy', () => {
   for (const row of FAMILIES) {
-    it(`${row.family}: the orphan delete removes what the new id just adopted`, async () => {
+    it(`${row.family}: the plan refuses the live name, and nothing is written or deleted`, async () => {
+      await withEstate(async (stack, estate, seen) => {
+        await stack.deploy(row.declare('X', 'a', '15m', destroy));
+        seen.length = 0;
+        await assert.rejects(stack.deploy(row.declare('Z', 'a', '15m', destroy)), NOT_OWNED);
+        assert.deepEqual(writesOf(seen), []);
+        assert.ok(row.has(estate, 'a'));
+      });
+    });
+
+    it(`${row.family}: --adopt is the takeover, and the old id's delete follows it`, async () => {
       await withEstate(async (stack, estate) => {
         await stack.deploy(row.declare('X', 'a', '15m', destroy));
-        const again = stack.deploy(row.declare('Z', 'a', '15m', destroy));
+        const again = stack.deploy(row.declare('Z', 'a', '15m', destroy), { adopt: true });
         if (row.family === 'Bao.MfaLoginEnforcement') await assert.rejects(again, REFUSES_DELETE);
         else assert.deepEqual(await again, { X: 'delete', Z: 'adopted' });
         assert.equal(row.has(estate, 'a'), KEEPS.has(row.family));
@@ -55,19 +66,21 @@ describe('the ways round it', () => {
     });
   });
 
-  it('a name another resource moves off is lost when taken in the same deploy', async () => {
-    await withEstate(async (stack, estate) => {
+  it('a name another resource moves off is refused when taken in the same deploy', async () => {
+    await withEstate(async (stack, estate, seen) => {
       await stack.deploy(row.declare('X', 'a', '15m', destroy));
+      seen.length = 0;
       const both = Effect.gen(function* () {
         yield* row.declare('X', 'b', '15m', destroy);
         yield* row.declare('Z', 'a', '30m', destroy);
       });
-      assert.deepEqual(await stack.deploy(both), { X: 'replace', Z: 'adopted' });
-      assert.ok(row.has(estate, 'b') && !row.has(estate, 'a'));
+      await assert.rejects(stack.deploy(both), NOT_OWNED);
+      assert.deepEqual(writesOf(seen), []);
+      assert.ok(row.has(estate, 'a') && !row.has(estate, 'b'));
     });
   });
 
-  it('and survives when taken in the deploy after the move', async () => {
+  it('and succeeds when taken in the deploy after the move', async () => {
     await withEstate(async (stack, estate) => {
       await stack.deploy(row.declare('X', 'a', '15m', destroy));
       await stack.deploy(row.declare('X', 'b', '15m', destroy));

package/src/openbao/role-reconcile.ts

@@ -15,6 +15,8 @@
  */
 import * as Effect from 'effect/Effect';
 import type * as HttpClient from 'effect/unstable/http/HttpClient';
+import type { Claim, Owner } from '../ownership/adopt.ts';
+import { ownedRead } from '../ownership/probe.ts';
 import { baoRead, baoWrite } from './bao-http.ts';
 import type { BaoError } from './bao-status.ts';
 
@@ -40,6 +42,21 @@ export const readRoleAt = <A>(
     live === undefined ? undefined : { attributes: spec.attributesOf(live), live },
   );
 
+/**
+ * `read`: the live attributes — `Unowned` with no state unless our own interrupted create wrote
+ * them, which is `planRole`'s `noop` against that create's props (ownership/probe.ts).
+ */
+export const readOwnedRole = <A extends object>(
+  ask: Owner,
+  spec: RoleSpec<A>,
+): Effect.Effect<A | undefined, BaoError, HttpClient.HttpClient> =>
+  Effect.flatMap(readRoleAt(spec), (found) => {
+    const ours = Effect.sync(
+      () => found !== undefined && spec.problems.length === 0 && spec.matches(found.attributes),
+    );
+    return ownedRead(ask, found?.attributes, ours);
+  });
+
 /** `update` or `noop` — the part of a diff after the identity checks. */
 export const planRole = <A>(
   spec: RoleSpec<A>,
@@ -53,12 +70,18 @@ export const planRole = <A>(
 const refuse = (spec: { readonly family: string; readonly path: string }, message: string) =>
   Effect.die(new Error(`${spec.family} ${spec.path}: ${message}`));
 
+/**
+ * ⛔ `claim` — every provider passes it — refuses, before any write, a create that finds a live
+ *   object this stack holds no state for (ownership/adopt.ts).
+ */
 export const reconcileRole = <A>(
   spec: RoleSpec<A>,
+  claim?: Claim,
 ): Effect.Effect<A, BaoError, HttpClient.HttpClient> =>
   Effect.gen(function* () {
     if (spec.problems.length > 0) return yield* refuse(spec, spec.problems.join('; '));
     const found = yield* readRoleAt(spec);
+    if (found !== undefined && claim !== undefined) yield* claim(`${spec.family} ${spec.path}`);
     if (found === undefined || !spec.matches(found.attributes)) {
       const lost = found === undefined ? [] : (spec.wouldErase?.(found.live) ?? []);
       if (lost.length > 0) {

package/src/openbao/ssh-role.ts

@@ -36,6 +36,9 @@ import { isResolved } from 'alchemy/Diff';
 import * as Provider from 'alchemy/Provider';
 import * as Effect from 'effect/Effect';
 import type * as HttpClient from 'effect/unstable/http/HttpClient';
+import { refuseTakeover } from '../ownership/adopt.ts';
+import { ownedRead } from '../ownership/probe.ts';
+import { provingResumes } from '../ownership/resume.ts';
 import { baoDelete, baoRead, baoWrite } from './bao-http.ts';
 import {
   type BaoSshRoleAttributes,
@@ -91,9 +94,13 @@ export const BaoSshRoleProvider = () =>
          */
         list: () => Effect.succeed([]),
 
-        read: Effect.fn(function* ({ olds }) {
+        /** ⛔ Stateless: `Unowned` unless our own interrupted create made it (ownership/probe.ts). */
+        read: Effect.fn(function* ({ fqn, instanceId, olds, output }) {
           const found = yield* readRole(resolve(olds));
-          return found?.attributes;
+          const ours = Effect.sync(
+            () => found !== undefined && matches(found.attributes, resolve(olds)),
+          );
+          return yield* ownedRead({ fqn, instanceId, output }, found?.attributes, ours);
         }),
 
         /**
@@ -115,6 +122,7 @@ export const BaoSshRoleProvider = () =>
            *   ⛔ a move onto a role that exists fails the plan (rename-identity.ts).
            */
           const move = yield* judgeRename(IDENTITY, olds, news, output);
+          // ★ No attributes: an unfinished generation, proven ours or not by provingResumes.
           if (output === undefined) return undefined;
           if (move !== undefined) return { action: 'replace' } as const;
           if (!isResolved(news)) return undefined;
@@ -126,7 +134,7 @@ export const BaoSshRoleProvider = () =>
             : ({ action: 'update' } as const);
         }),
 
-        reconcile: Effect.fn(function* ({ news, output }) {
+        reconcile: Effect.fn(function* ({ fqn, instanceId, news, output }) {
           const form = resolve(news);
           const path = readPath(form.mount, form.name);
           // ⛔ An `update` across a move the diff could not see — refused before any write.
@@ -157,6 +165,8 @@ export const BaoSshRoleProvider = () =>
           }
 
           const found = yield* readRole(form);
+          if (found !== undefined)
+            yield* refuseTakeover({ fqn, instanceId, output }, `Bao.SshRole ${path}`);
           if (found === undefined || !matches(found.attributes, form)) {
             if (found !== undefined) {
               const lost = wouldErase(found.live);
@@ -197,5 +207,5 @@ export const BaoSshRoleProvider = () =>
           return undefined;
         }),
       }),
-    ),
+    ).pipe(Effect.map(provingResumes)),
   );

package/src/ownership/adopt.ts

@@ -0,0 +1,122 @@
+/**
+ * Whether a live object this stack holds no state for may be written — the apply-time half of the
+ * house rule that NOTHING IS ADOPTED WITHOUT `--adopt` (decided 2026-09-21 for HostFile, LaunchdJob,
+ * CaddyConfig and every Bao.* family). probe.ts is the plan-time half.
+ *
+ * ★ FAMILY-NEUTRAL ON PURPOSE. The engine questions here — what `--adopt` resolves to for one FQN,
+ *   whether this apply resumes the resource's own interrupted create — are the same for a vault
+ *   role, a launchd plist and a Caddy config, so they live once, outside every subpath's directory.
+ */
+import { AdoptPolicy } from 'alchemy/AdoptPolicy';
+import { AlchemyContext } from 'alchemy/AlchemyContext';
+import { Stack } from 'alchemy/Stack';
+import * as Effect from 'effect/Effect';
+import * as Option from 'effect/Option';
+import { resumes, unfinished } from './resume.ts';
+import { forgetRefusedCreate, isCreate } from './rows.ts';
+
+/**
+ * Whether the resource at `fqn` may be adopted, resolved exactly as the planner resolves it (alchemy
+ * beta.79 Plan.ts: `resource.Adopt ?? shouldAdopt`): a resource-scoped `adopt(…)`, else the
+ * `AdoptPolicy` service, else `AlchemyContext.adopt`, else off.
+ * ★ FOR A CREATE THE ENGINE NEVER PROBED. Alchemy skips the adoption probe while `news` holds an
+ *   Output, so an ownership check that must still honour `--adopt` can only run at apply. All three
+ *   reach the apply: Alchemist runs plan AND apply under the session context, which provides the
+ *   services from the CLI flag and the Stack the resources registered on (Alchemist/Session.ts,
+ *   routes/stack.ts; Apply.ts reads the same Stack).
+ * ⛔ THE RESOURCE-SCOPED SETTING WINS, BOTH WAYS. The engine captures `adopt(…)` on the resource at
+ *   registration (Resource.ts `Adopt`, into `Stack.resources[fqn]`) and never hands it to a
+ *   provider. Reading only the deploy-wide flag let `--adopt` take over a resource declared
+ *   `.pipe(adopt(false))` — which the planner refuses — and refused one declared `adopt(true)`.
+ * ⚠️ `resources` carries an `@internal` comment in Alchemy's source, but it is in the published types
+ *   and the planner reads `Adopt` from it. caddy/adopt-scope.test.ts registers through the real
+ *   `Resource`, so an upgrade that stops recording it there fails the suite.
+ */
+export const adoptEnabled = (fqn: string): Effect.Effect<boolean> =>
+  Effect.gen(function* () {
+    const stack = yield* Effect.serviceOption(Stack);
+    const scoped = Option.isSome(stack) ? stack.value.resources[fqn]?.Adopt : undefined;
+    if (scoped !== undefined) return scoped;
+    const policy = yield* Effect.serviceOption(AdoptPolicy);
+    if (Option.isSome(policy)) return policy.value;
+    const context = yield* Effect.serviceOption(AlchemyContext);
+    return Option.isSome(context) ? context.value.adopt : false;
+  });
+
+/** The three fields of a `reconcile` (or `read`) call that say whose object this is. */
+export type Owner = {
+  readonly fqn: string;
+  readonly instanceId: string;
+  /** The attributes state holds; `undefined` on a create. */
+  readonly output: unknown;
+};
+
+/**
+ * Whether `--adopt` may speak for this apply's generation: a CREATE (rows.ts isCreate), or an
+ * UNFINISHED generation whose row this plan's diff saw with no attributes (resume.ts) — the
+ * resume Alchemy itself offers `--adopt` for ("Cannot resume creating … Re-run with --adopt").
+ * ⛔ NOT A FRESH REPLACE'S NEW GENERATION. The planner never probes it and never offers it adoption,
+ *   so the identity it moves to was never asked about under `--adopt`: 🔴 MEASURED 2026-09-21
+ *   (launchd/adopt-apply.test.ts), a HostFile whose path changed onto a file it did not own
+ *   overwrote that file under a deploy-wide `--adopt` meant for something else. A Bao rename onto a
+ *   taken identity already fails the plan, `--adopt` or not (rename.ts judgeMove); this keeps the
+ *   apply to the same answer.
+ */
+const adoptable = (owner: Owner): Effect.Effect<boolean> =>
+  Effect.gen(function* () {
+    if (yield* isCreate(owner.fqn, owner.instanceId)) return true;
+    return yield* unfinished(owner.instanceId);
+  });
+
+/** Whether a stateless `reconcile` may take over a live object: adoption on, for an adoptable one. */
+export const adoptsAtApply = (owner: Owner): Effect.Effect<boolean> =>
+  Effect.gen(function* () {
+    if (!(yield* adoptEnabled(owner.fqn))) return false;
+    return yield* adoptable(owner);
+  });
+
+/** A lifecycle helper's hook for refuseTakeover, bound to one call's Owner: `(what) => …`. */
+export type Claim = (what: string) => Effect.Effect<void>;
+
+/**
+ * `reconcile`'s check, called with the live object it found BEFORE any write: dies unless that
+ * object may be written. It may when state already vouches for it (`output`), when this apply
+ * resumes the resource's own interrupted create or replace and its diff proved the object that
+ * generation's (resume.ts), or when adoption is on for a create or an unfinished generation
+ * (adoptable).
+ * ⛔ WHY IT EXISTS AT ALL: THE PROBE DOES NOT GUARD EVERY CREATE. Alchemy skips it while `news` holds
+ *   an Output (Plan.ts), a new generation of a replace is never probed, and an object can appear
+ *   between plan and apply. Each of those used to be a silent takeover: written over, then recorded
+ *   as ours, and deleted with the stack under `destroy`.
+ * ⚠️ A CHECK, THEN A WRITE — NOT A LOCK. Two creates of one name in the same deploy run
+ *   concurrently, both read nothing, and both write (measured with the fakes, 2026-09-21). Nothing
+ *   between a read and a write can close that; declare each name once.
+ * ⚠️ AN IDENTICAL OBJECT IS STILL A TAKEOVER (decided 2026-09-21). Nothing would be written, but the
+ *   state row would claim it, and a later delete would remove what another owner still relies on.
+ * ⛔ A REFUSED CREATE FORGETS ITS `creating` ROW (rows.ts forgetRefusedCreate), or the next plan's
+ *   recovery read would adopt the very object this refused.
+ */
+export const refuseTakeover = (owner: Owner, what: string): Effect.Effect<void> =>
+  Effect.gen(function* () {
+    if (owner.output !== undefined) return;
+    if (yield* resumes(owner.instanceId)) return;
+    const may = yield* adoptable(owner);
+    if (may && (yield* adoptEnabled(owner.fqn))) return;
+    yield* forgetRefusedCreate(owner.fqn, owner.instanceId);
+    const remedy = may
+      ? 'Deploy with --adopt (or wrap the resource in adopt(true)) to take it over, or remove it first.'
+      : 'It is the new identity of a replace, which --adopt does not cover: remove it first.';
+    return yield* Effect.die(
+      new Error(
+        `${what}: already exists, and this stack holds no state for it — the plan could not ask ` +
+          'first (a prop was still an Output, a replace moved onto it, or it appeared after the ' +
+          `plan). Nothing was written. ${remedy}`,
+      ),
+    );
+  });
+
+/** refuseTakeover bound to one call's Owner, for a lifecycle helper that finds the live object. */
+export const claimFor =
+  (owner: Owner): Claim =>
+  (what) =>
+    refuseTakeover(owner, what);