@homeflare/alchemy 0.6.0 → 0.7.0

package/src/cloudflare/fake-mesh.ts

@@ -0,0 +1,181 @@
+/**
+ * A fake Cloudflare `warp_connector` API for the MeshNode tests — an in-memory `fetch` handed to
+ * Effect's real FetchHttpClient through its `Fetch` reference, so the tests exercise distilled's
+ * real path assembly, query and body encoding, envelope decoding and error matching.
+ *
+ * ⛔ TEST-ONLY, AND NO NETWORK. No provider imports this file. The base URL is RFC 2606
+ *   `api.example.com`, and any request outside `/accounts/<FAKE_ACCOUNT>/warp_connector` throws, so
+ *   a mis-wired test fails instead of reaching a real API. The credentials are placeholders.
+ * ★ THE NAME FILTER IS A SUBSTRING MATCH ON PURPOSE. The real filter's exactness is undocumented;
+ *   a loose fake proves the client re-checks the exact name.
+ * ★ PAGES OF TWO by default, so every lookup walks more than one page.
+ * ★ `is_deleted` IS HONOURED AS THE SDK DOCUMENTS IT: `false` → live only, `true` → deleted only,
+ *   absent → every tunnel. So a lookup that forgot the filter sees tombstones and must drop them.
+ * ★ `onCreate` runs before a POST is answered: a test uses it to put a node in the way between
+ *   the provider's lookup and its create — what a retried POST whose first response was lost does.
+ */
+import { type Credentials, fromApiToken } from '@distilled.cloud/cloudflare/Credentials';
+import * as Cloudflare from 'alchemy/Cloudflare';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as Redacted from 'effect/Redacted';
+import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
+
+export const FAKE_BASE = 'https://api.example.com/client/v4';
+export const FAKE_ACCOUNT = '00000000000000000000000000000001';
+/** ⚠️ A placeholder, not a credential. Tests assert it is what the SDK sends. */
+export const FAKE_API_TOKEN = 'placeholder-api-token';
+
+export type FakeNode = {
+  id: string;
+  name: string;
+  ha: boolean;
+  status: string;
+  token: string;
+  deleted_at: string | null;
+};
+
+export type Seen = { readonly method: string; readonly path: string; readonly body: unknown };
+
+const ok = (result: unknown, extra: Record<string, unknown> = {}) =>
+  Response.json({ success: true, errors: [], messages: [], result, ...extra });
+
+export const fakeFailure = (status: number, code: number, message: string) =>
+  Response.json(
+    { success: false, errors: [{ code, message }], messages: [], result: null },
+    { status },
+  );
+
+/** The wire shape of a node, as the API documents it — plus `token` on create, as the HA page says. */
+const wire = (node: FakeNode) => ({
+  id: node.id,
+  account_tag: FAKE_ACCOUNT,
+  created_at: '2026-09-21T00:00:00Z',
+  deleted_at: node.deleted_at,
+  name: node.name,
+  status: node.status,
+  tun_type: 'warp_connector',
+});
+
+export type FakeOptions = {
+  readonly perPage?: number;
+  /** Return a Response to answer the POST with it instead (e.g. `fakeFailure(409, 1013, …)`). */
+  readonly onCreate?: (name: string) => Response | void;
+};
+
+export const fakeMesh = (options: FakeOptions = {}) => {
+  const nodes = new Map<string, FakeNode>();
+  const seen: Seen[] = [];
+  const auth: string[] = [];
+  let next = 1;
+  const live = () => [...nodes.values()].filter((node) => node.deleted_at === null);
+  const listed = (isDeleted: string | null) =>
+    [...nodes.values()].filter((node) =>
+      isDeleted === null ? true : (node.deleted_at !== null) === (isDeleted === 'true'),
+    );
+
+  const seed = (node: Partial<FakeNode> & { name: string }): FakeNode => {
+    const id = node.id ?? `00000000-0000-4000-8000-${String(next++).padStart(12, '0')}`;
+    const full: FakeNode = {
+      id,
+      ha: false,
+      status: 'inactive',
+      token: `fake-node-token-${id}`,
+      deleted_at: null,
+      ...node,
+    };
+    nodes.set(id, full);
+    return full;
+  };
+
+  const route = (method: string, url: URL, body: Record<string, unknown>): Response => {
+    const prefix = `/client/v4/accounts/${FAKE_ACCOUNT}/warp_connector`;
+    if (url.host !== 'api.example.com' || !url.pathname.startsWith(prefix)) {
+      throw new Error(`fake-mesh: unexpected request ${method} ${url.href}`);
+    }
+    const [id, sub] = url.pathname.slice(prefix.length).split('/').filter(Boolean);
+    if (id === undefined && method === 'GET') {
+      const filter = url.searchParams.get('name') ?? '';
+      const page = Number(url.searchParams.get('page') ?? '1');
+      const perPage = Number(url.searchParams.get('per_page') ?? options.perPage ?? 2);
+      const hits = listed(url.searchParams.get('is_deleted')).filter((node) =>
+        node.name.includes(filter),
+      );
+      const slice = hits.slice((page - 1) * perPage, page * perPage);
+      return ok(slice.map(wire), { result_info: { page, per_page: perPage, count: slice.length } });
+    }
+    if (id === undefined && method === 'POST') {
+      const name = String(body['name']);
+      const override = options.onCreate?.(name);
+      if (override !== undefined) return override;
+      if (live().some((node) => node.name === name)) {
+        return fakeFailure(409, 1013, 'Tunnel with name already exists');
+      }
+      const node = seed({ name, ha: body['ha'] === true });
+      return ok({ ...wire(node), token: node.token });
+    }
+    const node = id === undefined ? undefined : nodes.get(id);
+    if (node === undefined) return fakeFailure(404, 1002, 'Tunnel not found');
+    if (sub === 'token' && method === 'GET') return ok(node.token);
+    if (sub !== undefined) throw new Error(`fake-mesh: unexpected ${method} ${url.pathname}`);
+    if (method === 'GET') return ok(wire(node));
+    if (method === 'PATCH') {
+      const name = String(body['name']);
+      if (live().some((other) => other.name === name && other.id !== node.id)) {
+        return fakeFailure(409, 1013, 'Tunnel with name already exists');
+      }
+      node.name = name;
+      return ok(wire(node));
+    }
+    if (method === 'DELETE') {
+      if (node.deleted_at !== null) return fakeFailure(404, 1002, 'Tunnel not found');
+      node.deleted_at = '2026-09-21T01:00:00Z';
+      return ok(wire(node));
+    }
+    throw new Error(`fake-mesh: unexpected ${method} ${url.pathname}`);
+  };
+
+  const fetch = (async (input: string | URL | Request, init?: RequestInit) => {
+    const request =
+      input instanceof Request ? new Request(input, init) : new Request(String(input), init);
+    const url = new URL(request.url);
+    const text = await request.text();
+    const body = text.length === 0 ? {} : (JSON.parse(text) as Record<string, unknown>);
+    seen.push({ method: request.method, path: `${url.pathname}${url.search}`, body });
+    auth.push(request.headers.get('authorization') ?? '');
+    return route(request.method, url, body);
+  }) as typeof globalThis.fetch;
+
+  return { auth, fetch, live, nodes, seed, seen };
+};
+
+export type FakeMesh = ReturnType<typeof fakeMesh>;
+
+/** distilled Credentials + the real FetchHttpClient over the fake — what a Bun script provides. */
+export const fakeClientLayer = (
+  fake: FakeMesh,
+  credentials: Layer.Layer<Credentials> = fromApiToken({
+    apiToken: FAKE_API_TOKEN,
+    apiBaseUrl: FAKE_BASE,
+  }),
+) =>
+  Layer.mergeAll(
+    credentials,
+    FetchHttpClient.layer,
+    Layer.succeed(FetchHttpClient.Fetch, fake.fetch),
+  );
+
+/** …plus the account, as Alchemy's CloudflareEnvironment hands it to a provider. */
+export const fakeProviderLayer = (fake: FakeMesh, accountId: string = FAKE_ACCOUNT) =>
+  Layer.mergeAll(
+    fakeClientLayer(fake),
+    Layer.succeed(
+      Cloudflare.CloudflareEnvironment,
+      Effect.succeed({
+        type: 'apiToken' as const,
+        apiToken: Redacted.make(FAKE_API_TOKEN),
+        accountId,
+        source: { type: 'env' as const },
+      }),
+    ),
+  );

package/src/cloudflare/index.ts

@@ -1,12 +1,18 @@
 /**
  * Cloudflare providers for Alchemy — the gaps the vendor SDK leaves.
  *
- * ★ Built on the official `cloudflare` SDK, not hand-rolled HTTP: it already has
- *   `r2.buckets.locks.update/get` over the documented endpoints, so there is no path
- *   string this package invents.
+ * ★ Built on vendor SDKs, not hand-rolled HTTP. `R2BucketLock` uses the official `cloudflare`
+ *   SDK, which already has `r2.buckets.locks.update/get` over the documented endpoints.
+ *   `MeshNode` uses `@distilled.cloud/cloudflare`, the SDK Alchemy's own Cloudflare providers
+ *   use, because `cloudflare@4.5.0` cannot create an HA node (mesh-node-api.ts). Either way
+ *   there is no path string this package invents.
  */
 export type { R2LockRule } from './lock-rules.ts';
 export { R2BucketLock, type R2BucketLockProps } from './r2-bucket-lock.ts';
+export { MeshNode, MeshNodeProvider, type MeshNodeServices } from './mesh-node.ts';
+export type { MeshNodeAttributes, MeshNodeProps } from './mesh-node-form.ts';
+export { MeshNodeError, type MeshNodeStatus } from './mesh-node-api.ts';
+export { fetchMeshNodeToken, type MeshNodeRef } from './mesh-node-token.ts';
 export { providers } from './providers.ts';
 export {
   astroWebsite,

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

@@ -0,0 +1,127 @@
+/**
+ * The `warp_connector` calls a Cloudflare Mesh node needs, and nothing else.
+ *
+ * ★ A MESH NODE IS A `warp_connector` OBJECT. Cloudflare's Mesh docs create one with
+ *   `POST /accounts/{account_id}/warp_connector` and fetch its enrolment token from
+ *   `GET …/warp_connector/{id}/token` (developers.cloudflare.com/mesh/get-started, read
+ *   2026-09-21). There is no separate "mesh node" endpoint.
+ *
+ * ★ OVER `@distilled.cloud/cloudflare`, THE SDK ALCHEMY'S OWN CLOUDFLARE PROVIDERS USE, not the
+ *   `cloudflare` npm SDK the R2 lock uses. Measured 2026-09-21: `cloudflare@4.5.0`'s
+ *   `WARPConnectorCreateParams` has only `account_id` and `name`, so it cannot create an HA node.
+ *   distilled `1.0.0-rc.12` (the version alchemy@2.0.0-beta.79 pins) has `ha?: boolean` on
+ *   `CreateTunnelWarpConnectorRequest`, typed errors (`TunnelNotFound` code 1002 / 404,
+ *   `DuplicateTunnelName` code 1013), and resolves credentials and the account exactly the way
+ *   `Cloudflare.Tunnel.WarpConnector` and `Cloudflare.Gateway.Rule` do — so the node and the Gateway
+ *   rules that pin its Mesh IP always land in the same account.
+ *
+ * ⛔ NO FUNCTION IN THIS FILE READS THE NODE TOKEN, and `observe` copies named fields only. The
+ *   HA docs say the create response carries a `token` field; distilled's decoder copies only the
+ *   fields in its schema (protocol.ts, `getProps(outputAst)`), and `observe` below would drop it
+ *   again if it ever got through. The one token read lives in mesh-node-token.ts, on demand.
+ */
+import * as zeroTrust from '@distilled.cloud/cloudflare/zero-trust';
+import * as Data from 'effect/Data';
+import * as Effect from 'effect/Effect';
+import * as Stream from 'effect/Stream';
+
+/** `inactive` (never run), `degraded`, `healthy` or `down` — Cloudflare's own four. */
+export type MeshNodeStatus = 'inactive' | 'degraded' | 'healthy' | 'down';
+
+/** A live node as this package sees it. ⛔ There is no token field here, on purpose. */
+export interface ObservedNode {
+  readonly id: string;
+  readonly name: string;
+  readonly status: MeshNodeStatus | undefined;
+}
+
+/** A refusal or failure, carrying the sentence an operator needs. Never a token. */
+export class MeshNodeError extends Data.TaggedError('MeshNodeError')<{
+  readonly message: string;
+}> {}
+
+type Raw = {
+  readonly id?: string | null;
+  readonly name?: string | null;
+  readonly status?: string | null;
+  readonly deletedAt?: string | null;
+};
+
+const STATUSES: readonly string[] = ['inactive', 'degraded', 'healthy', 'down'];
+
+/**
+ * ⚠️ A DELETED NODE IS NOT A NODE. Cloudflare keeps deleted tunnels (every response carries
+ *   `deleted_at`, and the list takes `is_deleted`), so a `GET` by id can answer for one. Treating
+ *   that as live would "adopt" a tombstone and PATCH it.
+ */
+export const observe = (raw: Raw): ObservedNode | undefined => {
+  if (typeof raw.id !== 'string' || raw.id.length === 0) return undefined;
+  if (raw.deletedAt !== undefined && raw.deletedAt !== null) return undefined;
+  const status =
+    typeof raw.status === 'string' && STATUSES.includes(raw.status)
+      ? (raw.status as MeshNodeStatus)
+      : undefined;
+  return { id: raw.id, name: raw.name ?? '', status };
+};
+
+/** The node with this id, or `undefined` when it is gone (404 / code 1002, or soft-deleted). */
+export const getNode = (accountId: string, nodeId: string) =>
+  zeroTrust.getTunnelWarpConnector({ accountId, tunnelId: nodeId }).pipe(
+    Effect.map(observe),
+    Effect.catchTag('TunnelNotFound', () => Effect.succeed(undefined)),
+  );
+
+/**
+ * The live node with exactly this name, or `undefined`.
+ *
+ * ★ `name` is also sent as the list filter, but the match is re-checked here: the filter's
+ *   exactness is not documented, and a prefix match would adopt the wrong node.
+ * ⛔ Two live matches is refused rather than resolved. Names are unique per account (the create
+ *   answers code 1013 otherwise), so two means something this package does not understand.
+ */
+export const findNodeByName = (accountId: string, name: string) =>
+  zeroTrust.listTunnelWarpConnectors.items({ accountId, name, isDeleted: false }).pipe(
+    Stream.map(observe),
+    Stream.filter((node): node is ObservedNode => node !== undefined && node.name === name),
+    Stream.runCollect,
+    Effect.flatMap((chunk) => {
+      const matches = Array.from(chunk);
+      if (matches.length <= 1) return Effect.succeed(matches[0]);
+      const ids = matches.map((node) => node.id).join(', ');
+      return Effect.fail(
+        new MeshNodeError({
+          message: `Mesh node name "${name}" matches ${matches.length} live nodes (${ids}). Names are unique per account, so refusing to guess which one is meant.`,
+        }),
+      );
+    }),
+  );
+
+/**
+ * ⛔ `ha` IS SENT ON CREATE AND NOWHERE ELSE. Cloudflare's HA page: "High availability is set at
+ *   node creation time and cannot be changed afterward." The PATCH body (`PatchTunnelWarpConnector
+ *   Request`) has only `name` and `tunnelSecret`.
+ */
+export const createNode = (accountId: string, name: string, ha: boolean) =>
+  zeroTrust.createTunnelWarpConnector({ accountId, name, ha }).pipe(
+    Effect.flatMap((raw) => {
+      const node = observe(raw);
+      return node === undefined
+        ? Effect.fail(
+            new MeshNodeError({ message: `Creating Mesh node "${name}" returned no id.` }),
+          )
+        : Effect.succeed(node);
+    }),
+  );
+
+/** ★ A rename is a PATCH: same id, same token, same enrolled replicas and Mesh IP. */
+export const renameNode = (accountId: string, nodeId: string, name: string) =>
+  zeroTrust
+    .patchTunnelWarpConnector({ accountId, tunnelId: nodeId, name })
+    .pipe(Effect.map((raw) => observe(raw) ?? { id: nodeId, name, status: undefined }));
+
+/** Idempotent: a node already gone (404 / code 1002) is a successful delete. */
+export const deleteNode = (accountId: string, nodeId: string) =>
+  zeroTrust.deleteTunnelWarpConnector({ accountId, tunnelId: nodeId }).pipe(
+    Effect.asVoid,
+    Effect.catchTag('TunnelNotFound', () => Effect.void),
+  );

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;
+};