@homeflare/alchemy 0.48.1 → 0.50.0

package/src/cloudflare/cloudflared-tunnel-api.ts

@@ -0,0 +1,150 @@
+/**
+ * The `cfd_tunnel` calls a Cloudflare Tunnel (the cloudflared kind) needs, and nothing else.
+ *
+ * ★ OVER `@distilled.cloud/cloudflare`, THE SDK ALCHEMY'S OWN CLOUDFLARE PROVIDERS USE, the same
+ *   one mesh-node-api.ts calls. The operations are `createTunnelCloudflared` (POST
+ *   `/accounts/{account_id}/cfd_tunnel`), `getTunnelCloudflared`, `patchTunnelCloudflared`,
+ *   `deleteTunnelCloudflared` and the account-wide `listTunnels` (GET `/accounts/{id}/tunnels`,
+ *   filtered to `cfd_tunnel`), all in distilled `1.0.0-rc.13` `src/services/zero_trust.ts`
+ *   (read 2026-10-09).
+ *
+ * ⛔ NO FUNCTION IN THIS FILE CALLS `getTunnelCloudflaredToken`, AND `observe` COPIES NAMED FIELDS
+ *   ONLY. Alchemy's own `Cloudflare.Tunnel.Tunnel` (beta.81, Tunnel/Tunnel.ts `reconcile`, `read`
+ *   and `list`) fetches the token on every call and stores it as a `Redacted` attribute, which
+ *   `encodeState` (State/StateEncoding.ts) writes into state as `{"__redacted__": "<token>"}`:
+ *   plaintext, and the token runs the tunnel. This package never holds it, so there is nothing to
+ *   leak. See cloudflared-tunnel-form.ts.
+ * ⚠️ `createTunnelCloudflared` takes no `tunnelSecret` here either: the schema calls the field the
+ *   password for a locally-managed tunnel and marks it optional (distilled rc.13 zero_trust.ts,
+ *   `CreateTunnelCloudflaredRequest`); that Cloudflare generates one when it is omitted is
+ *   UNVERIFIED, and a remotely managed tunnel needs no secret on our side.
+ */
+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';
+
+/** A live tunnel as this package sees it. ⛔ There is no token or secret field, on purpose. */
+export interface ObservedTunnel {
+  readonly id: string;
+  readonly name: string;
+  /** `undefined` when the response omitted it; only an explicit `local` is refused (lifecycle). */
+  readonly configSrc: 'cloudflare' | 'local' | undefined;
+}
+
+/** A refusal or failure, carrying the sentence an operator needs. Never a token. */
+export class CloudflaredTunnelError extends Data.TaggedError('CloudflaredTunnelError')<{
+  readonly message: string;
+}> {}
+
+type Raw = {
+  readonly id?: string | null;
+  readonly name?: string | null;
+  readonly configSrc?: string | null;
+  readonly tunType?: string | null;
+  readonly deletedAt?: string | null;
+};
+
+/**
+ * ⚠️ A DELETED TUNNEL IS NOT A TUNNEL. Cloudflare keeps deleted tunnels (every response carries
+ *   `deleted_at`), so a `GET` by id can answer for one; adopting that tombstone would PATCH it.
+ * ⚠️ NOR IS ANOTHER TUNNEL TYPE. `/tunnels` lists every type, and a `warp_connector` (a Mesh node)
+ *   shares the account's name space. An item whose `tun_type` is anything but `cfd_tunnel` is not
+ *   ours even when the name matches. A response with no `tun_type` is accepted: it came from a
+ *   `cfd_tunnel`-scoped call.
+ */
+export const observe = (raw: Raw): ObservedTunnel | undefined => {
+  if (typeof raw.id !== 'string' || raw.id.length === 0) return undefined;
+  if (raw.deletedAt !== undefined && raw.deletedAt !== null) return undefined;
+  if (typeof raw.tunType === 'string' && raw.tunType !== 'cfd_tunnel') return undefined;
+  const configSrc =
+    raw.configSrc === 'cloudflare' || raw.configSrc === 'local' ? raw.configSrc : undefined;
+  return { id: raw.id, name: raw.name ?? '', configSrc };
+};
+
+/** The tunnel with this id, or `undefined` when it is gone (404 / code 1002, or soft-deleted). */
+export const getTunnel = (accountId: string, tunnelId: string) =>
+  zeroTrust.getTunnelCloudflared({ accountId, tunnelId }).pipe(
+    Effect.map(observe),
+    Effect.catchTag('TunnelNotFound', () => Effect.succeed(undefined)),
+  );
+
+/**
+ * The live cloudflared tunnel with exactly this name, or `undefined`.
+ *
+ * ★ `name` and `tunTypes` are sent as filters, but the match is re-checked here: the filter's
+ *   exactness is not documented, and a prefix match would adopt the wrong tunnel.
+ * ⛔ 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 findTunnelByName = (accountId: string, name: string) =>
+  zeroTrust.listTunnels.items({ accountId, name, isDeleted: false, tunTypes: ['cfd_tunnel'] }).pipe(
+    Stream.map(observe),
+    Stream.filter((t): t is ObservedTunnel => t !== undefined && t.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((t) => t.id).join(', ');
+      return Effect.fail(
+        new CloudflaredTunnelError({
+          message: `Tunnel name "${name}" matches ${matches.length} live cloudflared tunnels (${ids}). Names are unique per account, so refusing to guess which one is meant.`,
+        }),
+      );
+    }),
+  );
+
+/**
+ * ⛔ ALWAYS `configSrc: 'cloudflare'` (remotely managed), NEVER OMITTED. The dashboard and the
+ *   ingress rules a consumer later PUTs are the remote configuration; a `local` tunnel ignores
+ *   them. The SDK types the field as optional with two values (zero_trust.ts
+ *   `CreateTunnelCloudflaredRequest`) and does not say which is the default, so it is sent
+ *   explicitly. Create-only (the PATCH body has `name` and `tunnelSecret` only).
+ */
+export const createTunnel = (accountId: string, name: string) =>
+  zeroTrust.createTunnelCloudflared({ accountId, name, configSrc: 'cloudflare' }).pipe(
+    Effect.flatMap((raw) => {
+      const tunnel = observe(raw);
+      return tunnel === undefined
+        ? Effect.fail(
+            new CloudflaredTunnelError({ message: `Creating tunnel "${name}" returned no id.` }),
+          )
+        : Effect.succeed(tunnel);
+    }),
+  );
+
+/** ★ A rename is a PATCH: same id, same connectors, same `<id>.cfargotunnel.com` target. */
+export const renameTunnel = (accountId: string, tunnelId: string, name: string) =>
+  zeroTrust
+    .patchTunnelCloudflared({ accountId, tunnelId, name })
+    .pipe(Effect.map((raw) => observe(raw) ?? { id: tunnelId, name, configSrc: undefined }));
+
+/**
+ * ⚠️ The SDK types `deleteTunnelCloudflared`'s errors as `CloudflareOpError`, which has no
+ *   `NotFound`, yet a 404 reaches the caller as `NotFound` at runtime (protocol.ts `HTTP_STATUS_MAP`,
+ *   measured through the fake). So the tag is matched by name, not by `catchTag`'s typed union.
+ */
+const isNotFound = (error: { readonly _tag: string }) => error._tag === 'NotFound';
+
+/**
+ * ⛔ DELETE BY THE STORED ID ONLY, AFTER A READ BY THAT ID. Never by name: a name can have been
+ *   re-used by another tunnel since this one was written, and a delete cannot be taken back. An
+ *   empty id is refused before any request (a blank path segment would address the collection).
+ * ★ Idempotent: a tunnel already gone or soft-deleted is a successful delete, including one that
+ *   vanishes between the read and the DELETE (see `isNotFound`). The API refuses a
+ *   delete while connectors are attached ("The tunnel must have no active connections", SDK doc on
+ *   `deleteTunnelCloudflared`); that error passes through, since the operator must stop cloudflared.
+ */
+export const deleteTunnel = (accountId: string, tunnelId: string) =>
+  Effect.gen(function* () {
+    if (tunnelId.length === 0) {
+      return yield* Effect.fail(
+        new CloudflaredTunnelError({ message: 'Refusing to delete a tunnel with an empty id.' }),
+      );
+    }
+    const live = yield* getTunnel(accountId, tunnelId);
+    if (live === undefined) return;
+    yield* zeroTrust
+      .deleteTunnelCloudflared({ accountId, tunnelId })
+      .pipe(Effect.catchIf(isNotFound, () => Effect.void));
+  });

package/src/cloudflare/cloudflared-tunnel-edges.test.ts

@@ -0,0 +1,179 @@
+/**
+ * CloudflaredTunnelProvider's refusals and recoveries — the cases a mutation of each guard must
+ * break: the two-match refusal, the tunnel-type check, the tombstone check, the 404 on a stored id
+ * (read says missing), the stored account, the 1013 race, the `local` refusal, delete's id
+ * precondition and a tunnel vanishing mid-delete.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { extra, ids, read, reconcile, run, stored, writes } from './cloudflared-tunnel-harness.ts';
+import { FAKE_ACCOUNT, fakeFailure } from './fake-mesh.ts';
+import { fakeTunnels } from './fake-tunnel.ts';
+
+const OTHER_ACCOUNT = '00000000000000000000000000000002';
+const UNKNOWN_ID = '00000000-0000-4000-9000-00000000ffff';
+const props = { name: 'k8s-admin' };
+
+describe('CloudflaredTunnelProvider edges', () => {
+  test('lookups filter by name, live-only and cfd_tunnel on the wire', async () => {
+    const fake = fakeTunnels();
+    await run(fake, (p) => read(p, props));
+    const list = fake.seen.find((s) => s.method === 'GET');
+    expect(list?.path).toContain('/tunnels?');
+    expect(list?.path).toContain('name=k8s-admin');
+    expect(list?.path).toContain('is_deleted=false');
+    expect(list?.path).toContain('tun_types=cfd_tunnel');
+  });
+
+  test('a prefix-only match, a deleted tunnel and a Mesh node of the same name are not adopted', async () => {
+    const fake = fakeTunnels();
+    fake.seed({ name: 'k8s-admin-2' });
+    fake.seed({ name: 'k8s-admin', deleted_at: '2026-10-08T00:00:00Z' });
+    // ⚠️ The fake's list honours tun_types, so this proves the client's own re-check by id: GET.
+    fake.seed({ name: 'k8s-admin', tun_type: 'warp_connector' });
+    expect(await run(fake, (p) => read(p, props))).toBeUndefined();
+    const mesh = [...fake.tunnels.values()].find((t) => t.tun_type === 'warp_connector');
+    const viaId = stored(FAKE_ACCOUNT, { id: mesh?.id ?? '' });
+    expect(await run(fake, (p) => read(p, { name: 'zz' }, viaId))).toBeUndefined();
+  });
+
+  test('two live tunnels with the declared name are refused, both named', async () => {
+    const fake = fakeTunnels();
+    const a = fake.seed({ name: 'k8s-admin' });
+    const b = fake.seed({ name: 'k8s-admin' });
+    const failure = await run(fake, (p) => Effect.flip(read(p, props)));
+    expect(failure.message).toContain(a.id);
+    expect(failure.message).toContain(b.id);
+  });
+
+  test('a stored id the API no longer knows (404): read says missing and never probes the name, reconcile creates', async () => {
+    const fake = fakeTunnels();
+    // ⚠️ A same-named foreign tunnel: Drift treats what read returns as ours, so adopting it
+    // here would bypass adopt(true). The probe is for a row-less read only.
+    fake.seed({ name: 'k8s-admin' });
+    const gone = stored(FAKE_ACCOUNT, { id: UNKNOWN_ID, name: 'k8s-admin' });
+    expect(await run(fake, (p) => read(p, props, gone))).toBeUndefined();
+    expect(fake.seen.map((s) => s.method)).toEqual(['GET']);
+    expect(fake.seen.some((s) => s.path.includes('/tunnels?'))).toBe(false);
+
+    const fresh = fakeTunnels();
+    const created = await run(fresh, (p) => reconcile(p, { name: 'k8s-other' }, gone));
+    expect(created.id).not.toBe(UNKNOWN_ID);
+    expect(writes(fresh)).toEqual(['POST']);
+  });
+
+  test('a gone row over a same-named foreign tunnel: reconcile refuses and names it, writes nothing', async () => {
+    const fake = fakeTunnels();
+    const foreign = fake.seed({ name: 'k8s-admin' });
+    const gone = stored(FAKE_ACCOUNT, { id: UNKNOWN_ID });
+    const failure = await run(fake, (p) => Effect.flip(reconcile(p, props, gone)));
+    expect(failure.message).toContain(foreign.id);
+    expect(failure.message).toContain('already exists');
+    expect(writes(fake)).toEqual([]);
+  });
+
+  test('read refreshes in the account the tunnel was written to, not the current environment', async () => {
+    const fake = fakeTunnels();
+    const tunnel = fake.seed({ name: 'k8s-admin', status: 'healthy' });
+    const output = stored(FAKE_ACCOUNT, { id: tunnel.id });
+    // ⚠️ The fake throws on any other account, so reading in OTHER_ACCOUNT fails this test.
+    const fresh = await run(fake, (p) => read(p, props, output), OTHER_ACCOUNT);
+    expect(fresh).toMatchObject({ id: tunnel.id, accountId: FAKE_ACCOUNT });
+  });
+
+  test('a rename onto a name another tunnel holds is refused, not forced', async () => {
+    const fake = fakeTunnels();
+    fake.seed({ name: 'k8s-taken' });
+    const failure = await run(fake, (p) =>
+      Effect.gen(function* () {
+        const first = yield* reconcile(p, props);
+        return yield* Effect.flip(reconcile(p, { name: 'k8s-taken' }, first));
+      }),
+    );
+    expect(failure.message).toContain('already exists');
+  });
+
+  test('create never converges on a tunnel it did not create', async () => {
+    const fake = fakeTunnels();
+    fake.seed({ name: 'k8s-admin' });
+    const failure = await run(fake, (p) => Effect.flip(reconcile(p, props)));
+    expect(failure.message).toContain('already exists');
+    expect(failure.message).toContain('do not delete it');
+    expect(writes(fake)).toEqual([]);
+  });
+
+  test('a 1013 after a clean lookup names the tunnel that appeared, and does not adopt it', async () => {
+    const fake = fakeTunnels({
+      onCreate: (name) => {
+        fake.seed({ name });
+        return fakeFailure(409, 1013, 'tunnel with name already exists');
+      },
+    });
+    const failure = await run(fake, (p) => Effect.flip(reconcile(p, props)));
+    const holder = fake.live()[0];
+    expect(failure.message).toContain(holder?.id ?? 'no holder');
+    expect(failure.message).toContain('adopt(true)');
+  });
+
+  test('a locally configured tunnel is refused on adoption and left untouched', async () => {
+    const fake = fakeTunnels();
+    const tunnel = fake.seed({ name: 'k8s-admin', config_src: 'local' });
+    const failure = await run(fake, (p) =>
+      Effect.gen(function* () {
+        const adopted = yield* read(p, props);
+        return yield* Effect.flip(reconcile(p, props, adopted));
+      }),
+    );
+    expect(failure.message).toContain('config_src local');
+    expect(writes(fake)).toEqual([]);
+    expect(fake.tunnels.get(tunnel.id)?.name).toBe('k8s-admin');
+  });
+
+  test('delete addresses the stored id only: a same-named newer tunnel survives', async () => {
+    const fake = fakeTunnels();
+    const old = fake.seed({ name: 'k8s-admin', deleted_at: '2026-10-08T00:00:00Z' });
+    const newer = fake.seed({ name: 'k8s-admin' });
+    await run(fake, (p) =>
+      p.delete({ ...ids, ...extra, olds: props, output: stored(FAKE_ACCOUNT, { id: old.id }) }),
+    );
+    expect(writes(fake)).toEqual([]);
+    expect(fake.live().map((t) => t.id)).toEqual([newer.id]);
+  });
+
+  test('delete refuses an empty id before any request', async () => {
+    const fake = fakeTunnels();
+    const failure = await run(fake, (p) =>
+      Effect.flip(
+        p.delete({ ...ids, ...extra, olds: props, output: stored(FAKE_ACCOUNT, { id: '' }) }),
+      ),
+    );
+    expect(failure.message).toContain('empty id');
+    expect(fake.seen).toHaveLength(0);
+  });
+
+  test('a tunnel that vanishes between the pre-read and the DELETE is a successful delete', async () => {
+    const fake = fakeTunnels({ onDelete: () => fakeFailure(404, 1002, 'Tunnel not found') });
+    const tunnel = fake.seed({ name: 'k8s-admin' });
+    await run(fake, (p) =>
+      p.delete({ ...ids, ...extra, olds: props, output: stored(FAKE_ACCOUNT, { id: tunnel.id }) }),
+    );
+    expect(writes(fake)).toEqual(['DELETE']);
+  });
+
+  test('delete while connectors are attached surfaces the API refusal, and deletes nothing', async () => {
+    const fake = fakeTunnels();
+    const tunnel = fake.seed({ name: 'k8s-admin', connected: true });
+    const failure = await run(fake, (p) =>
+      Effect.flip(
+        p.delete({
+          ...ids,
+          ...extra,
+          olds: props,
+          output: stored(FAKE_ACCOUNT, { id: tunnel.id }),
+        }),
+      ),
+    );
+    expect(String(JSON.stringify(failure))).toContain('active connections');
+    expect(fake.live()).toHaveLength(1);
+  });
+});

package/src/cloudflare/cloudflared-tunnel-form.ts

@@ -0,0 +1,78 @@
+/**
+ * `Cloudflare.CloudflaredTunnel` — its props, its attributes, and the pure `diff`.
+ *
+ * ⛔ THE ATTRIBUTES NEVER HOLD A TOKEN OR A SECRET. That is the reason this resource exists next to
+ *   Alchemy's `Cloudflare.Tunnel.Tunnel` (beta.81): its `reconcile`, `read` and `list` all call
+ *   `getTunnelCloudflaredToken` and keep the result as `token: Redacted<string>`, which
+ *   `encodeState` persists as `{"__redacted__": "<token>"}` in the (unencrypted) state store. That
+ *   token is what `cloudflared tunnel run --token` accepts: whoever reads state can run a connector
+ *   for the tunnel and receive its traffic. It also makes every PLAN need a token with a Write
+ *   permission. This resource never calls the endpoint, so a plan runs on a read token.
+ * ★ THE CONNECTOR'S TOKEN IS A RUNTIME CREDENTIAL, NOT INFRASTRUCTURE STATE. Whatever installs the
+ *   connector fetches it at that moment and hands it straight to the workload's secret store.
+ *   Nothing here does, and nothing here exports a helper that would.
+ * ★ SCOPE: the tunnel object only. No ingress rules, no routes, no DNS, no connector Deployment:
+ *   those are separate declarations that name this tunnel's `id`.
+ */
+import type { Diff } from 'alchemy/Diff';
+import type { Input } from 'alchemy/Input';
+import { CloudflaredTunnelError } from './cloudflared-tunnel-api.ts';
+
+export interface CloudflaredTunnelProps {
+  /**
+   * The tunnel's name in the account — and its identity when adopting (names are unique per
+   * account). ★ Changing it RENAMES the tunnel in place (`PATCH`): the id, the connectors and the
+   * `<id>.cfargotunnel.com` target survive.
+   */
+  readonly name: string;
+}
+
+export interface CloudflaredTunnelAttributes {
+  /** The tunnel's UUID: the `<id>.cfargotunnel.com` target and the key for ingress rules. */
+  readonly id: string;
+  /**
+   * The account the provider environment resolved when the tunnel was written. Not a secret; it
+   * is what `delete` and `read` address, so they never act on the current environment's account.
+   */
+  readonly accountId: string;
+  readonly name: string;
+  // ★ No `status`: it moves on its own as connectors attach and drop, so a stored copy would make
+  //   every `alchemy drift` report this tunnel as drifted. Health is the API's or the metrics' to say.
+}
+
+/** ⛔ Fail closed on a declaration the API would accept but nobody meant. */
+export const validateCloudflaredTunnel = (
+  props: CloudflaredTunnelProps,
+): CloudflaredTunnelError | undefined => {
+  if (typeof props.name !== 'string' || props.name.trim().length === 0) {
+    return new CloudflaredTunnelError({
+      message: 'CloudflaredTunnel `name` must be a non-empty string.',
+    });
+  }
+  if (props.name !== props.name.trim()) {
+    return new CloudflaredTunnelError({
+      message: `CloudflaredTunnel name "${props.name}" has leading or trailing whitespace; adoption matches names exactly.`,
+    });
+  }
+  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.
+ * - Name changed → `update` (a PATCH rename).
+ * - Otherwise → no opinion; the engine compares props.
+ */
+export const diffCloudflaredTunnel = (
+  news: Input<CloudflaredTunnelProps>,
+  output: CloudflaredTunnelAttributes | undefined,
+  accountId: string,
+): Diff | undefined => {
+  if (output === undefined) return undefined;
+  if (output.accountId !== accountId) return { action: 'replace' };
+  const name = (news as { readonly name?: unknown }).name;
+  if (typeof name === 'string' && name !== output.name) return { action: 'update' };
+  return undefined;
+};

package/src/cloudflare/cloudflared-tunnel-harness.ts

@@ -0,0 +1,126 @@
+/**
+ * CloudflaredTunnelProvider's handlers, called the way the engine calls them, over the fake
+ * Cloudflare in fake-tunnel.ts — and `engine`, which runs Alchemy's real plan/apply over the same
+ * fake and exposes the state rows it wrote. Shared by cloudflared-tunnel.test.ts,
+ * cloudflared-tunnel-edges.test.ts and cloudflared-tunnel-state.test.ts.
+ *
+ * ⛔ TEST-ONLY, like fake-tunnel.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/http/FetchHttpClient';
+import { CloudflaredTunnel, CloudflaredTunnelProvider } from './cloudflared-tunnel.ts';
+import type {
+  CloudflaredTunnelAttributes,
+  CloudflaredTunnelProps,
+} from './cloudflared-tunnel-form.ts';
+import { fakeProviderLayer } from './fake-mesh.ts';
+import type { FakeTunnels } from './fake-tunnel.ts';
+
+export const ids = { fqn: 'stack/admin', id: 'admin', instanceId: 'i-1' };
+export const extra = { bindings: [] as never, session: undefined as never };
+
+export type P = Effect.Success<typeof CloudflaredTunnel.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: FakeTunnels,
+  use: (p: P) => Effect.Effect<A, E>,
+  accountId?: string,
+) =>
+  Effect.runPromise(
+    Effect.gen(function* () {
+      return yield* use(yield* CloudflaredTunnel.Provider);
+    }).pipe(
+      Effect.provide(
+        CloudflaredTunnelProvider().pipe(Layer.provideMerge(fakeProviderLayer(fake, accountId))),
+      ),
+    ),
+  );
+
+export const reconcile = (
+  p: P,
+  news: CloudflaredTunnelProps,
+  output?: CloudflaredTunnelAttributes,
+) => p.reconcile({ ...ids, ...extra, news, olds: undefined, output });
+
+export const read = (p: P, olds: CloudflaredTunnelProps, output?: CloudflaredTunnelAttributes) =>
+  handler('read', p.read)({ ...ids, olds, output });
+
+export const diff = (
+  p: P,
+  news: CloudflaredTunnelProps,
+  olds: CloudflaredTunnelProps,
+  output: CloudflaredTunnelAttributes,
+) =>
+  handler(
+    'diff',
+    p.diff,
+  )({ ...ids, news, olds, newBindings: [] as never, oldBindings: [] as never, output });
+
+/** A stored attribute set for a tunnel that may or may not exist in the fake. */
+export const stored = (
+  accountId: string,
+  over: Partial<CloudflaredTunnelAttributes> = {},
+): CloudflaredTunnelAttributes => ({
+  id: 'x',
+  accountId,
+  name: 'k8s-admin',
+  ...over,
+});
+
+/** Requests the fake saw for any `/token` path. The provider must never make one. */
+export const tokenReads = (fake: FakeTunnels) =>
+  fake.seen.filter((s) => s.path.includes('/token')).length;
+
+/** The writes the fake saw, in order: `['POST', 'DELETE', …]`. */
+export const writes = (fake: FakeTunnels) =>
+  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 (the same construction as mesh-node-harness.ts, which says why
+ *   `FetchHttpClient.Fetch` is provided around the whole deploy). `rows` is the store itself, so a
+ *   test can serialize exactly what Alchemy would persist.
+ */
+export const engine = (fake: FakeTunnels) => {
+  const rows: Rows = {};
+  const state = Layer.succeed(State.State, State.InMemoryService(rows));
+  const providers = CloudflaredTunnelProvider().pipe(Layer.provide(fakeProviderLayer(fake)));
+  const deploy = <A, E, R>(declare: Effect.Effect<A, E, R>) =>
+    Effect.runPromiseExit(
+      declare.pipe(
+        makeStack({ name: 'tunnel', 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,
+    rows,
+    /** The stored row's status (`created`, `replacing`, …), or `undefined` when there is none. */
+    status: (fqn: string) => rows['tunnel']?.['test']?.[fqn]?.status,
+  };
+};
+
+/** 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/cloudflared-tunnel-lifecycle.ts

@@ -0,0 +1,146 @@
+/**
+ * read / reconcile / delete for `Cloudflare.CloudflaredTunnel`, as plain Effects over the SDK calls
+ * in cloudflared-tunnel-api.ts. cloudflared-tunnel.ts only wires them into Alchemy.
+ */
+import { Unowned } from 'alchemy/AdoptPolicy';
+import * as Effect from 'effect/Effect';
+import {
+  CloudflaredTunnelError,
+  type ObservedTunnel,
+  createTunnel,
+  deleteTunnel,
+  findTunnelByName,
+  getTunnel,
+  renameTunnel,
+} from './cloudflared-tunnel-api.ts';
+import {
+  type CloudflaredTunnelAttributes,
+  type CloudflaredTunnelProps,
+  validateCloudflaredTunnel,
+} from './cloudflared-tunnel-form.ts';
+
+const attributesOf = (tunnel: ObservedTunnel, accountId: string): CloudflaredTunnelAttributes => ({
+  id: tunnel.id,
+  accountId,
+  name: tunnel.name,
+});
+
+/**
+ * Owned: refresh by the stored id. Cold (no stored row): find the live tunnel by exact name and
+ * hand it back `Unowned`, so Alchemy refuses to take it over until the stack says `adopt(true)` —
+ * a `cfd_tunnel` carries no ownership marker to prove it was ours. Adoption is idempotent: the
+ * adopted row holds the id, so every later `read` takes the owned path and writes nothing.
+ *
+ * ⛔ A STORED ID THAT NO LONGER RESOLVES IS "MISSING", NEVER A NAME PROBE. Drift (alchemy beta.81
+ *   src/Drift.ts) passes the row's output and treats whatever `read` returns as already ours
+ *   (`stripUnowned`), then repairs by reconciling onto it. A by-name fallback there would write a
+ *   same-named tunnel somebody else made into this row, bypassing `adopt(true)`; a later rename
+ *   would PATCH it and `RemovalPolicy.destroy` would DELETE it. Returning `undefined` makes Drift
+ *   report "missing" and recreate through `reconcile`, where `createFresh` names the holder.
+ */
+export const readCloudflaredTunnel = (
+  accountId: string,
+  olds: CloudflaredTunnelProps | undefined,
+  output: CloudflaredTunnelAttributes | undefined,
+) =>
+  Effect.gen(function* () {
+    const account = output?.accountId ?? accountId;
+    if (output !== undefined) {
+      const tunnel = yield* getTunnel(account, output.id);
+      return tunnel === undefined ? undefined : attributesOf(tunnel, account);
+    }
+    const name = olds?.name;
+    if (name === undefined) return undefined;
+    const match = yield* findTunnelByName(account, name);
+    return match === undefined ? undefined : Unowned(attributesOf(match, account));
+  });
+
+/**
+ * ⛔ NEVER CONVERGE ON A TUNNEL THIS RESOURCE DID NOT FIND BY ITS OWN ID. Alchemy's own Tunnel
+ *   answers a duplicate-name failure by re-reading the holder and returning it (when its `adopt`
+ *   prop is set). Here adoption belongs to `read` and `adopt(true)` alone, where it is visible in
+ *   the plan. The holder is named, never deleted: it may be a live tunnel that serves traffic.
+ */
+const nameHeld = (name: string, holder: string) =>
+  new CloudflaredTunnelError({
+    message:
+      `A tunnel named "${name}" already exists (${holder}) and is not the tunnel this resource ` +
+      'tracks, so it is left alone: names are unique per account. If it is meant to be this ' +
+      'one, deploy under adopt(true). Otherwise choose another name; do not delete it.',
+  });
+
+/**
+ * 🔴 A 1013 AFTER A CLEAN LOOKUP IS USUALLY THIS DEPLOY'S OWN TUNNEL. distilled retries a POST on a
+ *   transport error or a 5xx, so a create that succeeded but lost its response is sent again and
+ *   answered 1013 by the tunnel the first attempt made. The lookup is repeated so the sentence
+ *   names that tunnel; it is still not adopted here, because a concurrent creator looks the same.
+ */
+const raced = (accountId: string, name: string) =>
+  findTunnelByName(accountId, name).pipe(
+    Effect.flatMap((holder) =>
+      Effect.fail(
+        holder === undefined
+          ? nameHeld(
+              name,
+              'not a live cloudflared tunnel: another tunnel type, or one just deleted',
+            )
+          : new CloudflaredTunnelError({
+              message:
+                `Tunnel "${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, deploy again under adopt(true). Otherwise ' +
+                'another creator raced this one.',
+            }),
+      ),
+    ),
+  );
+
+const createFresh = (accountId: string, name: string) =>
+  Effect.gen(function* () {
+    const existing = yield* findTunnelByName(accountId, name);
+    if (existing !== undefined) return yield* Effect.fail(nameHeld(name, existing.id));
+    const tunnel = yield* createTunnel(accountId, name).pipe(
+      Effect.catchTag('DuplicateTunnelName', () => raced(accountId, name)),
+    );
+    return attributesOf(tunnel, accountId);
+  });
+
+/**
+ * ⛔ `local` IS REFUSED. A tunnel's `config_src` is create-only, and adoption by name could land on
+ *   a locally configured tunnel, whose ingress is a YAML file on its origin: a consumer's remote
+ *   rules would be accepted by the API and never applied. The tunnel is left untouched.
+ */
+const requireRemote = (tunnel: ObservedTunnel) =>
+  tunnel.configSrc === 'local'
+    ? Effect.fail(
+        new CloudflaredTunnelError({
+          message: `Tunnel "${tunnel.name}" (${tunnel.id}) is locally configured (config_src local), which cannot be changed after creation. CloudflaredTunnel manages remotely configured tunnels only; create a new tunnel under another name.`,
+        }),
+      )
+    : Effect.void;
+
+export const reconcileCloudflaredTunnel = (
+  accountId: string,
+  news: CloudflaredTunnelProps,
+  output: CloudflaredTunnelAttributes | undefined,
+) =>
+  Effect.gen(function* () {
+    const invalid = validateCloudflaredTunnel(news);
+    if (invalid !== undefined) return yield* Effect.fail(invalid);
+    const owned = output !== undefined && output.accountId === accountId ? output : undefined;
+    const live = owned === undefined ? undefined : yield* getTunnel(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.name);
+    yield* requireRemote(live);
+    if (live.name === news.name) return attributesOf(live, accountId);
+    const renamed = yield* renameTunnel(accountId, live.id, news.name).pipe(
+      Effect.catchTag('DuplicateTunnelName', () =>
+        Effect.fail(nameHeld(news.name, 'held by another tunnel')),
+      ),
+    );
+    return attributesOf(renamed, accountId);
+  });
+
+/** By the stored id and account only (cloudflared-tunnel-api.ts, `deleteTunnel`). */
+export const deleteCloudflaredTunnel = (output: CloudflaredTunnelAttributes) =>
+  deleteTunnel(output.accountId, output.id);