@homeflare/alchemy 0.22.0 → 0.24.0

package/src/proxmox/zfs-pool.ts

@@ -6,20 +6,22 @@
  *   moment the worker runs. Every other decision in this file follows from that one sentence, and
  *   each of them is written out below rather than left to be inferred.
  *
- * ⛔ DESTROY IS REFUSED. `delete` MAKES NO API CALL — removing this resource from a stack leaves
- *   the zpool and its data exactly where they are, and Alchemy simply forgets about them. The
- *   asymmetry is the whole argument: an ORPHANED pool is recoverable (declare it again, or destroy
- *   it by hand once a human has looked at which disks are in it), a DESTROYED pool is not. Alchemy
- *   deletes for reasons that have nothing to do with anybody intending it — a line removed from a
- *   stack file, a resource renamed so the old id is dropped, a whole stack torn down by the wrong
- *   command, a replace triggered by a prop nobody meant to touch. Handing `zpool destroy` to any
- *   of those is not a feature. MEASURED in the node's own source: the DELETE handler forks
- *   `zfsremove`, which runs `zpool destroy <name>` unconditionally, and with `cleanup-disks` then
- *   calls `wipe_blockdev` on every member. Neither flag is offered as a prop, because there is no
- *   call here for them to reach.
- *   ★ THE OPERATOR'S PATH IS `pvesh delete /nodes/<node>/disks/zfs/<name>`, typed by a person who
- *     has just looked at the pool. Do not "complete the CRUD" by wiring `delete` to `ops.destroy`:
- *     that one line turns a text edit into an unrecoverable one.
+ * ⛔ ★ CORRECTED 2026-09-23 — THIS PARAGRAPH PREVIOUSLY SAID "DESTROY IS REFUSED" AND "`delete`
+ *   MAKES NO API CALL". THAT WAS FALSE: MEASURED against this file's own `handlers.delete` below,
+ *   which calls `destroyPool`, which sends `DELETE /nodes/{node}/disks/zfs/{name}` — the node's
+ *   own source forks `zfsremove`, which runs `zpool destroy <name>` unconditionally, and with
+ *   `cleanup-disks` then calls `wipe_blockdev` on every member (neither flag is offered as a prop,
+ *   because there is no call here for them to reach). `delete` is FULLY IMPLEMENTED, per S14
+ *   (alchemy-provider-standard): a `delete` that silently does nothing lies to whoever reads the
+ *   plan. What actually keeps an ordinary removed declaration from reaching it is
+ *   `defaultRemovalPolicy: 'retain'` below — Alchemy SKIPS `provider.delete` entirely for an
+ *   orphaned or destroyed resource under `retain`, so the state row drops and the zpool and its
+ *   data are left exactly where they are. The asymmetry is still the whole argument: an ORPHANED
+ *   pool is recoverable (declare it again, or destroy it by hand once a human has looked at which
+ *   disks are in it), a DESTROYED pool is not — which is why `retain` is the default rather than a
+ *   documented caution, and why `delete` runs only for a caller who opts in by name with
+ *   `.pipe(RemovalPolicy.destroy())`. See the ★ on `defaultRemovalPolicy` in resource-spec.ts, and
+ *   zfs-pool-adopt.test.ts's mutation row, which pins exactly one DELETE reaching the fake cluster.
  *
  * ⛔ THERE IS NO PUT ON THIS FAMILY AT ALL. MEASURED from the cluster's own published schema
  *   (`/usr/share/pve-docs/api-viewer/apidoc.js`, read on node-b 2026-09-13): `/nodes/{node}/disks/zfs`
@@ -47,39 +49,42 @@
  * ⚠️ TWO HANDLERS ARE OVERRIDDEN AND THE OTHER THREE COME FROM THE FACTORY — see the ★ above
  *   `handlers`. `delete` is the ⛔ above. `reconcile` is because the create is a FORKED WORKER, so
  *   the factory's immediate read-back would report a successful create as a failure; the measured
- *   detail is in the ⛔ on `createPool` in zfs-pool-create.ts.
+ *   detail, and the adopt-only refusal decision 9 adds, are both in `createPool` in
+ *   zfs-pool-write.ts.
  *
  * ⚠️ PRIVILEGES, FROM THE SCHEMA. Read and diff need `Sys.Audit` on `/` — both GETs check it.
  *   Reconcile needs `Sys.Modify` on `/` for the POST. `Datastore.Allocate` on `/storage` is NOT
- *   needed, because `add_storage` is not offered — see the ⛔ on `ZfsPoolProps`. `delete` needs
- *   nothing at all, since it calls nothing.
+ *   needed, because `add_storage` is not offered — see the ⛔ on `ZfsPoolProps`.
+ *   ★ CORRECTED 2026-09-23, ALONGSIDE THE HEADER ABOVE: `delete` needs `Sys.Modify` on `/` too,
+ *   for the DELETE it now sends under `.pipe(RemovalPolicy.destroy())` — the whole `disks/zfs`
+ *   family checks it, not only the POST. MEASURED the same day as the rest of this paragraph:
+ *   `ceph-osd.ts`'s own privilege comparison names `disks/zfs` as one of the sibling families
+ *   whose write verbs DO carry a `Sys.Modify` check, unlike `ceph/osd`'s create and delete, which
+ *   carry no permissions block at all and 403 for any identity but `root@pam`. This line
+ *   previously said delete "needs nothing at all, since it calls nothing", which repeated the same
+ *   mistake the header above corrects: `delete` calls the DELETE endpoint, so it needs whatever
+ *   that endpoint checks.
  */
 import { Resource } from 'alchemy';
 import * as Provider from 'alchemy/Provider';
 import * as Effect from 'effect/Effect';
-import {
-  type PveRequirements,
-  type PveSpec,
-  type WithTarget,
-  pveHandlers,
-  pveOperations,
-} from './resource.ts';
-import { text } from './values.ts';
-import { ZFS_POOL_ENDPOINT, createForm, createPool, destroyPool } from './zfs-pool-write.ts';
+import type { NodesNodeDisksZfsPostParams } from './generated/pve.ts';
+import { type PveRequirements, type WithTarget, pveHandlers, pveOperations } from './resource.ts';
+import { spec } from './zfs-pool-spec.ts';
+import { createPool, destroyPool } from './zfs-pool-write.ts';
 
-/** PVE's layouts. ⚠️ Each has a minimum disk count PVE enforces, and `raid10` needs an even one. */
-export type ZfsRaidLevel =
-  | 'single'
-  | 'mirror'
-  | 'raid10'
-  | 'raidz'
-  | 'raidz2'
-  | 'raidz3'
-  | 'draid'
-  | 'draid2'
-  | 'draid3';
+/**
+ * PVE's layouts, generated (2026-09-23) from `NodesNodeDisksZfsPostParams['raidlevel']`
+ * (`generated/pve.ts`, manifest `pve-apidoc` pve-manager 9.2.11 sha256 9def8f13…) rather than
+ * hand-typed, per decision 9. ⚠️ Each has a minimum disk count PVE enforces, and `raid10` needs an
+ * even one. ⛔ THERE IS NO `stripe` IN THIS ENUM. n1's `speed` pool is one (decision 14 accepts it
+ * as-is): `ZfsPoolProps` below is why a stripe pool is declarable at all — as an ADOPT-ONLY
+ * declaration with no `raidlevel`, never as a full one.
+ */
+export type ZfsRaidLevel = NonNullable<NodesNodeDisksZfsPostParams['raidlevel']>;
 
-export type ZfsCompression = 'on' | 'off' | 'gzip' | 'lz4' | 'lzjb' | 'zle' | 'zstd';
+/** Generated the same way, from `NodesNodeDisksZfsPostParams['compression']`. */
+export type ZfsCompression = NonNullable<NodesNodeDisksZfsPostParams['compression']>;
 
 /**
  * ⛔ THERE IS NO `add_storage`, `cleanup-config` OR `cleanup-disks` PROP, AND THAT IS NOT AN
@@ -112,9 +117,19 @@ export interface ZfsPoolProps extends WithTarget {
    *   `csv` sorts, and sorting this list silently re-pairs the mirrors into a different pool.
    * ⚠️ PVE's only guard is `assert_disk_unused`, i.e. its own `disk_is_used` over the same `used`
    *   column the Disks view shows. A blank disk it considers free is wiped with no confirmation.
+   *
+   * ⛔ OPTIONAL SINCE DECISION 9 (2026-09-23), AND OMITTING IT MEANS SOMETHING SPECIFIC: leaving
+   *   both this and `raidlevel` undeclared declares an ADOPT-ONLY pool — one this resource may
+   *   read and report but never build. That is the only shape available for a pool PVE's own POST
+   *   schema cannot fully describe, such as n1's `speed`, whose layout is a stripe and whose
+   *   `raidlevel` enum (above) has no stripe to declare. `createForm` (zfs-pool-write.ts) omits
+   *   both keys when they are absent, and `createPool` refuses before any POST if the pool it
+   *   would need to build is not already there — an adopt-only declaration never creates. Declare
+   *   both fields together for a pool this resource should build from scratch; declaring only one
+   *   of the two is refused the same way, since PVE's POST requires both.
    */
-  devices: readonly string[];
-  raidlevel: ZfsRaidLevel;
+  devices?: readonly string[];
+  raidlevel?: ZfsRaidLevel;
   /**
    * Sector size exponent, 9–16, PVE default 12.
    *
@@ -174,63 +189,6 @@ export const ProxmoxZfsPool = Resource<ProxmoxZfsPool>('Proxmox.ZfsPool', {
   defaultRemovalPolicy: 'retain',
 });
 
-/**
- * The device paths at the bottom of PVE's vdev tree, in the order ZFS reports them.
- *
- * ⚠️ "NO CHILDREN" IS THE LEAF TEST, AND IT IS NOT A GUESS — MEASURED in the node's `preparetree`,
- *   which sets `leaf` to 0 when there are children and 1 otherwise. Reading the flag would work
- *   equally well; recursing on `children` needs no second field to be present and is what makes
- *   nested sections (mirrors inside a raid10, `spares`, `cache`) flatten correctly.
- */
-const leafDevices = (children: unknown): string[] =>
-  Array.isArray(children)
-    ? children.flatMap((entry: unknown) => {
-        const vdev = entry as { children?: unknown; name?: unknown };
-        const nested = leafDevices(vdev.children);
-        return nested.length > 0 ? nested : [text(vdev.name)].filter((name) => name !== '');
-      })
-    : [];
-
-const spec: PveSpec<ZfsPoolProps, ZfsPoolAttributes> = {
-  /**
-   * ⚠️ `scan`, `status` AND `action` ARE DELIBERATELY NOT ATTRIBUTES. All three are advisory
-   *   strings ZFS rewrites on its own — `scan` on every scrub, the other two as feature flags and
-   *   faults come and go — so keeping them would rewrite this resource's state row for reasons no
-   *   declaration caused. Same reasoning as `digest` in storage.ts.
-   */
-  attributes: (live, props) => {
-    // ⚠️ A detail answer with no `name` is not a pool. `name` is non-optional in PVE's schema, so
-    //   this is a shape check rather than a default — and "absent" is the honest reading of a
-    //   reply that does not describe the object that was asked for.
-    if (text(live['name']) === '') return undefined;
-    return {
-      devices: leafDevices(live['children']).join(','),
-      errors: text(live['errors'], 'unknown'),
-      name: props.name,
-      node: props.node,
-      state: text(live['state'], 'unknown'),
-    };
-  },
-  collection: (props) => `nodes/${props.node}/disks/zfs`,
-  createForm,
-  endpoint: ZFS_POOL_ENDPOINT,
-  /**
-   * ⛔ IT ALWAYS ANSWERS TRUE, AND THAT IS THE POINT OF THIS FILE. A pool that is there under the
-   *   declared name on the declared node IS the declaration, because there is nothing else the two
-   *   can be compared on: every create parameter is write-only (see the ⛔ in the header) and
-   *   everything the read does return is telemetry that moves by itself. So declaring what is live
-   *   plans as `noop` — the only honest answer available, and the one the live cluster needs:
-   *   `rpool` exists on node-b, node-c and node-d with nothing about its construction readable.
-   *   ⛔ ANYTHING ADDED HERE IS A REPLACE, NOT AN UPDATE. `updateForm` is omitted because PVE has
-   *     no PUT, so `resource.ts` turns a false into `{action:'replace'}` — delete then create — on
-   *     a family whose delete is `zpool destroy`. A comparison added here would be one plan away
-   *     from destroying a pool over a field it cannot even read back. If a future PVE grows a PUT,
-   *     add `updateForm` FIRST and only then consider comparing what that PUT accepts.
-   */
-  matches: () => true,
-  path: (props) => `nodes/${props.node}/disks/zfs/${props.name}`,
-};
-
 const ops = pveOperations(spec);
 
 /**

package/src/release/archive.ts

@@ -24,12 +24,17 @@ import { type TarContents, tarReader } from './tar.ts';
 /** How much gzip is handed to the inflater at a time. */
 const SLICE = 1 << 20;
 
-/** Gunzip and read a tar, keeping only `wanted`. Throws ArchiveRefused. */
+/**
+ * Gunzip and read a tar, keeping only `wanted`. Throws ArchiveRefused.
+ * @param root The one declared leading directory to strip (tar.ts) — a directory-wrapped vendor
+ *   archive (the Prometheus family, measured 2026-09-23) without it, or one that carries no root.
+ */
 export const extractMembers = async (
   gzipped: Uint8Array,
   wanted: ReadonlySet<string>,
+  root?: string,
 ): Promise<TarContents> => {
-  const tar = tarReader(wanted);
+  const tar = tarReader(wanted, root);
   // ⚠️ FED IN SLICES, ON DEMAND. Enqueued whole, the 123.6 MB vmutils archive is inflated in one
   //   transform step and all 264 MB of output queue up before the first read: MEASURED 2026-09-22,
   //   a peak RSS of 1116 MB for vmalert alone under bun 1.4.0. `pull` hands over the next slice only
@@ -79,11 +84,12 @@ export const verifiedMember = async (
 ): Promise<Uint8Array> => {
   const archiveSha = sha256Hex(archive);
   if (archiveSha !== release.sha256) throw mismatch(release.url, release.sha256, archiveSha);
-  const { members, names } = await extractMembers(archive, new Set([release.member]));
+  const { members, names } = await extractMembers(archive, new Set([release.member]), release.root);
   const bytes = members.get(release.member);
   if (bytes === undefined) {
+    const under = release.root === undefined ? '' : ` under root "${release.root}/"`;
     throw new ArchiveRefused({
-      message: `${release.url} has no member named exactly "${release.member}" (it has ${names.map((n) => `"${n}"`).join(', ') || 'none'})`,
+      message: `${release.url} has no member named exactly "${release.member}"${under} (it has ${names.map((n) => `"${n}"`).join(', ') || 'none'})`,
     });
   }
   const memberSha = sha256Hex(bytes);

package/src/release/binary-form.ts

@@ -14,6 +14,7 @@
  */
 import type { HostFileAttributes } from '../launchd/host-file-form.ts';
 import { identityProblems, pathProblems } from '../launchd/host-file-form.ts';
+import { pinProblems } from './binary-pins.ts';
 
 /** One release archive, pinned: where it is published, and the bytes it must be. */
 export interface ReleaseArchive {
@@ -30,6 +31,17 @@ export interface ReleaseArchive {
   readonly size: number;
   /** The archive's SHA-256, lower-case hex, as the vendor's checksum file lists it. */
   readonly sha256: string;
+  /**
+   * The one directory the vendor wraps every entry in, exactly as its own archive names it —
+   * `'alertmanager-0.33.1.darwin-arm64'`, never `'alertmanager-0.33.1.darwin-arm64/'` (no trailing
+   * slash). Pinned from the walk-down, never derived from `asset` or `tag`: the vendor spells its
+   * wrapper however it likes (`darwin_arm64`, an `-enterprise` suffix, no version at all), so a
+   * computed name would drift onto a sibling the moment one vendor's naming changes. Omit it for a
+   * flat archive (Victoria, OpenBao); the tar reader then refuses a directory entry exactly as it
+   * always has (tar.ts).
+   * @default undefined — no wrapping directory; the archive is flat.
+   */
+  readonly root?: string;
 }
 
 export interface ReleaseBinaryProps {
@@ -82,6 +94,8 @@ export type PinnedDownload = {
   readonly member: string;
   /** The member's pinned SHA-256. */
   readonly memberSha256: string;
+  /** The one declared leading directory to strip, if the archive has one — `archive.root`. */
+  readonly root?: string;
 };
 
 export const DEFAULT_BINARY_MODE = 0o755;
@@ -109,6 +123,8 @@ export const pinnedDownload = (props: ReleaseBinaryProps): PinnedDownload => ({
   sha256: props.archive.sha256,
   size: props.archive.size,
   url: releaseUrl(props.archive.repo, props.archive.tag, props.archive.asset),
+  // ⚠️ exactOptionalPropertyTypes: never spell out `root: undefined`; leave the key off entirely.
+  ...(props.archive.root === undefined ? {} : { root: props.archive.root }),
 });
 
 export const modeProblems = (mode: number): string[] => {
@@ -123,83 +139,15 @@ export const modeProblems = (mode: number): string[] => {
   return found;
 };
 
-const HEX64 = /^[0-9a-f]{64}$/;
-export const MAX_ARCHIVE = 1 << 30;
-// ⛔ Strict on purpose: each is written into a URL or a path. GitHub's own owner and name alphabet.
-const REPO = /^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?\/[A-Za-z0-9._-]+$/;
-const SEGMENT = /^[A-Za-z0-9._-]+$/;
-// ★ ONLY WHAT THE READER HANDLES: a gzipped tar. A `.zip` or a bare binary is a new capability
-//   with its own walk-down, not a name this should accept and then fail to unpack.
-const TARBALL = /\.(tar\.gz|tgz)$/;
-
-/** A single path segment that cannot climb, hide or name the directory itself. */
-const segmentProblem = (what: string, value: string): string | undefined =>
-  !SEGMENT.test(value) || value === '.' || value === '..'
-    ? `${what} must be one path segment of letters, digits, '.', '_' or '-': ${JSON.stringify(value)}`
-    : undefined;
-
-/** Everything wrong with the pins alone — plain strings in any declaration, resolved or not. */
-export const pinProblems = (props: {
-  readonly archive?: Partial<ReleaseArchive>;
-  readonly member?: unknown;
-  readonly sha256?: unknown;
-  readonly name?: unknown;
-}): string[] => {
-  const archive = props.archive ?? {};
-  const found: string[] = [];
-  const text = (what: string, value: unknown): string | undefined => {
-    if (typeof value === 'string') return value;
-    found.push(`${what} is required, as a plain string`);
-    return undefined;
-  };
-  const repo = text('archive.repo', archive.repo);
-  // ⚠️ `owner/..` passes the alphabet, and a URL parser normalises it away: the request would go
-  //   to `github.com/releases/…`, somewhere nobody pinned. Refused by name.
-  const repoName = repo?.slice(repo.indexOf('/') + 1);
-  if (repo !== undefined && (!REPO.test(repo) || repoName === '.' || repoName === '..'))
-    found.push(`archive.repo must be "owner/name": ${JSON.stringify(repo)}`);
-  for (const [what, value] of [
-    ['archive.tag', archive.tag],
-    ['name', props.name],
-  ] as const) {
-    const given = text(what, value);
-    const problem = given === undefined ? undefined : segmentProblem(what, given);
-    if (problem !== undefined) found.push(problem);
-  }
-  const asset = text('archive.asset', archive.asset);
-  if (asset !== undefined) {
-    const problem = segmentProblem('archive.asset', asset);
-    if (problem !== undefined) found.push(problem);
-    else if (!TARBALL.test(asset))
-      found.push(`archive.asset must be a .tar.gz or .tgz: "${asset}"`);
-  }
-  // ⛔ THE SIZE IS ALLOCATED UP FRONT (download.ts fills one buffer of exactly this many bytes), so
-  //   a typo'd size is a memory bomb in the deploying process. vmutils, the largest archive pinned,
-  //   is 123.6 MB; a gibibyte is a ceiling nothing single-binary should reach.
-  const size = archive.size;
-  if (typeof size !== 'number' || !Number.isSafeInteger(size) || size <= 0 || size > MAX_ARCHIVE) {
-    found.push(`archive.size must be the asset's byte count, 1 to ${String(MAX_ARCHIVE)}`);
-  }
-  for (const [what, value] of [
-    ['archive.sha256', archive.sha256],
-    ['sha256', props.sha256],
-  ] as const) {
-    const given = text(what, value);
-    if (given !== undefined && !HEX64.test(given))
-      found.push(`${what} must be 64 lower-case hex digits`);
-  }
-  const member = text('member', props.member);
-  // ⛔ The tar reader refuses these entries anyway; asking for one is a mistake to name at plan.
-  if (
-    member !== undefined &&
-    (member === '' || member.startsWith('/') || member.split('/').includes('..'))
-  ) {
-    found.push(`member must be a relative name inside the archive: ${JSON.stringify(member)}`);
-  }
-  return found;
-};
+// `pinProblems` (imported above, for `binaryProblems` below) and the constant it needs,
+// `MAX_ARCHIVE`, moved to binary-pins.ts, split out to stay under the file-size cap; re-exported
+// here so every importer of './binary-form.ts' is unchanged.
+export { MAX_ARCHIVE, pinProblems } from './binary-pins.ts';
 
-const ARCHIVE_KEYS = ['repo', 'tag', 'asset', 'size', 'sha256'] as const;
+// ★ 'root' JOINED THIS LIST 2026-09-23. A state row from before this unit has no `root` at all
+//   (`undefined`), and `undefined !== undefined` is false, so an old row with no root and a new
+//   declaration that still has none does not move; declaring — or changing — a root does.
+const ARCHIVE_KEYS = ['repo', 'tag', 'asset', 'size', 'sha256', 'root'] as const;
 
 type Pins = Pick<ReleaseBinaryProps, 'archive' | 'member' | 'sha256'>;
 

package/src/release/binary-pins.ts

@@ -0,0 +1,95 @@
+/**
+ * `pinProblems` — everything wrong with a declaration's pins alone, as plain strings, checked
+ * before a plan resolves a directory or a host is asked anything. Split out of binary-form.ts
+ * 2026-09-23 to keep that file under the house's 250-line cap (it was 229, heading for ~250 once
+ * `archive.root` needed its own validation and JSDoc). binary-form.ts re-exports `pinProblems` and
+ * `MAX_ARCHIVE`, so nothing that imported them moves.
+ */
+import type { ReleaseArchive } from './binary-form.ts';
+
+const HEX64 = /^[0-9a-f]{64}$/;
+export const MAX_ARCHIVE = 1 << 30;
+// ⛔ Strict on purpose: each is written into a URL or a path. GitHub's own owner and name alphabet.
+const REPO = /^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?\/[A-Za-z0-9._-]+$/;
+const SEGMENT = /^[A-Za-z0-9._-]+$/;
+// ★ ONLY WHAT THE READER HANDLES: a gzipped tar. A `.zip` or a bare binary is a new capability
+//   with its own walk-down, not a name this should accept and then fail to unpack.
+const TARBALL = /\.(tar\.gz|tgz)$/;
+
+/** A single path segment that cannot climb, hide or name the directory itself. */
+const segmentProblem = (what: string, value: string): string | undefined =>
+  !SEGMENT.test(value) || value === '.' || value === '..'
+    ? `${what} must be one path segment of letters, digits, '.', '_' or '-': ${JSON.stringify(value)}`
+    : undefined;
+
+/** Everything wrong with the pins alone — plain strings in any declaration, resolved or not. */
+export const pinProblems = (props: {
+  readonly archive?: Partial<ReleaseArchive>;
+  readonly member?: unknown;
+  readonly sha256?: unknown;
+  readonly name?: unknown;
+}): string[] => {
+  const archive = props.archive ?? {};
+  const found: string[] = [];
+  const text = (what: string, value: unknown): string | undefined => {
+    if (typeof value === 'string') return value;
+    found.push(`${what} is required, as a plain string`);
+    return undefined;
+  };
+  const repo = text('archive.repo', archive.repo);
+  // ⚠️ `owner/..` passes the alphabet, and a URL parser normalises it away: the request would go
+  //   to `github.com/releases/…`, somewhere nobody pinned. Refused by name.
+  const repoName = repo?.slice(repo.indexOf('/') + 1);
+  if (repo !== undefined && (!REPO.test(repo) || repoName === '.' || repoName === '..'))
+    found.push(`archive.repo must be "owner/name": ${JSON.stringify(repo)}`);
+  for (const [what, value] of [
+    ['archive.tag', archive.tag],
+    ['name', props.name],
+  ] as const) {
+    const given = text(what, value);
+    const problem = given === undefined ? undefined : segmentProblem(what, given);
+    if (problem !== undefined) found.push(problem);
+  }
+  const asset = text('archive.asset', archive.asset);
+  if (asset !== undefined) {
+    const problem = segmentProblem('archive.asset', asset);
+    if (problem !== undefined) found.push(problem);
+    else if (!TARBALL.test(asset))
+      found.push(`archive.asset must be a .tar.gz or .tgz: "${asset}"`);
+  }
+  // ★ ONE DECLARED DIRECTORY, NEVER DERIVED. Optional: most archives (Victoria, OpenBao) are flat.
+  //   Where given, it is the vendor's own wrapper (measured, not guessed — tar.ts's header comment)
+  //   and must be exactly one safe segment, the same alphabet as a tag or an asset name.
+  if (archive.root !== undefined) {
+    if (typeof archive.root !== 'string') {
+      found.push('archive.root must be a plain string when given');
+    } else {
+      const problem = segmentProblem('archive.root', archive.root);
+      if (problem !== undefined) found.push(problem);
+    }
+  }
+  // ⛔ THE SIZE IS ALLOCATED UP FRONT (download.ts fills one buffer of exactly this many bytes), so
+  //   a typo'd size is a memory bomb in the deploying process. vmutils, the largest archive pinned,
+  //   is 123.6 MB; a gibibyte is a ceiling nothing single-binary should reach.
+  const size = archive.size;
+  if (typeof size !== 'number' || !Number.isSafeInteger(size) || size <= 0 || size > MAX_ARCHIVE) {
+    found.push(`archive.size must be the asset's byte count, 1 to ${String(MAX_ARCHIVE)}`);
+  }
+  for (const [what, value] of [
+    ['archive.sha256', archive.sha256],
+    ['sha256', props.sha256],
+  ] as const) {
+    const given = text(what, value);
+    if (given !== undefined && !HEX64.test(given))
+      found.push(`${what} must be 64 lower-case hex digits`);
+  }
+  const member = text('member', props.member);
+  // ⛔ The tar reader refuses these entries anyway; asking for one is a mistake to name at plan.
+  if (
+    member !== undefined &&
+    (member === '' || member.startsWith('/') || member.split('/').includes('..'))
+  ) {
+    found.push(`member must be a relative name inside the archive: ${JSON.stringify(member)}`);
+  }
+  return found;
+};

package/src/release/binary-root.test.ts

@@ -0,0 +1,122 @@
+/**
+ * `Release.Binary` end to end, through Alchemy's own Plan and Apply (openbao/fake-stack.ts), for a
+ * synthetic archive shaped like the Prometheus family: every entry wrapped in one directory
+ * (tar.ts's header comment, measured 2026-09-23). `archive.root` installs it; the same declaration
+ * without `root` refuses, exactly as tar-root.test.ts shows at the reader alone.
+ */
+import { describe, expect, test } from 'bun:test';
+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 { sha256Hex } from '../launchd/job-form.ts';
+import { type HostRunner, hostRunnerLayer } from '../launchd/runner.ts';
+import { HostDirectory, HostDirectoryProvider } from '../linux/directory.ts';
+import { fakeLinuxHost } from '../linux/fake-linux-host.ts';
+import { fakeStack } from '../openbao/fake-stack.ts';
+import { releaseUrl } from './binary-form.ts';
+import { ReleaseBinary, makeReleaseBinaryProvider } from './binary.ts';
+import type { PinnedBinary } from './catalog.ts';
+import { bytesOf, gzip, tarOf } from './fake-release.ts';
+
+const ROOT = '/opt/example/bin';
+const DIR = `${ROOT}/alertmanager-0.33.1`;
+const WRAPPED = 'alertmanager-0.33.1.darwin-arm64';
+const BYTES = bytesOf('#!fake alertmanager 0.33.1\n');
+const ARCHIVE = gzip(
+  tarOf([
+    { name: `${WRAPPED}/`, type: '5' },
+    { bytes: BYTES, name: `${WRAPPED}/alertmanager` },
+  ]),
+);
+const ASSET = 'alertmanager-0.33.1.darwin-arm64.tar.gz';
+const REPO = 'prometheus/alertmanager';
+const TAG = 'v0.33.1';
+const URL = releaseUrl(REPO, TAG, ASSET);
+const PATH = `${DIR}/alertmanager`;
+
+/** The pinned props, with or without the declared root — everything else identical. */
+const pins = (root?: string): PinnedBinary => ({
+  archive: {
+    asset: ASSET,
+    repo: REPO,
+    sha256: sha256Hex(ARCHIVE),
+    size: ARCHIVE.length,
+    tag: TAG,
+    ...(root === undefined ? {} : { root }),
+  },
+  member: 'alertmanager',
+  name: 'alertmanager',
+  sha256: sha256Hex(BYTES),
+});
+
+/** One fake host and one fake server; `events` is every host write and request, in order. */
+const harness = () => {
+  // ★ SEED THE PARENT, NOT `DIR` ITSELF: `HostDirectory` below creates `DIR` fresh, as
+  //   plan.test.ts's harness does — a directory pre-seeded at the declared path would instead be
+  //   an adoption question, which is not what this file is testing.
+  const fake = fakeLinuxHost({ dirs: { [ROOT]: 0 }, euid: 0 });
+  const events: string[] = [];
+  const runner: HostRunner = {
+    ...fake.runner,
+    writeFileAtomic: (path, bytes, options) => {
+      events.push(`write ${path}`);
+      return fake.runner.writeFileAtomic(path, bytes, options);
+    },
+  };
+  const client = HttpClient.make((request, url) => {
+    events.push(`GET ${url.toString()}`);
+    const body = url.toString() === URL ? new Blob([ARCHIVE.slice()]) : null;
+    return Effect.succeed(
+      HttpClientResponse.fromWeb(request, new Response(body, { status: body ? 200 : 404 })),
+    );
+  });
+  const providers = Layer.mergeAll(makeReleaseBinaryProvider(), HostDirectoryProvider()).pipe(
+    Layer.provide(
+      Layer.mergeAll(hostRunnerLayer(runner), Layer.succeed(HttpClient.HttpClient, client)),
+    ),
+  );
+  const stack = fakeStack(providers, {}, 'RootBinaryStack');
+  const declare = (binary: PinnedBinary) =>
+    Effect.gen(function* () {
+      const dir = yield* HostDirectory('alertmanager-dir', { mode: 0o755, path: DIR });
+      yield* ReleaseBinary('alertmanager', { ...binary, directory: dir.path });
+    });
+  return { declare, events, fake, stack };
+};
+
+describe('a directory-wrapped archive, declared with root', () => {
+  test('installs, reads back and re-hashes to the pinned member digest', async () => {
+    const h = harness();
+    const planned = await h.stack.deploy(h.declare(pins(WRAPPED)));
+    expect(planned).toEqual({ alertmanager: 'create', 'alertmanager-dir': 'create' });
+    expect(h.fake.files.get(PATH)?.bytes).toEqual(BYTES);
+    expect(sha256Hex(h.fake.files.get(PATH)?.bytes ?? new Uint8Array())).toBe(sha256Hex(BYTES));
+  });
+
+  test('a second deploy of the same declaration reads the file back; nothing downloaded again', async () => {
+    const h = harness();
+    await h.stack.deploy(h.declare(pins(WRAPPED)));
+    h.events.length = 0;
+    await h.stack.deploy(h.declare(pins(WRAPPED)));
+    expect(h.events).toEqual([]);
+    expect(h.fake.files.get(PATH)?.bytes).toEqual(BYTES);
+  });
+
+  test('the same declaration without root refuses, writes nothing, leaves no file at the path', async () => {
+    const h = harness();
+    await expect(h.stack.deploy(h.declare(pins()))).rejects.toThrow('is a directory');
+    expect(h.fake.files.has(PATH)).toBe(false);
+  });
+});
+
+describe('pinProblems refuses an unsafe root, before any host write or network call', () => {
+  test.each(['', '.', '..', 'a/b', './a'])('root %j', async (root) => {
+    const h = harness();
+    await expect(h.stack.deploy(h.declare(pins(root)))).rejects.toThrow('archive.root must be');
+    expect(h.fake.files.has(PATH)).toBe(false);
+    // ★ mkdir is not instrumented (it goes through `exec`, not `writeFileAtomic`), so HostDirectory
+    //   creating DIR is expected here; nothing about ReleaseBinary's own pin is.
+    expect(h.events.filter((e) => e.startsWith('GET') || e.startsWith('write'))).toEqual([]);
+  });
+});

package/src/release/catalog.ts

@@ -191,9 +191,17 @@ export const catalogBinary = (catalog: ReleaseCatalog, request: CatalogRequest):
       message: `Release.Binary ${request.binary}: ${problems.join('; ')}. Nothing was fetched.`,
     });
   }
-  const { asset, repo, sha256: archiveSha256, size, tag } = archive;
+  const { asset, repo, root, sha256: archiveSha256, size, tag } = archive;
   return {
-    archive: { asset, repo, sha256: archiveSha256, size, tag },
+    // ⚠️ exactOptionalPropertyTypes: a conditional spread, never `root: undefined` spelled out.
+    archive: {
+      asset,
+      repo,
+      sha256: archiveSha256,
+      size,
+      tag,
+      ...(root === undefined ? {} : { root }),
+    },
     member,
     name: request.binary,
     sha256,