@homeflare/alchemy 0.48.0 → 0.49.0

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);

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

@@ -0,0 +1,104 @@
+/**
+ * What Alchemy WRITES for a CloudflaredTunnel, through the real engine (`engine` in
+ * cloudflared-tunnel-harness.ts) over the fake Cloudflare: the serialization proof the resource
+ * exists for, plus the removal policy and adoption, which live in the engine, not the provider.
+ *
+ * ⛔ THE PROOF: the rows in the state store, encoded by Alchemy's own `encodeState` (the function
+ *   LocalState, HttpStateStore and PostgresState all call before writing), contain no `__redacted__`
+ *   marker, no `token` key and no token value — and the fake handed out a token on the create
+ *   response, every wire object and its `/token` endpoint. A negative control shows the same
+ *   encoder DOES write a `Redacted` token as plaintext, so the absence above means something.
+ */
+import { describe, expect, test } from 'bun:test';
+import { adopt } from 'alchemy/AdoptPolicy';
+import * as RemovalPolicy from 'alchemy/RemovalPolicy';
+import * as State from 'alchemy/State';
+import * as Effect from 'effect/Effect';
+import * as Redacted from 'effect/Redacted';
+import { CloudflaredTunnel } from './cloudflared-tunnel.ts';
+import { engine, failureOf, tokenReads, writes } from './cloudflared-tunnel-harness.ts';
+import { fakeTunnels } from './fake-tunnel.ts';
+
+const ADMIN = 'admin';
+const admin = (name = 'k8s-admin') => CloudflaredTunnel(ADMIN, { name });
+
+const persisted = (rows: object) => JSON.stringify(State.encodeState(rows));
+
+describe('CloudflaredTunnel state serialization', () => {
+  test('the persisted state holds no token, no __redacted__ marker and no secret field', async () => {
+    const fake = fakeTunnels();
+    const stack = engine(fake);
+    expect(failureOf(await stack.deploy(admin()))).toBe('');
+    // A second deploy re-reads and re-reconciles: the paths Alchemy's own Tunnel reads the token on.
+    expect(failureOf(await stack.deploy(admin('k8s-admin-2')))).toBe('');
+    const [tunnel] = fake.live();
+    const json = persisted(stack.rows);
+    expect(json).toContain(tunnel?.id ?? 'no tunnel');
+    expect(json).not.toContain(State.REDACTED_MARKER);
+    expect(json).not.toContain(tunnel?.token ?? 'no tunnel');
+    expect(json).not.toContain('fake-tunnel-token');
+    expect(json.toLowerCase()).not.toContain('token');
+    expect(json.toLowerCase()).not.toContain('secret');
+    expect(tokenReads(fake)).toBe(0);
+  });
+
+  test('the attributes in the row are exactly id, accountId and name', async () => {
+    const fake = fakeTunnels();
+    const stack = engine(fake);
+    await stack.deploy(admin());
+    const row = stack.rows['tunnel']?.['test']?.[ADMIN] as { attr?: object } | undefined;
+    expect(Object.keys(row?.attr ?? {}).sort()).toEqual(['accountId', 'id', 'name']);
+  });
+
+  test('negative control: the same encoder writes a Redacted token as a plaintext marker', () => {
+    const json = persisted({ attr: { token: Redacted.make('t0ken') } });
+    expect(json).toContain(State.REDACTED_MARKER);
+    expect(json).toContain('t0ken');
+  });
+});
+
+describe('CloudflaredTunnel through the real engine', () => {
+  test('retain is the default: dropping the declaration leaves the tunnel and sends no DELETE', async () => {
+    const fake = fakeTunnels();
+    const stack = engine(fake);
+    await stack.deploy(admin());
+    expect(failureOf(await stack.deploy(Effect.void))).toBe('');
+    expect(stack.status(ADMIN)).toBeUndefined();
+    expect(fake.live()).toHaveLength(1);
+    expect(writes(fake)).toEqual(['POST']);
+  });
+
+  test('RemovalPolicy.destroy() still reaches the implemented delete', async () => {
+    const fake = fakeTunnels();
+    const stack = engine(fake);
+    await stack.deploy(admin().pipe(RemovalPolicy.destroy()));
+    expect(failureOf(await stack.deploy(Effect.void))).toBe('');
+    expect(fake.live()).toHaveLength(0);
+    expect(writes(fake)).toEqual(['POST', 'DELETE']);
+  });
+
+  test('a rename deploys as a PATCH on the same tunnel', async () => {
+    const fake = fakeTunnels();
+    const stack = engine(fake);
+    await stack.deploy(admin());
+    const [before] = fake.live();
+    expect(failureOf(await stack.deploy(admin('k8s-admin-2')))).toBe('');
+    expect(fake.live().map((t) => [t.id, t.name])).toEqual([[before?.id ?? '', 'k8s-admin-2']]);
+    expect(writes(fake)).toEqual(['POST', 'PATCH']);
+  });
+
+  test('an existing tunnel is refused without adopt(true), adopted with it, and a repeat writes nothing', async () => {
+    const fake = fakeTunnels();
+    const tunnel = fake.seed({ name: 'k8s-admin', status: 'healthy' });
+    const stack = engine(fake);
+    expect(failureOf(await stack.deploy(admin()))).not.toBe('');
+    expect(writes(fake)).toEqual([]);
+    expect(failureOf(await stack.deploy(admin().pipe(adopt(true))))).toBe('');
+    expect(failureOf(await stack.deploy(admin().pipe(adopt(true))))).toBe('');
+    expect(writes(fake)).toEqual([]);
+    expect(fake.live().map((t) => t.id)).toEqual([tunnel.id]);
+    expect(tokenReads(fake)).toBe(0);
+    const row = stack.rows['tunnel']?.['test']?.[ADMIN] as { attr?: { id?: string } } | undefined;
+    expect(row?.attr?.id).toBe(tunnel.id);
+  });
+});