@gjsify/cli 0.44.0 → 0.46.0

package/lib/commands/ship.js

@@ -14,12 +14,14 @@
 // which is what a developer on one machine wants and what the e2e suite
 // compares the split against byte for byte.
 //
-// Scope today is Linux and `--app gjs`: no runtime is bundled, because GJS and
-// GTK come from the distribution and shipping ~100 MiB of them would be cargo
-// cult (ADR 0024 § 4). macOS and Windows layouts, and Flatpak as a target under
-// this command, are the later stages of the same ADR — and they are the reason
-// the split exists at all: a `.dmg` is a UDIF image over a real HFS+/APFS
-// volume and no Linux host in this tree can write one (§ A1).
+// THREE LAYOUTS AND NINE FORMATS as of #1354 M6, which is what the two-phase
+// split was built for. A Linux artifact bundles no runtime — GJS and GTK come
+// from the distribution and shipping ~100 MiB of them would be cargo cult (ADR
+// 0024 § 4) — while a `.app` and a Windows program directory CARRY theirs, since
+// neither OS ships one (`utils/ship/app-runtime.ts`). And the split earns itself
+// on the two rows that are host-bound: a `.dmg` is a UDIF image over a real
+// HFS+/APFS volume that no Linux host in this tree can write (§ A1), and a
+// signature is made where the identity lives (§ A14).
 import { mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { basename, dirname, join, relative, resolve } from 'node:path';
 import { Config } from '../config.js';
@@ -27,33 +29,56 @@ import { renderDesktopEntry, renderMetainfoApp, renderMetainfoCli, validateAppMe
 import { readPackageJson } from '../utils/pkg-json.js';
 import { describeExit, spawnToCompletion } from '../utils/spawn.js';
 import { buildDeb } from '../utils/ship/deb.js';
-import { deriveDepends, warnAboutGjsFloor } from '../utils/ship/depends.js';
+import { deriveDepends, warnAboutGjsFloor, warnAboutNodeFloor } from '../utils/ship/depends.js';
+import { isGtkRuntimeTarget, stageAppRuntime } from '../utils/ship/app-runtime.js';
 import { discoverPayload } from '../utils/ship/discover.js';
+import { buildDmgImage, dmgVolumeDir, dmgVolumeName } from '../utils/ship/dmg.js';
 import { buildFlatpakBundle } from '../utils/ship/flatpak.js';
-import { assertHostCanFinish, assertToolsInstalled, resolveFormats, DEFAULT_FORMAT_IDS, FORMAT_IDS, } from '../utils/ship/formats.js';
+import { localizeMetadata } from '../utils/ship/localize-metadata.js';
+import { assertHostCanFinish, assertToolsInstalled, canCarryTicket, configuredFormats, defaultFormatIds, formatIdsFor, resolveFormats, windowsProgramDirName, FORMAT_IDS, FORMATS, } from '../utils/ship/formats.js';
+import { assertLayoutSupportsArch, hostLayout, layoutForOs, place, placeStage, resolveLayout, LAYOUT_NAMES, } from '../utils/ship/layout.js';
+import { isNodeRuntimeTarget, resolveNodeRuntime } from '../utils/ship/node-runtime.js';
+import { isUnder, SHARE } from '../utils/ship/share-dirs.js';
+import { compileSchemasForStage } from '../utils/ship/schemas.js';
+import { buildMsi, MSI_PAYLOAD_DIR } from '../utils/ship/msi.js';
+import { buildZip, zipEntriesFromPayload } from '../utils/ship/zip.js';
 import { scanGiNamespaces } from '../utils/ship/gi-namespaces.js';
-import { assertPayloadMatchesArch, buildTimestamp, isArchIndependent, readPayloadFacts, } from '../utils/ship/payload.js';
+import { assertLauncherMatchesInterpreter, assertPayloadMatchesArch, buildTimestamp, isArchIndependent, linuxInstallDependent, readPayloadFacts, } from '../utils/ship/payload.js';
 import { assertOverlayIsLicensed, planOverlay, planStage } from '../utils/ship/plan.js';
+import { assertHostCanSign, notarizeArtifact, stapleArtifact, resolveNotaryPlan, resolveSignPlan, signPayload, } from '../utils/ship/signing.js';
 import { renderLauncher } from '../utils/ship/launcher.js';
 import { buildRpm } from '../utils/ship/rpm.js';
-import { declaredBundlePath, resolveShipSettings } from '../utils/ship/settings.js';
+import { declaredBundlePath, resolveShipApp, resolveShipSettings, } from '../utils/ship/settings.js';
 import { assertExpectedTarget, assertFormatsStaged, formatTarget, overlayFiles, readStageManifest, resolveStageMtime, warnOnToolSkew, writeStageManifest, STAGE_MANIFEST_FILE, } from '../utils/ship/stage-manifest.js';
-import { readStage, writeStage } from '../utils/ship/stage-writer.js';
+import { directorySize, readStage, writePayload, writeStage } from '../utils/ship/stage-writer.js';
 const LOG = '[gjsify ship]';
 export const shipCommand = {
-    command: 'ship',
+    command: 'ship [os]',
     description: `Build installable artifacts (${FORMAT_IDS.join(', ')}) from the current project.`,
-    // `DEFAULT_FORMAT_IDS` in the flag text, `FORMAT_IDS` in the description:
+    // `defaultFormatIds` in the flag text, `FORMAT_IDS` in the description:
     // one of them answers "what can this build", the other "what will it build
     // if I say nothing", and they stopped being the same list when a host-bound
-    // format arrived.
+    // format arrived — and then stopped again when a second layout did.
     builder: (yargs) => yargs
+        .positional('os', {
+        type: 'string',
+        // Deliberately no yargs `choices`: `resolveLayout` accepts
+        // `win32` beside `windows` — the spelling `--expect-target`
+        // prints — and says so when it refuses, which a `choices` list
+        // cannot.
+        description: `Operating system whose LAYOUT to assemble (${LAYOUT_NAMES.join('|')}, ADR 0024 § A2). ` +
+            'Default: this host. Assembly is not host-bound, so any of them can be staged anywhere.',
+    })
         .option('target', {
         type: 'string',
         array: true,
-        description: `Formats to build, comma-separated or repeated. Default: ${DEFAULT_FORMAT_IDS.join(',')}. ` +
-            `Also available, and opt-in because it needs tooling this CLI does not carry: ` +
-            `${FORMAT_IDS.filter((id) => !DEFAULT_FORMAT_IDS.includes(id)).join(', ')}.`,
+        description: 'Formats to build, comma-separated or repeated. Default: every format wrapping the ' +
+            `target OS's layout that needs no extra tooling — on linux, ` +
+            `${defaultFormatIds('linux').join(',')}. Also available for linux, and opt-in because it ` +
+            'needs tooling this CLI does not carry: ' +
+            `${formatIdsFor('linux')
+                .filter((id) => !defaultFormatIds('linux').includes(id))
+                .join(', ')}.`,
     })
         .option('out', {
         type: 'string',
@@ -84,6 +109,40 @@ export const shipCommand = {
         .option('arch', {
         type: 'string',
         description: 'Target architecture in `process.arch` spelling. Default: this host.',
+    })
+        .option('sign', {
+        type: 'string',
+        // `requiresArg`, and it is not tidiness. `-` is the RESERVED
+        // ad-hoc identity — the one value of this flag that needs no
+        // developer identity and the only one this project's own CI can
+        // use — and yargs-parser treats a lone `-` as a positional by
+        // convention (stdin), so `--sign -` parsed as `sign: ''` plus a
+        // stray `-` and the strict-mode refusal was "Unknown argument: -".
+        // Measured on the first cut of this flag. The cost is that a bare
+        // `--sign` with no value is now "Not enough arguments following"
+        // rather than the empty-identity skip; that skip stays reachable
+        // through `--sign ''` and through the config key, which is where
+        // an unset CI variable actually lands.
+        requiresArg: true,
+        // An IDENTITY, never a certificate (ADR 0024 § A12): `codesign`
+        // and `signtool` are both handed a NAME and look the private key
+        // up themselves, so this command is never given a secret and has
+        // nothing to redact. Deliberately no `default:` — a yargs default
+        // is indistinguishable from a value the user typed and would
+        // clobber `gjsify.ship.sign.<os>.identity`.
+        description: 'Sign the payload with this identity, e.g. a Developer ID name or SHA-1 fingerprint. ' +
+            '`-` signs ad-hoc and needs no developer identity. Default: ' +
+            '`gjsify.ship.sign.<darwin|win32>.identity`; absent means unsigned, which is a ' +
+            'legitimate output.',
+    })
+        .option('notarize', {
+        type: 'string',
+        // Same reason as `--sign` one option up, applied for consistency
+        // rather than for a measured case: a credential that begins with
+        // a dash is not a shape anybody should have to think about.
+        requiresArg: true,
+        description: 'Submit the signed artifact to Apple with this `notarytool` keychain profile. Needs ' +
+            '--sign; darwin only.',
     })
         .option('verbose', {
         type: 'boolean',
@@ -107,6 +166,10 @@ export const shipCommand = {
  */
 async function assemble(args) {
     const projectDir = process.cwd();
+    // FIRST, because everything below is decided per layout: which formats
+    // exist, which build target the launcher can run, and where every staged
+    // file lands. A bad positional must not cost a build.
+    const layout = args.os === undefined ? hostLayout() : resolveLayout(args.os);
     const config = new Config();
     // No `.catch(() => ({}))` here, unlike the flatpak commands: a config
     // file that fails to load would silently become "no config", and the
@@ -115,11 +178,98 @@ async function assemble(args) {
     const configData = await config.forCommand(projectDir);
     const ship = configData.ship ?? {};
     const flatpak = configData.flatpak ?? {};
-    assertShippableTarget(configData.app);
+    // THE ONE RESOLUTION, and it runs HERE because the format list is decided
+    // before anything is built while `resolveShipSettings` runs after. Its result
+    // is threaded into the settings rather than re-derived there: two defaulting
+    // rules for one question is how the format list and the emitted `Depends:`
+    // came to answer for different targets (#1486). Why the runtime is per target
+    // at all, and why an absent override means the project field: `resolveShipApp`.
+    const resolvedApp = resolveShipApp({ project: configData.app, perTarget: ship.app, layoutOs: layout.os });
+    const interpreter = resolvedApp.app;
+    // SAID, not swallowed, like every other narrowing in this function. An
+    // override that changed the launcher, the dependency and the format list
+    // without a line of output is one nobody can tell from the project default.
+    if (resolvedApp.overridden) {
+        console.log(`${LOG} runtime for ${layout.name}: ${interpreter} — \`${resolvedApp.key}\` overrides ` +
+            `\`gjsify.app${configData.app === undefined ? '' : `: "${configData.app}"`}\`.`);
+    }
     const pkg = (readPackageJson(join(projectDir, 'package.json')) ?? {});
     // Resolved before anything is built or written: a typo'd `--target`
     // should not cost a build and leave a half-written `ship/stage/`.
-    const formats = resolveFormats(args.target ?? ship.targets ?? DEFAULT_FORMAT_IDS);
+    //
+    // THREE sources, three meanings, and collapsing them was a real defect. A
+    // `--target` is a claim about THIS run, so a format belonging to another
+    // layout is refused by name. `gjsify.ship.targets` is a project-level
+    // DEFAULT written once, so it is filtered to this layout instead — passing it
+    // through the strict path made `gjsify ship darwin --stage` exit 1 inside
+    // this very repository, whose `packages/infra/cli/package.json` declares
+    // `targets: ["deb", "rpm"]`, with a message telling the author to run the
+    // command they had just run. And the derived default can legitimately be
+    // EMPTY, which `resolveFormats` refuses — rightly, for a list a caller typed.
+    let formats;
+    /** Formats that wrap this layout and cannot run this project — see the derived branch. */
+    let unusable = [];
+    if (args.target !== undefined) {
+        formats = resolveFormats(args.target, layout);
+    }
+    else if (ship.targets !== undefined) {
+        const configured = configuredFormats(ship.targets, layout);
+        formats = configured.formats;
+        // SAID, not swallowed. The `--target` path refuses a foreign format by
+        // name; this one used to shorten the list in silence, so a project whose
+        // configured formats all wrap another layout got a stage and no account
+        // of where its targets went.
+        if (configured.dropped.length > 0) {
+            console.log(`${LOG} \`gjsify.ship.targets\` names ${configured.dropped.join(', ')}, which wrap another ` +
+                `layout — not built for ${layout.name}. Pass --target to ask for one explicitly.`);
+        }
+    }
+    else {
+        // FILTERED BY THE INTERPRETER, and the third of the same shape as the two
+        // branches above: a derived default is not a claim anybody made, so a
+        // format this project cannot use is dropped rather than refused. It has to
+        // be — every format wrapping the darwin layout is `interpreters: ['node']`
+        // (there is no relocatable GJS to put in a bundle), so without this
+        // `gjsify ship darwin --stage` began exiting 1 on a `--app gjs` project,
+        // which is every project this command has today. Measured on the first cut
+        // of these rows: the whole audience of M1 lost the ability to assemble the
+        // layout M1 added, over a format none of them had asked for.
+        const wraps = defaultFormatIds(layout.os).map((id) => FORMATS[id]);
+        formats = wraps.filter((format) => format.interpreters.includes(interpreter));
+        unusable = wraps.filter((format) => !format.interpreters.includes(interpreter));
+        // SAID, like the layout filter one branch up. A stage whose `formats` is
+        // empty for this reason looks identical to one whose layout nothing wraps,
+        // and the two need different next steps.
+        if (unusable.length > 0) {
+            console.log(`${LOG} ${unusable.map((format) => format.id).join(', ')} wrap the ${layout.name} layout but ` +
+                `cannot run \`${interpreter}\`, which \`${resolvedApp.key}\` resolves to — ` +
+                `${unusable[0]?.interpreterGap ?? ''}. Set \`gjsify.ship.app.${layout.os}\` to ` +
+                `"${unusable[0]?.interpreters.join('" / "')}" to ship this OS on that runtime; it leaves every ` +
+                'other target on `gjsify.app`. Assembling the layout only; pass --target to be told the same ' +
+                'thing as an error.');
+        }
+    }
+    if (!args.stage)
+        assertPackable(formats, layout, args.os === undefined ? 'host' : 'positional', unusable);
+    // BEFORE the build, beside `assertCanPack` and for the same reason: a
+    // `--sign` this host cannot honour — wrong OS, no tool, a layout that has no
+    // signature at all — is knowable up front, and discovering it after the
+    // project's own build has run costs the whole build for a refusal nothing
+    // learned from building.
+    //
+    // `ship.sign` is read HERE and nowhere on the `--from-stage` path, and that
+    // asymmetry is § A14's amendment to § A1: a format declares where it can be
+    // packed, the RUN declares what it can sign with. The finishing host has no
+    // project to read a default out of, so there it is the flag or nothing.
+    const sign = resolveSignPlan({ flag: args.sign, config: ship.sign, layoutOs: layout.os });
+    const notarize = resolveNotaryPlan({ flag: args.notarize, layoutOs: layout.os, sign });
+    if (args.stage)
+        assertNothingToSignYet(args);
+    if (!args.stage) {
+        announceSigning(sign, notarize);
+        if (sign.kind === 'sign')
+            assertHostCanSign(sign.signer);
+    }
     // BEFORE the build, not before the pack. `gjsify ship` runs the project's
     // own `build` script first, so discovering a missing `flatpak-builder`
     // afterwards costs the whole build for a refusal that was knowable up
@@ -142,11 +292,22 @@ async function assemble(args) {
         pkg,
         ship,
         flatpak,
-        cli: { outDir: args.out, arch: args.arch },
+        cli: { outDir: args.out, arch: args.arch, layoutOs: layout.os },
         discovered,
+        // The RESOLVED runtime, never `configData.app`. Everything downstream —
+        // the launcher, `deriveDepends`, the carried runtime, the stage manifest —
+        // reads `settings.app`, so this is the one hand-off that decides whether
+        // those generators speak about this target or about the project.
+        app: interpreter,
     });
     for (const warning of warnings)
         console.warn(`${LOG} ${warning}`);
+    // BEFORE anything is staged, and NOT under `assertCanPack` (which `--stage`
+    // deliberately skips): a stage whose launcher execs an interpreter the target
+    // runtime does not have is already wrong, and it is the stage that crosses to
+    // the packing host.
+    for (const format of formats)
+        assertFormatCanRunInterpreter(format, settings.app);
     const mtime = buildTimestamp(settings.bundlePath);
     const metadataInputs = {
         appId: settings.appId,
@@ -171,21 +332,136 @@ async function assemble(args) {
         console.log(`${LOG} licence text from ${relative(projectDir, settings.licenseFile)} ` +
             '(this package carries none of its own)');
     }
-    const stageInputs = {
-        bundleFiles: discovered.bundleFiles,
-        launcher: renderLauncher(settings, basename(settings.bundlePath)),
+    // Rendered in English, then TRANSLATED with the catalogues this package
+    // already stages. Without this step the two halves never met: `share/locale/`
+    // shipped every `.mo` while `Name=` and `<name>` stayed English, so a fully
+    // translated app showed an English entry in the app menu and in Software.
+    // Both files stay valid either way, which is why nobody reported it.
+    const translated = localizeMetadata({
         metainfo: settings.kind === 'app' ? renderMetainfoApp(metadataInputs) : renderMetainfoCli(metadataInputs),
         desktopEntry: settings.kind === 'app' ? renderDesktopEntry(metadataInputs) : undefined,
+    }, settings.localeFiles);
+    // BEFORE the launcher is rendered, because the launcher's exec line and its two
+    // locators are functions of what the stage carries (#1354 M2b). Nothing is
+    // resolved for a layout whose interpreter is a package dependency: on Linux the
+    // `.deb`/`.rpm` `Depends:` is the promise that `node` or `gjs` is on `PATH`, and
+    // carrying a second copy inside the payload would be a private interpreter no
+    // distribution update ever patches.
+    const runtime = resolveCarriedRuntime(layout, settings, projectDir);
+    const stageInputs = {
+        bundleFiles: discovered.bundleFiles,
+        launcher: renderLauncher(settings, basename(settings.bundlePath), layout, runtime.launcher),
+        metainfo: translated.metainfo,
+        desktopEntry: translated.desktopEntry,
         licenseText: settings.licenseFile === undefined ? undefined : readFileSync(settings.licenseFile, 'utf-8'),
     };
     const outRoot = resolve(projectDir, settings.outDir);
     const stageDir = join(outRoot, 'stage');
-    const staged = planStage(settings, stageInputs);
+    // Planned once, in the prefix-relative shape, then PLACED. Keeping the two
+    // steps apart is what makes "one payload, three layouts" a checkable claim
+    // rather than a slogan: the plan is the payload, `placeStage` is the layout
+    // map, and `tests/e2e/ship-layout` asserts the three file sets agree modulo
+    // exactly that map.
+    //
+    // The ONE prefix-relative addition a layout makes, and it is not a second
+    // plan: a layout with no install step has to carry `gschemas.compiled`,
+    // because every launcher points XDG_DATA_DIRS at the staged `share/` and
+    // GSettings ABORTS on a schema directory that holds only sources. On Linux the
+    // `.deb`/`.rpm` postinst compiles the SYSTEM directory at install time
+    // (`utils/ship/scripts.ts`), where our schemas merge with every other
+    // package's — shipping a prebuilt cache there would be a file the install step
+    // overwrites. So the compile is conditional on the layout and nothing else.
+    const planned = [
+        ...planStage(settings, stageInputs),
+        ...(layout.os === 'linux'
+            ? []
+            : await compileSchemasForStage({
+                schemaFiles: settings.schemaFiles,
+                workDir: join(outRoot, 'schemas'),
+            })),
+    ];
+    const staged = placeStage(layout, settings, planned, runtime.files);
     writeStage(stageDir, staged);
-    console.log(`${LOG} staged ${staged.length} file(s) in ${relative(projectDir, stageDir)}/`);
+    console.log(`${LOG} staged ${staged.length} file(s) for ${layout.name} in ${relative(projectDir, stageDir)}/`);
     if (args.verbose)
         for (const file of staged)
             console.log(`${LOG}   ${file.path}`);
+    // Read the tree back and hold the payload against the label, HERE and not
+    // only in `packOne`. That check has always existed, one phase to the right,
+    // where it guards the artifact — and this is the first milestone in which the
+    // STAGE is the deliverable: darwin and windows have no packer, so a stage
+    // assembled `--arch x64` from an arm64 payload reached `--expect-target
+    // darwin-x64` with nothing having compared the two. Measured before this
+    // line: exit 0, `target: {os: "darwin", arch: "x64"}`, and a Mach-O
+    // `cputype` of arm64 inside it.
+    //
+    // It costs a second read of the payload on the one-shot Linux path, where
+    // `packOne` reads it again. That is the price of checking the tree that is
+    // shipped rather than the bytes that happen to be in memory, and it is the
+    // same reason `readStage` exists at all.
+    assertPayloadMatchesArch(readStage([stageDir], staged), settings.arch);
+    // What the map carried into a layout that has no install step for it.
+    //
+    // NOT a warning about this command's output being wrong — the files are the
+    // payload's and belong to it. It is the half the layout equality cannot see:
+    // three of these are only correct on Linux because a `.deb`/`.rpm` scriptlet
+    // compiles or reindexes them at install, and two are freedesktop metadata
+    // neither OS reads. Printed so the author of a `.app` knows before the
+    // container exists to decide what they become (ADR 0024 stages 4 and 5).
+    if (layout.os !== 'linux') {
+        const carried = linuxInstallDependent(planned);
+        if (carried.length > 0) {
+            console.warn(`${LOG} the ${layout.name} layout carries ${carried.length} file(s) whose Linux correctness ` +
+                'comes from a package install step it has no equivalent for:');
+            // The marker is the whole point of `ShareVerdict`. Every launcher
+            // exports XDG_DATA_DIRS at the staged `share/`, so an uncompiled
+            // schema directory is not a missing feature — `g_settings_new()`
+            // ABORTS on it. Printing that at the same weight as "neither OS reads
+            // one" is what buried it in a list of five.
+            const marker = { aborts: 'ABORTS: ', unknown: 'UNCLASSIFIED: ', inert: '' };
+            for (const { path, verdict, why } of carried) {
+                console.warn(`${LOG}   ${marker[verdict] ?? ''}${path} — ${why}`);
+            }
+        }
+        // WHAT THE BUNDLE CARRIES, and what it still does not. Printed where the
+        // layout's other honesty lives, and the `runtimeGap` is now CONDITIONAL:
+        // that string says "the staged launcher execs an interpreter off `PATH`,
+        // which a downloaded `.app` cannot assume", and printing it over a stage
+        // that carries its own interpreter would be the command telling the author
+        // something untrue about the tree it had just written.
+        for (const line of runtime.found)
+            console.log(`${LOG} carries its own ${line}`);
+        for (const line of runtime.missing)
+            console.warn(`${LOG} ${line}`);
+        if (runtime.launcher.interpreter === undefined && layout.runtimeGap !== undefined) {
+            console.warn(`${LOG} ${layout.runtimeGap}`);
+        }
+        // The same shape one axis over (ADR 0038). `share/fonts` is NOT in the list
+        // above — it needs no install step on any layout, so `linuxInstallDependent`
+        // classifies it as portable — but "the directory is reached" and "this OS's
+        // Pango reads that directory at all" are different questions, and only the
+        // first is settled by the payload. CONDITIONAL on the payload actually
+        // carrying a face, like `runtimeGap` is on the missing interpreter: telling a
+        // project that ships no font which fontconfig its Mac would consult is noise,
+        // and noise is what trains people to stop reading these lines.
+        if (layout.fontGap !== undefined && planned.some((file) => isUnder(file.path, SHARE.fonts))) {
+            console.warn(`${LOG} ${layout.fontGap}`);
+        }
+        // THE OTHER AXIS, warned about HERE and refused in `packOne`, and the split
+        // is the same one `runtimeGap` and `assertFormatCanRunInterpreter` already
+        // draw. A stage is a build intermediate, and assembling one for an
+        // architecture no runtime exists for is what `tests/e2e/ship-layout` does on
+        // purpose: it proves the layout MAP over one payload, and that payload's
+        // native file has an architecture. What must not leave is an ARTIFACT — so
+        // the refusal sits where an artifact is about to be written and the author
+        // is told here, at the `--arch` that caused it, rather than only on the far
+        // side of a handoff.
+        if (layout.arches !== null && !layout.arches.only.includes(settings.arch)) {
+            console.warn(`${LOG} this stage is labelled ${settings.arch} and the ${layout.name} layout has no runtime ` +
+                `for it — ${layout.arches.why}. Nothing can pack this stage; ` +
+                `\`--arch ${layout.arches.only.join('|')}\` is what produces an artifact.`);
+        }
+    }
     // Scanned from the BUILD TREE's bundle, which is why it has to be recorded:
     // `gi://` specifiers are what the emitted `Depends:` is derived from
     // (ADR 0024 § 6), and the packing host has the staged copy but no way to
@@ -193,17 +469,35 @@ async function assemble(args) {
     const namespaces = scanGiNamespaces(readFileSync(settings.bundlePath, 'utf-8'));
     if (args.verbose)
         console.log(`${LOG} gi namespaces: ${namespaces.join(', ') || '(none)'}`);
+    // PLACED, like the payload, and through the same map. `planOverlay` answers a
+    // question about the FORMAT (`share/doc/<pkg>/copyright` for Debian policy,
+    // `share/licenses/<pkg>/LICENSE` for rpm) in the prefix-relative shape every
+    // plan uses; `packOne` then merges the overlay into the payload it reads back,
+    // so the two have to be in one coordinate system. On Linux `place()` is the
+    // identity for `share/…` and nothing moves. On darwin the licence would
+    // otherwise land at the STAGE root, outside `<App>.app` — beside the bundle
+    // rather than in it, where `codesign` later refuses it and no user ever finds
+    // it. `dirs.other`'s doc already names that hazard for `extraFiles`; the
+    // overlay reaches it by the same route.
     const overlay = new Map();
-    for (const format of formats)
-        overlay.set(format.id, planOverlay(settings, format, stageInputs));
+    for (const format of formats) {
+        overlay.set(format.id, planOverlay(settings, format, stageInputs).map((file) => ({
+            ...file,
+            path: place(layout, settings, file.path),
+        })));
+    }
     // The dependency derivation runs HERE as well, and its result is thrown
     // away. It is the only check in the pipeline that can refuse a project
     // (`gi://Nautilus` with no known package, ADR 0024 § 6), and this is the
     // host that has the `package.json` the refusal tells you to edit — letting
     // it fire two jobs later, on a machine with no project, would name a fix
-    // nobody there can apply. Facts come from the PLAN, which has the same
-    // paths the payload will have.
-    const facts = readPayloadFacts(staged);
+    // nobody there can apply. Facts come from the PREFIX-RELATIVE plan, not from
+    // the placed tree: `readPayloadFacts` asks `share/icons/hicolor/…` questions,
+    // which is the shape the plan is written in and the shape the only formats
+    // that read the answer (`deb`, `rpm`) install into. Reading the placed tree
+    // would give the same answer on Linux and quietly give `false` everywhere
+    // else the day a format wraps another layout.
+    const facts = readPayloadFacts(planned);
     for (const format of formats) {
         // `format.depends`, not `format.id`: a Flatpak has no package
         // dependency list at all, and asking for one would either invent a
@@ -217,14 +511,21 @@ async function assemble(args) {
             namespaces,
             hasIcons: facts.hasIcons,
             hasSchemas: facts.hasSchemas,
+            interpreter: settings.app,
             extra: settings.extraDepends[format.depends],
             typelibPackages: settings.typelibPackages,
             bundledTypelibs: facts.bundledTypelibs,
             minGjsVersion: settings.minGjsVersion,
+            minNodeVersion: settings.minNodeVersion,
         });
-        for (const warning of warnAboutGjsFloor(format.depends, settings.minGjsVersion)) {
+        // One warning per package, for the interpreter it actually declares. A
+        // floor warning about a dependency this package does not emit is noise,
+        // and a noisy warning is the one nobody reads when it matters.
+        const floorWarnings = settings.app === 'node'
+            ? warnAboutNodeFloor(format.depends, settings.minNodeVersion)
+            : warnAboutGjsFloor(format.depends, settings.minGjsVersion);
+        for (const warning of floorWarnings)
             console.warn(`${LOG} ${warning}`);
-        }
     }
     // Written unconditionally, not only under `--stage`: a `ship/stage/` that
     // is sometimes packable elsewhere and sometimes not is a worse contract
@@ -232,7 +533,27 @@ async function assemble(args) {
     // one-process artifact with the two-phase one.
     const manifest = writeStageManifest({ stageDir, settings, formats, mtime, namespaces, staged, overlay });
     if (args.stage) {
-        console.log(`${LOG} stage manifest: ${formatTarget(manifest.target)}, formats ${manifest.formats.join(', ')}`);
+        // `(none)` spelled out, because an empty list printed as nothing after
+        // "formats " reads as a truncated line rather than as a fact. WHICH fact
+        // it is depends on the layout: all three now have formats — three rows each
+        // for darwin and windows — so an empty list means this project cannot use
+        // them, and printing "none yet" would tell a `--app gjs` author to wait for
+        // a milestone that has already landed.
+        // Three reasons a list can be empty, and each names a different next step:
+        // this project cannot use the formats that wrap the layout; the layout has
+        // none; or the configured `targets` all wrap another one, which the branch
+        // above has already SAID in its own words rather than repeating here.
+        const none = unusable.length > 0
+            ? // The key that fixes it, which used to be `gjsify.app` and is now
+                // this target's own: naming the project field here is how a macOS
+                // stage came to move the Linux `Depends:` (#1486).
+                `(none — ${unusable.map((format) => format.id).join(' and ')} need ` +
+                    `\`gjsify.ship.app.${layout.os}: "node"\`)`
+            : formatIdsFor(layout.os).length === 0
+                ? `(none — no format wraps the ${layout.name} layout)`
+                : '(none asked for)';
+        const wraps = manifest.formats.join(', ') || none;
+        console.log(`${LOG} stage manifest: ${formatTarget(manifest.target)}, formats ${wraps}`);
         return;
     }
     const artifacts = [];
@@ -247,11 +568,83 @@ async function assemble(args) {
             outRoot,
             namespaces,
             mtime,
+            sign,
+            notarize,
             verbose: args.verbose,
         }));
     }
     printArtifacts(projectDir, artifacts);
 }
+/**
+ * Refuse `--sign` / `--notarize` on the phase that produces no artifact.
+ *
+ * `--stage` writes a build intermediate, and a signature over one would be
+ * invalidated by the very next thing that happens to it — the packer reads the
+ * tree back and the container is built around it (ADR 0024 § A17 fixes that
+ * order for the opposite reason: `readStage` compares SIZES, and a re-signed
+ * file has a new one). Silently accepting the flag would produce a stage nobody
+ * could tell from an unsigned one.
+ */
+function assertNothingToSignYet(args) {
+    const given = args.sign !== undefined ? '--sign' : args.notarize !== undefined ? '--notarize' : undefined;
+    if (given === undefined)
+        return;
+    throw new Error(`gjsify ship: ${given} belongs to the finish phase, and --stage produces no artifact to sign — it ` +
+        'writes the tree a packing host reads back. Assemble here, then run ' +
+        '`gjsify ship --from-stage <dir> --sign <identity>` on the host that holds the identity ' +
+        '(ADR 0024 § A2, § A14).');
+}
+/**
+ * Say what this run will do about signatures, once, before any of it happens.
+ *
+ * PRINTED rather than silent, and to stderr, because ADR 0024 § A13 makes the
+ * skip the visible half of "unsigned is the default path": a pipeline that
+ * captures the artifact list still shows the line, and an unsigned artifact
+ * nobody was told about is how a signature gets claimed that was never made.
+ */
+function announceSigning(sign, notarize) {
+    if (sign.kind === 'skip')
+        console.warn(`${LOG} ${sign.message}`);
+    if (notarize.kind === 'skip' && sign.kind === 'sign')
+        console.warn(`${LOG} ${notarize.message}`);
+}
+/**
+ * The runtime this artifact carries INSIDE itself, or an empty answer.
+ *
+ * THE GATE IS THE LAYOUT AND THE INTERPRETER, both. A Linux package declares
+ * `Depends: nodejs` and takes the distribution's — carrying a second copy would be
+ * a private interpreter no security update ever reaches. And a `--app gjs` payload
+ * gets nothing even on macOS: there is no relocatable GJS to put in a bundle
+ * (`build-gtk-runtime-darwin.mjs`: "GJS ships no relocation"), which is what
+ * `macos-app`'s `interpreters: ['node']` already records, so staging a NODE
+ * interpreter in front of a GJS bundle would be an interpreter that cannot read
+ * its own payload.
+ *
+ * `${layout.os}-${settings.arch}` — the target the PAYLOAD was built for, never
+ * the host's. Assembling a `darwin-arm64` bundle on a Linux x64 workstation is the
+ * supported path (ADR 0024 § A1) and is what this project's own CI does; a
+ * host-derived target would resolve the wrong closure, and the mismatch would only
+ * surface as a dlopen failure on the user's machine. `assertPayloadMatchesArch`
+ * reads the staged tree back afterwards and refuses a closure whose Mach-O
+ * `cputype` disagrees with the label — a check the carried runtime is the first
+ * thing to make non-vacuous on this layout, since a JavaScript bundle has no
+ * cputype to disagree with.
+ */
+function resolveCarriedRuntime(layout, settings, projectDir) {
+    const empty = { files: [], launcher: {}, found: [], missing: [] };
+    if (layout.os === 'linux' || settings.app !== 'node')
+        return empty;
+    const target = `${layout.os}-${settings.arch}`;
+    if (!isGtkRuntimeTarget(target))
+        return empty;
+    return stageAppRuntime({
+        layout,
+        identity: settings,
+        target,
+        cwd: projectDir,
+        interpreter: isNodeRuntimeTarget(target) ? resolveNodeRuntime(target, { cwd: projectDir }) : null,
+    });
+}
 /**
  * Phase two: pack a stage that was assembled somewhere else.
  *
@@ -276,14 +669,54 @@ async function finishFromStage(args, fromStage) {
             '`gjsify ship --stage`, and use `--expect-target <os>-<arch>` here to assert which leg you are ' +
             'packing.');
     }
+    if (args.os !== undefined) {
+        // Same reason as `--arch`, one axis over: the LAYOUT is what phase one
+        // wrote — the launcher's language, every staged path, the recorded
+        // target. Naming it again here could only agree with the stage or
+        // contradict it, and there is no useful behaviour behind either.
+        throw new Error(`gjsify ship: the layout is decided when the stage is assembled, so "${args.os}" has nothing to ` +
+            "change here — the staged tree already IS one OS's layout. Use `--expect-target <os>-<arch>` " +
+            'to assert which one you are packing.');
+    }
     const cwd = process.cwd();
     const stageDir = resolve(cwd, fromStage);
     const manifest = readStageManifest(stageDir);
     assertExpectedTarget(manifest, args['expect-target']);
-    const formats = resolveFormats(args.target ?? manifest.formats);
+    // `layoutForOs`, not `resolveLayout`: the manifest is a wire format with one
+    // legal spelling per OS, and `readStageManifest` has already refused any other.
+    const layout = layoutForOs(manifest.target.os);
+    // Before `resolveFormats`, which would otherwise answer a `--target` the
+    // caller never typed: a stage for a layout no format wraps carries
+    // `formats: []`, and the empty-list refusal there names `--target` and the
+    // three Linux formats — three sentences about the wrong thing.
+    // THE STAGE'S list, not the layout's. The two agreed while darwin and windows
+    // had no formats at all, and stopped the moment two rows wrapped darwin: a
+    // `--app gjs` project's darwin stage records `formats: []` against a layout
+    // that now has two. Asking the layout would let that stage past this refusal
+    // and into `resolveFormats([])`, whose message is about a `--target` the caller
+    // never typed.
+    if (args.target === undefined) {
+        assertPackable(manifest.formats.map((id) => FORMATS[id]), layout, 'stage', 
+        // What WOULD have wrapped it, so this can tell a `--app gjs` darwin
+        // stage apart from a windows one, which nothing wraps at all.
+        defaultFormatIds(layout.os)
+            .map((id) => FORMATS[id])
+            .filter((format) => !format.interpreters.includes(manifest.settings.app)));
+    }
+    const formats = resolveFormats(args.target ?? manifest.formats, layout);
     assertFormatsStaged(manifest, formats);
     for (const format of formats)
         assertCanPack(format);
+    // NO `config` — this phase has no project, by construction (`tests/e2e/
+    // ship-from-stage` deletes the project tree between the two phases). So the
+    // identity is the flag or nothing, which is also the right answer: § A14
+    // amends § A1 to *a format declares where it can be packed; the RUN declares
+    // what it can sign with*, and this run is the one holding the keychain.
+    const sign = resolveSignPlan({ flag: args.sign, layoutOs: layout.os });
+    const notarize = resolveNotaryPlan({ flag: args.notarize, layoutOs: layout.os, sign });
+    announceSigning(sign, notarize);
+    if (sign.kind === 'sign')
+        assertHostCanSign(sign.signer);
     for (const warning of warnOnToolSkew(manifest))
         console.warn(`${LOG} ${warning}`);
     const { mtime, warnings } = resolveStageMtime(manifest);
@@ -303,10 +736,21 @@ async function finishFromStage(args, fromStage) {
     const outRoot = args.out === undefined ? dirname(stageDir) : resolve(cwd, args.out);
     const artifacts = [];
     for (const format of formats) {
+        // Re-asserted here and not only in phase one. `--from-stage` can be
+        // pointed at any stage with any `--target`, so a stage assembled for
+        // deb+rpm can be packed as a Flatpak on the finishing host — the phase
+        // that HAS no project and cannot re-read `gjsify.app` from it. The stage
+        // manifest carries the answer precisely so this stays checkable.
+        assertFormatCanRunInterpreter(format, manifest.settings.app);
         if (format.depends !== null) {
-            for (const warning of warnAboutGjsFloor(format.depends, manifest.settings.minGjsVersion)) {
+            // From the stage manifest's settings, which is all this phase has: it
+            // may be running on a machine that has never seen the project
+            // (ADR 0024 § A2).
+            const floorWarnings = manifest.settings.app === 'node'
+                ? warnAboutNodeFloor(format.depends, manifest.settings.minNodeVersion)
+                : warnAboutGjsFloor(format.depends, manifest.settings.minGjsVersion);
+            for (const warning of floorWarnings)
                 console.warn(`${LOG} ${warning}`);
-            }
         }
         artifacts.push(await packOne({
             format,
@@ -318,6 +762,8 @@ async function finishFromStage(args, fromStage) {
             outRoot,
             namespaces: manifest.namespaces,
             mtime,
+            sign,
+            notarize,
             verbose: args.verbose,
         }));
     }
@@ -328,21 +774,31 @@ async function packOne(input) {
     assertOverlayIsLicensed(format.id, settings.binaryName, input.overlay);
     const overlayDir = join(outRoot, 'overlay', format.id);
     writeStage(overlayDir, input.overlay);
-    const payload = readStage([stageDir, overlayDir], [...input.staged, ...input.overlay]);
+    // THE PRE-SIGN TREE, and the name says which one it is (ADR 0024 § A17).
+    // `readStage` holds each file's SIZE against the stage manifest, and a size is
+    // no more re-sign-proof than a digest would be — measured on this tree:
+    // append one byte to a staged file and it refuses with "… is 6 bytes in the
+    // stage and 5 in its manifest". So the validation runs over what phase one
+    // wrote, and the signer below takes its OUTPUT: the signed bytes are computed
+    // from the validated ones and therefore cannot exist before them, which is
+    // what makes the order structural rather than a comment somebody may reorder.
+    const assembled = readStage([stageDir, overlayDir], [...input.staged, ...input.overlay]);
     // What the package installs, read off what it installs. The three questions
     // this answers used to be answered from the project's file lists, which are
     // absolute paths on the build host and therefore unavailable here.
-    const facts = readPayloadFacts(payload);
+    const facts = readPayloadFacts(assembled);
     const depends = format.depends === null
         ? []
         : deriveDepends(format.depends, {
             namespaces: input.namespaces,
             hasIcons: facts.hasIcons,
             hasSchemas: facts.hasSchemas,
+            interpreter: settings.app,
             extra: settings.extraDepends[format.depends],
             typelibPackages: settings.typelibPackages,
             bundledTypelibs: facts.bundledTypelibs,
             minGjsVersion: settings.minGjsVersion,
+            minNodeVersion: settings.minNodeVersion,
         });
     // `--arch` is a CLAIM about the payload and nothing else compared it to one:
     // an x86-64 `.so` staged with `--arch arm64` packed at exit 0 and `rpm -qp
@@ -357,7 +813,77 @@ async function packOne(input) {
     // asserting afterwards would compare against a label that no longer names an
     // architecture, and the mismatch that matters is exactly the one on a payload
     // that IS architecture-specific.
-    assertPayloadMatchesArch(payload, input.arch);
+    assertPayloadMatchesArch(assembled, input.arch);
+    // The second half of the same idea, on the other label this artifact carries:
+    // something declares which interpreter runs the app, and until now nothing
+    // compared it to the launcher that will. They CAN disagree — a stage assembled
+    // by one gjsify and packed by another — and an artifact that promises one
+    // interpreter and runs another installs cleanly and dies at first launch.
+    //
+    // EVERY FORMAT, not only the ones with a `Depends:`. The guard used to run
+    // behind `format.depends !== null`, which was the right condition while the
+    // only declaration was a package list. The macOS rows have no dependency list
+    // and a HARDER promise instead: `interpreters: ['node']`, because there is no
+    // relocatable GJS to put in a bundle. So the launcher has to be read for them
+    // too. Widening this costs the Flatpak path nothing — its row is
+    // `interpreters: ['gjs']` and `assertFormatCanRunInterpreter` has already
+    // refused anything else — and the check is asymmetric by construction, so a
+    // launcher it cannot resolve stays silent rather than failing a working
+    // artifact.
+    const layout = layoutForOs(format.layoutOs);
+    assertLauncherMatchesInterpreter(assembled, layout, settings, settings.app);
+    // The label against the LAYOUT, which is the question one level up from
+    // `assertPayloadMatchesArch`: that one asks whether the bytes agree with the
+    // label, this asks whether an artifact for that label can exist at all. They
+    // are not the same check, and the windows row is where they come apart — a
+    // payload of x64 DLLs labelled `arm64` fails the first, while a payload of pure
+    // JavaScript labelled `arm64` passes it and still produces a program directory
+    // no Windows/ARM machine has a GTK for (#1117).
+    //
+    // HERE and not at `--stage`, which is the same split `Layout.runtimeGap` draws:
+    // a stage is a build intermediate and assembling one for a foreign arch is what
+    // `tests/e2e/ship-layout` does on purpose (one payload, three layouts, and that
+    // payload's native file has an architecture). What must not leave is an
+    // ARTIFACT. `assemble` warns at the `--arch` that caused it.
+    //
+    // And BEFORE `archName`, deliberately: that function refuses an unknown value
+    // too, with a message about a table. This one names the blocker and where it is
+    // tracked, which is the difference between "unsupported" and "here is what
+    // would have to change".
+    assertLayoutSupportsArch(layout, input.arch);
+    // AFTER every check above and BEFORE any container below — the seam § A17
+    // asks M2's packer to leave, filled. Signing is a MUTATION of the payload
+    // (§ A4): what the packers get back is new bytes, not a wrapper, because a
+    // Developer-ID-signed main executable will not load ad-hoc-signed dylibs
+    // under library validation and all 106 images in the shipped darwin closure
+    // are ad-hoc today.
+    //
+    // Per FORMAT rather than once per run, and that costs darwin a second
+    // `codesign` pass over the same images (`macos-app` and `macos-app-zip` are
+    // two calls). It is not avoidable by hoisting: the payload a format signs
+    // includes that format's own overlay — on darwin the licence, which lands
+    // INSIDE `<App>.app` — so two formats have two payloads.
+    //
+    // `signed/<id>/` is scratch this function owns. The arriving stage is never
+    // written to: `writeStage` wipes what it is pointed at, and a re-signed file
+    // in it would fail the very `readStage` above on the next run.
+    const payload = input.sign.kind === 'sign'
+        ? await signPayload({
+            payload: assembled,
+            identity: input.sign.identity,
+            signer: input.sign.signer,
+            workDir: join(outRoot, 'signed', format.id),
+            // What the darwin signer SEALS, from the layout that named it —
+            // `<App>.app` there, `''` on the two layouts with no bundle.
+            bundleRoot: layout.root(settings),
+            // OUTSIDE `signed/<id>/`: that directory is listed and compared
+            // with the payload, so an entitlements plist written into it would
+            // read as a file `codesign` added.
+            entitlementsPath: join(outRoot, 'signed', `${format.id}.entitlements.plist`),
+            verbose: input.verbose,
+            log: (line) => console.log(`${LOG} ${line}`),
+        })
+        : assembled;
     const archLabel = format.archName(input.arch, isArchIndependent(payload));
     const common = { settings, payload, prefix: format.prefix, depends, archLabel, mtime };
     const outDir = join(outRoot, 'out');
@@ -395,12 +921,177 @@ async function packOne(input) {
                 verbose: input.verbose,
             });
             break;
+        case 'macos-app':
+        case 'windows-dir':
+            // ONE STATEMENT FOR TWO ROWS, folded because the code really is
+            // identical: `Layout.root` is where the two differ, and the first draft
+            // of the windows arm said "NO REBASE, which is the one place the two
+            // rows differ" over a line byte-identical to this one.
+            //
+            // No container at all: the artifact IS the payload plus this format's
+            // overlay, written out. `writePayload` rather than a directory copy of
+            // the stage, so the same two properties every other packer has hold
+            // here — modes come from the plan (`readStage` has applied them, and
+            // the artifact upload that flattens them cannot reach in between), and
+            // the stage's own sidecar stays out because it was never payload.
+            //
+            // REBASED ON `Layout.root`, which is `<App>.app` on darwin and `''` on
+            // windows — the difference between the artifact and a directory
+            // containing it, measured as a defect on the first: every staged darwin
+            // path already begins with `<App>.app/` and `format.fileName` names the
+            // artifact the same thing, so writing them verbatim produced
+            // `out/Ship Demo.app/Ship Demo.app/Contents/…`, a folder the Finder does
+            // not treat as an application with a real bundle hidden one level down,
+            // at exit 0, with `zipinfo` on the sibling zip showing the correct tree
+            // the whole time. On windows the stage IS the directory's contents,
+            // because an installer picks the parent, and `writePayload` documents
+            // `stripPrefix === ''` as a no-op — so the same call is right for both.
+            // Neither zip needs a rebase, and for opposite reasons: the darwin
+            // archive INHERITS its top level from the staged paths, the windows one
+            // SYNTHESISES it (see `windows-dir-zip`).
+            writePayload(target, payload, layout.root(settings));
+            break;
+        case 'macos-app-dmg': {
+            // FROM THE STAGE, never from the `out/<App>.app` the row above
+            // writes, and that is a design decision rather than an accident of
+            // where the bytes were handy. Three reasons, in the order they bite:
+            //
+            //  * a `--target macos-app-dmg` run alone must produce a `.dmg`.
+            //    Reading the sibling artifact would make this row depend on
+            //    another row having run, and the only thing that orders them
+            //    today is `resolveFormats`' alphabetical sort — an invariant
+            //    nothing states and `--target macos-app-dmg` on its own breaks.
+            //  * ADR 0024 § A17 fixes the seam for a later `--sign`: `readStage`
+            //    validates the PRE-sign tree, the re-sign runs after it, and the
+            //    container is built after that. A packer that opened an artifact
+            //    would put its container step on the far side of a directory
+            //    nothing validated.
+            //  * the modes. `writePayload` applies the PLAN's modes, which
+            //    `readStage` has already resolved from the manifest; a directory
+            //    copy would inherit whatever the filesystem — or a CI artifact
+            //    round trip — left behind.
+            //
+            // `stripPrefix: ''` and not `layout.root(settings)`, which is the one
+            // line where this differs from the `macos-app` arm above: that
+            // artifact IS the bundle, so the `<App>.app/` prefix comes off; this
+            // one is the VOLUME, and the bundle has to sit inside it or the image
+            // mounts showing `Contents/` — a window with no application in it.
+            const volumeDir = dmgVolumeDir(outRoot);
+            writePayload(volumeDir, payload, '');
+            await buildDmgImage({
+                volumeName: dmgVolumeName(settings),
+                sourceDir: volumeDir,
+                target,
+                workDir: dirname(volumeDir),
+                verbose: input.verbose,
+            });
+            break;
+        }
+        case 'macos-app-zip':
+            // The SAME payload, in the one container a browser download can be.
+            // Written by this tree (`utils/ship/zip.ts`) so the packing host needs
+            // no `zip(1)` and `zipinfo` stays an independent reader — ADR 0024
+            // § A3's argument for the hand-written deb and rpm, applied again.
+            // The paths inside are the staged ones, so the archive expands to
+            // `<App>.app/…` and not to a bare `Contents/`.
+            writeFileSync(target, buildZip(zipEntriesFromPayload(payload), mtime));
+            break;
+        case 'windows-dir-zip':
+            // The same payload, with the top level the layout deliberately does not
+            // carry. `windowsProgramDirName` is the same function the row above
+            // names the directory with, so unzipping this archive and running the
+            // installer put the app at the same relative path — and a user who
+            // unzips it in `Downloads` gets one directory rather than `app\`,
+            // `share\` and a `.cmd` loose in it.
+            writeFileSync(target, buildZip(zipEntriesFromPayload(payload, windowsProgramDirName(settings)), mtime));
+            break;
+        case 'msi': {
+            // The SAME payload again, and the third artifact to carry it —
+            // `payload`, which is `signPayload`'s OUTPUT when an identity was
+            // passed and `assembled` otherwise (§ A17). The installer therefore
+            // packs the signed bytes by construction rather than by ordering: it
+            // cannot read them before the signer has produced them.
+            //
+            // The source document addresses files by PATH, so the tree is written
+            // out once into the work directory and the `.wxs` points at it with
+            // paths RELATIVE to that directory — the same shape the Flatpak packer
+            // uses, where a manifest also names a directory the packer just laid
+            // down. Relative and not absolute because the same document is compiled
+            // a second time by WiX on another machine; see `utils/ship/msi.ts`.
+            // Not a copy of `out/<App>/`: `--target msi` alone must work, and the
+            // directory row may not be in this run's format list at all.
+            const workDir = join(outRoot, 'msi');
+            writePayload(join(workDir, MSI_PAYLOAD_DIR), payload, layout.root(settings));
+            await buildMsi({
+                settings,
+                // POSIX-separated and RELATIVE to `workDir`, so the `.wxs` plus the
+                // tree beside it is a pair that can be handed to a second compiler
+                // on another machine — which is what the WiX half of the
+                // cross-check does with this exact document.
+                files: payload.map((entry) => ({
+                    path: entry.path,
+                    source: `${MSI_PAYLOAD_DIR}/${entry.path}`,
+                })),
+                programDirName: windowsProgramDirName(settings),
+                archLabel,
+                workDir,
+                target,
+                verbose: input.verbose,
+            });
+            break;
+        }
         default: {
             const unhandled = format.id;
             throw new Error(`gjsify ship: no packer is wired for format "${String(unhandled)}".`);
         }
     }
-    return { format: format.id, path: target, size: statSync(target).size };
+    // The SIZE of a directory is not `statSync().size`, which answers 4096 for the
+    // directory entry — so a `.app` with a 20 MiB bundle would be reported as
+    // "4096 bytes". `artifactKind` is on the descriptor for exactly this.
+    const size = format.artifactKind === 'directory' ? directorySize(target) : statSync(target).size;
+    // LAST, on the artifact that landed — notarisation is a check on a finished,
+    // signed container and there is nothing to submit before one exists.
+    //
+    // A DIRECTORY IS SKIPPED, not refused. `notarytool` takes an archive or an
+    // installer, so a `<App>.app` has no submittable form of its own; on darwin
+    // the zip beside it is the one that goes. Refusing here would make
+    // `--notarize` unusable with the default format set, which is both rows.
+    if (input.notarize.kind === 'notarize') {
+        if (format.artifactKind === 'directory') {
+            console.warn(`${LOG} ${format.id} is a directory, and notarytool submits an archive or an installer — ` +
+                'not notarised. The container format beside it is what carries the ticket.');
+        }
+        else {
+            await notarizeArtifact({
+                plan: input.notarize,
+                artifact: target,
+                verbose: input.verbose,
+                log: (line) => console.log(`${LOG} ${line}`),
+            });
+            // AND THEN THE TICKET, on the artifacts that can hold one. Submitting
+            // and stapling are two questions with two answers, and the `.zip` is
+            // where they come apart: the notary service accepts it and `stapler`
+            // refuses it. Without the ticket the artifact still installs — every
+            // launch asks Gatekeeper online instead, and fails closed on a machine
+            // with no network, which is the failure a user reads as "the app is
+            // damaged".
+            if (canCarryTicket(format.id)) {
+                await stapleArtifact({
+                    notary: input.notarize.notary,
+                    artifact: target,
+                    verbose: input.verbose,
+                    log: (line) => console.log(`${LOG} ${line}`),
+                });
+            }
+            else {
+                console.warn(`${LOG} ${format.id} is notarised and NOT stapled: \`stapler\` takes a UDIF image, a ` +
+                    "signed flat package or a code-signed bundle, and an archive is none of them. Apple's " +
+                    'remedy is to staple each item that went INTO the archive and re-create it — for this ' +
+                    'artifact that is the `.app`, which `--target macos-app` writes beside it.');
+            }
+        }
+    }
+    return { format: format.id, path: target, size };
 }
 function printArtifacts(base, artifacts) {
     for (const artifact of artifacts) {
@@ -420,28 +1111,129 @@ function assertCanPack(format) {
     assertToolsInstalled(format);
 }
 /**
- * Refuse a build target this command cannot package correctly.
+ * Refuse a pack for a layout no format wraps.
+ *
+ * Reached only when the format list was DERIVED — no `--target`, or a
+ * `gjsify.ship.targets` filtered empty by this layout — where the empty set is a
+ * fact about the layout rather than something a caller typed. Without it,
+ * `gjsify ship darwin` would assemble the tree, iterate an empty format list,
+ * print no artifact line and exit 0 — a success that produced nothing, which is
+ * the same shape `resolveFormats` refuses an empty `--target` for.
+ *
+ * `chosenBy` is not decoration. When the layout came from the HOST rather than
+ * from the positional, this is a BEHAVIOUR CHANGE the caller did not ask for:
+ * a bare `gjsify ship` on a Mac used to emit `.deb` + `.rpm`, because the default
+ * format set was host-independent. It is deliberate — the positional means what
+ * it says, and a Linux package built on a Mac is now something you ask for — but
+ * a refusal that does not name the one-word replacement is just a regression.
+ */
+function assertPackable(formats, layout, chosenBy, unusable = []) {
+    if (formats.length > 0)
+        return;
+    // A DIFFERENT emptiness, and conflating the two sends the reader to the wrong
+    // fix. "No format wraps this layout" is answered by a later milestone; "the
+    // formats that wrap it cannot run this project's interpreter" is answered by
+    // the project, today — and the two produce byte-identical empty lists.
+    if (unusable.length > 0) {
+        throw new Error(`gjsify ship: ${unusable.map((format) => format.id).join(' and ')} wrap the ${layout.name} ` +
+            `layout, and neither can run this project — ${unusable[0]?.interpreterGap ?? ''}.\n` +
+            `    Set \`gjsify.ship.app.${layout.os}\` to ` +
+            `"${unusable[0]?.interpreters.join('" / "')}" — it overrides \`gjsify.app\` for THIS target and\n` +
+            '    leaves every other one alone, which is what lets one project be GJS on Linux and Node here.\n' +
+            `    \`gjsify ship ${layout.name} --stage\` assembles the tree either way.`);
+    }
+    // A THIRD emptiness, and the one the last throw in this function used to
+    // mis-diagnose. A layout that HAS formats still reaches here with none
+    // SELECTED: `configuredFormats` filters `gjsify.ship.targets` to the layout
+    // being assembled and returns an empty list when they all wrap another one,
+    // and `--stage` records that empty list for the finishing host to read.
+    //
+    // MEASURED before this branch existed, on a `--app node` project carrying
+    // `targets: ["deb","rpm"]` — the key `packages/infra/cli/package.json` itself
+    // carries — with `gjsify ship darwin --stage` then `gjsify ship --from-stage`:
+    // "no format wraps the darwin layout … Keep it for the milestone that packs it
+    // … this is a layout added without a `FORMATS` row". Three rows wrap darwin,
+    // the milestone landed, and the cause was a configured list for another OS.
+    const wrapping = formatIdsFor(layout.os).sort();
+    if (wrapping.length > 0) {
+        // The assembling host is where the answer is, whichever caller got here:
+        // phase two cannot add a format the stage never rendered an overlay for
+        // (`assertFormatsStaged`), so `--target` HERE is not the fix.
+        const where = chosenBy === 'stage' ? `${layout.name} --stage --target` : `${layout.name} --target`;
+        throw new Error(`gjsify ship: this run records no formats for the ${layout.name} layout, so there is nothing ` +
+            `to pack — and it is not that none exist: ${wrapping.join(', ')} wrap it.\n` +
+            '    An empty list means none were SELECTED. `gjsify.ship.targets` is filtered to the layout ' +
+            'being assembled,\n' +
+            "    so a configured list naming only another OS's formats leaves this one empty and says so " +
+            'at stage time.\n' +
+            `    Name one where the payload is assembled: \`gjsify ship ${where} ${wrapping[0]}\`.`);
+    }
+    const linux = defaultFormatIds('linux').join(',');
+    // Three callers, three different next steps. Telling a `--from-stage` caller
+    // to run `gjsify ship <os> --stage` names the command that PRODUCED the stage
+    // they are holding, which is advice to go in a circle.
+    const advice = {
+        host: `This host is ${process.platform}, so \`gjsify ship\` assembled the ${layout.name} layout. ` +
+            'Assembly is not host-bound (ADR 0024 § A1), so the Linux packages are still one word away: ' +
+            `\`gjsify ship linux\` builds ${linux} from right here.`,
+        positional: `\`gjsify ship ${layout.name} --stage\` assembles the payload and stops, which is the whole of ` +
+            'what this command does for that OS today.',
+        stage: `This stage carries the ${layout.name} layout and nothing here can wrap it — a stage is a build ` +
+            'intermediate, not an artifact. Keep it for the milestone that packs it, or re-assemble with ' +
+            '`gjsify ship linux --stage` if a Linux package is what you wanted.',
+    }[chosenBy];
+    // NOW ACTUALLY UNREACHABLE from the three layouts that exist — the branch
+    // above holds every one of them, because `formatIdsFor` answers non-empty for
+    // all three as of #1354 M5. Kept rather than deleted: this is what a fourth
+    // layout gets on the day it is added and before a `FORMATS` row wraps it, the
+    // state windows was in between M1 and M3, and deleting it would make that
+    // day's failure a `TypeError` on an empty list.
+    //
+    // It used to claim this for the whole function while the `targets`-elsewhere
+    // route reached it and got all three of its sentences wrong. A comment saying
+    // "unreachable" is a claim about a predicate; this one now has the predicate
+    // above it in code.
+    throw new Error(`gjsify ship: no format wraps the ${layout.name} layout, so there is nothing to pack. ${advice}` +
+        ' Every layout this gjsify knows has one (ADR 0024 stages 2-5), so this is a layout added ' +
+        'without a `FORMATS` row.');
+}
+/**
+ * Refuse a format whose runtime cannot provide the interpreter the launcher execs.
  *
- * The launcher execs `gjs -m <bundle>`, so a `--app node` bundle would produce
- * a package that installs and then fails at startup — and ADR 0024 § 4 says
- * that case needs a BUNDLED Node, whose delivery (fetched at ship time versus a
- * platform package) is still an open decision. Better to say so than to ship
- * the broken half of it.
+ * THE HOLE THIS CLOSES, and it was opened by the commit that made `--app node`
+ * packageable. The shippable-target refusal — `resolveShipApp` in
+ * `utils/ship/settings.ts`, a free function in this file until #1486 — used to
+ * refuse `app: 'node'` outright, so no format ever saw one. Lifting that made deb and rpm correct and left Flatpak
+ * silently wrong: measured at exit 0, a `--target flatpak --stage` with
+ * `app: 'node'` emitted a manifest with `runtime: org.gnome.Platform`,
+ * `runtime-version: 50`, no `sdk-extensions` and no `append-path`, beside a
+ * launcher that execs `node`. That runtime ships `gjs` and no `node`.
  *
- * An undeclared target is the common case for a GJS app and is allowed: `app`
- * otherwise defaults to the HOST runtime, which would refuse a perfectly good
- * GJS project merely for running this command under Node.
+ * WHY THE OTHER CHECK DOES NOT CATCH IT. `assertLauncherMatchesInterpreter`
+ * compares the launcher against the DEPENDENCY, and a Flatpak has no dependency
+ * list — `format.depends` is `null`, so both sides come from `settings.app` and
+ * agree by construction. Only the format's runtime knows what it can execute,
+ * which is why the answer is a descriptor field.
  *
- * Phase one only, and nothing checks it again in phase two: a stage can only
- * exist because this passed, and the staged `bin/<name>` carries the
- * `exec gjs -m` line that proves it.
+ * Not a warning. The artifact would install and die at first launch on a user's
+ * machine, which is the failure this whole command is built to make impossible.
  */
-function assertShippableTarget(app) {
-    if (app === undefined || app === 'gjs')
+function assertFormatCanRunInterpreter(format, app) {
+    if (format.interpreters.includes(app))
         return;
-    throw new Error(`gjsify ship: this project declares \`gjsify.app: "${app}"\`, and only \`gjs\` can be packaged today. ` +
-        'The launcher execs `gjs -m <bundle>`, so any other target would install and then fail to start. ' +
-        'ADR 0024 § 4 has the runtime-per-OS table and what is still open for the other targets.');
+    throw new Error(
+    // The TARGET's runtime, not "this project is": since #1486 the two can
+    // differ, and a message naming `gjsify.app` for a per-target answer sends
+    // the reader to the key whose edit moves every OTHER target's `Depends:`.
+    `gjsify ship: this ${format.layoutOs} target runs \`${app}\`, and the ${format.id} runtime cannot ` +
+        `run it — it provides ${format.interpreters.join(', ')}.\n` +
+        // The ROW's own sentence, not one written here. Hardcoded, this
+        // paragraph told the first `.app` author about
+        // `org.freedesktop.Sdk.Extension.node2x` and the GNOME runtime.
+        `    ${format.interpreterGap}.\n` +
+        '    Build the formats that wrap this layout and can run it, or set ' +
+        `\`gjsify.ship.app.${format.layoutOs}: "${format.interpreters.join('" / "')}"\` ` +
+        '(which overrides `gjsify.app` for this target alone).');
 }
 /**
  * Run the project's own `build` script, as a CHILD process.
@@ -471,6 +1263,6 @@ async function runProjectBuild(projectDir) {
             'yourself and pass --skip-build.'),
     });
     if (result.code !== 0) {
-        throw new Error(`gjsify ship: the project's build script failed${describeExit(result)}.`);
+        throw new Error(`gjsify ship: the project's build script failed with ${describeExit(result)}.`);
     }
 }