@gjsify/cli 0.53.0 → 0.55.0

package/lib/utils/ship/gi-namespaces.js

@@ -34,6 +34,18 @@
 // `walkModuleAst` answers both questions in ONE pass, and it is the same acorn
 // pass the CLI already uses to compute its own runtime closure — so there is one
 // definition of "what does this file import" rather than two.
+//
+// HARD OR OPTIONAL, since ADR 0087: a `gi://Ns?version=X&optional` import still
+// appears in the emitted file, so this scanner still reports its namespace — and
+// `depends.ts` has to know it may be absent. The discriminator is the marker
+// statement the bundler's own optional shim emits (`GI_OPTIONAL_MARKER`, imported
+// from the plugin that writes it rather than restated here). NOT the `import()`
+// SHAPE, which was the tempting reading of the same file: an app that writes its own
+// `await import('gi://Goa')` without the flag must stay a HARD dependency, and
+// classifying it as optional would move a package the host must have out of its
+// `Depends:` — the failure this whole chain exists to prevent, reached from the other
+// direction.
+import { GI_OPTIONAL_MARKER } from '@gjsify/rolldown-plugin-gjsify';
 import { importedSpecifier, staticStringValue, walkModuleAst, } from '../cli-runtime-closure.js';
 /** The module a `--app node` bundle reaches GI through. */
 const NODE_GI_MODULE = '@gjsify/node-gi/gi';
@@ -44,7 +56,12 @@ const NAMESPACE = /^[A-Za-z][A-Za-z\d_]*$/;
  * specifier pins one and bare `Ns` when it does not.
  */
 export function scanGiNamespaces(source) {
+    return scanGiRequirements(source).namespaces;
+}
+/** {@link scanGiNamespaces}, plus which of them the artifact marks optional (ADR 0087). */
+export function scanGiRequirements(source) {
     const found = new Set();
+    const optional = new Set();
     // TWO SETS, because the two kinds of binding are not interchangeable and
     // treating them as one over-approximated on a real minified bundle. A
     // namespace object (`import * as gi`) and a required module object are only
@@ -89,11 +106,57 @@ export function scanGiNamespaces(source) {
             calls.push(node);
     });
     for (const call of calls) {
+        const marker = optionalMarkerNamespace(call);
+        if (marker !== null) {
+            optional.add(marker);
+            continue;
+        }
         const key = requireGiNamespace(call, callable, objects);
         if (key !== null)
             found.add(key);
     }
-    return [...found].sort();
+    return { namespaces: [...found].sort(), optional: [...optional].filter((ns) => found.has(ns)).sort() };
+}
+/**
+ * The namespace an optional-marker call names, or `null` when this is not one.
+ *
+ * The shape is the bundler's: `globalThis[Symbol.for(GI_OPTIONAL_MARKER)]?.("Ns", "X")`,
+ * matched on BOTH halves rather than on the whole statement — the minifier rewrites
+ * the string literals to backticks and the optional call to a `ChainExpression`
+ * around the `CallExpression` this walk still reaches, and a plain call (a host that
+ * has a handler the minifier could prove is non-null) reads the same way.
+ */
+function optionalMarkerNamespace(call) {
+    const callee = call.callee;
+    if (callee?.type !== 'MemberExpression' || callee.computed !== true)
+        return null;
+    // `globalThis[Symbol.for(KEY)]` — a computed member whose PROPERTY is the
+    // `Symbol.for` call, so the key is an argument of that inner call rather than
+    // of the outer one. Verified against acorn's own shape: `optional` chaining
+    // wraps the whole thing in a `ChainExpression`, which the walk descends into,
+    // so the `CallExpression` reaches this function either way.
+    const keyCall = callee.property;
+    if (keyCall?.type !== 'CallExpression')
+        return null;
+    const keyCallee = keyCall.callee;
+    const keyObject = keyCallee?.type === 'MemberExpression' ? keyCallee.object : undefined;
+    const keyProperty = keyCallee?.type === 'MemberExpression' ? keyCallee.property : undefined;
+    if (keyObject?.type !== 'Identifier' || keyObject.name !== 'Symbol')
+        return null;
+    if (keyProperty?.type !== 'Identifier' || keyProperty.name !== 'for')
+        return null;
+    const keyArgs = keyCall.arguments ?? [];
+    if (staticStringValue(keyArgs[0]) !== GI_OPTIONAL_MARKER)
+        return null;
+    const host = callee.object;
+    if (host?.type !== 'Identifier' || host.name !== 'globalThis')
+        return null;
+    const args = call.arguments ?? [];
+    const namespace = staticStringValue(args[0]);
+    if (namespace === null || !NAMESPACE.test(namespace))
+        return null;
+    const version = staticStringValue(args[1]);
+    return version === null || version === '' ? namespace : `${namespace}-${version}`;
 }
 /** `gi://Gtk?version=4.0` → `Gtk-4.0`; `gi://Gtk` → `Gtk`; anything else → null. */
 export function parseGiSpecifier(specifier) {

package/lib/utils/ship/launcher.js

@@ -171,7 +171,7 @@ function renderPrefixLauncher(settings, bundleRelPath, layout) {
  * IT EXECS WHAT THE BUNDLE CARRIES. `runtime` comes from
  * `utils/ship/app-runtime.ts` and names the interpreter, the relocated GTK
  * closure and the node-gi addon staged inside `Contents/` — so the exec line is
- * `"$here/node"` and the two locators below point into `Contents/Frameworks`.
+ * `"$here/node"` and the two locators below point into `dirs.native`.
  * When the stage carries none of them every line here is byte-identical to what
  * M2a wrote, which is what keeps a bundle assembled without the runtime packages
  * exactly as (un)usable as it was rather than differently broken.
@@ -261,7 +261,7 @@ function renderAppBundleLauncher(settings, bundleRelPath, layout, runtime) {
     // `node_modules`, and a shipped `.app` has neither: its JavaScript is one
     // bundled file under `Contents/Resources/lib`, so `import.meta.url` there
     // resolves node-gi's "package root" to the bundle's directory and every probed
-    // path lands beside the bundle instead of in `Contents/Frameworks`.
+    // path lands beside the bundle instead of in `dirs.native`.
     //
     // `NODE_GI_NATIVE` is the same problem for the addon: `prebuildAddonPath()`
     // joins `prebuilds/<target>/node_gi.node` onto that same wrong root

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

@@ -230,9 +230,10 @@ export interface Layout {
      *
      *  * a REASON. `archName` answers "no Windows architecture is known for
      *    `process.arch` \"arm64\"", which reads as a gap in our table. The truth is
-     *    that gvsbuild publishes no arm64 GTK, the blocker is upstream, and #1117
-     *    is where it is tracked — and the difference between "unsupported" and
-     *    "here is what would have to change" is the whole value of the message.
+     *    a package this project has not built yet — ordered in
+     *    `status/open-todos/windows.md` and tracked in #1117 — and the difference
+     *    between "unsupported" and "here is what would have to change" is the whole
+     *    value of the message.
      *  * a STAGE-TIME warning at the flag that caused it (`commands/ship.ts`), for
      *    a phase that deliberately does not refuse — `tests/e2e/ship-layout`
      *    assembles all three layouts from ONE payload on purpose, and that
@@ -314,9 +315,9 @@ export declare function hostLayout(platform?: string): Layout;
  * AT STAGE TIME, which is the whole point — see {@link Layout.arches}. The
  * message carries the row's own `why` rather than a generic "unsupported", because
  * the two refusals a reader can act on are different jobs: `x64` is what a Windows
- * artifact is built for TODAY, and `win32-arm64` is blocked in a repository we do
- * not own. Telling an author "unknown architecture" for the second one would send
- * them to look for a flag.
+ * artifact is built for TODAY, and `win32-arm64` waits on a package of ours that
+ * does not exist yet. Telling an author "unknown architecture" for the second one
+ * would send them to look for a flag.
  *
  * `process.arch` spelling on both sides, so the value quoted back is the one the
  * user typed after `--arch`.

package/lib/utils/ship/layout.js

@@ -7,7 +7,8 @@
 // is the first layout that is NOT a prefix substitution: the launcher, the bundle,
 // the shared libraries and the data tree each move somewhere different, and on
 // macOS the native files leave the bundle directory altogether for
-// `Contents/Frameworks`.
+// `Contents/Resources/native` — a path Apple's own layout does not have, for the
+// measured reason {@link layoutForOs}'s darwin row carries.
 //
 // So the layout is a MAP from the prefix-relative plan to a stage-relative path,
 // and `planStage` keeps producing the prefix-relative plan for all three. That
@@ -168,12 +169,34 @@ export const LAYOUTS = {
         // everything that is not, and `Contents/Frameworks` the dylibs — which is
         // the split that makes this more than a prefix: the `gi/` directory that
         // sits INSIDE `lib/<name>/` on Linux leaves the bundle directory entirely.
+        //
+        // …AND THE NATIVE DIRECTORY IS NOT APPLE'S, because `Contents/Frameworks`
+        // is RESERVED FOR NESTED CODE and one directory of it is loadable code
+        // that cannot be there. Measured on darwin-arm64 / macOS 27 with the
+        // published `@gjsify/gtk-runtime-darwin-arm64` staged by M2b: `codesign`
+        // refuses the BUNDLE SEAL with *"bundle format unrecognized, invalid, or
+        // unsuitable / In subcomponent: …/gtk/lib/gstreamer-1.0"*, so
+        // `gjsify ship darwin --sign` cannot sign a real GTK application at all —
+        // and it does so at exit 1 with the payload half-signed. The trigger is not
+        // gstreamer: it is any directory under `Contents/Frameworks` whose last
+        // dot-separated component parses as a version, because `codesign` reads
+        // `foo-1.0`, `foo1.0` and `Versions/1.0` as a VERSIONED NESTED BUNDLE
+        // (`<name>-<version>` is a framework's shape) and then finds no
+        // `Contents/Info.plist` inside. The relocated closure carries three:
+        // `girepository-1.0`, `gdk-pixbuf-2.0/2.10.0` and `lib/gstreamer-1.0`.
+        //
+        // The same three under `Contents/Resources` seal and verify at exit 0, which
+        // is the whole measurement. So `native` is the ONE seam that moves: the
+        // relocated closure, the addon, the app's own `gi/` dylibs and both launchers'
+        // `GI_TYPELIB_PATH`/`GJSIFY_GI_LIBRARY_PATH` all read it, so the tree and
+        // every path that names it move together. Library validation is unaffected —
+        // it follows the SIGNATURE (§ `signing.ts`'s darwin row), not the directory.
         dirs: (identity) => {
             const app = appBundleDir(identity);
             return {
                 launcher: `${app}/Contents/MacOS`,
                 bundle: `${app}/Contents/Resources/lib`,
-                native: `${app}/Contents/Frameworks`,
+                native: `${app}/Contents/Resources/native`,
                 data: `${app}/Contents/Resources/share`,
                 other: `${app}/Contents/Resources`,
             };
@@ -355,19 +378,22 @@ export const LAYOUTS = {
                 ]
                 : [];
         },
-        // ONE, and the blocker is a project we do not own. `wingtk/gvsbuild`
-        // hardcodes `self.platform = "x64"` in `utils/base_project.py` and its last
-        // five releases publish exactly two assets each, both x64 — so there is no
-        // arm64 GTK to build `@gjsify/gtk-runtime-win32-arm64` OUT OF, and on
-        // Windows that bundle is the only GTK there is. `@gjsify/node-gi` declares
-        // `win32-x64` only for the same reason. Tracked in #1117, which also
-        // records why an exploratory arm64 leg must NOT be added: its first step
-        // downloads a ZIP that does not exist, so it would be red by construction.
+        // ONE, and the blocker is OURS now. `wingtk/gvsbuild` hardcodes
+        // `self.platform = "x64"` and publishes x64 assets only — but we stopped
+        // waiting for it: ADR 0089 builds the arm64 GTK prefix from
+        // `gjsify/gvsbuild` in our own CI and `@gjsify/node-gi` declares
+        // `win32-arm64` against it (#2003). What is missing is
+        // `@gjsify/gtk-runtime-win32-arm64`, the closure this layout stages and on
+        // Windows the only GTK there is, so a Windows/ARM artifact still has
+        // nothing to load. Adding arm64 to `only` is the PR that builds that
+        // package, not this one.
         arches: {
             only: ['x64'],
-            why: 'gvsbuild publishes no arm64 GTK (it hardcodes `self.platform = "x64"`), so there is nothing ' +
-                'to build `@gjsify/gtk-runtime-win32-arm64` out of and no GTK for a Windows/ARM artifact to ' +
-                'load — the blocker is upstream and is tracked in gjsify/gjsify#1117',
+            why: 'the arm64 GTK closure `@gjsify/gtk-runtime-win32-arm64` does not exist yet — the prefix it ' +
+                'would be built from is no longer missing, because ADR 0089 builds it from our `gjsify/gvsbuild` ' +
+                'fork in CI and `@gjsify/node-gi` ships a win32-arm64 prebuild against it — so what is left is ' +
+                'the runtime package this layout would stage, ordered in `status/open-todos/windows.md` and ' +
+                'tracked in gjsify/gjsify#1117',
         },
     },
 };
@@ -479,9 +505,9 @@ export function hostLayout(platform = process.platform) {
  * AT STAGE TIME, which is the whole point — see {@link Layout.arches}. The
  * message carries the row's own `why` rather than a generic "unsupported", because
  * the two refusals a reader can act on are different jobs: `x64` is what a Windows
- * artifact is built for TODAY, and `win32-arm64` is blocked in a repository we do
- * not own. Telling an author "unknown architecture" for the second one would send
- * them to look for a flag.
+ * artifact is built for TODAY, and `win32-arm64` waits on a package of ours that
+ * does not exist yet. Telling an author "unknown architecture" for the second one
+ * would send them to look for a flag.
  *
  * `process.arch` spelling on both sides, so the value quoted back is the one the
  * user typed after `--arch`.

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

@@ -5,6 +5,11 @@ export interface RpmInputs {
     payload: readonly PayloadEntry[];
     prefix: string;
     depends: readonly string[];
+    /**
+     * Soft dependencies, written as the `RECOMMEND*` tags — an `&optional` typelib
+     * (ADR 0087), which the package installs with and runs without.
+     */
+    recommends?: readonly string[];
     /** RPM architecture (`x86_64`, `noarch`, …). */
     archLabel: string;
     mtime: number;

package/lib/utils/ship/rpm.js

@@ -54,6 +54,17 @@ const TAG = {
     REQUIREFLAGS: 1048,
     REQUIRENAME: 1049,
     REQUIREVERSION: 1050,
+    // The recommend trio. NOT the 1099/1046/1047 of rpm ≤ 4.18, which shared ONE
+    // index space with `REQUIRENAME`; since 4.19 each dependency tag carries its
+    // own arrays. MEASURED against a package `rpmbuild` produced and read back with
+    // `rpm` 6.0.2: RECOMMENDNAME is a STRING_ARRAY of its own right after
+    // PROVIDEVERSION, not an extension of the four REQUIRE entries. The numbers are
+    // in the 5000s for that reason and a wrong one is invisible here — rpm either
+    // ignores the tag or refuses the header, and `rpm -qp --recommends` is what
+    // says which (e2e `ship`).
+    RECOMMENDNAME: 5046,
+    RECOMMENDVERSION: 5047,
+    RECOMMENDFLAGS: 5048,
     RPMVERSION: 1064,
     POSTINPROG: 1086,
     POSTUNPROG: 1088,
@@ -225,6 +236,10 @@ function mainHeaderEntries(inputs, files, cpio, compressed) {
     // From the PAYLOAD, not the settings — see the same call in `deb.ts`.
     const scripts = renderRpmScriptlets(readPayloadFacts(inputs.payload), inputs.prefix);
     const requires = buildRequires(inputs.depends, scripts, readShebangInterpreters(inputs.payload));
+    // OMITTED, not written empty: rpm rejects a zero-count array (the same rule
+    // `encodeValue` enforces), so a package with no `&optional` namespace carries
+    // no RECOMMEND tag at all.
+    const recommends = buildRecommends(inputs.recommends ?? []);
     const entries = [
         { tag: TAG.HEADERI18NTABLE, type: RpmType.STRING_ARRAY, value: ['C'] },
         { tag: TAG.NAME, type: RpmType.STRING, value: settings.binaryName },
@@ -277,6 +292,13 @@ function mainHeaderEntries(inputs, files, cpio, compressed) {
         { tag: TAG.REQUIRENAME, type: RpmType.STRING_ARRAY, value: requires.names },
         { tag: TAG.REQUIREFLAGS, type: RpmType.INT32, value: requires.flags },
         { tag: TAG.REQUIREVERSION, type: RpmType.STRING_ARRAY, value: requires.versions },
+        ...(recommends.names.length > 0
+            ? [
+                { tag: TAG.RECOMMENDNAME, type: RpmType.STRING_ARRAY, value: recommends.names },
+                { tag: TAG.RECOMMENDFLAGS, type: RpmType.INT32, value: recommends.flags },
+                { tag: TAG.RECOMMENDVERSION, type: RpmType.STRING_ARRAY, value: recommends.versions },
+            ]
+            : []),
         { tag: TAG.PAYLOADFORMAT, type: RpmType.STRING, value: 'cpio' },
         { tag: TAG.PAYLOADCOMPRESSOR, type: RpmType.STRING, value: 'gzip' },
         // Write-side metadata only — no reader acts on it (rpm-format.md § 6.5).
@@ -383,6 +405,26 @@ function buildRequires(depends, scripts, interpreters) {
     }
     return { names, flags, versions };
 }
+/**
+ * The three parallel `Recommends` arrays — the soft half of
+ * {@link buildRequires}, same relation spelling, no `RPMLIB` and no sense bits.
+ *
+ * `0` is the right flags value and not a missing one: rpm reads an unversioned
+ * recommendation as "any version", which is what an `&optional` typelib package
+ * means (the app asks for the NAMESPACE, never for a version of the package).
+ */
+function buildRecommends(recommends) {
+    const names = [];
+    const flags = [];
+    const versions = [];
+    for (const depend of recommends) {
+        const parsed = parseDepend(depend);
+        names.push(parsed.name);
+        flags.push(senseFor(parsed.relation));
+        versions.push(parsed.version ?? '');
+    }
+    return { names, flags, versions };
+}
 function senseFor(relation) {
     switch (relation) {
         case '>=':

package/lib/utils/ship/settings.js

@@ -166,6 +166,12 @@ export function resolveShipSettings(input) {
         throw new Error('gjsify ship: no licence — set `license` in package.json (an SPDX id, e.g. "MIT") ' +
             'or `gjsify.ship.license.project`. Both deb and rpm carry it as a required field.');
     }
+    // Written BACK, not read twice: the packers read `settings.license` and the AppStream
+    // renderers read `metadata.license.project`, so resolving the `package.json#license`
+    // fallback into the first alone left `<project_license>` empty in the staged metainfo
+    // and warned about a field the project had answered. The returned metadata is what every
+    // renderer reads, so this is where the one answer has to land.
+    metadata.license = { ...metadata.license, project: license };
     const maintainer = ship.maintainer ?? formatAuthor(pkg.author) ?? formatDeveloper(metadata);
     if (!maintainer) {
         throw new Error('gjsify ship: no maintainer — set `author` in package.json ("Name <you@example.com>"), ' +

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

@@ -30,14 +30,19 @@ export interface SignerDescriptor {
     /** argv after {@link tool}, for ONE file. */
     args: (input: SignArgs) => readonly string[];
     /**
-     * The entitlements this signer asks for, or `[]` where the OS has none.
+     * The entitlements this signer asks for, given the identity in hand.
+     *
+     * A FUNCTION, not a list, and the darwin row's second argument is what makes
+     * that necessary: the set depends on whether the identity is a real one, and
+     * one entitlement is exactly wrong in one of the two directions. It is a
+     * measured difference, not a preference — see {@link SIGNERS}.darwin.
      *
      * `[]` is an ANSWER and not an omission — the same rule `Layout.metadata`
      * states. Windows has no equivalent concept at all, and a signer that granted
      * nothing on macOS would be a different decision from one that has nothing to
      * grant.
      */
-    entitlements: readonly string[];
+    entitlements: (adhoc: boolean) => readonly string[];
     /**
      * Does this signer seal the ARTIFACT ROOT after signing the images inside it?
      *

package/lib/utils/ship/signing.js

@@ -18,7 +18,10 @@
 //     an ad-hoc `LC_CODE_SIGNATURE` already (they must — `install_name_tool`
 //     invalidates the original during relocation). So the darwin leg re-signs
 //     every image, and the result is new BYTES for the packer rather than a
-//     container around the old ones.
+//     container around the old ones. § A16's corollary of this — "the same
+//     identity everywhere, so library validation has nothing to object to" — is
+//     measured FALSE for the ad-hoc identity, and the darwin row's
+//     `entitlements` is where that correction lives.
 //  4. THE ORDER IS STRUCTURAL, not conventional (§ A17). `readStage` compares
 //     each file's SIZE against `.gjsify-ship-stage.json`, and a size is no more
 //     re-sign-proof than a digest. BOTH halves are measured and they agree:
@@ -66,10 +69,10 @@
 //    `.dmg` is stapled and the `.zip` is told what a user has to do instead.
 //
 // WHAT IS STILL NOT DONE, deliberately: `signtool` is never given a timestamp URL
-// (see the win32 row), and the entitlement § A16 is about —
-// `com.apple.security.cs.disable-library-validation` — is NOT granted, because
-// § A4's re-sign of every image in the closure is the design of record and
-// granting the entitlement would quietly make it look unnecessary.
+// (see the win32 row), and the named-identity half of § A16 is untested because it
+// needs a certificate — the GRANT of `disable-library-validation` is the measured
+// ad-hoc answer, and § A4's re-sign of every image stays the design of record for
+// the Developer ID that notarisation will actually require.
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join, sep } from 'node:path';
 import { isOnPath } from '../check-system-deps.js';
@@ -123,32 +126,52 @@ export const SIGNERS = {
             ...(adhoc ? [] : ['--timestamp']),
             file,
         ],
-        // FOUR OF THE REFERENCE'S SIX, and both omissions are decisions:
+        // FIVE OF THE REFERENCE'S SIX for an ad-hoc identity, FOUR for a real one,
+        // and the difference is the one § A16 left open — now MEASURED, on
+        // darwin-arm64 with the published `@gjsify/gtk-runtime-darwin-arm64` staged
+        // into the bundle (`utils/ship/layout.ts` carries the rest of that run).
         //
-        //  * `com.apple.security.cs.get-task-allow` is granted by
-        //    `refs/node/tools/osx-entitlements.plist:15` and is a DEBUGGING
-        //    entitlement — it lets another process attach to this one. Apple's
-        //    notarisation rules refuse a Developer-ID artifact carrying it, so
-        //    shipping it would trade a working debug build for an artifact that
-        //    cannot be distributed. The reference signs its own build; we sign what
-        //    a stranger downloads.
-        //  * `com.apple.security.cs.disable-library-validation` is § A16's open
-        //    question and stays open. § A4's design of record is that every Mach-O
-        //    in the closure is re-signed with the SAME identity as the launcher, so
-        //    library validation has nothing to object to — and granting the
-        //    entitlement anyway would make that re-sign look optional the first
-        //    time somebody reads this list.
+        // § A16's premise was that library validation has nothing to object to
+        // because every Mach-O carries the SAME identity as the launcher. That is
+        // true for a Developer ID and FALSE for `--sign -`: an ad-hoc signature has
+        // no team at all, so the running process and the dylib it dlopens report
+        // different team IDs and the load is refused —
         //
-        // The four that remain are what a shipped V8 needs under a hardened
-        // runtime, plus the one our own loader story needs:
-        // `@gjsify/node-gi`'s `maybeReexecForGtkRuntime` sets `DYLD_*` for its
-        // child on darwin, and a hardened process may not do that without
-        // `allow-dyld-environment-variables`.
-        entitlements: [
+        //   dlopen(…/prebuilds/darwin-arm64/node_gi.node): code signature in
+        //   <378B2FDA-…> '…node_gi.node' not valid for use in process: mapping
+        //   process and mapped file (non-platform) have different Team IDs
+        //
+        // — at `require('@gjsify/node-gi')`, the FIRST thing a shipped `.app` does,
+        // with every image correctly signed. Same bundle, same signer, same argv,
+        // one more entitlement: `interpreter:`/`gtk-runtime:`/`chrome: ok`/
+        // `render: 480x320`/`done: 0`.
+        //
+        // So it is granted WHERE IT IS NEEDED, which is ad-hoc only. A Developer ID
+        // signs the whole closure with one team and needs nothing, and Apple's
+        // notarisation rules read a `disable-library-validation` entitlement on a
+        // Developer-ID artifact as shipping unsigned code — so granting it there
+        // would trade a distributable artifact for a locally runnable one. The
+        // GRANT therefore stays what § A16 asked to know: § A4's re-sign of every
+        // image is the design of record, and the entitlement is what makes the
+        // ad-hoc proof of it RUNNABLE rather than a signature `codesign` accepts and
+        // dyld refuses.
+        //
+        // The four both share are what a shipped V8 needs under a hardened runtime,
+        // plus the one our own loader story needs: `@gjsify/node-gi`'s
+        // `maybeReexecForGtkRuntime` sets `DYLD_*` for its child on darwin, and a
+        // hardened process may not do that without `allow-dyld-environment-variables`.
+        //
+        // `get-task-allow` is absent from both, and that is a decision:
+        // `refs/node/tools/osx-entitlements.plist:15` grants it, it is a DEBUGGING
+        // entitlement — it lets another process attach to this one — and Apple's
+        // notarisation rules refuse a Developer-ID artifact carrying it. The
+        // reference signs its own build; we sign what a stranger downloads.
+        entitlements: (adhoc) => [
             'com.apple.security.cs.allow-jit',
             'com.apple.security.cs.allow-unsigned-executable-memory',
             'com.apple.security.cs.disable-executable-page-protection',
             'com.apple.security.cs.allow-dyld-environment-variables',
+            ...(adhoc ? ['com.apple.security.cs.disable-library-validation'] : []),
         ],
         // The `.app` is a bundle, and a bundle's signature is the seal over its
         // whole tree — the images alone leave `codesign --verify` with nothing to
@@ -156,9 +179,10 @@ export const SIGNERS = {
         sealsBundle: true,
         sealAddPrefix: (bundleRoot) => `${bundleRoot}/Contents/_CodeSignature/`,
         configKey: 'gjsify.ship.sign.darwin.identity',
-        gap: 'the images are signed and the bundle is sealed; UNVERIFIED end to end — no macOS host in this ' +
-            'repository has run a `--sign` over a real `.app`, and ADR 0024 § A16 still leaves library ' +
-            'validation unmeasured',
+        gap: 'the images are signed and the bundle is sealed, and the seal survives both the `.zip` and the ' +
+            '`.dmg` round trip; § A16 stands measured in ONE direction only — library validation refuses an ' +
+            'ad-hoc-signed dylib, so the ad-hoc identity grants `disable-library-validation` while a named ' +
+            'one does not, and no run in this repository has ever held the named one',
     },
     win32: {
         layoutOs: 'win32',
@@ -180,8 +204,10 @@ export const SIGNERS = {
         // Windows has no equivalent concept. An Authenticode signature carries no
         // capability claims — what a hardened runtime and an entitlement do on
         // macOS is done on Windows by the manifest and by AppContainer, neither of
-        // which this signer touches.
-        entitlements: [],
+        // which this signer touches. `() => []` rather than `[]` because the field is
+        // a function of the identity (see the darwin row), and this one ignores the
+        // argument instead of reading `adhoc` out of it.
+        entitlements: () => [],
         // A Windows program directory is a DIRECTORY and nothing more: there is no
         // manifest to seal and no per-directory signature format. `signtool` signs
         // images, one at a time, which is what the loop above already does.
@@ -303,9 +329,10 @@ export async function signPayload(input) {
     writePayload(workDir, payload, '');
     const adhoc = input.identity === ADHOC_IDENTITY;
     let entitlements;
-    if (signer.entitlements.length > 0) {
+    const granted = signer.entitlements(adhoc);
+    if (granted.length > 0) {
         mkdirSync(dirname(input.entitlementsPath), { recursive: true });
-        writeFileSync(input.entitlementsPath, renderEntitlements(signer.entitlements));
+        writeFileSync(input.entitlementsPath, renderEntitlements(granted));
         entitlements = input.entitlementsPath;
     }
     const run = async (file, what) => {

package/lib/utils/ship/stage-manifest.d.ts

@@ -102,6 +102,18 @@ export interface StageManifest {
     mtime: number;
     /** GI namespaces the bundle imports, `Ns-Version` where the specifier pins one. */
     namespaces: string[];
+    /**
+     * The subset of {@link namespaces} the BUNDLE marks optional (ADR 0087).
+     *
+     * OPTIONAL on read, deliberately, and that is the {STAGE_SCHEMA_VERSION} header's
+     * "a field an older reader would simply ignore" case: a stage written before the
+     * split has no such key, and answering "nothing is optional" makes every
+     * namespace a `Depends:` again — today's behaviour, and the SAFE direction. A
+     * newer reader packing an OLDER stage therefore over-declares instead of dropping
+     * a requirement the artifact cannot run without, which is the one error here that
+     * ships a package that dies at first launch.
+     */
+    optionalNamespaces?: string[];
     settings: PackSettings;
     staged: StageFileRecord[];
     overlay: Partial<Record<FormatId, StageOverlayFile[]>>;
@@ -113,6 +125,8 @@ export interface StageManifestInput {
     formats: readonly FormatDescriptor[];
     mtime: number;
     namespaces: readonly string[];
+    /** The optional subset of {@link namespaces} — see {@link StageManifest}. */
+    optionalNamespaces?: readonly string[];
     staged: readonly StagedFile[];
     /** Per-format overlay, as `planOverlay` produced it. */
     overlay: ReadonlyMap<FormatId, readonly StagedFile[]>;

package/lib/utils/ship/stage-manifest.js

@@ -187,6 +187,7 @@ export function writeStageManifest(input) {
         formats: input.formats.map((format) => format.id),
         mtime: input.mtime,
         namespaces: [...input.namespaces],
+        optionalNamespaces: [...(input.optionalNamespaces ?? [])],
         settings: toPackSettings(input.settings),
         staged: input.staged.map((file) => ({
             path: file.path,
@@ -276,6 +277,12 @@ export function readStageManifest(stageDir) {
         }),
         mtime: expectInteger(data.mtime, at('mtime')),
         namespaces: expectArray(data.namespaces, at('namespaces')).map((entry, index) => expectString(entry, at(`namespaces[${index}]`))),
+        // Absent is the empty set, not an error — see the field's doc comment.
+        ...(data.optionalNamespaces === undefined
+            ? {}
+            : {
+                optionalNamespaces: expectArray(data.optionalNamespaces, at('optionalNamespaces')).map((entry, index) => expectString(entry, at(`optionalNamespaces[${index}]`))),
+            }),
         settings: readPackSettings(record(data.settings, at('settings')), at('settings')),
         staged: expectArray(data.staged, at('staged')).map((entry, index) => {
             const file = record(entry, at(`staged[${index}]`));

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

@@ -423,6 +423,8 @@ export interface PackSettings {
  * model back in the tree — which is the one thing § 8 gates the whole migration
  * on. A project that genuinely needs to BUILD something inside the sandbox
  * still has `gjsify flatpak init` + `gjsify flatpak build`, unchanged.
+ * A project that sets those keys and ships `flatpak` anyway is refused up front
+ * (`assertNoDroppedFlatpakModules`), never silently stripped of them.
  */
 export interface ShipFlatpakSettings {
     /** Runtime id, e.g. `org.gnome.Platform`. */

package/lib/utils/webext/targets.d.ts

@@ -1,4 +1,4 @@
-export type WebextBrowser = 'chrome' | 'edge' | 'firefox' | 'safari';
+export type WebextBrowser = 'chrome' | 'edge' | 'firefox' | 'opera' | 'safari';
 export interface WebextTarget {
     /** As spelled in `gjsify.webext.targets` and the output directory name. */
     readonly id: string;

package/lib/utils/webext/targets.js

@@ -4,14 +4,22 @@
 // `@gjsify/manifest-conformance` (plain `.mjs`, no import from here), so a
 // target added on one side and not the other is refused by the rule before a
 // build ever sees it.
-export const WEBEXT_BROWSERS = ['chrome', 'edge', 'firefox', 'safari'];
+export const WEBEXT_BROWSERS = ['chrome', 'edge', 'firefox', 'opera', 'safari'];
 /** What a project gets when it declares no `targets`. */
 export const DEFAULT_WEBEXT_TARGETS = ['chrome-mv3', 'firefox-mv3'];
 /**
- * Chromium-based browsers no longer load Manifest V2 at all, so a `chrome-mv2`
- * folder would build, zip, and then be rejected by the browser and the store.
+ * Why a browser takes no Manifest V2 folder, absent where it still does. Chrome
+ * and Edge removed MV2 in the browser, so the folder would build, zip, and then
+ * be refused on load. Opera still LOADS an MV2 extension but its store is
+ * MV3-only (Opera, 2025-09), so the folder is refused a step later instead. The
+ * outcome is the same either way, which is why the sentence is per browser and
+ * not one claim the three do not all support.
  */
-const MV2_REMOVED = new Set(['chrome', 'edge']);
+const MV2_UNSUPPORTED = new Map([
+    ['chrome', 'chrome has removed Manifest V2'],
+    ['edge', 'edge has removed Manifest V2'],
+    ['opera', "opera's extension store accepts Manifest V3 only"],
+]);
 export function parseWebextTarget(id) {
     const match = /^([a-z]+)-mv([23])$/.exec(id);
     const browser = match?.[1];
@@ -20,9 +28,9 @@ export function parseWebextTarget(id) {
             `${WEBEXT_BROWSERS.join(', ')} (e.g. chrome-mv3, firefox-mv2).`);
     }
     const manifestVersion = match[2] === '2' ? 2 : 3;
-    if (manifestVersion === 2 && MV2_REMOVED.has(browser)) {
-        throw new Error(`gjsify webext: target "${id}" does not exist any more: ${browser} has removed Manifest V2. ` +
-            `Use ${browser}-mv3.`);
+    const why = manifestVersion === 2 ? MV2_UNSUPPORTED.get(browser) : undefined;
+    if (why !== undefined) {
+        throw new Error(`gjsify webext: target "${id}" does not exist any more: ${why}. Use ${browser}-mv3.`);
     }
     return { id, browser, manifestVersion };
 }
@@ -30,7 +38,11 @@ export function parseWebextTarget(id) {
 export function webExtRunTarget(target) {
     if (target.browser === 'firefox')
         return 'firefox-desktop';
-    if (target.browser === 'chrome' || target.browser === 'edge')
+    // By ENGINE, not by brand: the chromium driver's only browser-specific input is the
+    // binary, and `--browser-binary` already carries it — the claim branded Chrome and
+    // Edge already make. Refusing opera here would be a claim about the operator's
+    // binary, which is not what this switch is about.
+    if (target.browser === 'chrome' || target.browser === 'edge' || target.browser === 'opera')
         return 'chromium';
     return null;
 }