@homeflare/alchemy 0.6.0 → 0.8.0

package/src/cloudflare/mesh-node-policy.test.ts

@@ -0,0 +1,151 @@
+/**
+ * MeshNode's removal policy, through Alchemy's real plan/apply (`engine` in mesh-node-harness.ts)
+ * over the fake Cloudflare. The policy lives in the engine, not the provider, so the handler-level
+ * tests beside this one cannot see it.
+ *
+ * ⛔ WHAT THESE PIN: `retain` is the default (a dropped declaration deletes nothing), a same-name
+ *   `ha` change refuses and writes nothing until the deploy opts in with
+ *   `RemovalPolicy.destroy()`, and the sentence's way back (drop the row, adopt) works while a
+ *   plain revert does not. Deleting `defaultRemovalPolicy`, or turning `deleteFirst` off in
+ *   mesh-node-form.ts, fails at least one test here.
+ * ⛔ AND THE SENTENCES NEVER SEND AN OPERATOR THE WRONG WAY: a node holding a create-first
+ *   replace's NEW name is not called the old node, and `adopt(true)` alone, which does nothing to
+ *   a `replacing` row, is never offered as the way back from inside a replace.
+ */
+import { describe, expect, test } from 'bun:test';
+import { adopt } from 'alchemy/AdoptPolicy';
+import * as RemovalPolicy from 'alchemy/RemovalPolicy';
+import * as Effect from 'effect/Effect';
+import { fakeFailure, fakeMesh } from './fake-mesh.ts';
+import { engine, failureOf, writes } from './mesh-node-harness.ts';
+import { MeshNode } from './mesh-node.ts';
+
+/** The logical id every test declares; at the stack root it is also the state row's fqn. */
+const DOOR = 'door';
+const door = (ha: boolean, name = 'door-a') => MeshNode(DOOR, { name, ha });
+const liveNodes = (fake: ReturnType<typeof fakeMesh>) =>
+  fake.live().map((node) => ({ id: node.id, name: node.name, ha: node.ha }));
+
+describe('MeshNode removal policy (the real engine)', () => {
+  test('retain is the default: dropping the declaration leaves the node and sends no DELETE', async () => {
+    const fake = fakeMesh();
+    const stack = engine(fake);
+    expect(failureOf(await stack.deploy(door(false)))).toBe('');
+    expect(failureOf(await stack.deploy(Effect.void))).toBe('');
+    expect(stack.status(DOOR)).toBeUndefined();
+    expect(liveNodes(fake)).toHaveLength(1);
+    expect(writes(fake)).toEqual(['POST']);
+  });
+
+  test('RemovalPolicy.destroy() still reaches the implemented delete', async () => {
+    const fake = fakeMesh();
+    const stack = engine(fake);
+    await stack.deploy(door(false).pipe(RemovalPolicy.destroy()));
+    expect(failureOf(await stack.deploy(Effect.void))).toBe('');
+    expect(liveNodes(fake)).toHaveLength(0);
+    expect(writes(fake)).toEqual(['POST', 'DELETE']);
+  });
+
+  test('an `ha` change under the default refuses, writes nothing, and names the opt-in', async () => {
+    const fake = fakeMesh();
+    const stack = engine(fake);
+    await stack.deploy(door(false));
+    const [before] = liveNodes(fake);
+    const failure = failureOf(await stack.deploy(door(true)));
+    expect(failure).toContain(`"door-a" already exists (${before?.id})`);
+    expect(failure).toContain('RemovalPolicy.retain');
+    expect(failure).toContain('.pipe(RemovalPolicy.destroy())');
+    expect(failure).toContain('reverting `ha` is not enough');
+    expect(liveNodes(fake)).toEqual([{ id: before?.id ?? '', name: 'door-a', ha: false }]);
+    expect(writes(fake)).toEqual(['POST']);
+  });
+
+  test('opting in with RemovalPolicy.destroy() completes it delete-first, then retain is back', async () => {
+    const fake = fakeMesh();
+    const stack = engine(fake);
+    await stack.deploy(door(false));
+    await stack.deploy(door(true));
+    const done = await stack.deploy(door(true).pipe(RemovalPolicy.destroy()));
+    expect(failureOf(done)).toBe('');
+    expect(writes(fake)).toEqual(['POST', 'DELETE', 'POST']);
+    expect(liveNodes(fake)).toMatchObject([{ name: 'door-a', ha: true }]);
+    // ★ The opt-in lasts one deploy: without it the row is re-committed as retain.
+    await stack.deploy(door(true));
+    await stack.deploy(Effect.void);
+    expect(liveNodes(fake)).toHaveLength(1);
+  });
+
+  test('reverting `ha` does not undo a refused replace; dropping the row and adopting does', async () => {
+    const fake = fakeMesh();
+    const stack = engine(fake);
+    await stack.deploy(door(false));
+    const [original] = liveNodes(fake);
+    await stack.deploy(door(true));
+    expect(stack.status(DOOR)).toBe('replacing');
+    expect(failureOf(await stack.deploy(door(false)))).toContain('already exists');
+
+    stack.forget(DOOR);
+    const back = await stack.deploy(door(false).pipe(adopt(true)));
+    expect(failureOf(back)).toBe('');
+    expect(stack.status(DOOR)).not.toBe('replacing');
+    expect(liveNodes(fake)).toEqual([{ id: original?.id ?? '', name: 'door-a', ha: false }]);
+    expect(writes(fake)).toEqual(['POST']);
+  });
+
+  test('`ha` and `name` together replace create-first, and the old node stays live', async () => {
+    const fake = fakeMesh();
+    const stack = engine(fake);
+    await stack.deploy(door(false));
+    expect(failureOf(await stack.deploy(door(true, 'door-b')))).toBe('');
+    expect(liveNodes(fake).map((node) => [node.name, node.ha])).toEqual([
+      ['door-a', false],
+      ['door-b', true],
+    ]);
+    expect(writes(fake)).toEqual(['POST', 'POST']);
+  });
+
+  test('`ha` and `name` into a name another node holds: not called the old node, and nothing deletes it', async () => {
+    const fake = fakeMesh();
+    const stack = engine(fake);
+    await stack.deploy(door(false));
+    const other = fake.seed({ name: 'door-b', ha: false });
+    const refused = failureOf(await stack.deploy(door(true, 'door-b')));
+    expect(refused).toContain(`"door-b" already exists (${other.id})`);
+    expect(refused).toContain('If this deploy changed `ha` and kept the name');
+    expect(refused).toContain('Otherwise it is another node: do not delete it.');
+    // ★ destroy() reaches only the old generation, never the name holder: refused again.
+    const optedIn = door(true, 'door-b').pipe(RemovalPolicy.destroy());
+    expect(failureOf(await stack.deploy(optedIn))).toContain('already exists');
+    // ⚠️ adopt(true) alone does not act on the `replacing` row either.
+    const adopted = door(true, 'door-b').pipe(adopt(true));
+    expect(failureOf(await stack.deploy(adopted))).toContain('already exists');
+    expect(liveNodes(fake).map((node) => node.name)).toEqual(['door-a', 'door-b']);
+    expect(writes(fake)).toEqual(['POST']);
+  });
+
+  test('a lost-response retry inside an opted-in replace names state rm, which adopt(true) alone is not', async () => {
+    let lose = false;
+    const fake = fakeMesh({
+      onCreate: (name) => {
+        if (!lose) return undefined;
+        lose = false;
+        // What a retried POST meets: the node its first, lost-response attempt created.
+        fake.seed({ name, ha: true });
+        return fakeFailure(409, 1013, 'Tunnel with name already exists');
+      },
+    });
+    const stack = engine(fake);
+    await stack.deploy(door(false));
+    lose = true;
+    const raced = failureOf(await stack.deploy(door(true).pipe(RemovalPolicy.destroy())));
+    expect(raced).toContain('appeared between');
+    expect(raced).toContain("after a replace drop this resource's state row (alchemy state rm");
+    expect(stack.status(DOOR)).toBe('replacing');
+    expect(failureOf(await stack.deploy(door(true).pipe(adopt(true))))).toContain('already exists');
+
+    stack.forget(DOOR);
+    expect(failureOf(await stack.deploy(door(true).pipe(adopt(true))))).toBe('');
+    expect(liveNodes(fake)).toMatchObject([{ name: 'door-a', ha: true }]);
+    expect(writes(fake)).toEqual(['POST', 'DELETE', 'POST']);
+  });
+});

package/src/cloudflare/mesh-node-token.test.ts

@@ -0,0 +1,117 @@
+/**
+ * fetchMeshNodeToken against the fake Cloudflare, provided the way a Bun `mesh-enroll` script
+ * provides it: distilled Credentials from an API token, plus FetchHttpClient.
+ *
+ * ⛔ The value comes back `Redacted`: printing it, logging it or serialising it shows
+ *   `<redacted>`. Only `Redacted.value` yields the token, and only the write to the host's 0600
+ *   file should call it.
+ */
+import { describe, expect, test } from 'bun:test';
+import {
+  type Credentials,
+  fromApiKey,
+  fromApiToken,
+} from '@distilled.cloud/cloudflare/Credentials';
+import * as Effect from 'effect/Effect';
+import type * as Layer from 'effect/Layer';
+import * as Redacted from 'effect/Redacted';
+import { FAKE_ACCOUNT, FAKE_BASE, type FakeMesh, fakeClientLayer, fakeMesh } from './fake-mesh.ts';
+import { type MeshNodeRef, fetchMeshNodeToken } from './mesh-node-token.ts';
+
+const token = (fake: FakeMesh, ref: MeshNodeRef) =>
+  Effect.runPromise(fetchMeshNodeToken(ref).pipe(Effect.provide(fakeClientLayer(fake))));
+
+const failure = (fake: FakeMesh, ref: MeshNodeRef, credentials?: Layer.Layer<Credentials>) =>
+  Effect.runPromise(
+    Effect.flip(fetchMeshNodeToken(ref)).pipe(Effect.provide(fakeClientLayer(fake, credentials))),
+  );
+
+describe('fetchMeshNodeToken', () => {
+  test('by id: the token, redacted everywhere but Redacted.value', async () => {
+    const fake = fakeMesh();
+    const node = fake.seed({ name: 'door-a' });
+    const value = await token(fake, { accountId: FAKE_ACCOUNT, id: node.id });
+    expect(Redacted.value(value)).toBe(node.token);
+    expect(String(value)).not.toContain(node.token);
+    expect(JSON.stringify({ value })).not.toContain(node.token);
+    expect(fake.seen.map((s) => s.path)).toEqual([
+      `/client/v4/accounts/${FAKE_ACCOUNT}/warp_connector/${node.id}/token`,
+    ]);
+  });
+
+  test('by name: resolved by exact match first', async () => {
+    const fake = fakeMesh();
+    fake.seed({ name: 'door-a-2' });
+    const node = fake.seed({ name: 'door-a' });
+    const value = await token(fake, { accountId: FAKE_ACCOUNT, name: 'door-a' });
+    expect(Redacted.value(value)).toBe(node.token);
+  });
+
+  test('an unknown node fails with a sentence naming it', async () => {
+    const fake = fakeMesh();
+    const missing = '00000000-0000-4000-8000-00000000ffff';
+    expect((await failure(fake, { accountId: FAKE_ACCOUNT, id: missing })).message).toContain(
+      missing,
+    );
+    expect((await failure(fake, { accountId: FAKE_ACCOUNT, name: 'nope' })).message).toContain(
+      'No live Mesh node named "nope"',
+    );
+  });
+
+  test('an empty token fails closed rather than enrolling nothing', async () => {
+    const fake = fakeMesh();
+    const node = fake.seed({ name: 'door-a', token: '' });
+    const error = await failure(fake, { accountId: FAKE_ACCOUNT, id: node.id });
+    expect(error.message).toContain('empty token');
+  });
+
+  test('a 403 names the Write permission the endpoint needs', async () => {
+    const fake = fakeMesh();
+    const node = fake.seed({ name: 'door-a' });
+    const denying: FakeMesh = {
+      ...fake,
+      fetch: (async () =>
+        Response.json(
+          {
+            success: false,
+            errors: [{ code: 9109, message: 'Unauthorized to access requested resource' }],
+          },
+          { status: 403 },
+        )) as unknown as typeof globalThis.fetch,
+    };
+    const error = await failure(denying, { accountId: FAKE_ACCOUNT, id: node.id });
+    expect(error.message).toContain('Cloudflare One Connectors Write');
+    expect(error.message).toContain(FAKE_ACCOUNT);
+  });
+
+  test('refused before any request while DISTILLED_DEBUG_HTTP would print the token', async () => {
+    // ⛔ distilled console.errors the first 400 bytes of every response body when this is set.
+    const fake = fakeMesh();
+    const node = fake.seed({ name: 'door-a' });
+    const before = process.env['DISTILLED_DEBUG_HTTP'];
+    process.env['DISTILLED_DEBUG_HTTP'] = '1';
+    try {
+      const error = await failure(fake, { accountId: FAKE_ACCOUNT, id: node.id });
+      expect(error.message).toContain('DISTILLED_DEBUG_HTTP');
+    } finally {
+      if (before === undefined) delete process.env['DISTILLED_DEBUG_HTTP'];
+      else process.env['DISTILLED_DEBUG_HTTP'] = before;
+    }
+    expect(fake.seen).toHaveLength(0);
+  });
+
+  test('the Global API Key and an empty API token are refused before any request', async () => {
+    const fake = fakeMesh();
+    const node = fake.seed({ name: 'door-a' });
+    const ref = { accountId: FAKE_ACCOUNT, id: node.id };
+    const globalKey = fromApiKey({
+      apiKey: 'placeholder-global-key',
+      email: 'ops@example.com',
+      apiBaseUrl: FAKE_BASE,
+    });
+    expect((await failure(fake, ref, globalKey)).message).toContain('Global API Key');
+    const empty = fromApiToken({ apiToken: '', apiBaseUrl: FAKE_BASE });
+    expect((await failure(fake, ref, empty)).message).toContain('EMPTY');
+    expect(fake.seen).toHaveLength(0);
+  });
+});

package/src/cloudflare/mesh-node-token.ts

@@ -0,0 +1,125 @@
+/**
+ * `fetchMeshNodeToken` — a Mesh node's enrolment token, fetched on demand for a one-off Bun
+ * `mesh-enroll` step. ⛔ Not a Resource, and never an attribute: see mesh-node-form.ts for why
+ * the token must stay out of Alchemy state.
+ *
+ * ⛔ WHERE THE VALUE MAY GO. Straight into a root-owned `0600` file on the node's host, which the
+ *   enrolment reads (`warp-cli --accept-tos connector new <token>`, per the Mesh get-started page,
+ *   read 2026-09-21). Nowhere else: not Alchemy state, not a secrets store (a runtime credential
+ *   belongs to the host that runs it), not a log line, not a CI variable. It is returned
+ *   `Redacted`, so an accidental `console.log` or `Effect.log` prints `<redacted>`; call
+ *   `Redacted.value` only at the write.
+ * ⚠️ `warp-cli` takes the token as an ARGUMENT, so it is visible in the host's process list for
+ *   the life of that command. Run the enrolment as root on the node itself, never over a shell
+ *   whose history is kept.
+ * ⚠️ THE ENDPOINT NEEDS A WRITE PERMISSION. Its API reference (read 2026-09-21) accepts
+ *   "Cloudflare One Connectors Write", "Cloudflare One Connector: cloudflared Write" or
+ *   "Cloudflare Tunnel Write"; the Mesh get-started guide also names "Cloudflare One Connector:
+ *   WARP Write". Connectors Write is in both lists. Mint a short-lived token for this step alone;
+ *   a read-only plan token gets a 403 here.
+ *
+ * ★ Requires distilled `Credentials` and an `HttpClient`, not Alchemy's CloudflareEnvironment: a
+ *   Bun script has no Alchemy profile, so the account id is an argument. Provide
+ *   `Credentials.fromApiToken({ apiToken })` (from `@distilled.cloud/cloudflare/Credentials`) and
+ *   `FetchHttpClient.layer`. ⛔ Not `Credentials.fromEnv()`: it falls back to the Global API Key
+ *   (`CLOUDFLARE_API_KEY` + `CLOUDFLARE_EMAIL`) when no token is set — and `refuseUnsafe` below
+ *   refuses that key rather than trusting the caller to have read this.
+ */
+import { Credentials } from '@distilled.cloud/cloudflare/Credentials';
+import * as zeroTrust from '@distilled.cloud/cloudflare/zero-trust';
+import * as Effect from 'effect/Effect';
+import * as Redacted from 'effect/Redacted';
+import { MeshNodeError, findNodeByName } from './mesh-node-api.ts';
+
+/** Which node: by id (the `MeshNode` attribute) or by its exact name. */
+export type MeshNodeRef = { readonly accountId: string } & (
+  | { readonly id: string; readonly name?: undefined }
+  | { readonly name: string; readonly id?: undefined }
+);
+
+/**
+ * ⛔ REFUSED BEFORE ANY REQUEST IS SENT:
+ * - `DISTILLED_DEBUG_HTTP` set. distilled's Cloudflare protocol then `console.error`s the first
+ *   400 characters of EVERY response body (protocol.ts, measured in 1.0.0-rc.12) — the token
+ *   response is `{"success":true,…,"result":"<token>"}`, so the whole token lands on stderr and in
+ *   whatever captures it. The check reads `process.env` because that is what distilled reads.
+ * - The Global API Key (`apiKey` credentials). Account-wide and long-lived: the one credential a
+ *   one-off enrolment must never use.
+ * - An EMPTY API token. A denied secrets-store grant renders empty, and Cloudflare then answers
+ *   like a bad permission — which would send the operator to widen a grant that was fine
+ *   (client.ts says the same for `CLOUDFLARE_API_TOKEN`).
+ */
+const refuseUnsafe = Effect.gen(function* () {
+  if ((globalThis.process?.env?.['DISTILLED_DEBUG_HTTP'] ?? '') !== '') {
+    return yield* Effect.fail(
+      new MeshNodeError({
+        message:
+          'Refusing to fetch a Mesh node token while DISTILLED_DEBUG_HTTP is set: the SDK would print the token to stderr. Unset it and run again.',
+      }),
+    );
+  }
+  const credentials = yield* yield* Credentials;
+  if (credentials.type === 'apiKey') {
+    return yield* Effect.fail(
+      new MeshNodeError({
+        message:
+          'Refusing the Global API Key for a Mesh node token. Mint a short-lived API token with "Cloudflare One Connectors Write" and pass it with fromApiToken.',
+      }),
+    );
+  }
+  if (credentials.type === 'apiToken' && Redacted.value(credentials.apiToken).length === 0) {
+    return yield* Effect.fail(
+      new MeshNodeError({
+        message:
+          'The Cloudflare API token is EMPTY. That is a missing or denied secrets grant, not a Cloudflare permission: re-mint the token before changing any grant.',
+      }),
+    );
+  }
+});
+
+const resolveId = (ref: MeshNodeRef) => {
+  if (ref.id !== undefined) return Effect.succeed(ref.id);
+  const name = ref.name;
+  return Effect.flatMap(findNodeByName(ref.accountId, name), (node) =>
+    node === undefined
+      ? Effect.fail(new MeshNodeError({ message: `No live Mesh node named "${name}".` }))
+      : Effect.succeed(node.id),
+  );
+};
+
+/**
+ * ⛔ An EMPTY token fails closed: `warp-cli connector new ""` would not enrol, and a script that
+ *   wrote an empty file would report success over a host that never joined.
+ * ⛔ The failures made here name the node and account and quote no response body, because the
+ *   success body IS the token. Other SDK errors pass through; they come only from non-2xx
+ *   responses, which carry an error envelope, not a token.
+ */
+export const fetchMeshNodeToken = (ref: MeshNodeRef) =>
+  Effect.gen(function* () {
+    yield* refuseUnsafe;
+    const nodeId = yield* resolveId(ref);
+    const token = yield* zeroTrust
+      .getTunnelWarpConnectorToken({ accountId: ref.accountId, tunnelId: nodeId })
+      .pipe(
+        Effect.catchTag('TunnelNotFound', () =>
+          Effect.fail(
+            new MeshNodeError({
+              message: `Mesh node ${nodeId} does not exist in account ${ref.accountId}.`,
+            }),
+          ),
+        ),
+        Effect.catchTag('Forbidden', () =>
+          Effect.fail(
+            new MeshNodeError({
+              message: `Reading Mesh node ${nodeId}'s token was refused (403). The endpoint needs a Write permission such as "Cloudflare One Connectors Write", on a token scoped to account ${ref.accountId}.`,
+            }),
+          ),
+        ),
+      );
+    if (typeof token !== 'string' || token.length === 0) {
+      return yield* Effect.fail(
+        new MeshNodeError({ message: `Mesh node ${nodeId} returned an empty token.` }),
+      );
+    }
+    return Redacted.make(token);
+  });

package/src/cloudflare/mesh-node.test.ts

@@ -0,0 +1,172 @@
+/**
+ * MeshNodeProvider against a fake Cloudflare (fake-mesh.ts), its handlers called the way the
+ * engine calls them.
+ *
+ * ⛔ THE ASSERTION THAT MATTERS MOST: no lifecycle handler ever requests `/token`, and nothing
+ *   the provider returns contains the node token — even though the fake's create response carries
+ *   one, as Cloudflare's HA page says the real one does.
+ */
+import { describe, expect, test } from 'bun:test';
+import { Unowned } from 'alchemy/AdoptPolicy';
+import type { StackServices } from 'alchemy/Stack';
+import * as Effect from 'effect/Effect';
+import type * as Layer from 'effect/Layer';
+import { FAKE_ACCOUNT, FAKE_API_TOKEN, fakeMesh } from './fake-mesh.ts';
+import { diff, extra, ids, read, reconcile, run, stored, tokenReads } from './mesh-node-harness.ts';
+import { providers } from './providers.ts';
+
+// ⛔ Compile-time: a stack's `providers` must be `Layer<…, never, StackServices>`. Adding MeshNode
+//   first leaked Alchemy's auth errors into the error channel; `bun run types` now catches that.
+type Built = Layer.Success<ReturnType<typeof providers>>;
+const _stackShaped: Layer.Layer<Built, never, StackServices> = providers();
+void _stackShaped;
+
+describe('MeshNodeProvider', () => {
+  test('create sends ha, and the attributes carry no token', async () => {
+    const fake = fakeMesh();
+    const out = await run(fake, (p) => reconcile(p, { name: 'door-a', ha: true }));
+    const post = fake.seen.find((s) => s.method === 'POST');
+    expect(post?.body).toEqual({ name: 'door-a', ha: true });
+    expect(out).toMatchObject({
+      name: 'door-a',
+      ha: true,
+      accountId: FAKE_ACCOUNT,
+      status: 'inactive',
+    });
+    expect(Object.keys(out).sort()).toEqual(['accountId', 'ha', 'id', 'name', 'status']);
+    expect(JSON.stringify(out)).not.toContain('fake-node-token');
+    expect(tokenReads(fake)).toBe(0);
+    expect(new Set(fake.auth)).toEqual(new Set([`Bearer ${FAKE_API_TOKEN}`]));
+  });
+
+  test('read with state refreshes by id; without state it adopts by exact name, Unowned', async () => {
+    const fake = fakeMesh();
+    fake.seed({ name: 'door-a-old' });
+    fake.seed({ name: 'door-a-older' });
+    const node = fake.seed({ name: 'door-a', status: 'healthy' });
+    const props = { name: 'door-a', ha: false };
+    const [owned, probe] = await run(fake, (p) =>
+      Effect.gen(function* () {
+        const output = stored(FAKE_ACCOUNT, { id: node.id });
+        return [yield* read(p, props, output), yield* read(p, props)] as const;
+      }),
+    );
+    expect(Unowned.is(owned)).toBe(false);
+    expect(owned).toMatchObject({ id: node.id, status: 'healthy' });
+    expect(Unowned.is(probe)).toBe(true);
+    expect(probe).toMatchObject({ id: node.id, name: 'door-a', ha: false });
+    expect(tokenReads(fake)).toBe(0);
+  });
+
+  test('a prefix-only match or a deleted node is not adopted', async () => {
+    const fake = fakeMesh();
+    fake.seed({ name: 'door-a-2' });
+    fake.seed({ name: 'door-a', deleted_at: '2026-09-20T00:00:00Z' });
+    const probe = await run(fake, (p) => read(p, { name: 'door-a', ha: false }));
+    expect(probe).toBeUndefined();
+  });
+
+  test('a rename is a PATCH on the same id', async () => {
+    const fake = fakeMesh();
+    const [first, second] = await run(fake, (p) =>
+      Effect.gen(function* () {
+        const first = yield* reconcile(p, { name: 'door-a', ha: false });
+        return [first, yield* reconcile(p, { name: 'door-b', ha: false }, first)] as const;
+      }),
+    );
+    expect(second.id).toBe(first.id);
+    expect(second.name).toBe('door-b');
+    expect(fake.seen.filter((s) => s.method === 'POST')).toHaveLength(1);
+    expect(fake.seen.find((s) => s.method === 'PATCH')?.body).toEqual({ name: 'door-b' });
+  });
+
+  test('an unchanged node costs no write', async () => {
+    const fake = fakeMesh();
+    await run(fake, (p) =>
+      Effect.flatMap(reconcile(p, { name: 'door-a', ha: false }), (out) =>
+        reconcile(p, { name: 'door-a', ha: false }, out),
+      ),
+    );
+    expect(fake.seen.filter((s) => s.method !== 'GET').map((s) => s.method)).toEqual(['POST']);
+  });
+
+  test('reconcile refuses an ha change that reached it as an update', async () => {
+    const fake = fakeMesh();
+    const failure = await run(fake, (p) =>
+      Effect.flip(
+        Effect.flatMap(reconcile(p, { name: 'door-a', ha: false }), (out) =>
+          reconcile(p, { name: 'door-a', ha: true }, out),
+        ),
+      ),
+    );
+    expect(String(failure)).toContain('create-only');
+  });
+
+  test('create never converges on a node it did not create (a retained old generation)', async () => {
+    const fake = fakeMesh();
+    fake.seed({ name: 'door-a', ha: false });
+    const failure = await run(fake, (p) => Effect.flip(reconcile(p, { name: 'door-a', ha: true })));
+    expect(String(failure)).toContain('already exists');
+    expect(fake.seen.some((s) => s.method === 'POST')).toBe(false);
+  });
+
+  test('a node deleted out of band is created again', async () => {
+    const fake = fakeMesh();
+    const [first, second] = await run(fake, (p) =>
+      Effect.gen(function* () {
+        const first = yield* reconcile(p, { name: 'door-a', ha: false });
+        const node = fake.nodes.get(first.id);
+        if (node !== undefined) node.deleted_at = '2026-09-21T02:00:00Z';
+        return [first, yield* reconcile(p, { name: 'door-a', ha: false }, first)] as const;
+      }),
+    );
+    expect(second.id).not.toBe(first.id);
+    expect(fake.live()).toHaveLength(1);
+  });
+
+  test('delete removes the node, and deleting it again succeeds', async () => {
+    const fake = fakeMesh();
+    await run(fake, (p) =>
+      Effect.gen(function* () {
+        const output = yield* reconcile(p, { name: 'door-a', ha: false });
+        const olds = { name: 'door-a', ha: false };
+        yield* p.delete({ ...ids, ...extra, olds, output });
+        yield* p.delete({ ...ids, ...extra, olds, output });
+      }),
+    );
+    expect(fake.live()).toHaveLength(0);
+    expect(fake.seen.filter((s) => s.method === 'DELETE')).toHaveLength(2);
+  });
+
+  test('diff reads the account from the provider environment', async () => {
+    const fake = fakeMesh();
+    const props = { name: 'door-a', ha: false };
+    const plan = (p: Parameters<typeof diff>[0]) => diff(p, props, props, stored(FAKE_ACCOUNT));
+    expect(await run(fake, plan)).toBeUndefined();
+    expect(await run(fake, plan, '00000000000000000000000000000002')).toEqual({
+      action: 'replace',
+    });
+  });
+
+  test('an invalid declaration fails the PLAN, before a delete-first replace tears anything down', async () => {
+    const fake = fakeMesh();
+    const failure = await run(fake, (p) =>
+      Effect.flip(
+        diff(p, { name: 'door-a ', ha: true }, { name: 'door-a', ha: false }, stored(FAKE_ACCOUNT)),
+      ),
+    );
+    expect(String(failure)).toContain('whitespace');
+    expect(fake.seen).toHaveLength(0);
+  });
+
+  test('list is empty and nuke skips it: Alchemy WarpConnector already enumerates these', async () => {
+    const fake = fakeMesh();
+    fake.seed({ name: 'door-a' });
+    const [listed, nuke] = await run(fake, (p) =>
+      Effect.map(p.list(), (rows) => [rows, p.nuke] as const),
+    );
+    expect(listed).toEqual([]);
+    expect(nuke).toEqual({ skip: true });
+    expect(fake.seen).toHaveLength(0);
+  });
+});