@homeflare/alchemy 0.22.0 → 0.24.0

package/dist/proxmox/zfs-pool-spec.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The `PveSpec` for `Proxmox.ZfsPool`: where a pool lives, what its GET reports, and the vendor
+ * endpoint its create form is checked against.
+ *
+ * ★ SPLIT OUT OF zfs-pool.ts TO KEEP THAT FILE UNDER THE 250-LINE CAP, and the seam is the same
+ *   one metric-server-form.ts and zfs-pool-write.ts already cut on: zfs-pool.ts answers "what is
+ *   a zpool and when has it changed", this file answers "what PVE's own GET/{node}/disks/zfs
+ *   collection and item say, read into that shape". `leafDevices` moved with `spec` because it
+ *   exists for exactly one field of `spec.attributes` and nothing else in this package calls it.
+ *
+ * ⚠️ THE `import type` BACK TO zfs-pool.ts IS A CYCLE ON PAPER ONLY — type-only, erased before
+ *   anything runs, so the resource's public shape stays in the file that declares the resource.
+ *   Same reasoning as zfs-pool-write.ts.
+ */
+import type { PveSpec } from './resource.ts';
+import type { ZfsPoolAttributes, ZfsPoolProps } from './zfs-pool.ts';
+/**
+ * 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.
+ */
+export declare const leafDevices: (children: unknown) => string[];
+export declare const spec: PveSpec<ZfsPoolProps, ZfsPoolAttributes>;
+//# sourceMappingURL=zfs-pool-spec.d.ts.map

package/dist/proxmox/zfs-pool-spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zfs-pool-spec.d.ts","sourceRoot":"","sources":["../../src/proxmox/zfs-pool-spec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAG7C,OAAO,KAAK,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAErE;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW,aAAc,OAAO,KAAG,MAAM,EAO9C,CAAC;AAET,eAAO,MAAM,IAAI,EAAE,OAAO,CAAC,YAAY,EAAE,iBAAiB,CAuCzD,CAAC"}

package/dist/proxmox/zfs-pool-write.d.ts

@@ -35,15 +35,44 @@ import type { ZfsPoolAttributes, ZfsPoolProps } from './zfs-pool.ts';
  *   declaration asked for, and this is the one call that writes to physical disks.
  */
 /**
- * The vendor rules the create form is checked against at plan time.
+ * The vendor rules a FULL declaration's create form is checked against at plan time.
  *
  * ⛔ HERE RATHER THAN INLINE IN zfs-pool.ts BECAUSE THAT FILE IS ALREADY OVER THE 250-LINE CAP,
  *   and a `pve:POST …` literal has to live in a non-test source file for the generator to table
- *   it at all. The spec imports it on the line it already imports `createForm` from.
+ *   it at all. zfs-pool-spec.ts imports it on the line it already imports `createForm` from.
  * ⚠️ NO UPDATE KEY: PVE registers no PUT under `/nodes/{node}/disks/zfs`, which is exactly why
  *   the spec declares no `updateForm` and a changed prop is a REPLACE.
+ * ⚠️ `spec.endpoint` DOES NOT RETURN THIS CONSTANT DIRECTLY — see the ★ on `zfsPoolEndpoint`
+ *   below, and the ⛔ on `devices`/`raidlevel` in zfs-pool.ts (decision 9, 2026-09-23).
  */
 export declare const ZFS_POOL_ENDPOINT: EndpointPair;
+/**
+ * ★ `PveSpec['endpoint']` AS A FUNCTION OF PROPS, THE WAY notification-target.ts AND
+ *   ceph-daemon.ts ALREADY DO IT FOR A DIFFERENT REASON (resource-spec.ts's ⚠️ on that field).
+ *   Here the reason is decision 9's adopt-only mode: `guardCreate` runs on the FIRST plan of
+ *   ANY declaration (resource.ts `ops.diff`, `output === undefined` branch) and checks the
+ *   create form's REQUIRED fields whenever `endpoint.create` resolves to a key — and PVE marks
+ *   both `devices` and `raidlevel` required (measured, codegen/constraints's `pve-nodes-disks`
+ *   row). An adopt-only declaration deliberately omits both, so returning the real key there
+ *   would refuse a MATCHING adoption at plan time, before `read` ever ran — exactly the gap
+ *   `guardCreate`/`guardUpdate` being exported (resource.ts's ★) says this family must not fall
+ *   through. Returning `{}` (no `create` key) makes `guardCreate` a no-op (`constraint-guard.ts`:
+ *   `create === undefined ? Effect.void : …`) for an adopt-only declaration, while a FULL one
+ *   (`devices` and `raidlevel` both present) is checked exactly as before.
+ * ⚠️ THE RUNTIME BACKSTOP IS `createPool` BELOW, NOT THIS FUNCTION. Skipping the plan-time guard
+ *   for an adopt-only declaration does not skip the check that the pool is actually there —
+ *   `createPool` refuses before any POST when the read comes back absent and either field is
+ *   undefined, which is what a genuinely absent adopt-only declaration hits at apply time.
+ */
+export declare const zfsPoolEndpoint: (props: ZfsPoolProps) => EndpointPair;
+/**
+ * ⚠️ EVERY KEY IS OMITTED WHEN ABSENT, `devices` AND `raidlevel` INCLUDED — not just the
+ *   optional ones. An adopt-only declaration (both undefined, decision 9) must produce a form
+ *   `createPool`'s own guard can inspect for their absence, and one this function itself does
+ *   not throw building: `props.devices.join(',')` on an undefined `devices` is exactly the
+ *   `TypeError` the plan-time guard hit before this change, because `guardCreate` evaluates
+ *   `spec.createForm(props)` eagerly (resource-guard.ts) — before it even looks at `presence`.
+ */
 export declare const createForm: (props: ZfsPoolProps) => Record<string, string>;
 /**
  * Create the pool if it is absent, and otherwise leave it completely alone.
@@ -69,14 +98,26 @@ export declare const createForm: (props: ZfsPoolProps) => Record<string, string>
  * ⚠️ SHORT POLLS WITH A HARD CAP, NOT ONE LONG WAIT. `read` cannot tell "not yet" from "forbidden"
  *   — both are `undefined` — so the loop gives up with the UPID rather than retrying forever, and
  *   the UPID is the only thing that leads to the worker's real error.
+ *
+ * ⛔ THE ADOPT-ONLY GUARD, RIGHT AFTER THE READ AND BEFORE ANYTHING ELSE. Decision 9 (2026-09-23):
+ *   omitting `devices` and `raidlevel` declares a pool this resource may only ADOPT, for a pool
+ *   PVE's own schema cannot fully describe — n1's `speed` is a stripe, and `raidlevel`'s enum has
+ *   no stripe (zfs-pool.ts). `zfsPoolEndpoint` above already keeps the vendor constraint guard
+ *   from refusing such a declaration at PLAN time; this is the matching refusal at APPLY time, for
+ *   the one case that guard cannot see — the pool genuinely is not there. MEASURED without it: a
+ *   tolerant `createForm` sends `POST … {name: "rpool"}` with no `devices`/`raidlevel`, which PVE's
+ *   own schema would 400 on eventually, but only after the request left this process; refusing
+ *   here is the same `Effect.die` idiom as every other refusal in this package, and it costs
+ *   nothing this pool did not already lack.
  */
 export declare const createPool: <E, R>(props: ZfsPoolProps, collection: string, path: string, read: (props: ZfsPoolProps) => Effect.Effect<ZfsPoolAttributes | undefined, E, R>) => Effect.Effect<ZfsPoolAttributes, E | Error, R | import("effect/unstable/http/HttpClient").HttpClient>;
 /**
- * ⛔ `DELETE /nodes/{node}/disks/zfs/{name}` RUNS `zpool destroy` AND THE DATASETS GO WITH IT.
- *   It is implemented rather than stubbed, because a `delete` that silently does nothing lies to
- *   whoever reads the plan. What keeps a deleted line from destroying a pool is the resource's
- *   `defaultRemovalPolicy: 'retain'` above — an orphaned pool is forgotten, not destroyed, and a
- *   caller who means it says `.pipe(RemovalPolicy.destroy())`.
+ * ⛔ `DELETE /nodes/{node}/disks/zfs/{name}` RUNS `zpool destroy` AND THE DATASETS GO WITH IT. Per
+ *   S14 (alchemy-provider-standard), it is implemented rather than stubbed — a `delete` that
+ *   silently does nothing lies to whoever reads the plan — and what keeps an ordinary removed
+ *   declaration from reaching it is the resource's `defaultRemovalPolicy: 'retain'` (zfs-pool.ts):
+ *   an orphaned pool is forgotten, not destroyed, unless a caller opts in with
+ *   `.pipe(RemovalPolicy.destroy())`. See the corrected header in zfs-pool.ts.
  *
  * ⚠️ `cleanup-config` IS NOT SENT. It would additionally remove the PVE storage entry pointing
  *   at this pool, which is a different object with its own resource (`Proxmox.Storage`); one

package/dist/proxmox/zfs-pool-write.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"zfs-pool-write.d.ts","sourceRoot":"","sources":["../../src/proxmox/zfs-pool-write.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,OAAO,KAAK,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAErE;;;;;;;;;;;;;GAaG;AACH;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,EAAE,YAA6D,CAAC;AAE9F,eAAO,MAAM,UAAU,UAAW,YAAY,KAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAOpE,CAAC;AAKH;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,UAAU,GAAI,CAAC,EAAE,CAAC,SACtB,YAAY,cACP,MAAM,QACZ,MAAM,QACN,CAAC,KAAK,EAAE,YAAY,KAAK,MAAM,CAAC,MAAM,CAAC,iBAAiB,GAAG,SAAS,EAAE,CAAC,EAAE,CAAC,CAAC,0GAmC/E,CAAC;AAEL;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,WAAW,SAAU,YAAY,QAAQ,MAAM,wFACb,CAAC"}
+{"version":3,"file":"zfs-pool-write.d.ts","sourceRoot":"","sources":["../../src/proxmox/zfs-pool-write.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,OAAO,KAAK,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAErE;;;;;;;;;;;;;GAaG;AACH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB,EAAE,YAA6D,CAAC;AAE9F;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,eAAe,UAAW,YAAY,KAAG,YACiC,CAAC;AAExF;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU,UAAW,YAAY,KAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAOpE,CAAC;AAKH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,eAAO,MAAM,UAAU,GAAI,CAAC,EAAE,CAAC,SACtB,YAAY,cACP,MAAM,QACZ,MAAM,QACN,CAAC,KAAK,EAAE,YAAY,KAAK,MAAM,CAAC,MAAM,CAAC,iBAAiB,GAAG,SAAS,EAAE,CAAC,EAAE,CAAC,CAAC,0GA8C/E,CAAC;AAEL;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,WAAW,SAAU,YAAY,QAAQ,MAAM,wFACb,CAAC"}

package/dist/proxmox/zfs-pool.d.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,19 +49,37 @@
  * ⚠️ 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 type { NodesNodeDisksZfsPostParams } from './generated/pve.ts';
 import { type PveRequirements, type WithTarget } from './resource.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';
-export type ZfsCompression = 'on' | 'off' | 'gzip' | 'lz4' | 'lzjb' | 'zle' | 'zstd';
+/**
+ * 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']>;
+/** 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
  *   OVERSIGHT. The last two belong to the DELETE this resource refuses to make. `add_storage=1`
@@ -91,9 +111,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.
      *

package/dist/proxmox/zfs-pool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"zfs-pool.d.ts","sourceRoot":"","sources":["../../src/proxmox/zfs-pool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACnC,OAAO,KAAK,QAAQ,MAAM,kBAAkB,CAAC;AAE7C,OAAO,EACL,KAAK,eAAe,EAEpB,KAAK,UAAU,EAGhB,MAAM,eAAe,CAAC;AAIvB,oGAAoG;AACpG,MAAM,MAAM,YAAY,GACpB,QAAQ,GACR,QAAQ,GACR,QAAQ,GACR,OAAO,GACP,QAAQ,GACR,QAAQ,GACR,OAAO,GACP,QAAQ,GACR,QAAQ,CAAC;AAEb,MAAM,MAAM,cAAc,GAAG,IAAI,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,CAAC;AAErF;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAa,SAAQ,UAAU;IAC9C;;;;;OAKG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,+FAA+F;IAC/F,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;;;;;;;OAYG;IACH,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,SAAS,EAAE,YAAY,CAAC;IACxB;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,WAAW,CAAC,EAAE,cAAc,CAAC;IAC7B;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,mFAAmF;IACnF,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,KAAK,EAAE,MAAM,CAAC;IACd,4DAA4D;IAC5D,MAAM,EAAE,MAAM,CAAC;IACf;;;;;;;OAOG;IACH,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,cAAe,SAAQ,QAAQ,CAC9C,iBAAiB,EACjB,YAAY,EACZ,iBAAiB,EACjB,KAAK,EACL,eAAe,CAChB;CAAG;AAEJ,mGAAmG;AACnG,eAAO,MAAM,cAAc,iDAEzB,CAAC;AA8EH,eAAO,MAAM,sBAAsB,oIACoD,CAAC"}
+{"version":3,"file":"zfs-pool.d.ts","sourceRoot":"","sources":["../../src/proxmox/zfs-pool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkEG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACnC,OAAO,KAAK,QAAQ,MAAM,kBAAkB,CAAC;AAE7C,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,oBAAoB,CAAC;AACtE,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,UAAU,EAA8B,MAAM,eAAe,CAAC;AAIlG;;;;;;;GAOG;AACH,MAAM,MAAM,YAAY,GAAG,WAAW,CAAC,2BAA2B,CAAC,WAAW,CAAC,CAAC,CAAC;AAEjF,iFAAiF;AACjF,MAAM,MAAM,cAAc,GAAG,WAAW,CAAC,2BAA2B,CAAC,aAAa,CAAC,CAAC,CAAC;AAErF;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAa,SAAQ,UAAU;IAC9C;;;;;OAKG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,+FAA+F;IAC/F,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,SAAS,CAAC,EAAE,YAAY,CAAC;IACzB;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,WAAW,CAAC,EAAE,cAAc,CAAC;IAC7B;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,mFAAmF;IACnF,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,KAAK,EAAE,MAAM,CAAC;IACd,4DAA4D;IAC5D,MAAM,EAAE,MAAM,CAAC;IACf;;;;;;;OAOG;IACH,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,cAAe,SAAQ,QAAQ,CAC9C,iBAAiB,EACjB,YAAY,EACZ,iBAAiB,EACjB,KAAK,EACL,eAAe,CAChB;CAAG;AAEJ,mGAAmG;AACnG,eAAO,MAAM,cAAc,iDAEzB,CAAC;AAqBH,eAAO,MAAM,sBAAsB,oIACoD,CAAC"}

package/dist/release/archive.d.ts

@@ -1,7 +1,11 @@
 import type { PinnedDownload } from './binary-form.ts';
 import { type TarContents } from './tar.ts';
-/** Gunzip and read a tar, keeping only `wanted`. Throws ArchiveRefused. */
-export declare const extractMembers: (gzipped: Uint8Array, wanted: ReadonlySet<string>) => Promise<TarContents>;
+/**
+ * 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 declare const extractMembers: (gzipped: Uint8Array, wanted: ReadonlySet<string>, root?: string) => Promise<TarContents>;
 /**
  * The declared member's bytes out of a downloaded archive, both layers checked.
  * ⚠️ `archive` may be shared with another resource's extraction (download.ts sharingInFlight):

package/dist/release/archive.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"archive.d.ts","sourceRoot":"","sources":["../../src/release/archive.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD,OAAO,EAAE,KAAK,WAAW,EAAa,MAAM,UAAU,CAAC;AAKvD,2EAA2E;AAC3E,eAAO,MAAM,cAAc,YAChB,UAAU,UACX,WAAW,CAAC,MAAM,CAAC,KAC1B,OAAO,CAAC,WAAW,CA8BrB,CAAC;AAUF;;;;GAIG;AACH,eAAO,MAAM,cAAc,YAChB,UAAU,WACV,cAAc,KACtB,OAAO,CAAC,UAAU,CAepB,CAAC"}
+{"version":3,"file":"archive.d.ts","sourceRoot":"","sources":["../../src/release/archive.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD,OAAO,EAAE,KAAK,WAAW,EAAa,MAAM,UAAU,CAAC;AAKvD;;;;GAIG;AACH,eAAO,MAAM,cAAc,YAChB,UAAU,UACX,WAAW,CAAC,MAAM,CAAC,SACpB,MAAM,KACZ,OAAO,CAAC,WAAW,CA8BrB,CAAC;AAUF;;;;GAIG;AACH,eAAO,MAAM,cAAc,YAChB,UAAU,WACV,cAAc,KACtB,OAAO,CAAC,UAAU,CAgBpB,CAAC"}

package/dist/release/binary-form.d.ts

@@ -28,6 +28,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 {
     /** The pinned archive the binary comes out of. `catalogBinary()` fills it from a data set. */
@@ -77,6 +88,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 declare const DEFAULT_BINARY_MODE = 493;
 /**
@@ -95,14 +108,7 @@ export declare const releaseBinaryPath: (props: {
 /** The download a declaration means. ⚠️ Validate first (binaryProblems): this trusts its input. */
 export declare const pinnedDownload: (props: ReleaseBinaryProps) => PinnedDownload;
 export declare const modeProblems: (mode: number) => string[];
-export declare const MAX_ARCHIVE: number;
-/** Everything wrong with the pins alone — plain strings in any declaration, resolved or not. */
-export declare const pinProblems: (props: {
-    readonly archive?: Partial<ReleaseArchive>;
-    readonly member?: unknown;
-    readonly sha256?: unknown;
-    readonly name?: unknown;
-}) => string[];
+export { MAX_ARCHIVE, pinProblems } from './binary-pins.ts';
 type Pins = Pick<ReleaseBinaryProps, 'archive' | 'member' | 'sha256'>;
 /** Whether two declarations pin different bytes: another archive, member or member digest. */
 export declare const pinsMoved: (olds: Pins, news: Pins) => boolean;
@@ -114,5 +120,4 @@ export declare const pinsMoved: (olds: Pins, news: Pins) => boolean;
 export declare const inPlaceRefusal: (olds: Pins, news: Pins) => string;
 /** Everything wrong with a declaration, before any host or network is asked anything. */
 export declare const binaryProblems: (props: ReleaseBinaryProps) => string[];
-export {};
 //# sourceMappingURL=binary-form.d.ts.map

package/dist/release/binary-form.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"binary-form.d.ts","sourceRoot":"","sources":["../../src/release/binary-form.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"binary-form.d.ts","sourceRoot":"","sources":["../../src/release/binary-form.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAIvE,oFAAoF;AACpF,MAAM,WAAW,cAAc;IAC7B,kGAAkG;IAClG,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2DAA2D;IAC3D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,yFAAyF;IACzF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,qFAAqF;IACrF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;;;;;;;OASG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,kBAAkB;IACjC,8FAA8F;IAC9F,OAAO,EAAE,cAAc,CAAC;IACxB,oGAAoG;IACpG,MAAM,EAAE,MAAM,CAAC;IACf,uEAAuE;IACvE,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;OAMG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uEAAuE;IACvE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB,yEAAyE;IACzE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,uBAAwB,SAAQ,kBAAkB;IACjE,8CAA8C;IAC9C,GAAG,EAAE,MAAM,CAAC;IACZ,uEAAuE;IACvE,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,4FAA4F;AAC5F,MAAM,MAAM,cAAc,GAAG;IAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,oCAAoC;IACpC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,oDAAoD;IACpD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,mCAAmC;IACnC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,4FAA4F;IAC5F,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,eAAO,MAAM,mBAAmB,MAAQ,CAAC;AAEzC;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,SAAU,MAAM,OAAO,MAAM,SAAS,MAAM,KAAG,MACN,CAAC;AAEjE,iEAAiE;AACjE,eAAO,MAAM,iBAAiB,UAAW;IACvC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB,KAAG,MAA4C,CAAC;AAEjD,mGAAmG;AACnG,eAAO,MAAM,cAAc,UAAW,kBAAkB,KAAG,cAQzD,CAAC;AAEH,eAAO,MAAM,YAAY,SAAU,MAAM,KAAG,MAAM,EAUjD,CAAC;AAKF,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAO5D,KAAK,IAAI,GAAG,IAAI,CAAC,kBAAkB,EAAE,SAAS,GAAG,QAAQ,GAAG,QAAQ,CAAC,CAAC;AAEtE,8FAA8F;AAC9F,eAAO,MAAM,SAAS,SAAU,IAAI,QAAQ,IAAI,KAAG,OAGkB,CAAC;AAEtE;;;;GAIG;AACH,eAAO,MAAM,cAAc,SAAU,IAAI,QAAQ,IAAI,KAAG,MAGqB,CAAC;AAE9E,yFAAyF;AACzF,eAAO,MAAM,cAAc,UAAW,kBAAkB,KAAG,MAAM,EAMhE,CAAC"}

package/dist/release/binary-pins.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `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';
+export declare const MAX_ARCHIVE: number;
+/** Everything wrong with the pins alone — plain strings in any declaration, resolved or not. */
+export declare const pinProblems: (props: {
+    readonly archive?: Partial<ReleaseArchive>;
+    readonly member?: unknown;
+    readonly sha256?: unknown;
+    readonly name?: unknown;
+}) => string[];
+//# sourceMappingURL=binary-pins.d.ts.map

package/dist/release/binary-pins.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"binary-pins.d.ts","sourceRoot":"","sources":["../../src/release/binary-pins.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAGvD,eAAO,MAAM,WAAW,QAAU,CAAC;AAcnC,gGAAgG;AAChG,eAAO,MAAM,WAAW,UAAW;IACjC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC;IAC3C,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;CACzB,KAAG,MAAM,EAgET,CAAC"}

package/dist/release/catalog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../../src/release/catalog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAG3E;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,wFAAwF;IACxF,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,wFAAwF;AACxF,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,0CAA0C;IAC1C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,6CAA6C;IAC7C,QAAQ,CAAC,GAAG,EAAE;QAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9F,+EAA+E;IAC/E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,+FAA+F;AAC/F,MAAM,WAAW,aAAc,SAAQ,cAAc;IACnD,kGAAkG;IAClG,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACnD;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC;IAC7D,gGAAgG;IAChG,QAAQ,CAAC,SAAS,EAAE;QAClB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAC1B,+GAA+G;QAC/G,QAAQ,CAAC,SAAS,CAAC,EAAE,iBAAiB,CAAC;KACxC,CAAC;CACH;AAED,sEAAsE;AACtE,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACpD,uFAAuF;IACvF,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;CACtF;AAED,kCAAkC;AAClC,MAAM,WAAW,cAAc;IAC7B,8DAA8D;IAC9D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC;CAC7D;AAED,+CAA+C;AAC/C,MAAM,MAAM,cAAc,GAAG;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,qEAAqE;IACrE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF,+FAA+F;AAC/F,MAAM,MAAM,YAAY,GAAG,IAAI,CAAC,kBAAkB,EAAE,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAC,CAAC;AAqB9F,iFAAiF;AACjF,eAAO,MAAM,eAAe,YAAa,cAAc,WAAW,cAAc,KAAG,MAAM,EAkDxF,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,aAAa,YAAa,cAAc,WAAW,cAAc,KAAG,YA4BhF,CAAC;AAEF,4FAA4F;AAC5F,eAAO,MAAM,gBAAgB,SACrB,MAAM,WACH,IAAI,CAAC,cAAc,EAAE,SAAS,GAAG,SAAS,CAAC,KACnD,MAAyD,CAAC;AAE7D,8EAA8E;AAC9E,MAAM,MAAM,gBAAgB,GAAG,cAAc,GAAG;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE5E;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,aACf,SAAS,cAAc,EAAE,UAC3B,MAAM,KACb,gBAAgB,GAAG,SAgBrB,CAAC"}
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../../src/release/catalog.ts"],"names":[],"mappings":"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"}

package/dist/release/index.js

@@ -71,31 +71,7 @@ var fileProblems = (props) => {
   return found;
 };
 
-// src/release/binary-form.ts
-var DEFAULT_BINARY_MODE = 493;
-var releaseUrl = (repo, tag, asset) => `https://github.com/${repo}/releases/download/${tag}/${asset}`;
-var releaseBinaryPath = (props) => `${props.directory}/${props.name}`;
-var pinnedDownload = (props) => ({
-  member: props.member,
-  memberSha256: props.sha256,
-  sha256: props.archive.sha256,
-  size: props.archive.size,
-  url: releaseUrl(props.archive.repo, props.archive.tag, props.archive.asset)
-});
-var modeProblems = (mode) => {
-  if (!Number.isSafeInteger(mode) || mode < 0 || mode > 4095)
-    return ["mode must be 0–0o7777"];
-  const found = [];
-  if ((mode & 3584) !== 0)
-    found.push("mode must not set setuid, setgid or sticky");
-  if ((mode & 18) !== 0)
-    found.push("mode must not be group- or world-writable");
-  if ((mode & 64) === 0)
-    found.push("mode must let the owner execute it");
-  if ((mode & 256) === 0)
-    found.push("mode must let the owner read it (it is re-hashed)");
-  return found;
-};
+// src/release/binary-pins.ts
 var HEX64 = /^[0-9a-f]{64}$/;
 var MAX_ARCHIVE = 1 << 30;
 var REPO = /^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?\/[A-Za-z0-9._-]+$/;
@@ -132,6 +108,15 @@ var pinProblems = (props) => {
     else if (!TARBALL.test(asset))
       found.push(`archive.asset must be a .tar.gz or .tgz: "${asset}"`);
   }
+  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);
+    }
+  }
   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)}`);
@@ -150,7 +135,34 @@ var pinProblems = (props) => {
   }
   return found;
 };
-var ARCHIVE_KEYS = ["repo", "tag", "asset", "size", "sha256"];
+
+// src/release/binary-form.ts
+var DEFAULT_BINARY_MODE = 493;
+var releaseUrl = (repo, tag, asset) => `https://github.com/${repo}/releases/download/${tag}/${asset}`;
+var releaseBinaryPath = (props) => `${props.directory}/${props.name}`;
+var pinnedDownload = (props) => ({
+  member: props.member,
+  memberSha256: props.sha256,
+  sha256: props.archive.sha256,
+  size: props.archive.size,
+  url: releaseUrl(props.archive.repo, props.archive.tag, props.archive.asset),
+  ...props.archive.root === undefined ? {} : { root: props.archive.root }
+});
+var modeProblems = (mode) => {
+  if (!Number.isSafeInteger(mode) || mode < 0 || mode > 4095)
+    return ["mode must be 0–0o7777"];
+  const found = [];
+  if ((mode & 3584) !== 0)
+    found.push("mode must not set setuid, setgid or sticky");
+  if ((mode & 18) !== 0)
+    found.push("mode must not be group- or world-writable");
+  if ((mode & 64) === 0)
+    found.push("mode must let the owner execute it");
+  if ((mode & 256) === 0)
+    found.push("mode must let the owner read it (it is re-hashed)");
+  return found;
+};
+var ARCHIVE_KEYS = ["repo", "tag", "asset", "size", "sha256", "root"];
 var pinsMoved = (olds, news) => olds.member !== news.member || olds.sha256 !== news.sha256 || ARCHIVE_KEYS.some((key) => olds.archive[key] !== news.archive[key]);
 var inPlaceRefusal = (olds, news) => `a new pin (${news.archive.tag} ${news.member} ${news.sha256}) at the path of the installed ` + `one (${olds.archive.tag} ${olds.member} ${olds.sha256}) would overwrite it in place; give each ` + "version its own directory (catalogDirectory), so an upgrade is a new path";
 var binaryProblems = (props) => [
@@ -778,7 +790,7 @@ var concatBytes = (parts) => {
   }
   return out;
 };
-var tarReader = (wanted) => {
+var tarReader = (wanted, root) => {
   const header = new Uint8Array(BLOCK);
   const members = new Map;
   const names = [];
@@ -790,6 +802,8 @@ var tarReader = (wanted) => {
   let zeros = 0;
   let name = "";
   let parts;
+  let rootSeen = false;
+  const rootPrefix = root === undefined ? undefined : `${root}/`;
   const endEntry = () => {
     if (parts !== undefined)
       members.set(name, concatBytes(parts));
@@ -812,20 +826,45 @@ var tarReader = (wanted) => {
     if (!posix && magic !== "ustar  \x00")
       throw refuse("an entry header is neither ustar nor GNU");
     const prefix = posix ? text(header, 345, 155) : "";
-    name = prefix === "" ? text(header, 0, 100) : `${prefix}/${text(header, 0, 100)}`;
-    const problem = nameProblem(name);
+    const rawName = prefix === "" ? text(header, 0, 100) : `${prefix}/${text(header, 0, 100)}`;
+    const problem = nameProblem(rawName);
     if (problem !== undefined)
-      throw refuse(`entry ${JSON.stringify(name)} ${problem}`);
+      throw refuse(`entry ${JSON.stringify(rawName)} ${problem}`);
+    if (rootPrefix !== undefined && rawName === rootPrefix) {
+      if (rootSeen) {
+        throw refuse(`entry "${rawName}" reuses the declared root's own name, appearing twice`);
+      }
+      const type2 = String.fromCharCode(header[156] ?? 0);
+      const size = octal(header, 124, 12, `entry "${rawName}"'s size`);
+      if (type2 !== "5" || size !== 0) {
+        throw refuse(`entry "${rawName}" is the declared root but is not an empty directory`);
+      }
+      rootSeen = true;
+      phase = "header";
+      return;
+    }
+    let stripped = rawName;
+    if (rootPrefix !== undefined) {
+      if (!rawName.startsWith(rootPrefix)) {
+        throw refuse(`entry "${rawName}" is outside the declared root "${rootPrefix}"`);
+      }
+      stripped = rawName.slice(rootPrefix.length);
+      const strippedProblem = nameProblem(stripped);
+      if (strippedProblem !== undefined) {
+        throw refuse(`entry "${rawName}" strips to ${JSON.stringify(stripped)}, which ${strippedProblem}`);
+      }
+    }
+    name = stripped;
     const type = String.fromCharCode(header[156] ?? 0);
     if (type !== "0" && type !== "\x00") {
       const kind = KINDS[type] ?? `of unknown type ${JSON.stringify(type)}`;
-      throw refuse(`entry "${name}" is ${kind}; only regular files are accepted`);
+      throw refuse(`entry "${rawName}" is ${kind}; only regular files are accepted`);
     }
     if (seen.has(name))
-      throw refuse(`entry "${name}" appears twice`);
+      throw refuse(`entry "${rawName}" appears twice`);
     seen.add(name);
     names.push(name);
-    remaining = octal(header, 124, 12, `entry "${name}"'s size`);
+    remaining = octal(header, 124, 12, `entry "${rawName}"'s size`);
     padding = (BLOCK - remaining % BLOCK) % BLOCK;
     parts = wanted.has(name) ? [] : undefined;
     phase = "data";
@@ -869,6 +908,9 @@ var tarReader = (wanted) => {
   const finish = () => {
     if (phase !== "end")
       throw refuse("the archive stops before its end-of-archive marker");
+    if (rootPrefix !== undefined && !rootSeen) {
+      throw refuse(`the declared root "${rootPrefix}" never appears in the archive`);
+    }
     return { members, names };
   };
   return { finish, push };
@@ -876,8 +918,8 @@ var tarReader = (wanted) => {
 
 // src/release/archive.ts
 var SLICE = 1 << 20;
-var extractMembers = async (gzipped, wanted) => {
-  const tar = tarReader(wanted);
+var extractMembers = async (gzipped, wanted, root) => {
+  const tar = tarReader(wanted, root);
   let offset = 0;
   const source = new ReadableStream({
     pull(controller) {
@@ -917,11 +959,12 @@ var verifiedMember = async (archive, release) => {
   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);
@@ -1214,9 +1257,16 @@ var catalogBinary = (catalog, request) => {
       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 },
+    archive: {
+      asset,
+      repo,
+      sha256: archiveSha256,
+      size,
+      tag,
+      ...root === undefined ? {} : { root }
+    },
     member,
     name: request.binary,
     sha256
@@ -1421,5 +1471,5 @@ export {
   releaseUrl
 };
 
-//# debugId=95AC8419C10B267864756E2164756E21
+//# debugId=684C5D2BD8F11B9A64756E2164756E21
 //# sourceMappingURL=index.js.map