@gjsify/cli 0.49.0 → 0.51.0

package/lib/utils/ship/changelog.d.ts

@@ -38,19 +38,20 @@ export declare function changelogEntriesFor(version: string, source: string): st
  * wrong: exactly one leading space, then `--`, one space, the maintainer, and TWO
  * spaces before the date.
  *
- * TWO lintian tags this file still raises, both measured on lintian 2.117 against
- * gjsify's own `.deb` and both left alone deliberately:
- *
- *  - `initial-upload-closes-no-bugs`, because the Debian revision is `-1` and the
- *    entry closes no bug. It is a statement about the Debian ARCHIVE's ITP
- *    workflow — the first upload of a new source package should close its ITP bug
- *    — and a package built by `gjsify ship` is never uploaded there. There is no
- *    bug number that would be true to write, so the tag is inapplicable rather
- *    than unmet.
- *  - `changelog-not-compressed-with-max-compression`. Policy asks for `gzip -9`
- *    and neither `CompressionStream` nor `@gjsify/zlib` takes a level, so
- *    `gzipDeterministic` cannot ask for one. Ledgered in `status/open-todos.md`:
- *    the fix is a capability in the core, and stamping the header's XFL byte to
- *    claim max compression we did not use is not one.
+ * ONE lintian tag this file still raises, measured on lintian 2.117 against
+ * gjsify's own `.deb` and left alone deliberately: `initial-upload-closes-no-bugs`,
+ * because the Debian revision is `-1` and the entry closes no bug. It is a
+ * statement about the Debian ARCHIVE's ITP workflow — the first upload of a new
+ * source package should close its ITP bug — and a package built by `gjsify ship`
+ * is never uploaded there. There is no bug number that would be true to write, so
+ * the tag is inapplicable rather than unmet.
+ *
+ * `changelog-not-compressed-with-max-compression` was a second one, and closing it
+ * was a capability gap in the CORE rather than anything wrong in this file:
+ * neither `CompressionStream` nor `@gjsify/zlib` would take a compression level,
+ * so `gzipDeterministic` had none to pass on. `@gjsify/zlib` honours
+ * `options.level` now and `plan.ts` compresses this file at
+ * `POLICY_MAX_COMPRESSION`. `verify-deb.sh` gates the tag by name, so it cannot
+ * come back quietly.
  */
 export declare function renderDebianChangelog(settings: PackSettings, source: string | undefined, mtime: number): string;

package/lib/utils/ship/changelog.js

@@ -134,20 +134,21 @@ const WIDTH = 80;
  * wrong: exactly one leading space, then `--`, one space, the maintainer, and TWO
  * spaces before the date.
  *
- * TWO lintian tags this file still raises, both measured on lintian 2.117 against
- * gjsify's own `.deb` and both left alone deliberately:
+ * ONE lintian tag this file still raises, measured on lintian 2.117 against
+ * gjsify's own `.deb` and left alone deliberately: `initial-upload-closes-no-bugs`,
+ * because the Debian revision is `-1` and the entry closes no bug. It is a
+ * statement about the Debian ARCHIVE's ITP workflow — the first upload of a new
+ * source package should close its ITP bug — and a package built by `gjsify ship`
+ * is never uploaded there. There is no bug number that would be true to write, so
+ * the tag is inapplicable rather than unmet.
  *
- *  - `initial-upload-closes-no-bugs`, because the Debian revision is `-1` and the
- *    entry closes no bug. It is a statement about the Debian ARCHIVE's ITP
- *    workflow — the first upload of a new source package should close its ITP bug
- *    — and a package built by `gjsify ship` is never uploaded there. There is no
- *    bug number that would be true to write, so the tag is inapplicable rather
- *    than unmet.
- *  - `changelog-not-compressed-with-max-compression`. Policy asks for `gzip -9`
- *    and neither `CompressionStream` nor `@gjsify/zlib` takes a level, so
- *    `gzipDeterministic` cannot ask for one. Ledgered in `status/open-todos.md`:
- *    the fix is a capability in the core, and stamping the header's XFL byte to
- *    claim max compression we did not use is not one.
+ * `changelog-not-compressed-with-max-compression` was a second one, and closing it
+ * was a capability gap in the CORE rather than anything wrong in this file:
+ * neither `CompressionStream` nor `@gjsify/zlib` would take a compression level,
+ * so `gzipDeterministic` had none to pass on. `@gjsify/zlib` honours
+ * `options.level` now and `plan.ts` compresses this file at
+ * `POLICY_MAX_COMPRESSION`. `verify-deb.sh` gates the tag by name, so it cannot
+ * come back quietly.
  */
 export function renderDebianChangelog(settings, source, mtime) {
     const entries = source === undefined ? [] : changelogEntriesFor(settings.version, source);

package/lib/utils/ship/depends.d.ts

@@ -91,6 +91,26 @@ export interface DependsInputs {
     /** Minimum Node major, when one is depended on. Default {@link DEFAULT_NODE_FLOOR}. */
     minNodeVersion?: string;
 }
+/**
+ * The namespaces the bundle imports that the HOST has to provide — scanned set
+ * minus everything the payload carries itself.
+ *
+ * LIFTED OUT OF {@link deriveDepends} because a second caller appeared and the
+ * question is not a `.deb`'s. `appimage.ts` asks it to write the one sentence an
+ * AppImage owes its user — *this file carries the application, and takes these
+ * from your system* — and an AppImage has no `Depends:` field, so it cannot go
+ * through the package-name table below. A copied filter would drift in the
+ * direction that is invisible: the drifted copy would still produce a plausible
+ * list, just one that no longer matches the dependencies the `.deb` beside it
+ * declares from the same payload.
+ *
+ * Deriving the carried set from the staged FILENAMES is the point, and it is
+ * `deriveDepends`' reasoning unchanged: `Gwebgl-0.1.typelib` answers for both
+ * `Gwebgl-0.1` and `Gwebgl`, so a project that declared a namespace bundled
+ * without the file being there gets an artifact that names its real requirement
+ * instead of one that installs and dies at the first import.
+ */
+export declare function hostProvidedNamespaces(namespaces: readonly string[], bundledTypelibs?: readonly string[]): string[];
 /**
  * The `Depends:` / `Requires:` list for one format.
  *

package/lib/utils/ship/depends.js

@@ -256,6 +256,36 @@ const TYPELIB_PACKAGES = {
  * whose bundle reaches one, which includes every `@gjsify/http` server.
  */
 const BUNDLED_TYPELIB = /^Gjsify[A-Z]/;
+/**
+ * The namespaces the bundle imports that the HOST has to provide — scanned set
+ * minus everything the payload carries itself.
+ *
+ * LIFTED OUT OF {@link deriveDepends} because a second caller appeared and the
+ * question is not a `.deb`'s. `appimage.ts` asks it to write the one sentence an
+ * AppImage owes its user — *this file carries the application, and takes these
+ * from your system* — and an AppImage has no `Depends:` field, so it cannot go
+ * through the package-name table below. A copied filter would drift in the
+ * direction that is invisible: the drifted copy would still produce a plausible
+ * list, just one that no longer matches the dependencies the `.deb` beside it
+ * declares from the same payload.
+ *
+ * Deriving the carried set from the staged FILENAMES is the point, and it is
+ * `deriveDepends`' reasoning unchanged: `Gwebgl-0.1.typelib` answers for both
+ * `Gwebgl-0.1` and `Gwebgl`, so a project that declared a namespace bundled
+ * without the file being there gets an artifact that names its real requirement
+ * instead of one that installs and dies at the first import.
+ */
+export function hostProvidedNamespaces(namespaces, bundledTypelibs = []) {
+    const shipped = new Set();
+    for (const file of bundledTypelibs) {
+        const match = /([A-Za-z0-9]+)-([\d.]+)\.typelib$/.exec(file);
+        if (!match)
+            continue;
+        shipped.add(`${match[1]}-${match[2]}`);
+        shipped.add(match[1]);
+    }
+    return [...new Set(namespaces)].sort().filter((ns) => !BUNDLED_TYPELIB.test(ns) && !shipped.has(ns));
+}
 /**
  * The `Depends:` / `Requires:` list for one format.
  *
@@ -271,22 +301,7 @@ export function deriveDepends(format, inputs) {
         ? [`${NODE_PACKAGE[format]} >= ${inputs.minNodeVersion ?? DEFAULT_NODE_FLOOR}`]
         : [`gjs >= ${inputs.minGjsVersion ?? DEFAULT_GJS_FLOOR}`];
     const unmapped = [];
-    // Namespaces the package SHIPS ITSELF, read off the staged filenames rather than from a
-    // separate declaration: `Gwebgl-0.1.typelib` → `Gwebgl-0.1` and `Gwebgl`. Deriving it is the
-    // point — a project that declared a namespace bundled without the file being there would get
-    // a package that installs and dies at the first import, which is exactly what this check
-    // exists to prevent.
-    const shipped = new Set();
-    for (const file of inputs.bundledTypelibs ?? []) {
-        const match = /([A-Za-z0-9]+)-([\d.]+)\.typelib$/.exec(file);
-        if (!match)
-            continue;
-        shipped.add(`${match[1]}-${match[2]}`);
-        shipped.add(match[1]);
-    }
-    for (const namespace of [...new Set(inputs.namespaces)].sort()) {
-        if (BUNDLED_TYPELIB.test(namespace) || shipped.has(namespace))
-            continue;
+    for (const namespace of hostProvidedNamespaces(inputs.namespaces, inputs.bundledTypelibs)) {
         const entry = lookupTypelib(namespace, inputs.typelibPackages);
         if (entry === undefined) {
             unmapped.push(namespace);

package/lib/utils/ship/formats.d.ts

@@ -138,4 +138,13 @@ export declare function configuredFormats(raw: readonly string[], layout: Layout
  * the two questions are separate, and a `.app` is precisely the item Apple's
  * remedy above tells you to staple after submitting the archive around it.
  */
+/**
+ * Refuse a project whose `kind` no chosen container can hold.
+ *
+ * DERIVED FROM THE TABLE (`FormatDescriptor.requiresDesktopEntry`), never from a
+ * list of format ids here — a fourth format that also needs an entry would
+ * otherwise be refused by appimagetool's own "Desktop file not found, aborting"
+ * after a full build, which is the message this replaced.
+ */
+export declare function assertKindCanPack(formats: readonly FormatDescriptor[], kind: 'app' | 'cli'): void;
 export declare function canCarryTicket(id: FormatId): boolean;

package/lib/utils/ship/formats.js

@@ -8,6 +8,7 @@
 // and one filename. What it also proved is what the design did NOT predict —
 // a format can be host-bound (§ A3), so `host` is a descriptor field now.
 import { isOnPath } from '../check-system-deps.js';
+import { APPIMAGE_TOOL } from './appimage.js';
 import { DMG_TOOL } from './dmg.js';
 import { LAYOUTS, LAYOUT_NAMES } from './layout.js';
 import { SCHEMA_COMPILER, SCHEMA_COMPILER_HINT } from './schemas.js';
@@ -72,6 +73,33 @@ function rpmArch(arch, archIndependent) {
 function flatpakArch(arch, _archIndependent) {
     return lookupArch(FLATPAK_ARCH, arch, 'Flatpak');
 }
+/**
+ * `process.arch` → the name appimagetool uses, which is `uname -m`'s.
+ *
+ * A TABLE OF ITS OWN even though it currently equals `RPM_ARCH` on every row it
+ * has, and the reason is that the two answer different questions: rpm's is a
+ * package-manager namespace with `noarch`, `i686` and `ppc64le` in it, while this
+ * one is the string appimagetool puts in `$ARCH` and matches against the runtimes
+ * it can embed. Sharing the table would make an rpm row addition silently claim
+ * an AppImage architecture that has no runtime — `ppc64le` is exactly that case
+ * today. So the short list is the honest one, and an arch not in it is REFUSED
+ * rather than guessed, which is `FLATPAK_ARCH`'s rule for `FLATPAK_ARCH`'s reason:
+ * the value ends up in a filename a user is asked to download.
+ *
+ * `archIndependent` is IGNORED, like Flatpak's and unlike deb's and rpm's. There
+ * is no `noarch` AppImage: the file BEGINS with an ELF runtime, so a payload of
+ * pure JavaScript still ships in an x86-64 executable and labelling it otherwise
+ * would name a file nothing can run.
+ */
+const APPIMAGE_ARCH = {
+    x64: 'x86_64',
+    arm64: 'aarch64',
+    ia32: 'i686',
+    arm: 'armhf',
+};
+function appImageArch(arch, _archIndependent) {
+    return lookupArch(APPIMAGE_ARCH, arch, 'AppImage');
+}
 /**
  * `process.arch` → the name Apple's tools use.
  *
@@ -344,6 +372,108 @@ export const FORMATS = {
         fileName: (s, archLabel) => `${s.appId}-${s.version}-${s.release}.${archLabel}.flatpak`,
         artifactKind: 'file',
     },
+    // THE FOURTH CONTAINER OVER THE LINUX TREE, and the first row added to this
+    // table that needed NOTHING staged: `deb`, `rpm` and `flatpak` already wrap
+    // this exact payload, so ADR 0024 § 2's "one payload, a handful of layouts"
+    // is here a row plus a packer and no change to `plan.ts` at all. ADR 0024
+    // § 9 deferred it and § A24 lifts the deferral; `appimage.ts`'s header
+    // carries the argument, and the short form is that the two promises an
+    // AppImage can keep with no relocatable Linux closure — no install, no root
+    // — are the two nothing else in this table offers, and the third is
+    // DECLARED rather than implied.
+    appimage: {
+        id: 'appimage',
+        layoutOs: 'linux',
+        // `/usr`, exactly as the `.deb` — and that is the whole layout difference
+        // between the two formats. An AppImage mounts its squashfs and the AppDir's
+        // `usr/` becomes the prefix, which the staged launcher computes for itself
+        // (ADR 0024 § 3): `readlink -f "$0"` then two `dirname`s, measured inside a
+        // mount as `/tmp/.mount_xxxx/usr`. So the same `bin/<name>` works under
+        // `/usr`, under `/app` and under a mountpoint nobody chose.
+        prefix: '/usr',
+        host: {
+            // Linux-bound the way the Flatpak row is, and NOT the way the `.dmg`
+            // is: the container is an ELF runtime for Linux with a Linux filesystem
+            // behind it, so the format is bound the way the application is.
+            finishOn: ['linux'],
+            // The SCHEMA COMPILER IS ABSENT here, unlike the two windows rows and
+            // for the `.dmg`'s reason inverted: this layout HAS an install step in
+            // every other format, and inside an AppImage it does not — there is no
+            // `postinst` to run `glib-compile-schemas` in a read-only squashfs. But
+            // `compileSchemasForStage` has already run at ASSEMBLY time and
+            // `gschemas.compiled` is in the payload, so declaring the compiler on
+            // the PACK path would refuse a `--from-stage` pack that works.
+            requiredTools: [APPIMAGE_TOOL],
+            // A URL AND NOT A PACKAGE NAME, and it is the first hint in this table
+            // that has to be. `flatpak-builder` and `msitools` are in Fedora and in
+            // Debian; `appimagetool` is in neither, so pointing at a distro would
+            // send the reader to an `E: Unable to locate package`. The `--stage`
+            // half is repeated here because it is the answer for a CI image that is
+            // not going to grow a hand-installed binary.
+            installHint: 'no distribution packages it — take the release from ' +
+                'https://github.com/AppImage/appimagetool/releases, `chmod +x` it and put it on PATH as ' +
+                '`appimagetool`; or assemble here with `gjsify ship linux --stage` and pack where it is',
+            oracle: {
+                // TWO READERS, NEITHER OF THEM appimagetool AND NEITHER OF THEM THE
+                // ARTIFACT'S OWN RUNTIME — which is what `--appimage-offset` and
+                // `--appimage-extract` would be, the format reading what the format
+                // wrote (ADR 0024 § A3).
+                //
+                //   * CPython reads the ELF SECTION-HEADER TABLE for the offset the
+                //     filesystem starts at — `e_shoff + e_shnum * e_shentsize`,
+                //     twelve bytes of `struct.unpack_from`, straight out of the ELF
+                //     specification. Measured against `--appimage-offset` on a real
+                //     artifact: 944632 both ways. That agreement is the
+                //     discriminator for the whole container, because a truncated or
+                //     empty image has no squashfs superblock there. `python3` and
+                //     NOT `readelf`, which the first draft of this row declared and
+                //     `verify-appimage.py` never execs — the field names the tools
+                //     the oracle RUNS, and binutils is not one of them here. Same
+                //     reader family the two `macos-app` rows already declare.
+                //   * `unsquashfs` (squashfs-tools) then lists the filesystem at
+                //     that offset with names, modes and sizes, which
+                //     `.github/ship-oracle/verify-appimage.py` compares against the
+                //     stage manifest. A different PROGRAM from the bundled
+                //     mksquashfs appimagetool packs with, and the leg that runs it
+                //     is the Linux one that already reads the `.deb`.
+                readWith: ['python3', 'unsquashfs'],
+                readOn: ['linux'],
+                selfReading: false,
+            },
+        },
+        // No `Depends:` FIELD — which is not the same as no dependencies, and this
+        // row is the one place in the table where that distinction has teeth. A
+        // `.deb` declares `gir1.2-gtk-4.0` and apt refuses to install without it;
+        // an AppImage has nowhere to write that down, so `appImageHostRequirements`
+        // derives the same set from the same scan and `ship` PRINTS it while
+        // `AppRun` carries the interpreter half as a refusal. See `depends.ts`'s
+        // `DistroFormatId`: this is `null` because there is no field, never because
+        // there is nothing to say.
+        depends: null,
+        // BOTH, like `deb` and `rpm` and for the same reason: the interpreter comes
+        // from the machine. The difference from those two is that nothing declares
+        // it — see the `depends` note above and `interpreterGap` below.
+        interpreters: ['gjs', 'node'],
+        interpreterGap: 'an AppImage carries the application and takes its interpreter from the host, exactly as a distro ' +
+            'package does — but with no dependency field to declare it in, so the requirement is printed at ' +
+            'pack time and checked by `AppRun` at launch instead',
+        licenseDest: SHARE_LICENSE_DEST,
+        licenseKind: 'plain',
+        archName: appImageArch,
+        // The BINARY name, like the `.dmg` and the two zips and for their reason:
+        // this artifact is a DOWNLOAD that lands in a browser's folder beside other
+        // files, so it carries the version and the architecture and avoids the
+        // spaces a display name may contain. Not the app id, which is the Flatpak's
+        // convention because a Flatpak ref IS the id; an AppImage installs as
+        // nothing and is addressed by its path.
+        fileName: (s, archLabel) => `${s.binaryName}-${s.version}-${s.release}.${archLabel}.AppImage`,
+        artifactKind: 'file',
+        // THE ONLY ROW THAT SETS IT. appimagetool refuses an AppDir with no
+        // `.desktop` at its root, and `kind: 'cli'` stages none by design — a
+        // refusal `gjsify.ship.kind` decides on its own, so it belongs before the
+        // build beside the tool gate rather than after it inside the packer.
+        requiresDesktopEntry: true,
+    },
     // ── macOS (#1354 M2a) ────────────────────────────────────────────────
     //
     // TWO ROWS FOR ONE TREE, and the pair is what `layoutOs` was added for. The
@@ -450,7 +580,21 @@ export const FORMATS = {
         // is a download: it lands in a browser's downloads folder beside other
         // files, so it carries the version and the arch, and it avoids the spaces
         // a display name may contain.
-        fileName: (s, archLabel) => `${s.binaryName}-${s.version}-${s.release}.${archLabel}.zip`,
+        //
+        // AND THE OPERATING SYSTEM, which the extension does not name. Every other
+        // row's suffix names exactly one platform — `.deb`, `.rpm`, `.flatpak`,
+        // `.dmg`, `.msi` — and `.zip` names none, so this row and `windows-dir-zip`
+        // are the only two artifacts in the table a user cannot tell apart by
+        // looking at them. Before this token they were separated by nothing but a
+        // coincidence between two unrelated arch tables (`MACOS_ARCH` maps x64 to
+        // `x86_64`, `WINDOWS_ARCH` to `x64`), which put a bare `…-1.arm64.zip` on a
+        // release page beside a Windows zip with no way to choose — and would have
+        // had the two formats silently overwrite each other in `ship/out/` the day
+        // a Windows/arm64 row became possible, an upstream blocker (#1117) being
+        // all that stood in the way. `macos`, not `darwin`, for the same reason
+        // `MACOS_ARCH` writes `x86_64` rather than `x64`: this label is read by
+        // whoever downloads the file, never by `process.platform`.
+        fileName: (s, archLabel) => `${s.binaryName}-${s.version}-${s.release}.macos.${archLabel}.zip`,
         artifactKind: 'file',
     },
     // ── macOS (#1354 M4) ─────────────────────────────────────────────────
@@ -661,7 +805,14 @@ export const FORMATS = {
         // pair splits them: this one is a download that lands in a browser's
         // folder beside other files, so it carries the version and the arch and
         // avoids the spaces a display name may contain.
-        fileName: (s, archLabel) => `${s.binaryName}-${s.version}-${s.release}.${archLabel}.zip`,
+        //
+        // …and the OS, for the reason spelled out on the `macos-app-zip` row it was
+        // copied from: `.zip` is the one container this table puts on more than one
+        // operating system, so it is the one name that has to say which. `windows`
+        // rather than `win32` — the spelling is the user's, like the `x64` this row
+        // keeps because Node's own archives, gvsbuild's assets and the runner label
+        // all use it.
+        fileName: (s, archLabel) => `${s.binaryName}-${s.version}-${s.release}.windows.${archLabel}.zip`,
         artifactKind: 'file',
     },
     // ── The Windows installer (#1354 M5) ─────────────────────────────────
@@ -974,6 +1125,25 @@ export function configuredFormats(raw, layout) {
  * the two questions are separate, and a `.app` is precisely the item Apple's
  * remedy above tells you to staple after submitting the archive around it.
  */
+/**
+ * Refuse a project whose `kind` no chosen container can hold.
+ *
+ * DERIVED FROM THE TABLE (`FormatDescriptor.requiresDesktopEntry`), never from a
+ * list of format ids here — a fourth format that also needs an entry would
+ * otherwise be refused by appimagetool's own "Desktop file not found, aborting"
+ * after a full build, which is the message this replaced.
+ */
+export function assertKindCanPack(formats, kind) {
+    if (kind === 'app')
+        return;
+    const needsEntry = formats.filter((format) => format.requiresDesktopEntry);
+    if (needsEntry.length === 0)
+        return;
+    throw new Error(`gjsify ship: ${needsEntry.map((format) => format.id).join(', ')} cannot package a ` +
+        '`kind: "cli"` project — the container needs a desktop entry at its root and a CLI stages none ' +
+        'by design. Set `gjsify.ship.kind` to "app" if this is a GUI application, or ship it as a `.deb`, ' +
+        'an `.rpm` or a Flatpak, none of which need one.');
+}
 export function canCarryTicket(id) {
     switch (id) {
         case 'macos-app':
@@ -986,6 +1156,7 @@ export function canCarryTicket(id) {
         case 'deb':
         case 'rpm':
         case 'flatpak':
+        case 'appimage':
         case 'windows-dir':
         case 'windows-dir-zip':
         case 'msi':

package/lib/utils/ship/gzip.d.ts

@@ -1,2 +1,31 @@
-/** gzip with the header's timestamp zeroed and the OS byte pinned to Unix. */
-export declare function gzipDeterministic(input: Uint8Array): Promise<Uint8Array>;
+/**
+ * gzip with the header's timestamp zeroed and the OS byte pinned to Unix.
+ *
+ * @param level 0-9, or omitted for zlib's default. THE ONLY HONEST WAY TO SET XFL:
+ *   byte 8 of the header records how hard the compressor tried (2 = maximum,
+ *   4 = fastest, 0 = neither), `lintian` reads it to raise
+ *   `changelog-not-compressed-with-max-compression`, and `file` prints it as
+ *   "max compression". Stamping that byte here beside the mtime and OS bytes would
+ *   be a different thing entirely and was rejected for it: mtime and OS are facts
+ *   about the build ENVIRONMENT, which a reproducible build is entitled to
+ *   normalise, while XFL is a statement about the compression actually performed.
+ *   Writing a 2 we had not earned would make the artifact lie to the tool reading
+ *   it. So the level travels down to the compressor instead.
+ *
+ *   AND THE TEMPTATION IS REAL, which is why this is worth writing down: measured
+ *   on gjsify's own `.deb`, the changelog member compressed at the default level
+ *   and at 9 differs in EXACTLY ONE BYTE — position 9, XFL, 0 against 2 — and is
+ *   1152 bytes either way. For this input, stamping the byte would have produced
+ *   the identical artifact. It is identical by coincidence of a small input: over
+ *   this repo's full `CHANGELOG.md` the same two levels differ by thousands of
+ *   bytes. A rule that happens to hold on today's input is not the rule.
+ */
+export declare function gzipDeterministic(input: Uint8Array, level?: number): Promise<Uint8Array>;
+/**
+ * `gzip -9`, the level Debian Policy § 4.4 asks of a packaging changelog.
+ *
+ * Named rather than spelled `9` at the call site so the reason travels with the
+ * number: the `-n` half of Policy's `gzip -9 -n` is what {@link gzipDeterministic}
+ * already does to bytes 4-7.
+ */
+export declare const POLICY_MAX_COMPRESSION = 9;

package/lib/utils/ship/gzip.js

@@ -5,10 +5,54 @@
 // input produce different bytes — which no test notices, because every test
 // compares the DECOMPRESSED content. It is the single most-missed
 // reproducibility bug in package writers, and it costs nothing to close.
+//
+// WHAT "DETERMINISTIC" DOES NOT COVER, measured 2026-09-11 and named here because
+// the function's own name overstates it: the bytes are reproducible for a given
+// HOST, not for a given artifact. `@gjsify/tar`'s gzip runs on the platform's
+// zlib, and the platforms do not ship the same one — Fedora's libz is
+// `zlib-ng-compat` (2.3.3) while Node bundles its own zlib (1.3.2.1-motley). Over
+// this repo's `CHANGELOG.md` (876 192 bytes) at the DEFAULT level they produce
+// 272 003 and 272 000 bytes respectively, so a `.deb` packed under GJS and one
+// packed under Node already differ, today, before any level argument exists.
+// Levels 1-4 differ too, in the other direction (zlib-ng is smaller). Two
+// consequences worth keeping:
+//
+//   * `tests/e2e/ship-from-stage` asserts byte-equality between a direct pack and
+//     a `--from-stage` pack, and it holds because both run on ONE host. It is
+//     structurally blind to this, and a cross-host pack is exactly what
+//     `--from-stage` exists to enable.
+//   * zlib-ng's level 9 is WORSE than its level 8 on large inputs — 277 974 vs
+//     270 255 bytes on the file above, ~2.9 % bigger — which is why `level: 9` is
+//     asked for only where a reader demands it (see below) and not blanket-applied
+//     to the payload tarballs.
+//
+// Ledgered in `status/open-todos.md`; closing it means pinning ONE deflate
+// implementation, which is a larger decision than this file.
 import { gzip } from '@gjsify/tar';
-/** gzip with the header's timestamp zeroed and the OS byte pinned to Unix. */
-export async function gzipDeterministic(input) {
-    const out = await gzip(input);
+/**
+ * gzip with the header's timestamp zeroed and the OS byte pinned to Unix.
+ *
+ * @param level 0-9, or omitted for zlib's default. THE ONLY HONEST WAY TO SET XFL:
+ *   byte 8 of the header records how hard the compressor tried (2 = maximum,
+ *   4 = fastest, 0 = neither), `lintian` reads it to raise
+ *   `changelog-not-compressed-with-max-compression`, and `file` prints it as
+ *   "max compression". Stamping that byte here beside the mtime and OS bytes would
+ *   be a different thing entirely and was rejected for it: mtime and OS are facts
+ *   about the build ENVIRONMENT, which a reproducible build is entitled to
+ *   normalise, while XFL is a statement about the compression actually performed.
+ *   Writing a 2 we had not earned would make the artifact lie to the tool reading
+ *   it. So the level travels down to the compressor instead.
+ *
+ *   AND THE TEMPTATION IS REAL, which is why this is worth writing down: measured
+ *   on gjsify's own `.deb`, the changelog member compressed at the default level
+ *   and at 9 differs in EXACTLY ONE BYTE — position 9, XFL, 0 against 2 — and is
+ *   1152 bytes either way. For this input, stamping the byte would have produced
+ *   the identical artifact. It is identical by coincidence of a small input: over
+ *   this repo's full `CHANGELOG.md` the same two levels differ by thousands of
+ *   bytes. A rule that happens to hold on today's input is not the rule.
+ */
+export async function gzipDeterministic(input, level) {
+    const out = await gzip(input, level === undefined ? undefined : { level });
     if (out.byteLength < 10 || out[0] !== 0x1f || out[1] !== 0x8b) {
         throw new Error('gjsify ship: internal error — gzip did not produce a gzip stream.');
     }
@@ -19,3 +63,11 @@ export async function gzipDeterministic(input) {
     out[9] = 3;
     return out;
 }
+/**
+ * `gzip -9`, the level Debian Policy § 4.4 asks of a packaging changelog.
+ *
+ * Named rather than spelled `9` at the call site so the reason travels with the
+ * number: the `-n` half of Policy's `gzip -9 -n` is what {@link gzipDeterministic}
+ * already does to bytes 4-7.
+ */
+export const POLICY_MAX_COMPRESSION = 9;

package/lib/utils/ship/plan.d.ts

@@ -67,11 +67,39 @@ export declare function planOverlay(settings: ShipSettings, format: FormatDescri
  */
 export declare function assertOverlayIsLicensed(formatId: FormatId, binaryName: string, overlay: readonly StagedFile[]): void;
 /**
- * The hicolor subdirectory for an icon: `scalable` for SVG, otherwise the
- * pixel size read from a `<n>x<n>` path component or a trailing number in the
- * filename.
+ * Whether an icon belongs in the theme's SYMBOLIC context rather than at a size.
+ *
+ * `symbolic` is a directory of its own in a hicolor theme and NOT a size value.
+ * Measured in `refs/adwaita-icon-theme/index.theme`, which lists `symbolic/apps`
+ * in `Directories=` beside `scalable/apps` and `16x16/apps` and gives it its own
+ * section — `Context=Applications`, `Size=16`, `MinSize=8`, `MaxSize=512`,
+ * `Type=Scalable` — against the scalable row's `Size=128`. The freedesktop icon
+ * theme specification has no notion of `symbolic` at all: a theme expresses it by
+ * giving the directory a section, which is exactly why reading the EXTENSION
+ * cannot see it, and why this question has to be asked before the size one.
+ *
+ * TWO SIGNALS, the same pair `iconThemeDir` already reads for a size: the
+ * directory an author put the file in, and the name they gave it. GTK resolves a
+ * symbolic icon by the `-symbolic` name suffix, so an author who wrote the name
+ * has said as much as one who wrote the path.
+ *
+ * SVG ONLY, because the symbolic directory is declared `Type=Scalable`: the
+ * raster form GTK's own `gtk-encode-symbolic-svg` produces
+ * (`<name>-symbolic.symbolic.png`) is installed at a SIZE instead. So a PNG keeps
+ * answering the size question, and one that cannot answer it stays refused rather
+ * than quietly becoming a scalable icon that does not scale.
+ */
+export declare function isSymbolicIcon(iconPath: string): boolean;
+/**
+ * The hicolor subdirectory for an icon: the `symbolic` CONTEXT, else `scalable`
+ * for an SVG, else the pixel size read from a `<n>x<n>` path component or a
+ * trailing number in the filename.
+ *
+ * Named for the theme DIRECTORY rather than a size from the moment the first of
+ * those answers stopped being one: `iconSizeDir` returning `symbolic` would be a
+ * name every caller has to read past.
  */
-export declare function iconSizeDir(iconPath: string): string;
+export declare function iconThemeDir(iconPath: string): string;
 /**
  * A native module inside the payload has to keep its executable bit.
  *