@homeflare/alchemy 0.6.0 → 0.8.0

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

@@ -0,0 +1,103 @@
+/**
+ * MeshNodeProvider's refusals and recoveries — the cases a mutation of each guard must break.
+ *
+ * ★ Every test here was written against a guard that a mutation pass (2026-09-21) could delete
+ *   without any other test noticing: the two-match refusal, the 404 on a stored id, the stored
+ *   account in `read`, the rename collision, the `stables` list and the 1013-after-lookup race.
+ */
+import { describe, expect, test } from 'bun:test';
+import { Unowned } from 'alchemy/AdoptPolicy';
+import * as Effect from 'effect/Effect';
+import { FAKE_ACCOUNT, fakeFailure, fakeMesh } from './fake-mesh.ts';
+import { read, reconcile, run, stored } from './mesh-node-harness.ts';
+
+const OTHER_ACCOUNT = '00000000000000000000000000000002';
+const UNKNOWN_ID = '00000000-0000-4000-8000-00000000ffff';
+
+describe('MeshNodeProvider edges', () => {
+  test('lookups filter by name and live-only on the wire', async () => {
+    const fake = fakeMesh();
+    fake.seed({ name: 'door-a', deleted_at: '2026-09-20T00:00:00Z' });
+    await run(fake, (p) => read(p, { name: 'door-a', ha: false }));
+    const list = fake.seen.find((s) => s.method === 'GET');
+    expect(list?.path).toContain('name=door-a');
+    expect(list?.path).toContain('is_deleted=false');
+  });
+
+  test('two live nodes with the declared name are refused, both named', async () => {
+    const fake = fakeMesh();
+    const a = fake.seed({ name: 'door-a' });
+    const b = fake.seed({ name: 'door-a' });
+    const failure = await run(fake, (p) => Effect.flip(read(p, { name: 'door-a', ha: false })));
+    expect(failure.message).toContain(a.id);
+    expect(failure.message).toContain(b.id);
+  });
+
+  test('a stored id the API no longer knows (404): read falls back to the name, reconcile creates', async () => {
+    const fake = fakeMesh();
+    const node = fake.seed({ name: 'door-a' });
+    const gone = stored(FAKE_ACCOUNT, { id: UNKNOWN_ID, name: 'door-b' });
+    const probe = await run(fake, (p) => read(p, { name: 'door-a', ha: false }, gone));
+    expect(Unowned.is(probe)).toBe(true);
+    expect(probe).toMatchObject({ id: node.id });
+
+    const fresh = fakeMesh();
+    const created = await run(fresh, (p) => reconcile(p, { name: 'door-b', ha: true }, gone));
+    expect(created.id).not.toBe(UNKNOWN_ID);
+    expect(fresh.seen.find((s) => s.method === 'POST')?.body).toEqual({ name: 'door-b', ha: true });
+  });
+
+  test('read refreshes in the account the node was written to, not the current environment', async () => {
+    const fake = fakeMesh();
+    const node = fake.seed({ name: 'door-a', status: 'healthy' });
+    const output = stored(FAKE_ACCOUNT, { id: node.id });
+    // ⚠️ The fake throws on any other account, so reading in OTHER_ACCOUNT fails this test.
+    const fresh = await run(
+      fake,
+      (p) => read(p, { name: 'door-a', ha: false }, output),
+      OTHER_ACCOUNT,
+    );
+    expect(fresh).toMatchObject({ id: node.id, accountId: FAKE_ACCOUNT, status: 'healthy' });
+  });
+
+  test('a rename onto a taken name fails with a sentence and changes nothing', async () => {
+    const fake = fakeMesh();
+    fake.seed({ name: 'door-b' });
+    const node = fake.seed({ name: 'door-a' });
+    const output = stored(FAKE_ACCOUNT, { id: node.id });
+    const failure = await run(fake, (p) =>
+      Effect.flip(reconcile(p, { name: 'door-b', ha: false }, output)),
+    );
+    expect(failure.message).toContain('"door-b" already exists');
+    expect(fake.nodes.get(node.id)?.name).toBe('door-a');
+  });
+
+  test('only id, accountId and ha are stable across an update (a rename changes name)', async () => {
+    const fake = fakeMesh();
+    const stables = await run(fake, (p) => Effect.succeed(p.stables));
+    expect(stables).toEqual(['id', 'accountId', 'ha']);
+  });
+
+  test('a 1013 after a clean lookup names the node that appeared, and does not adopt it', async () => {
+    let appeared = '';
+    const fake = fakeMesh({
+      onCreate: (name) => {
+        // What a retried POST meets: the node its first, lost-response attempt created.
+        appeared = fake.seed({ name, ha: true }).id;
+      },
+    });
+    const failure = await run(fake, (p) => Effect.flip(reconcile(p, { name: 'door-a', ha: true })));
+    expect(failure.message).toContain(appeared);
+    expect(failure.message).toContain('adopt(true)');
+  });
+
+  test('a 1013 with no live Mesh node of that name blames another tunnel type', async () => {
+    const fake = fakeMesh({
+      onCreate: () => fakeFailure(409, 1013, 'Tunnel with name already exists'),
+    });
+    const failure = await run(fake, (p) =>
+      Effect.flip(reconcile(p, { name: 'door-a', ha: false })),
+    );
+    expect(failure.message).toContain('another tunnel type');
+  });
+});

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

@@ -0,0 +1,80 @@
+/**
+ * The pure half of MeshNode: which edits are an update and which a replace — and in which order.
+ *
+ * ★ The replace ORDER is the part worth testing. Names are unique per account, so an `ha` change
+ *   that keeps the name must delete first; one that also renames must not, or it would take the
+ *   node offline for no reason.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { type MeshNodeAttributes, diffMeshNode, validateMeshNode } from './mesh-node-form.ts';
+
+const ACCOUNT = '00000000000000000000000000000001';
+const output: MeshNodeAttributes = {
+  id: '00000000-0000-4000-8000-000000000001',
+  accountId: ACCOUNT,
+  name: 'door-a',
+  status: 'healthy',
+  ha: false,
+};
+
+describe('diffMeshNode', () => {
+  test('no prior output: no opinion, the engine creates', () => {
+    expect(diffMeshNode({ name: 'door-a', ha: false }, undefined, ACCOUNT)).toBeUndefined();
+  });
+
+  test('nothing changed: no opinion', () => {
+    expect(diffMeshNode({ name: 'door-a', ha: false }, output, ACCOUNT)).toBeUndefined();
+  });
+
+  test('a rename alone is an in-place update (PATCH keeps id, token and Mesh IPs)', () => {
+    expect(diffMeshNode({ name: 'door-b', ha: false }, output, ACCOUNT)).toEqual({
+      action: 'update',
+    });
+  });
+
+  test('ha changed under the same name: replace, delete first (names are unique)', () => {
+    expect(diffMeshNode({ name: 'door-a', ha: true }, output, ACCOUNT)).toEqual({
+      action: 'replace',
+      deleteFirst: true,
+    });
+  });
+
+  test('ha changed with a new name: replace, create first (nothing collides)', () => {
+    expect(diffMeshNode({ name: 'door-b', ha: true }, output, ACCOUNT)).toEqual({
+      action: 'replace',
+    });
+  });
+
+  test('ha changed while the name is unresolved: the order that cannot collide', () => {
+    const news = { name: Effect.succeed('door-a'), ha: true } as never;
+    expect(diffMeshNode(news, output, ACCOUNT)).toEqual({ action: 'replace', deleteFirst: true });
+  });
+
+  test('an unresolved ha gives no answer; reconcile re-checks it', () => {
+    const news = { name: 'door-a', ha: Effect.succeed(true) } as never;
+    expect(diffMeshNode(news, output, ACCOUNT)).toBeUndefined();
+  });
+
+  test('another account is a create-first replace', () => {
+    const other = '00000000000000000000000000000002';
+    expect(diffMeshNode({ name: 'door-a', ha: false }, output, other)).toEqual({
+      action: 'replace',
+    });
+  });
+});
+
+describe('validateMeshNode', () => {
+  test('accepts a plain declaration', () => {
+    expect(validateMeshNode({ name: 'door-a', ha: true })).toBeUndefined();
+  });
+
+  test('refuses an empty or padded name, because adoption matches exactly', () => {
+    expect(validateMeshNode({ name: '  ', ha: false })?.message).toContain('non-empty');
+    expect(validateMeshNode({ name: ' door-a', ha: false })?.message).toContain('whitespace');
+  });
+
+  test('refuses a missing ha: it is create-only, so there is no default', () => {
+    expect(validateMeshNode({ name: 'door-a' } as never)?.message).toContain('no default');
+  });
+});

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

@@ -0,0 +1,115 @@
+/**
+ * `Cloudflare.MeshNode` — its props, its attributes, and the pure `diff` that decides between
+ * update and replace.
+ *
+ * ⛔ THE ATTRIBUTES NEVER HOLD THE NODE TOKEN. That is the whole reason this resource exists:
+ *   Alchemy beta.79's `Cloudflare.Tunnel.WarpConnector` calls `getTunnelWarpConnectorToken` in
+ *   `toAttributes`, so EVERY read, reconcile and list fetches the token, and Alchemy state (which
+ *   is not encrypted) stores it — `Redacted` hides it from logs, not from the state store. It also
+ *   has no `ha` prop. The token is a runtime credential: fetch it on demand with
+ *   `fetchMeshNodeToken` (mesh-node-token.ts) and write it straight to the host.
+ * ★ A BONUS OF NOT READING IT: the token endpoint needs a Write permission ("Cloudflare One
+ *   Connectors Write", per its API reference, read 2026-09-21), so a plan over this resource can
+ *   run on a read-only token. WarpConnector's cannot.
+ */
+import type { Diff } from 'alchemy/Diff';
+import type { Input } from 'alchemy/Input';
+import { MeshNodeError, type MeshNodeStatus } from './mesh-node-api.ts';
+
+export interface MeshNodeProps {
+  /**
+   * The node's name in the account — and its identity when adopting (names are unique per
+   * account). ★ Changing it RENAMES the node in place (`PATCH`): the id, the token, the
+   *   enrolled replicas and their Mesh IPs all survive, so a rename never re-enrols a host.
+   */
+  readonly name: string;
+  /**
+   * High availability (active-passive replicas sharing one node token).
+   *
+   * ⛔ CREATE-ONLY, AND REQUIRED FOR THAT REASON. Cloudflare's Mesh HA page: "High availability
+   *   is set at node creation time and cannot be changed afterward." The PATCH body carries no
+   *   `ha`. So a change REPLACES the node — a new id, a new token, a new Mesh IP per replica —
+   *   and a default would silently fix an irreversible choice. The API's own default is `false`;
+   *   the dashboard's is `true`. Say which one you mean.
+   * ★ A NODE WITH NO ROUTES — A DOOR — IS `ha: false`, AND A SECOND DOOR IS A SECOND NODE. HA
+   *   fails over the CIDR routes a node advertises; "Nodes without routes do not benefit from HA
+   *   failover", because the node's Mesh IP is tied to the individual replica (same page, "When to
+   *   use" and "Considerations", read 2026-09-21). After a failover the promoted replica answers
+   *   on its own Mesh IP, so nothing that dials a door's first replica follows it. Declare the
+   *   second door as its own `MeshNode` (own name, token, Mesh IP) and have callers list both.
+   * ⚠️ `ha` NEEDS MASQUE on the node's device profile (same page).
+   */
+  readonly ha: boolean;
+}
+
+export interface MeshNodeAttributes {
+  /** The node's UUID (the `warp_connector` tunnel id). Pass it to `fetchMeshNodeToken`. */
+  readonly id: string;
+  /** The account the provider environment resolved when the node was written. */
+  readonly accountId: string;
+  readonly name: string;
+  /** As of the last read or write; it moves on its own as replicas connect and drop. */
+  readonly status: MeshNodeStatus | undefined;
+  /**
+   * The value the node was CREATED with (or declared with when adopted — see mesh-node.md).
+   * ⚠️ No documented read returns it: `GET /warp_connector/{id}` has no `ha` field (API
+   *   reference, read 2026-09-21), so drift here cannot be observed, only prevented.
+   */
+  readonly ha: boolean;
+}
+
+/** ⛔ Fail closed on a declaration the API would accept but nobody meant. */
+export const validateMeshNode = (props: MeshNodeProps): MeshNodeError | undefined => {
+  if (typeof props.name !== 'string' || props.name.trim().length === 0) {
+    return new MeshNodeError({ message: 'MeshNode `name` must be a non-empty string.' });
+  }
+  if (props.name !== props.name.trim()) {
+    return new MeshNodeError({
+      message: `MeshNode name "${props.name}" has leading or trailing whitespace; adoption matches names exactly.`,
+    });
+  }
+  if (typeof props.ha !== 'boolean') {
+    return new MeshNodeError({
+      message: 'MeshNode `ha` must be true or false. It is create-only, so it has no default.',
+    });
+  }
+  return undefined;
+};
+
+/**
+ * update or replace, from the declaration and what was last written.
+ *
+ * - Account changed → `replace`, create-first: names are unique per ACCOUNT, so the two
+ *   generations cannot collide.
+ * - `ha` changed → `replace`. ⛔ `deleteFirst` when the name stays the same: the new node needs
+ *   the name the old one holds, so create-first would fail with code 1013 (or, worse, a
+ *   create path that "converged" on the old node would record an `ha` it does not have).
+ *   Create-first when the name changes in the same edit, because then nothing collides.
+ *   ⚠️ UNDER THE DEFAULT `retain` (mesh-node.ts) the engine skips the old node's delete in both
+ *   orders: delete-first then REFUSES at the create (mesh-node-lifecycle.ts) until the deploy
+ *   opts in with `RemovalPolicy.destroy()`, and create-first leaves the old node live, unmanaged.
+ *   The answer here is the same under both policies: `diff` is not handed the policy (Provider.ts,
+ *   its input), and delete-first is exactly what lets the opted-in deploy reuse the name.
+ * - Name changed alone → `update` (a PATCH rename).
+ * - Otherwise → no opinion; the engine compares props.
+ *
+ * ★ An unresolved `ha` gives no answer here; `reconcile` re-checks it once resolved and refuses
+ *   rather than updating across a create-only change. An unresolved `name` next to a changed `ha`
+ *   counts as "unchanged", which picks the delete-first order that cannot collide.
+ */
+export const diffMeshNode = (
+  news: Input<MeshNodeProps>,
+  output: MeshNodeAttributes | undefined,
+  accountId: string,
+): Diff | undefined => {
+  if (output === undefined) return undefined;
+  if (output.accountId !== accountId) return { action: 'replace' };
+  const fields = news as { readonly name?: unknown; readonly ha?: unknown };
+  const name = typeof fields.name === 'string' ? fields.name : undefined;
+  if (typeof fields.ha === 'boolean' && fields.ha !== output.ha) {
+    const sameName = name === undefined || name === output.name;
+    return sameName ? { action: 'replace', deleteFirst: true } : { action: 'replace' };
+  }
+  if (name !== undefined && name !== output.name) return { action: 'update' };
+  return undefined;
+};

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

@@ -0,0 +1,124 @@
+/**
+ * MeshNodeProvider's handlers, called the way the engine calls them, over the fake Cloudflare in
+ * fake-mesh.ts — and `engine`, which runs Alchemy's real plan/apply over the same fake. Shared by
+ * mesh-node.test.ts, mesh-node-edges.test.ts and mesh-node-policy.test.ts.
+ *
+ * ⛔ TEST-ONLY, like fake-mesh.ts: no provider imports this file and it is not on the barrel.
+ */
+import { apply } from 'alchemy/Apply';
+import * as Plan from 'alchemy/Plan';
+import { type CompiledStack, make as makeStack } from 'alchemy/Stack';
+import { Stage } from 'alchemy/Stage';
+import * as State from 'alchemy/State';
+import * as Cause from 'effect/Cause';
+import * as Effect from 'effect/Effect';
+import * as Exit from 'effect/Exit';
+import * as Layer from 'effect/Layer';
+import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
+import { type FakeMesh, fakeProviderLayer } from './fake-mesh.ts';
+import { MeshNode, MeshNodeProvider } from './mesh-node.ts';
+import type { MeshNodeAttributes, MeshNodeProps } from './mesh-node-form.ts';
+
+export const ids = { fqn: 'stack/door', id: 'door', instanceId: 'i-1' };
+export const extra = { bindings: [] as never, session: undefined as never };
+
+export type P = Effect.Success<typeof MeshNode.Provider>;
+
+export const handler = <F>(name: string, fn: F | undefined): F => {
+  if (fn === undefined) throw new Error(`provider has no ${name} handler`);
+  return fn;
+};
+
+/** Build the provider over the fake (as `accountId`'s environment) and hand it to `use`. */
+export const run = <A, E>(fake: FakeMesh, use: (p: P) => Effect.Effect<A, E>, accountId?: string) =>
+  Effect.runPromise(
+    Effect.gen(function* () {
+      return yield* use(yield* MeshNode.Provider);
+    }).pipe(
+      Effect.provide(
+        MeshNodeProvider().pipe(Layer.provideMerge(fakeProviderLayer(fake, accountId))),
+      ),
+    ),
+  );
+
+export const reconcile = (p: P, news: MeshNodeProps, output?: MeshNodeAttributes) =>
+  p.reconcile({ ...ids, ...extra, news, olds: undefined, output });
+
+export const read = (p: P, olds: MeshNodeProps, output?: MeshNodeAttributes) =>
+  handler('read', p.read)({ ...ids, olds, output });
+
+export const diff = (p: P, news: MeshNodeProps, olds: MeshNodeProps, output: MeshNodeAttributes) =>
+  handler(
+    'diff',
+    p.diff,
+  )({
+    ...ids,
+    news,
+    olds,
+    newBindings: [] as never,
+    oldBindings: [] as never,
+    output,
+  });
+
+/** A stored attribute set for a node that may or may not exist in the fake. */
+export const stored = (
+  accountId: string,
+  over: Partial<MeshNodeAttributes> = {},
+): MeshNodeAttributes => ({
+  id: 'x',
+  accountId,
+  name: 'door-a',
+  status: undefined,
+  ha: false,
+  ...over,
+});
+
+export const tokenReads = (fake: FakeMesh) =>
+  fake.seen.filter((s) => s.path.endsWith('/token')).length;
+
+/** The writes the fake saw, in order: `['POST', 'DELETE', …]`. */
+export const writes = (fake: FakeMesh) =>
+  fake.seen.filter((s) => s.method !== 'GET').map((s) => s.method);
+
+type Rows = Record<string, Record<string, Record<string, State.ResourceState>>>;
+
+/**
+ * ★ THE REAL ENGINE, NOT A MODEL OF IT: Alchemy's own `Plan.make` + `apply` over an in-memory
+ *   state store, which is what its Test harness's scratch stacks run (Test/Core.ts
+ *   `scratchStack`), minus the profile, config and telemetry layers a fake Cloudflare does not
+ *   need. Removal policy lives in the engine, so only this can show what it does to a replace.
+ * ⚠️ `FetchHttpClient.Fetch` IS READ PER REQUEST, from the fiber running the engine, so it is
+ *   provided around the whole deploy. Provided only under the provider layer, the requests went
+ *   to the real `fetch` (measured 2026-09-21: ENOTFOUND api.example.com, the RFC 2606 host, so
+ *   no API answered — but a real DNS lookup went out).
+ */
+export const engine = (fake: FakeMesh) => {
+  const rows: Rows = {};
+  const state = Layer.succeed(State.State, State.InMemoryService(rows));
+  const providers = MeshNodeProvider().pipe(Layer.provide(fakeProviderLayer(fake)));
+  const deploy = <A, E, R>(declare: Effect.Effect<A, E, R>) =>
+    Effect.runPromiseExit(
+      declare.pipe(
+        makeStack({ name: 'mesh', providers, state }) as never,
+        Effect.flatMap((compiled: CompiledStack) =>
+          Plan.make(compiled).pipe(Effect.flatMap(apply), Effect.provide(compiled.services)),
+        ),
+        Effect.provide(Layer.succeed(Stage, 'test')),
+        Effect.scoped,
+        Effect.provideService(FetchHttpClient.Fetch, fake.fetch),
+      ) as Effect.Effect<unknown, unknown>,
+    );
+  return {
+    deploy,
+    /** The stored row's status (`created`, `replacing`, …), or `undefined` when there is none. */
+    status: (fqn: string) => rows['mesh']?.['test']?.[fqn]?.status,
+    /** ★ What `alchemy state rm` does ("Delete state records without deleting cloud resources"). */
+    forget: (fqn: string) => {
+      delete rows['mesh']?.['test']?.[fqn];
+    },
+  };
+};
+
+/** The failure sentence of a deploy, or `''` when it succeeded. */
+export const failureOf = (exit: Exit.Exit<unknown, unknown>) =>
+  Exit.isFailure(exit) ? String(Cause.squash(exit.cause)) : '';

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

@@ -0,0 +1,187 @@
+/**
+ * read / reconcile / delete for `Cloudflare.MeshNode`, as plain Effects over the SDK calls in
+ * mesh-node-api.ts. mesh-node.ts only wires them into Alchemy.
+ */
+import { Unowned } from 'alchemy/AdoptPolicy';
+import * as Effect from 'effect/Effect';
+import {
+  MeshNodeError,
+  type ObservedNode,
+  createNode,
+  deleteNode,
+  findNodeByName,
+  getNode,
+  renameNode,
+} from './mesh-node-api.ts';
+import { type MeshNodeAttributes, type MeshNodeProps, validateMeshNode } from './mesh-node-form.ts';
+
+const attributesOf = (node: ObservedNode, accountId: string, ha: boolean): MeshNodeAttributes => ({
+  id: node.id,
+  accountId,
+  name: node.name,
+  status: node.status,
+  ha,
+});
+
+/**
+ * Owned: refresh by the stored id. Cold: find the live node by exact name and hand it back
+ * `Unowned`, so Alchemy refuses to take it over until the stack says `adopt(true)` — the same
+ * gate `Cloudflare.Tunnel.WarpConnector` uses, because a `warp_connector` carries no ownership
+ * marker to prove it was ours.
+ *
+ * ⚠️ ADOPTION RECORDS THE DECLARED `ha`, BECAUSE NOTHING ELSE CAN. No documented read returns a
+ *   node's HA flag. Adopting an existing node with the wrong `ha` records the wrong value, and no
+ *   later plan can notice. Check the node's HA badge in the dashboard before adopting.
+ */
+export const readMeshNode = (
+  accountId: string,
+  olds: MeshNodeProps | undefined,
+  output: MeshNodeAttributes | undefined,
+) =>
+  Effect.gen(function* () {
+    const account = output?.accountId ?? accountId;
+    if (output !== undefined) {
+      const node = yield* getNode(account, output.id);
+      if (node !== undefined) return attributesOf(node, account, output.ha);
+    }
+    const name = olds?.name ?? output?.name;
+    const ha = olds?.ha ?? output?.ha;
+    if (name === undefined || ha === undefined) return undefined;
+    const match = yield* findNodeByName(account, name);
+    return match === undefined ? undefined : Unowned(attributesOf(match, account, ha));
+  });
+
+/**
+ * ⛔ NEVER CONVERGE ON A NODE THIS RESOURCE DID NOT FIND BY ITS OWN ID. Alchemy's WarpConnector
+ *   answers `DuplicateTunnelName` by re-reading the node that holds the name and returning it.
+ *   Here that would be wrong in exactly the case that matters: an `ha` replace whose old node is
+ *   still alive (the default `retain` skips the delete-first teardown, mesh-node.ts) would
+ *   "create" by silently re-using the old node and record the new `ha` on it. Adoption belongs to
+ *   `read` and `adopt(true)`. An interrupted create is recovered through `read` too, which returns
+ *   the node `Unowned`, so the engine asks for `adopt(true)` there as well (as for WarpConnector).
+ */
+const nameTaken = (name: string, holder: string) =>
+  new MeshNodeError({
+    message:
+      `A tunnel named "${name}" already exists (${holder}). Names are unique per account, and ` +
+      'this resource never takes over a node it did not create by its own id.',
+  });
+
+/**
+ * ★ HOW TO TAKE A NODE OVER WHILE THIS RESOURCE HAS A STATE ROW, WRITTEN ONCE. The plan asks
+ *   `read` to adopt only for a resource with NO row (Plan.ts, `oldState === undefined`) or for an
+ *   interrupted create's `creating` row. A replace's `replacing` row gets neither, so `adopt(true)`
+ *   alone changes nothing there and the create refuses again (measured in mesh-node-policy.test.ts).
+ *   `alchemy state rm` is Alchemy's "Delete state records without deleting cloud resources".
+ */
+const REOWN =
+  "drop this resource's state row (alchemy state rm, which leaves the node alone), then deploy " +
+  'under adopt(true)';
+
+/**
+ * 🔴 THE REFUSAL AN `ha` CHANGE MEETS UNDER THE DEFAULT, SO IT NAMES EVERY WAY ON. The plan says
+ *   `replace` (delete-first), the engine skips that delete because of `retain`, and the old node
+ *   still holds the name here. A node made outside the stack is caught earlier, by the plan's
+ *   adoption probe in `read`.
+ * ⛔ BUT THE HOLDER IS NOT ALWAYS THE OLD NODE, AND `create` CANNOT TELL: the engine passes it no
+ *   `olds` (Apply.ts, the replace branch). An `ha` + `name` change is a create-first replace, and
+ *   there the holder of the NEW name is some other node, which `RemovalPolicy.destroy()` never
+ *   touches. So the old-node advice is conditional, and the other case says not to delete it: a
+ *   sentence that called any holder "the old node" would send an operator to delete a live node
+ *   and cut its replicas off the Mesh (measured 2026-09-21 in mesh-node-policy.test.ts).
+ * ⚠️ REVERTING `ha` DOES NOT UNDO IT. The failed deploy leaves a `replacing` row, and the next
+ *   plan resumes that replace (Plan.ts, the `replacing` branch), so it refuses again. Dropping the
+ *   row and adopting is the way back. All measured in mesh-node-policy.test.ts.
+ */
+const oldNodeHoldsName = (name: string, holder: string) =>
+  new MeshNodeError({
+    message:
+      `Mesh node "${name}" already exists (${holder}) and is not the node this resource tracks, ` +
+      'so it is left alone: names are unique per account. If this deploy changed `ha` and kept ' +
+      "the name, it is this resource's old node, kept by MeshNode's default " +
+      'RemovalPolicy.retain because HA cannot change in place. To replace it (a new id, token and ' +
+      'Mesh IP per replica), deploy once with .pipe(RemovalPolicy.destroy()), which deletes it ' +
+      `first, or delete it by hand. To keep it, reverting \`ha\` is not enough: ${REOWN}, with ` +
+      'the original `ha`. Otherwise it is another node: do not delete it. Choose another name, ' +
+      `or, if it is meant to be this one, check its HA badge, then ${REOWN}.`,
+  });
+
+/**
+ * 🔴 A 1013 AFTER A CLEAN LOOKUP IS USUALLY THIS DEPLOY'S OWN NODE. distilled retries a POST on
+ *   a transport error or a 5xx (core `isTransientError`, measured in its source 2026-09-21), so a
+ *   create that succeeded but lost its response is sent again and answered 1013 by the node the
+ *   first attempt made. The lookup is repeated so the sentence names that node instead of blaming
+ *   another tunnel type; it is still not adopted here (see above), because a concurrent creator
+ *   looks the same and its `ha` is unknown.
+ * ⚠️ `adopt(true)` ALONE ONLY RECOVERS A FIRST CREATE. Inside a replace (any `ha` change, either
+ *   order) the row is `replacing`, which the plan never probes, so the sentence names `REOWN` for
+ *   that case (measured in mesh-node-policy.test.ts).
+ */
+const raced = (accountId: string, name: string) =>
+  findNodeByName(accountId, name).pipe(
+    Effect.flatMap((holder) =>
+      Effect.fail(
+        holder === undefined
+          ? // ⚠️ No live warp_connector of that name: another tunnel TYPE holds it (a cloudflared
+            //   tunnel), or — UNMEASURED — a node deleted moments ago (a delete-first `ha`
+            //   replace) still reserves it.
+            nameTaken(name, 'not a live Mesh node: another tunnel type, or a just-deleted node')
+          : new MeshNodeError({
+              message:
+                `Mesh node "${name}" (${holder.id}) appeared between this deploy's lookup and its ` +
+                'create. The likeliest cause is this deploy itself: the SDK retries a create whose ' +
+                'response was lost. If so, check its HA badge matches the declared `ha`, then ' +
+                'adopt it: adopt(true) after a first create, but after a replace ' +
+                `${REOWN}, because adopt(true) alone does not act on a replace's row. ` +
+                'Otherwise another creator raced this one.',
+            }),
+      ),
+    ),
+  );
+
+const createFresh = (accountId: string, news: MeshNodeProps) =>
+  Effect.gen(function* () {
+    const existing = yield* findNodeByName(accountId, news.name);
+    if (existing !== undefined) return yield* Effect.fail(oldNodeHoldsName(news.name, existing.id));
+    const node = yield* createNode(accountId, news.name, news.ha).pipe(
+      Effect.catchTag('DuplicateTunnelName', () => raced(accountId, news.name)),
+    );
+    return attributesOf(node, accountId, news.ha);
+  });
+
+export const reconcileMeshNode = (
+  accountId: string,
+  news: MeshNodeProps,
+  output: MeshNodeAttributes | undefined,
+) =>
+  Effect.gen(function* () {
+    const invalid = validateMeshNode(news);
+    if (invalid !== undefined) return yield* Effect.fail(invalid);
+    const owned = output !== undefined && output.accountId === accountId ? output : undefined;
+    const live = owned === undefined ? undefined : yield* getNode(accountId, owned.id);
+    // ★ Gone out of band (or a replace's new generation): create, under the same refusals.
+    if (owned === undefined || live === undefined) return yield* createFresh(accountId, news);
+    if (owned.ha !== news.ha) {
+      // ⛔ The plan would have said `replace`; it can only reach here with `ha` unresolved then.
+      return yield* Effect.fail(
+        new MeshNodeError({
+          message: `MeshNode "${news.name}": \`ha\` is create-only (stored ${owned.ha}, declared ${news.ha}). Plan again so the change is a replace.`,
+        }),
+      );
+    }
+    if (live.name === news.name) return attributesOf(live, accountId, owned.ha);
+    const renamed = yield* renameNode(accountId, live.id, news.name).pipe(
+      Effect.catchTag('DuplicateTunnelName', () =>
+        Effect.fail(nameTaken(news.name, 'held by another tunnel')),
+      ),
+    );
+    return attributesOf(renamed, accountId, owned.ha);
+  });
+
+/**
+ * ⚠️ Cloudflare may refuse to delete a node while replicas are connected (Alchemy's WarpConnector
+ *   notes "Deleting requires all connector sessions to be down"; unmeasured here). Stop the
+ *   client on every replica first. A node already gone is a successful delete.
+ */
+export const deleteMeshNode = (output: MeshNodeAttributes) =>
+  deleteNode(output.accountId, output.id);