@homeflare/alchemy 0.23.0 → 0.24.0

package/src/postgres/errors.ts

@@ -0,0 +1,131 @@
+/**
+ * `Postgres.Database`'s failures as typed tags (S21).
+ *
+ * ⛔ NONE OF THESE IS A STATUS-CODE OR MESSAGE MATCH. Every one is raised by this family's own
+ *   code from a fact it already checked (a byte count, a live catalog row, a role lookup) — never
+ *   from sniffing a driver error's text. The one live-SQLSTATE check this family makes —
+ *   `isDuplicateDatabaseRace` in `database-sql.ts`, for the `42P04` create race — reads the raw
+ *   code `@effect/sql-pg` classified onto `SqlSyntaxError.cause.code` (measured in
+ *   `node_modules/@effect/sql-pg/src/internal/sqlError.ts#classifySqlState`: every `42xxx` code,
+ *   `42P04` included, becomes `SqlSyntaxError` — there is no more specific tag for it), and it
+ *   never produces one of these tags: a race converges instead of failing.
+ */
+import * as Data from 'effect/Data';
+
+/**
+ * A declared name would be silently truncated by the server (`NAMEDATALEN` 64, so 63 UTF-8
+ * bytes is the last one that survives whole) — refused at plan, before any statement runs.
+ *
+ * ⛔ WHY THIS IS A PLAN-TIME REFUSAL AND NOT A SERVER ERROR. `truncate_identifier`
+ *   (`scansup.c@REL_18_6` line 93) clips a long name to 63 bytes and raises only a `NOTICE`
+ *   (`errcode(ERRCODE_NAME_TOO_LONG)`), never an error. A create would succeed against the
+ *   TRUNCATED name, so the next plan's read (`WHERE datname = $1`, the name exactly as
+ *   declared) would find nothing and try to create it again — forever. See
+ *   `doc/postgres.md#name`.
+ */
+export class PostgresDatabaseNameRefused extends Data.TaggedError('PostgresDatabaseNameRefused')<{
+  readonly name: string;
+  readonly byteLength: number;
+  readonly limit: number;
+}> {
+  override get message(): string {
+    return (
+      `Postgres.Database "${this.name}": ${String(this.byteLength)} UTF-8 bytes, over the ` +
+      `${String(this.limit)}-byte limit (NAMEDATALEN 64, minus the terminator). PostgreSQL would ` +
+      'accept the CREATE and silently truncate the name with only a NOTICE, so this plan refuses ' +
+      'it instead of creating a database no later read will ever find again.'
+    );
+  }
+}
+
+/** A logical id's `name` changed. A database's name is its identity; there is no `ALTER … RENAME`
+ * in this family's vocabulary (see `docs/postgres.md`), and `diff` never turns this into a
+ * `replace` — a replace here is `DROP DATABASE` before `CREATE DATABASE`, on data. */
+export class PostgresDatabaseRenameRefused extends Data.TaggedError(
+  'PostgresDatabaseRenameRefused',
+)<{
+  readonly from: string;
+  readonly to: string;
+}> {
+  override get message(): string {
+    return (
+      `Postgres.Database: the declared name changed from "${this.from}" to "${this.to}". A ` +
+      'rename is refused at plan — this provider never replaces a database (that is DROP then ' +
+      'CREATE) and never runs ALTER … RENAME. Declare a new logical id for the new name, and ' +
+      'remove the old one once its data has moved.'
+    );
+  }
+}
+
+/** `OWNER` names a role `pg_roles` does not have, checked before the `CREATE DATABASE` that
+ * would otherwise fail on it. Postgres itself refuses the same case with `ERROR:  role "…" does
+ * not exist` (`createdb()`, `dbcommands.c`) — this tag exists so the refusal is typed and the
+ * check runs before any statement, not caught from the driver's text. */
+export class PostgresDatabaseOwnerMissing extends Data.TaggedError('PostgresDatabaseOwnerMissing')<{
+  readonly database: string;
+  readonly owner: string;
+}> {
+  override get message(): string {
+    return `Postgres.Database "${this.database}": OWNER "${this.owner}" is not a role in pg_roles.`;
+  }
+}
+
+/** A live, asserted property no longer matches the declaration. `reconcile` never issues an
+ * `ALTER DATABASE` to fix this — see `docs/postgres.md` for why each asserted prop stops at
+ * create. */
+export class PostgresDatabaseDrift extends Data.TaggedError('PostgresDatabaseDrift')<{
+  readonly database: string;
+  readonly prop: string;
+  readonly declared: unknown;
+  readonly live: unknown;
+}> {
+  override get message(): string {
+    return (
+      `Postgres.Database "${this.database}": ${this.prop} is declared as ` +
+      `${JSON.stringify(this.declared)} but the live database has ${JSON.stringify(this.live)}. ` +
+      'This provider never issues ALTER DATABASE — update the declaration to match the live ' +
+      'value, or change it by hand and re-plan.'
+    );
+  }
+}
+
+/** `delete` never drops a database. `DROP DATABASE` is destructive and irreversible on data
+ * this family did not create from nothing (most declared databases here are adopted, not
+ * created); the decision to remove one stays a human act on the host. */
+export class PostgresDatabaseDropRefused extends Data.TaggedError('PostgresDatabaseDropRefused')<{
+  readonly database: string;
+}> {
+  override get message(): string {
+    return (
+      `Postgres.Database "${this.database}": delete is refused. This provider never issues DROP ` +
+      'DATABASE. Drop it by hand over the trust socket if you mean to remove it, then remove the ' +
+      'declaration.'
+    );
+  }
+}
+
+/** `CREATE DATABASE` raised no error, but the immediate re-read (S10: never trust the write's
+ * own report) still finds nothing. Measured to have no real trigger in a correctly speaking
+ * client, but S20 forbids `Effect.die` here regardless — an invariant violation is a typed
+ * failure the caller can see and retry, never a defect that crashes the whole engine. */
+export class PostgresDatabaseCreateVanished extends Data.TaggedError(
+  'PostgresDatabaseCreateVanished',
+)<{
+  readonly database: string;
+}> {
+  override get message(): string {
+    return (
+      `Postgres.Database "${this.database}": CREATE DATABASE raised no error, but the database ` +
+      'is still absent on the immediate re-read. Re-plan — this is not a state this provider ' +
+      'expects to reach.'
+    );
+  }
+}
+
+export type PostgresDatabaseError =
+  | PostgresDatabaseNameRefused
+  | PostgresDatabaseRenameRefused
+  | PostgresDatabaseOwnerMissing
+  | PostgresDatabaseDrift
+  | PostgresDatabaseDropRefused
+  | PostgresDatabaseCreateVanished;

package/src/postgres/fake-sql.ts

@@ -0,0 +1,123 @@
+/**
+ * A recording fake `PgExecutor` (S28: "Tests use `bun:test`… a test never trusts the deploy's
+ * own report" — here read back from the fake's own catalog, not from the statement list) for
+ * every lifecycle test in this family. No socket, no `@effect/sql-pg` client — it is small
+ * enough to re-derive the one thing this provider ever asks of a real one: three statement
+ * shapes, matched by text, against an in-memory `pg_roles` set and `pg_database` map.
+ *
+ * ⛔ IT PARSES ITS OWN OUTPUT, NOT SQL IN GENERAL. `parseCreate` below understands exactly the
+ *   text `buildCreateDatabaseSql` (`database-sql.ts`) produces — quoted with `quoteIdent` /
+ *   `quoteStringLiteral` — because that is the only `CREATE DATABASE` this family ever issues. A
+ *   general SQL parser would hide a quoting bug instead of tripping over it.
+ */
+import * as Effect from 'effect/Effect';
+import { SqlError, SqlSyntaxError } from 'effect/unstable/sql/SqlError';
+import type { PostgresDatabaseAttributes } from './database-attrs.ts';
+import type { PgExecutor } from './database-sql.ts';
+
+export interface RecordedStatement {
+  readonly text: string;
+  readonly params: ReadonlyArray<unknown>;
+}
+
+export interface FakeSql extends PgExecutor {
+  readonly statements: ReadonlyArray<RecordedStatement>;
+  /** Mutable on purpose: a test seeds a row a "competing" statement would have produced (the
+   * `42P04` race case) before the fake ever sees it. */
+  readonly databases: Map<string, PostgresDatabaseAttributes>;
+}
+
+export interface FakeSqlOptions {
+  readonly roles?: ReadonlyArray<string>;
+  readonly databases?: ReadonlyArray<PostgresDatabaseAttributes>;
+  /** Fail the NEXT `CREATE DATABASE` with SQLSTATE `42P04` (duplicate_database), once, the way a
+   * concurrent creator racing this reconcile would — classified exactly as
+   * `@effect/sql-pg`'s own driver classifies it (`database-sql.ts`'s header). */
+  readonly raceNextCreate?: boolean;
+}
+
+const unquoteIdent = (raw: string): string => raw.replace(/""/g, '"');
+const unquoteLiteral = (raw: string): string => raw.replace(/''/g, "'");
+
+/** Pull every field back out of exactly the text `buildCreateDatabaseSql` writes. */
+const parseCreate = (text: string): PostgresDatabaseAttributes => {
+  const name = /^CREATE DATABASE "((?:[^"]|"")*)" WITH /.exec(text);
+  const owner = /OWNER "((?:[^"]|"")*)"/.exec(text);
+  const encoding = /ENCODING '((?:[^']|'')*)'/.exec(text);
+  const localeProvider = /LOCALE_PROVIDER '((?:[^']|'')*)'/.exec(text);
+  const lcCollate = /LC_COLLATE '((?:[^']|'')*)'/.exec(text);
+  const lcCtype = /LC_CTYPE '((?:[^']|'')*)'/.exec(text);
+  const tablespace = /TABLESPACE "((?:[^"]|"")*)"/.exec(text);
+  const allowConnections = /ALLOW_CONNECTIONS (true|false)/.exec(text);
+  const connectionLimit = /CONNECTION LIMIT (-?\d+)/.exec(text);
+  const isTemplate = /IS_TEMPLATE (true|false)/.exec(text);
+  if (name === null || owner === null) {
+    throw new Error(`fake-sql: could not parse a generated CREATE DATABASE statement: ${text}`);
+  }
+  return {
+    name: unquoteIdent(name[1] as string),
+    oid: 0,
+    owner: unquoteIdent(owner[1] as string),
+    encoding: encoding === null ? 'UTF8' : unquoteLiteral(encoding[1] as string),
+    localeProvider:
+      localeProvider === null ? 'libc' : (unquoteLiteral(localeProvider[1] as string) as 'libc'),
+    collate: lcCollate === null ? 'C' : unquoteLiteral(lcCollate[1] as string),
+    ctype: lcCtype === null ? 'C' : unquoteLiteral(lcCtype[1] as string),
+    tablespace: tablespace === null ? 'pg_default' : unquoteIdent(tablespace[1] as string),
+    allowConnections: allowConnections === null ? true : allowConnections[1] === 'true',
+    connectionLimit: connectionLimit === null ? -1 : Number(connectionLimit[1]),
+    isTemplate: isTemplate === null ? false : isTemplate[1] === 'true',
+  };
+};
+
+export const makeFakeSql = (options: FakeSqlOptions = {}): FakeSql => {
+  const statements: RecordedStatement[] = [];
+  const roles = new Set(options.roles ?? []);
+  const databases = new Map(options.databases?.map((d) => [d.name, d] as const) ?? []);
+  let raceRemaining = options.raceNextCreate === true ? 1 : 0;
+  let oidCounter = 20000;
+
+  const unsafe = <A extends object>(
+    text: string,
+    params: ReadonlyArray<unknown> = [],
+  ): Effect.Effect<ReadonlyArray<A>, SqlError> =>
+    Effect.suspend(() => {
+      statements.push({ text, params });
+
+      if (text.startsWith('SELECT 1 AS present FROM pg_roles')) {
+        const role = params[0] as string;
+        return Effect.succeed(
+          (roles.has(role) ? [{ present: 1 }] : []) as unknown as ReadonlyArray<A>,
+        );
+      }
+
+      if (text.includes('FROM pg_database')) {
+        const name = params[0] as string;
+        const row = databases.get(name);
+        return Effect.succeed((row === undefined ? [] : [row]) as unknown as ReadonlyArray<A>);
+      }
+
+      if (text.startsWith('CREATE DATABASE')) {
+        if (raceRemaining > 0) {
+          raceRemaining -= 1;
+          return Effect.fail(
+            new SqlError({
+              reason: new SqlSyntaxError({
+                cause: Object.assign(new Error('database "x" already exists'), { code: '42P04' }),
+                message: 'duplicate_database (fake race)',
+                operation: 'CREATE DATABASE',
+              }),
+            }),
+          );
+        }
+        const row = { ...parseCreate(text), oid: oidCounter };
+        oidCounter += 1;
+        databases.set(row.name, row);
+        return Effect.succeed([] as unknown as ReadonlyArray<A>);
+      }
+
+      throw new Error(`fake-sql: unrecognised statement: ${text}`);
+    });
+
+  return { unsafe, statements, databases };
+};

package/src/postgres/fixtures/pg-REL_18_6-create-database-synopsis.txt

@@ -0,0 +1,26 @@
+# path: doc/src/sgml/ref/create_database.sgml
+# blob: 4da8aeebb50a29e89bd9f68a8deac4b1a3ec7b18
+# tag: REL_18_6 (commit 724edf9bde9d356724ad384a2e196edc3c9f80f7)
+# fetched: 2026-09-23 via gh api repos/postgres/postgres/contents/...?ref=724edf9bde9d356724ad384a2e196edc3c9f80f7
+# excerpt: the <synopsis> block only (lines 23-42 of the full file), cut per house doc-size convention
+#
+<synopsis>
+CREATE DATABASE <replaceable class="parameter">name</replaceable>
+    [ WITH ] [ OWNER [=] <replaceable class="parameter">user_name</replaceable> ]
+           [ TEMPLATE [=] <replaceable class="parameter">template</replaceable> ]
+           [ ENCODING [=] <replaceable class="parameter">encoding</replaceable> ]
+           [ STRATEGY [=] <replaceable class="parameter">strategy</replaceable> ]
+           [ LOCALE [=] <replaceable class="parameter">locale</replaceable> ]
+           [ LC_COLLATE [=] <replaceable class="parameter">lc_collate</replaceable> ]
+           [ LC_CTYPE [=] <replaceable class="parameter">lc_ctype</replaceable> ]
+           [ BUILTIN_LOCALE [=] <replaceable class="parameter">builtin_locale</replaceable> ]
+           [ ICU_LOCALE [=] <replaceable class="parameter">icu_locale</replaceable> ]
+           [ ICU_RULES [=] <replaceable class="parameter">icu_rules</replaceable> ]
+           [ LOCALE_PROVIDER [=] <replaceable class="parameter">locale_provider</replaceable> ]
+           [ COLLATION_VERSION = <replaceable>collation_version</replaceable> ]
+           [ TABLESPACE [=] <replaceable class="parameter">tablespace_name</replaceable> ]
+           [ ALLOW_CONNECTIONS [=] <replaceable class="parameter">allowconn</replaceable> ]
+           [ CONNECTION LIMIT [=] <replaceable class="parameter">connlimit</replaceable> ]
+           [ IS_TEMPLATE [=] <replaceable class="parameter">istemplate</replaceable> ]
+           [ OID [=] <replaceable class="parameter">oid</replaceable> ]
+</synopsis>

package/src/postgres/fixtures/pg-REL_18_6-pg_database.h.txt

@@ -0,0 +1,67 @@
+# path: src/include/catalog/pg_database.h
+# blob: 54f0d38c9c9e1cd4d419b05b296b8f84875e9768
+# tag: REL_18_6 (commit 724edf9bde9d356724ad384a2e196edc3c9f80f7)
+# fetched: 2026-09-23 via gh api repos/postgres/postgres/contents/...?ref=724edf9bde9d356724ad384a2e196edc3c9f80f7
+# excerpt: the CATALOG(pg_database...) { ... } FormData_pg_database struct only (lines 29-89 of the full file)
+#
+CATALOG(pg_database,1262,DatabaseRelationId) BKI_SHARED_RELATION BKI_ROWTYPE_OID(1248,DatabaseRelation_Rowtype_Id) BKI_SCHEMA_MACRO
+{
+	/* oid */
+	Oid			oid;
+
+	/* database name */
+	NameData	datname;
+
+	/* owner of database */
+	Oid			datdba BKI_DEFAULT(POSTGRES) BKI_LOOKUP(pg_authid);
+
+	/* character encoding */
+	int32		encoding;
+
+	/* locale provider, see pg_collation.collprovider */
+	char		datlocprovider;
+
+	/* allowed as CREATE DATABASE template? */
+	bool		datistemplate;
+
+	/* new connections allowed? */
+	bool		datallowconn;
+
+	/* database has login event triggers? */
+	bool		dathasloginevt;
+
+	/*
+	 * Max connections allowed. Negative values have special meaning, see
+	 * DATCONNLIMIT_* defines below.
+	 */
+	int32		datconnlimit;
+
+	/* all Xids < this are frozen in this DB */
+	TransactionId datfrozenxid;
+
+	/* all multixacts in the DB are >= this */
+	TransactionId datminmxid;
+
+	/* default table space for this DB */
+	Oid			dattablespace BKI_LOOKUP(pg_tablespace);
+
+#ifdef CATALOG_VARLEN			/* variable-length fields start here */
+	/* LC_COLLATE setting */
+	text		datcollate BKI_FORCE_NOT_NULL;
+
+	/* LC_CTYPE setting */
+	text		datctype BKI_FORCE_NOT_NULL;
+
+	/* ICU locale ID */
+	text		datlocale;
+
+	/* ICU collation rules */
+	text		daticurules;
+
+	/* provider-dependent version of collation data */
+	text		datcollversion BKI_DEFAULT(_null_);
+
+	/* access permissions */
+	aclitem		datacl[1];
+#endif
+} FormData_pg_database;

package/src/postgres/index.ts

@@ -0,0 +1,30 @@
+/**
+ * PostgreSQL providers for Alchemy — `Postgres.Database`, create-and-assert over a self-hosted
+ * cluster, walked against PostgreSQL 18.6. See `docs/postgres.md`.
+ *
+ * ⛔ THIS BARREL IS THE PUBLIC API, deliberately smaller than the directory: `fake-sql.ts` is a
+ *   test double, not something a consuming stack should import.
+ */
+export type { PostgresConnectionConfig } from './connection.ts';
+export { PostgresConnection, postgresConnection, withPg } from './connection.ts';
+export type { PostgresDatabaseAttributes, PostgresDatabaseProps } from './database-attrs.ts';
+export { POSTGRES_NAME_MAX_BYTES, nameByteRefusal, utf8ByteLength } from './database-attrs.ts';
+export {
+  buildCreateDatabaseSql,
+  firstDrift,
+  isDuplicateDatabaseRace,
+  quoteIdent,
+  quoteStringLiteral,
+  roleExists,
+  selectDatabase,
+} from './database-sql.ts';
+export { PostgresDatabase, PostgresDatabaseProvider, isPostgresDatabase } from './database.ts';
+export {
+  PostgresDatabaseDrift,
+  PostgresDatabaseDropRefused,
+  PostgresDatabaseNameRefused,
+  PostgresDatabaseOwnerMissing,
+  PostgresDatabaseRenameRefused,
+  type PostgresDatabaseError,
+} from './errors.ts';
+export { postgresProviders } from './providers.ts';

package/src/postgres/providers.ts

@@ -0,0 +1,16 @@
+/**
+ * `Postgres.Database`'s provider, pre-wired to one cluster:
+ *
+ *     const providers = postgresProviders({ host: '/opt/homeflare/postgres/sockets', database: 'postgres', username: 'tim' });
+ *
+ * ★ THE CLUSTER IS A PARAMETER, NOT A DEFAULT (S15, and `docs/postgres.md#path`). This kit is
+ *   PUBLIC; the mini's socket directory, its user and its port are the CONSUMING stack's values,
+ *   never baked in here. A stack with more than one cluster calls this more than once and merges
+ *   the results under whatever logical grouping it wants.
+ */
+import * as Layer from 'effect/Layer';
+import { type PostgresConnectionConfig, postgresConnection } from './connection.ts';
+import { PostgresDatabaseProvider } from './database.ts';
+
+export const postgresProviders = (config: PostgresConnectionConfig) =>
+  PostgresDatabaseProvider().pipe(Layer.provide(postgresConnection(config)));

package/src/proxmox/zfs-pool.ts

@@ -54,8 +54,16 @@
  *
  * ⚠️ 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';

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