@homeflare/alchemy 0.37.8 → 0.39.0

package/src/proxmox/storage-download-props.ts

@@ -0,0 +1,38 @@
+/** What a `Proxmox.StorageDownload` declaration says, and what its state keeps. See storage-download.ts's header. */
+import type { WithTarget } from './resource.ts';
+
+export type ChecksumAlgorithm = 'md5' | 'sha1' | 'sha224' | 'sha256' | 'sha384' | 'sha512';
+
+export interface StorageDownloadProps extends WithTarget {
+  /** The node this download runs on. Content lands on `storage`, shared or not — see the header. */
+  node: string;
+  storage: string;
+  /** The name PVE gives the file under `storage`'s `import` content. Normalized by PVE on write. */
+  filename: string;
+  /** Where to fetch the image from. ⚠️ Not re-verified after create — PVE does not store it. */
+  url: string;
+  /** ⛔ Required. See storage-download.ts's header on why this resource narrows the vendor's own optional field. */
+  checksum: string;
+  checksumAlgorithm: ChecksumAlgorithm;
+  /** Decompress the downloaded file with this algorithm before it lands on `storage`. */
+  compression?: string;
+  /** Verify the source's TLS certificate. PVE defaults this on; declare `false` for a self-signed mirror. */
+  verifyCertificates?: boolean;
+}
+
+export interface StorageDownloadAttributes {
+  node: string;
+  storage: string;
+  filename: string;
+  /**
+   * ⚠️ REASONED, NOT MEASURED LIVE. PVE's file-based content types spell a volid
+   *   `<storage>:<segment>/<filename>` — this codebase already relies on that shape for `iso` and
+   *   `vztmpl` (lxc-create-form.ts's `existingVolume`, lxc-create.test.ts's own fixture) — but the
+   *   exact `<segment>` spelling for `import` content is not independently confirmed against a
+   *   live cluster. `storage-download-lifecycle.ts`'s `readDownload` does not depend on knowing
+   *   it: it matches by filename SUFFIX within a list already server-filtered to `content=import`.
+   */
+  volid: string;
+  size: number;
+  format: string;
+}

package/src/proxmox/storage-download-task.ts

@@ -0,0 +1,72 @@
+/**
+ * `download-url` and the content DELETE both answer a UPID (protocol.ts's "three 200-traps",
+ * trap (a)) — bounded task observation on the exact credential that started the worker.
+ * ★ THE SAME SHAPE AS qemu-task.ts/lxc-task.ts. Not merged with either: a fourth near-identical
+ *   copy would be the moment to extract a shared poller, not this one (⚠️ flagged, not fixed here
+ *   — see the PR description).
+ */
+import * as nodes from '@distilled.cloud/proxmox/nodes';
+import type { ProxmoxOpContext } from '@distilled.cloud/proxmox/Protocol';
+import * as Effect from 'effect/Effect';
+import { runPveWith } from './distilled-pve.ts';
+import { mint } from './mint.ts';
+import { StorageDownloadRefusedError } from './storage-download-errors.ts';
+import { text } from './values.ts';
+import type { PveTarget } from './credentials.ts';
+
+export interface StorageDownloadWhere {
+  readonly node: string;
+  readonly target: PveTarget;
+}
+
+/**
+ * ⛔ A CHECKSUM MISMATCH SURFACES HERE, NOT AS A DISTINCT TYPED ERROR. `download-url`'s POST
+ *   answers 200 with a UPID regardless of whether the checksum will match — PVE validates the
+ *   download itself, INSIDE the task, and reports the mismatch as that task's `exitstatus`. So
+ *   the refusal below (`exit !== 'OK'`) IS the checksum-mismatch refusal: this poller fails the
+ *   plan whenever the task did not report exactly `"OK"`, whatever the reason, without needing a
+ *   new SDK tag to name it.
+ */
+export const storageDownloadTask = <E>(
+  where: StorageDownloadWhere,
+  operation: Effect.Effect<string, E, ProxmoxOpContext>,
+  what: string,
+  polls: number,
+) =>
+  Effect.gen(function* () {
+    const credential = yield* mint(where.target, 'provision');
+    const upid = text(yield* runPveWith(where.target, credential, true, operation));
+    if (upid === '') {
+      return yield* Effect.fail(
+        new StorageDownloadRefusedError(
+          `${what}: PVE returned no task id, so the write cannot be confirmed and is not claimed.`,
+        ),
+      );
+    }
+    let exit = 'still running when this provider stopped waiting';
+    for (let attempt = 0; attempt < polls; attempt++) {
+      const status = yield* runPveWith(
+        where.target,
+        credential,
+        false,
+        nodes.getNodeTaskStatus({ node: where.node, upid }),
+      ).pipe(Effect.orElseSucceed(() => undefined));
+      // ⚠️ Matches qemu-task.ts's own note: only exactly "stopped" ends the poll.
+      if (status === undefined || status.status === undefined) {
+        exit = 'the task could not be read';
+        break;
+      }
+      if (status.status === 'stopped') {
+        exit = text(status.exitstatus, 'stopped with no exitstatus');
+        break;
+      }
+      yield* Effect.sleep('1 second');
+    }
+    if (exit !== 'OK') {
+      return yield* Effect.fail(
+        new StorageDownloadRefusedError(
+          `${what}: task ${upid} ended "${exit}". Read the task log before running the deploy again.`,
+        ),
+      );
+    }
+  });

package/src/proxmox/storage-download.test.ts

@@ -0,0 +1,216 @@
+/**
+ * `Proxmox.StorageDownload` engine tests over a stub fetch. No live host, no live cluster.
+ * ⚠️ The exact `import/` volid segment is REASONED, not measured — see storage-download-props.ts.
+ *   These fixtures spell it that way for readability only; `readDownload` matches by filename
+ *   suffix, so the tests below would pass with any segment spelling PVE actually uses.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import { engineOver } from '../verify/fake-engine.ts';
+import { FAKE_TARGET, type FakePve, fakePve, withoutBao } from './fake-pve.ts';
+import type { StorageDownloadProps } from './storage-download-props.ts';
+import { ProxmoxStorageDownload, ProxmoxStorageDownloadProvider } from './storage-download.ts';
+
+const NODE = 'pve1';
+const STORAGE = 'cephfs-tb4';
+const FILENAME = 'talos-v1.13.0-metal-amd64.qcow2';
+const UPID = `UPID:${NODE}:00000002:0:0:imgdownload:${STORAGE}:test@pve!fake:`;
+const row = (over: Partial<Record<string, unknown>> = {}) => ({
+  format: 'qcow2',
+  size: 123_456,
+  volid: `${STORAGE}:import/${FILENAME}`,
+  ...over,
+});
+
+const declare = (over: Partial<StorageDownloadProps> = {}): StorageDownloadProps => ({
+  checksum: 'a'.repeat(64),
+  checksumAlgorithm: 'sha256',
+  filename: FILENAME,
+  node: NODE,
+  storage: STORAGE,
+  target: FAKE_TARGET,
+  url: 'https://images.example.test/talos.qcow2',
+  ...over,
+});
+
+const engine = (fake: FakePve) =>
+  engineOver(ProxmoxStorageDownloadProvider().pipe(Layer.provideMerge(fake.layer)));
+
+const isTaskStatus = (call: { method: string; path: string }) =>
+  call.path.includes('/tasks/') && call.path.endsWith('/status');
+const isList = (call: { method: string; path: string }) =>
+  call.method === 'GET' && call.path.includes('/content?');
+const isDownload = (call: { method: string; path: string }) =>
+  call.method === 'POST' && call.path.endsWith('/download-url');
+
+describe('creating a download', () => {
+  test('one POST to download-url, a task wait, then the next plan is noop', async () => {
+    let downloaded = false;
+    const fake = fakePve((call) => {
+      if (isTaskStatus(call)) return { status: 'stopped', exitstatus: 'OK' };
+      if (isList(call)) return downloaded ? [row()] : [];
+      if (isDownload(call)) {
+        downloaded = true;
+        return UPID;
+      }
+      return null;
+    });
+    await withoutBao(async () => {
+      const stack = engine(fake);
+      expect(await stack.deploy(ProxmoxStorageDownload('image', declare()))).toEqual({
+        image: 'create',
+      });
+      expect(
+        (await stack.verify(ProxmoxStorageDownload('image', declare()), { all: true })).rows[0],
+      ).toMatchObject({ diff: 'noop' });
+    });
+    expect(fake.writes()).toEqual([`POST nodes/${NODE}/storage/${STORAGE}/download-url`]);
+    const posted = fake.calls.find((call) => call.method === 'POST')?.form;
+    expect(posted?.['checksum']).toBe('a'.repeat(64));
+    expect(posted?.['checksum-algorithm']).toBe('sha256');
+    expect(posted?.['content']).toBe('import');
+    expect(fake.calls.some((call) => call.path.includes('/tasks/'))).toBe(true);
+  });
+
+  test('⛔ checksum is required: an empty one is refused before any write ("checksum-pinned")', async () => {
+    const fake = fakePve((call) => (isList(call) ? [] : null));
+    await withoutBao(async () => {
+      await expect(
+        engine(fake).deploy(ProxmoxStorageDownload('image', declare({ checksum: '  ' }))),
+      ).rejects.toThrow(/checksum is required/);
+    });
+    expect(fake.writes()).toEqual([]);
+  });
+
+  test('a failed download task refuses the plan — the checksum-mismatch refusal', async () => {
+    const fake = fakePve((call) => {
+      if (isTaskStatus(call)) return { exitstatus: 'checksum mismatch', status: 'stopped' };
+      if (isList(call)) return [];
+      if (isDownload(call)) return UPID;
+      return null;
+    });
+    await withoutBao(async () => {
+      await expect(engine(fake).deploy(ProxmoxStorageDownload('image', declare()))).rejects.toThrow(
+        /checksum mismatch/,
+      );
+    });
+  });
+});
+
+describe('removing a download', () => {
+  test('not retain by default: dropping the declaration deletes the file and waits for its task', async () => {
+    let exists = false;
+    const fake = fakePve((call) => {
+      if (isTaskStatus(call)) return { status: 'stopped', exitstatus: 'OK' };
+      if (isList(call)) return exists ? [row()] : [];
+      if (isDownload(call)) {
+        exists = true;
+        return UPID;
+      }
+      if (call.method === 'DELETE') {
+        exists = false;
+        return UPID;
+      }
+      return null;
+    });
+    await withoutBao(async () => {
+      const stack = engine(fake);
+      await stack.deploy(ProxmoxStorageDownload('image', declare()));
+      await stack.deploy(Effect.void);
+    });
+    expect(fake.writes()).toHaveLength(2);
+    expect(fake.writes()[0]).toBe(`POST nodes/${NODE}/storage/${STORAGE}/download-url`);
+    expect(fake.writes()[1]).toMatch(
+      new RegExp(`^DELETE nodes/${NODE}/storage/${STORAGE}/content/`),
+    );
+  });
+
+  test('⛔ idempotent delete: a volume already gone by removal time sends no DELETE', async () => {
+    let created = false;
+    let vanished = false;
+    const fake = fakePve((call) => {
+      if (isTaskStatus(call)) return { status: 'stopped', exitstatus: 'OK' };
+      if (isList(call)) return created && !vanished ? [row()] : [];
+      if (isDownload(call)) {
+        created = true;
+        return UPID;
+      }
+      return null; // a DELETE here would fail the test below by never answering it
+    });
+    await withoutBao(async () => {
+      const stack = engine(fake);
+      await stack.deploy(ProxmoxStorageDownload('image', declare()));
+      vanished = true; // out-of-band: something else already removed the file
+      await stack.deploy(Effect.void);
+    });
+    expect(fake.writes()).toEqual([`POST nodes/${NODE}/storage/${STORAGE}/download-url`]);
+  });
+});
+
+describe('identity (red-team I1/I2 on PR 297)', () => {
+  test('a changed filename replaces: the old file is deleted, the new one downloaded', async () => {
+    const NEW_FILENAME = 'talos-v1.14.0-metal-amd64.qcow2';
+    // ⚠️ ALCHEMY REPLACES CREATE-FIRST (acl.test.ts's own note): the new file exists alongside the
+    //   old one for a moment, so the fixture tracks a SET of files, not one current name.
+    const files = new Set<string>();
+    const fake = fakePve((call) => {
+      if (isTaskStatus(call)) return { status: 'stopped', exitstatus: 'OK' };
+      if (isList(call)) return [...files].map((f) => row({ volid: `${STORAGE}:import/${f}` }));
+      if (isDownload(call)) {
+        files.add(call.form['filename'] ?? '');
+        return UPID;
+      }
+      if (call.method === 'DELETE') {
+        // ⚠️ The volid path segment may arrive percent-encoded (its own `:` and `/`) — match by
+        //   decoded suffix, the same way readDownload matches a listed row (storage-download-props.ts).
+        const decoded = decodeURIComponent(call.path);
+        const gone = [...files].find((f) => decoded.endsWith(f));
+        if (gone !== undefined) files.delete(gone);
+        return UPID;
+      }
+      return null;
+    });
+    await withoutBao(async () => {
+      const stack = engine(fake);
+      await stack.deploy(ProxmoxStorageDownload('image', declare()));
+      expect(
+        await stack.deploy(ProxmoxStorageDownload('image', declare({ filename: NEW_FILENAME }))),
+      ).toEqual({ image: 'replace' });
+    });
+    const [download1, download2] = fake.writes().filter((w) => w.includes('download-url'));
+    expect(download1).toBeDefined();
+    expect(download2).toBeDefined();
+    expect(fake.writes().some((w) => w.startsWith('DELETE') && w.endsWith(FILENAME))).toBe(true);
+    expect(files).toEqual(new Set([NEW_FILENAME]));
+  });
+
+  test('a changed checksum on the same filename is refused, never silently planned noop', async () => {
+    let downloaded = false;
+    const fake = fakePve((call) => {
+      if (isTaskStatus(call)) return { status: 'stopped', exitstatus: 'OK' };
+      if (isList(call)) return downloaded ? [row()] : [];
+      if (isDownload(call)) {
+        downloaded = true;
+        return UPID;
+      }
+      return null;
+    });
+    await withoutBao(async () => {
+      const stack = engine(fake);
+      await stack.deploy(ProxmoxStorageDownload('image', declare()));
+      await expect(
+        stack.deploy(ProxmoxStorageDownload('image', declare({ checksum: 'b'.repeat(64) }))),
+      ).rejects.toThrow(/checksum changed but filename did not/);
+    });
+    expect(fake.writes()).toEqual([`POST nodes/${NODE}/storage/${STORAGE}/download-url`]);
+  });
+});
+
+describe('no secret prop', () => {
+  test('every declared field is a public identity or download parameter, never a credential', () => {
+    for (const key of Object.keys(declare())) {
+      expect(key).not.toMatch(/pass|secret|token|key$|credential/i);
+    }
+  });
+});

package/src/proxmox/storage-download.ts

@@ -0,0 +1,58 @@
+/**
+ * `Proxmox.StorageDownload` — one `download-url` fetch of an image onto a named storage's
+ * `import` content, declared. Joined 2026-09-26 for Talos: a node needs a boot image on shared
+ * storage (`cephtb4`/`cephfs-tb4`) before `Proxmox.Vm` can reference it as a disk source.
+ *
+ * ★ A CREATE-ORIENTED FAMILY, NOT A GENERAL DOWNLOADER. `content` is fixed to `import` — never a
+ *   prop — because that is the one content type a VM disk import consumes; an ISO or a container
+ *   template already has its own path (`upload`, or an out-of-band copy) and does not belong here.
+ *
+ * ⛔ `checksum` AND `checksumAlgorithm` ARE REQUIRED, NOT OPTIONAL, EVEN THOUGH PVE'S OWN SCHEMA
+ *   MARKS BOTH OPTIONAL (`generated/pve/nodes-node-storage-storage.ts`). An unpinned download is
+ *   not a declaration — it is a promise that whatever the URL answers today is what a Talos node
+ *   boots from, silently, on every future adopt. This resource narrows the vendor's own contract
+ *   on purpose; `storage-download-lifecycle.ts`'s `createRefusals` is the runtime backstop for a
+ *   caller that casts around the type.
+ *
+ * ⛔ THERE IS NO UPDATE PATH. PVE does not remember the `url` or `checksum` a volume was created
+ *   from — `GET .../content` reports only `format`/`size`/`volid` — so once the file exists on
+ *   `storage`, this resource has nothing left to compare a new declaration against except the
+ *   PREVIOUS one (storage-download-identity.ts). A DIFFERENT `checksum`/`url` on the SAME `filename`
+ *   is REFUSED, never silently written or silently `noop` (2026-09-26, red-team I2 on PR 297):
+ *   change `filename` to force a new download, which plans a `replace` — the old file is deleted and
+ *   the new one downloaded under its own name — exactly as an immutable artifact should be.
+ *
+ * ⛔ NO SECRET IS A PROP. Every field here — `node`, `storage`, `filename`, `url`, the checksum
+ *   pair, `compression`, `verifyCertificates` — is either an identity or a public download
+ *   parameter; none is a credential, matching the "no secret prop" rule every PVE family here
+ *   carries (see qemu-props.ts's `cipassword`/`machine` for the family that has one to guard).
+ *
+ * ★ NOT `retain` BY DEFAULT, UNLIKE `Proxmox.Vm`/`Proxmox.Lxc`. A downloaded image is reproducible
+ *   from its own declaration (the same `url` and `checksum` rebuild it byte-for-byte); a VM's
+ *   disk state or a container's data is not. Dropping this declaration deletes the file — an
+ *   operator who wants to keep an unreferenced image around pins its own `RemovalPolicy.retain()`.
+ */
+import { Resource } from 'alchemy';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import type { PveRequirements } from './resource.ts';
+import { storageDownloadHandlers } from './storage-download-lifecycle.ts';
+import type { StorageDownloadAttributes, StorageDownloadProps } from './storage-download-props.ts';
+
+export type { StorageDownloadAttributes, StorageDownloadProps } from './storage-download-props.ts';
+
+export interface ProxmoxStorageDownload extends Resource<
+  'Proxmox.StorageDownload',
+  StorageDownloadProps,
+  StorageDownloadAttributes,
+  never,
+  PveRequirements
+> {}
+
+export const ProxmoxStorageDownload = Resource<ProxmoxStorageDownload>('Proxmox.StorageDownload');
+
+export const ProxmoxStorageDownloadProvider = () =>
+  Provider.effect(
+    ProxmoxStorageDownload,
+    Effect.succeed(ProxmoxStorageDownload.Provider.of(storageDownloadHandlers)),
+  );

package/src/telemetry/fake-collector.ts

@@ -0,0 +1,59 @@
+/**
+ * A fake OTLP/HTTP collector for the tests beside it — `Bun.serve` on an ephemeral 127.0.0.1 port,
+ * answering every POST with 200 and recording each request's path, headers and raw body bytes.
+ *
+ * ⛔ TEST-ONLY, and no live call ever leaves this process: nothing here reaches a real Victoria
+ *   endpoint, satisfying the workflow's "no live calls to Victoria from tests" rule. A consumer's
+ *   own integration test points `telemetryLayer` at ITS running Victoria; this file exists so this
+ *   package's tests never need one.
+ * ★ 200 UNCONDITIONALLY. `OtlpExporter.make` treats any non-2xx as a transient failure and retries
+ *   three times with backoff (OtlpExporter.ts `policy`/`retryTransient`) — a fake that ever answered
+ *   with an error would make a test wait through that retry schedule for no reason.
+ * ⛔ RAW BYTES, NOT PARSED JSON (redteam PR 302 CRITICAL item 1, 2026-09-26): `telemetryLayer` now
+ *   sends `OtlpSerialization.layerProtobuf`, not JSON, so there is no body to `JSON.parse`. `sawText`
+ *   below is what every test needing to inspect content uses instead — it works unchanged for either
+ *   encoding, since protobuf's string fields are raw UTF-8 with no escaping: a leaked literal (a
+ *   secret, a span name, `<redacted>`) always appears as a contiguous byte run in the raw body,
+ *   exactly like it would in JSON, with no OTLP protobuf decoder needed to find it.
+ */
+export interface CollectedRequest {
+  readonly path: string;
+  readonly headers: Headers;
+  readonly raw: Uint8Array;
+}
+
+export interface FakeCollector {
+  readonly url: string;
+  readonly requests: CollectedRequest[];
+  /** `requests` filtered to POSTs at exactly this path (e.g. `/v1/traces`). */
+  at(path: string): CollectedRequest[];
+  /** True when `text`'s bytes appear anywhere in ANY collected request's raw body. ASCII text (a
+   * secret, a hostname, `<redacted>`) decodes to itself regardless of what surrounds it in an
+   * otherwise-binary protobuf buffer — see this file's own header for why that's sound. */
+  sawText(text: string): boolean;
+  stop(): void;
+}
+
+const rawTextDecoder = new TextDecoder('utf-8', { fatal: false });
+
+export const fakeCollector = (): FakeCollector => {
+  const requests: CollectedRequest[] = [];
+  const server = Bun.serve({
+    fetch: async (request) => {
+      const url = new URL(request.url);
+      const raw = new Uint8Array(await request.arrayBuffer());
+      requests.push({ headers: request.headers, path: url.pathname, raw });
+      return new Response('{}', { headers: { 'content-type': 'application/json' }, status: 200 });
+    },
+    hostname: '127.0.0.1',
+    port: 0,
+  });
+  return {
+    at: (path) => requests.filter((request) => request.path === path),
+    requests,
+    sawText: (text) =>
+      requests.some((request) => rawTextDecoder.decode(request.raw).includes(text)),
+    stop: () => void server.stop(true),
+    url: `http://127.0.0.1:${String(server.port ?? 0)}`,
+  };
+};

package/src/telemetry/http-client-sealing.test.ts

@@ -0,0 +1,82 @@
+/**
+ * The leak `layer.ts`'s own ★ describes: caddy's `admin-transport-scope.test.ts` measured that a
+ * provider Layer merging its own `HttpClient.HttpClient` straight into its output can shadow a
+ * sibling fetch-based provider's ambient client once both sit in the same `Layer.mergeAll`. This
+ * file is that same test shape, for `telemetryLayer`'s own (real, `fetch`-backed) `FetchHttpClient`.
+ */
+import { afterEach, describe, expect, test } from 'bun:test';
+import { Resource } from 'alchemy';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as HttpClient from 'effect/unstable/http/HttpClient';
+import * as HttpClientResponse from 'effect/unstable/http/HttpClientResponse';
+import { engineOver } from '../verify/fake-engine.ts';
+import { type FakeCollector, fakeCollector } from './fake-collector.ts';
+import { telemetryLayer } from './layer.ts';
+
+interface Probe extends Resource<'Test.TelemetrySealingProbe', { name: string }, { via: string }> {}
+const Probe = Resource<Probe>('Test.TelemetrySealingProbe');
+
+/** A sibling fetch-based provider (Forgejo, LiteLLM in the estate) — it just needs SOME
+ * `HttpClient.HttpClient` in scope, and reports which one it got. */
+const ProbeProvider = (vias: string[]) => {
+  const hit = Effect.gen(function* () {
+    const client = yield* HttpClient.HttpClient;
+    const response = yield* client.get('http://sibling.invalid/probe');
+    vias.push(yield* response.text);
+  });
+  return Provider.succeed(Probe, {
+    read: () => Effect.as(hit, undefined),
+    reconcile: () => Effect.as(hit, { via: 'ambient' }),
+    delete: () => Effect.void,
+  });
+};
+
+/** Answers instantly and records that IT (not telemetry's own client) was the one asked. */
+const labeledClient = (label: string, seen: string[]): Layer.Layer<HttpClient.HttpClient> =>
+  Layer.succeed(
+    HttpClient.HttpClient,
+    HttpClient.make((request) => {
+      seen.push(label);
+      return Effect.succeed(HttpClientResponse.fromWeb(request, new Response(label)));
+    }),
+  );
+
+let otlp: FakeCollector | undefined;
+afterEach(() => {
+  otlp?.stop();
+  otlp = undefined;
+});
+
+describe('telemetryLayer HttpClient sealing', () => {
+  test("a sibling provider merged alongside it gets the AMBIENT client, never telemetry's own", async () => {
+    otlp = fakeCollector();
+    const vias: string[] = [];
+    const ambient = labeledClient('ambient', vias);
+    const engine = engineOver(
+      Layer.mergeAll(
+        ProbeProvider(vias),
+        telemetryLayer({ endpoints: { traces: `${otlp.url}/v1/traces` }, serviceName: 'test' }),
+      ).pipe(Layer.provideMerge(ambient)),
+    );
+    await engine.deploy(Probe('p', { name: 'sibling' }));
+    expect(vias.length).toBeGreaterThan(0);
+    expect(new Set(vias)).toEqual(new Set(['ambient']));
+  });
+
+  test("with no ambient client at all, the sibling fails rather than silently reaching telemetry's own", async () => {
+    otlp = fakeCollector();
+    const vias: string[] = [];
+    // ★ No `ambient` layer this time. If `telemetryLayer`'s `FetchHttpClient` ever leaked into its
+    //   own output, the sibling below would resolve it and this would succeed instead of throwing —
+    //   exactly the failure mode docs/telemetry-spike.md's first run hit by accident before `ambient` was added.
+    const engine = engineOver(
+      Layer.mergeAll(
+        ProbeProvider(vias),
+        telemetryLayer({ endpoints: { traces: `${otlp.url}/v1/traces` }, serviceName: 'test' }),
+      ),
+    );
+    await expect(engine.deploy(Probe('p', { name: 'sibling' }))).rejects.toThrow();
+  });
+});

package/src/telemetry/index.ts

@@ -0,0 +1,10 @@
+/**
+ * `@homeflare/alchemy/telemetry` — an OTLP tracing/logging/metrics Layer for a stack's own
+ * `providers`, off unless a consumer gives it real endpoints. See docs/telemetry.md for how a site
+ * file wires it up and docs/telemetry-spike.md for what a stack's `providers` Layer can and cannot
+ * capture (measured against alchemy 2.0.0-beta.79's own engine).
+ */
+export { telemetryLayer } from './layer.ts';
+export type { TelemetryEndpoints, TelemetryOptions } from './layer.ts';
+export { DROP, REDACTED, redactAttribute, wrapTracer } from './redact.ts';
+export type { RedactionPolicy } from './redact.ts';