@gjsify/cli 0.27.1 → 0.29.0

package/lib/utils/detect-native-packages.js

@@ -29,6 +29,7 @@
 import { readdirSync, existsSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { readPackageJson } from './pkg-json.js';
+import { splitSearchPath, systemGiLibraryDirs } from './system-gi.js';
 /**
  * Map a Node `process.arch` value to the uname-style spelling the Vala/meson
  * bridges used to stage into (`prebuilds/linux-x86_64/`, the output of
@@ -558,6 +559,18 @@ export function libraryPathVar(platform) {
         return { name: 'PATH', separator: ';' };
     return { name: 'LD_LIBRARY_PATH', separator: ':' };
 }
+/**
+ * dyld's *fallback* search path — consulted only AFTER the normal search
+ * (rpath / absolute name / dyld cache) has failed.
+ *
+ * Deliberately NOT part of {@link libraryPathVar}, which answers a different
+ * question: that one names the variable that OVERRIDES resolution for every
+ * dylib in the process (the right home for a prebuild we ship and want used),
+ * this one names the variable that fills in what nothing else could find (the
+ * right home for the host's own libdirs). Mixing the two roles is the mistake
+ * `buildNativeEnv` documents at length.
+ */
+const DYLD_FALLBACK_VAR = 'DYLD_FALLBACK_LIBRARY_PATH';
 /**
  * Build the typelib + shared-library search-path environment for the detected
  * native packages. Prepends the new paths to any existing values.
@@ -569,6 +582,40 @@ export function libraryPathVar(platform) {
  * (a stock Windows env block uses `Path`) — Windows env names are
  * case-insensitive, but a plain JS object is not, and `{...process.env,
  * PATH: …}` would hand a child process two competing entries.
+ *
+ * ── DARWIN ALSO GETS THE *HOST'S* GI LIBDIRS ─────────────────────────────────
+ *
+ * Everything above is about the prebuilds gjsify itself ships. On macOS there is
+ * a second, independent gap that has nothing to do with gjsify: a typelib names
+ * its library by BARE LEAF (`libgtk-4.1.dylib`), and dyld carries neither
+ * `/usr/local/lib` nor `/opt/homebrew/lib` in its default fallback path.
+ * Homebrew's `gjs` has an rpath into GLIB's keg only, so it resolves no other
+ * keg's leaves — measured: bare `gjs -c "imports.gi.Gtk; Gtk.init()"`, no gjsify
+ * in the process, dies on that dlopen (full trace in `utils/system-gi.ts`). This
+ * is the ONE place `gjsify run`, `showcase`, `storybook`, `tsc` and `info` all
+ * pass through, so it is where the child's launch env is repaired.
+ *
+ * Two properties are load-bearing:
+ *
+ *   1. **`DYLD_FALLBACK_LIBRARY_PATH`, never `DYLD_LIBRARY_PATH`.** The override
+ *      variable wins by LEAF for every dylib in the process, including ones the
+ *      host already resolved correctly — pointing it at a whole system libdir is
+ *      how you replace a linked-against library with a same-named different one.
+ *      The fallback is consulted only after the normal search fails, which is
+ *      exactly the "nothing else found it" case. Consequence, and it is the
+ *      intended precedence: gjsify's own prebuilds keep priority through the
+ *      override variable, the system stack fills in behind it.
+ *   2. **Our dirs go FIRST, an inherited fallback is kept BEHIND them, and
+ *      `/usr/lib` is appended when there is none.** Setting the variable
+ *      REPLACES dyld's own default fallback list, so writing only our dirs would
+ *      silently remove `/usr/lib` from the search — a host that exported the
+ *      variable itself already carries whatever tail it wants. Same composition
+ *      as node-gi's re-exec.
+ *
+ * Emitted even when `packages` is empty: the gap is in the host's loader, not in
+ * a gjsify prebuild, so a plain `gjsify run script.gjs.js` that touches GTK needs
+ * it just as much. Empty off darwin — `ld.so`'s configured cache already resolves
+ * these leaves on Linux, and Windows re-reads `PATH` per `LoadLibrary`.
  */
 export function buildNativeEnv(packages, opts = {}) {
     const platform = opts.platform ?? process.platform;
@@ -588,5 +635,14 @@ export function buildNativeEnv(packages, opts = {}) {
         GI_TYPELIB_PATH: prepend(env['GI_TYPELIB_PATH'], giSeparator),
     };
     out[libVarKey] = prepend(env[libVarKey], libSeparator);
+    // The host's own GI libdirs — see the block comment above. `systemGiLibraryDirs`
+    // is itself `[]` off darwin, so this is a no-op elsewhere without a second
+    // platform test; the variable is only WRITTEN when there is something to put in
+    // it, so a Mac with no GI stack installed is left byte-unchanged.
+    const systemDirs = (opts.systemGiDirs ?? systemGiLibraryDirs)({ platform, env });
+    if (systemDirs.length > 0) {
+        const inherited = splitSearchPath(env[DYLD_FALLBACK_VAR]);
+        out[DYLD_FALLBACK_VAR] = [...systemDirs, ...(inherited.length > 0 ? inherited : ['/usr/lib'])].join(':');
+    }
     return out;
 }

package/lib/utils/install-backend-native.d.ts

@@ -5,7 +5,13 @@ interface ParsedSpec {
     name: string;
     range: string;
 }
-interface ResolvedNode {
+/**
+ * One placed package in the resolved tree. Exported as a TYPE only: it is the
+ * graph shape {@link computeOptionalFlags} and {@link applyPlatformFilter} take,
+ * so a spec can inject a tree by hand instead of driving a whole install to reach
+ * them. Nothing outside this module constructs one for real.
+ */
+export interface ResolvedNode {
     /** Package name (e.g. `@gjsify/cli`, `lodash`). */
     name: string;
     version: string;
@@ -133,6 +139,78 @@ export declare function applyPlatformFilter(nodes: ResolvedNode[], target: Platf
  * detection — no script is run, so node-free-ness is preserved.
  */
 export declare function warnMissingNativeBuilds(nodes: ResolvedNode[], prefix: string, log: Logger): void;
+/**
+ * A node's REQUIRED dependency edges: its `dependencies`, minus every name its
+ * `optionalDependencies` also lists. The one place that decides what kind an edge
+ * is — both the resolve walk and the optionality fixpoint read it, so the two
+ * cannot drift.
+ *
+ * THE SUBTRACTION IS npm's RULE, not a policy of ours: "entries in
+ * optionalDependencies will override entries of the same name in dependencies, so
+ * it's usually best to only put in one place" (npm's package.json docs). Measured
+ * on `@parcel/rust@2.16.4`, which lists all eight per-platform napi packages in
+ * both blocks: `npm install` exits 0, installs `@parcel/rust-linux-x64-gnu` only,
+ * and writes `"optional": true` for all eight in its `package-lock.json`.
+ *
+ * WHY IT IS NOT MERELY A DEDUP: the kind decides what an incompatible
+ * `os`/`cpu`/`libc` MEANS (`applyPlatformFilter` — fatal vs. inert) and whether a
+ * failed resolve is tolerated. Reading `dependencies` alone therefore does not
+ * just visit a name twice, it promotes a foreign-platform binary to a required
+ * dependency and fails installs npm completes.
+ *
+ * The inverse direction is deliberately NOT symmetric: a name in
+ * `optionalDependencies` alone is optional (no `dependencies` entry to override),
+ * which is what {@link resolveDeps}'s second queue loop covers.
+ */
+export declare function requiredDepEntries(node: Pick<ResolvedNode, 'dependencies' | 'optionalDependencies'>): [string, string][];
+/**
+ * Recompute every node's `optional` flag as a FIXPOINT over the placed graph.
+ * The only writer of the final flag; whatever the nodes arrive carrying is an
+ * input nothing checked (a BFS forward guess on the resolve path, a value read
+ * back out of a file on the lockfile path) and is overwritten unconditionally.
+ *
+ * DEFINITION: a node is REQUIRED iff it is reachable from `requiredNames`
+ * through REQUIRED edges alone ({@link requiredDepEntries} — `dependencies` minus
+ * the names `optionalDependencies` overrides); every other node is optional.
+ * Optionality is therefore INHERITED — a plain dependency OF an optional package
+ * is still optional — which is what npm's `optionalSet` computes.
+ *
+ * WHY A FIXPOINT AND NOT A ONE-SHOT PROMOTION AT THE REUSE SITE (the reviewed
+ * defect): the walk queues a node's own dep edges at the moment it is placed,
+ * carrying the optionality it had THEN. Promoting the node later leaves its
+ * children behind, so the answer depends on which edge BFS happened to traverse
+ * first — a genuinely required transitive dep reached first through an optional
+ * edge stayed flagged optional, was persisted that way, and was then silently
+ * skipped by the platform filter on every machine instead of raising
+ * EBADPLATFORM. A monotone worklist over the FINISHED graph cannot have that
+ * property: "required" only ever spreads, so the result is independent of visit
+ * order. npm reaches for the same shape and says so —
+ * refs/npm-cli/workspaces/arborist/lib/calc-dep-flags.js: "If a node is changed,
+ * we add to the queue and continue until no more changes."
+ *
+ * PATH-INDEPENDENCE IS THE OTHER REQUIREMENT, and it is why the lockfile carries
+ * an `optionalDependencies` map per entry (v4). The walk USED to read
+ * `dependencies` only, for exactly that reason — a lockfile entry recorded nothing
+ * else, so consulting `node.optionalDependencies` would have made the two paths
+ * compute different flags for the same tree. The premise was fixable and the
+ * consequence was not: a publisher listing the same name in BOTH blocks means
+ * "optional" to npm, came out REQUIRED here, and the shape is not rare — it is
+ * `@parcel/rust@2.16.4` (all eight per-platform napi packages in both blocks), so
+ * every Linux install of any tree containing parcel failed with EBADPLATFORM on
+ * `@parcel/rust-darwin-x64` while `npm install` thinned the same tree and exited
+ * 0. "Erring toward REQUIRED errs toward the loud failure" is true and was the
+ * wrong trade: the loud failure was not a real one, and no `--force` lifts it
+ * (nor should it). So the declaration is persisted and both paths subtract it.
+ * Reading a pre-v4 lockfile leaves the map empty, which reproduces the old
+ * behaviour for that file alone — see READABLE_LOCKFILE_VERSIONS.
+ *
+ * Runs before `writeLockfile` so the persisted flag is the final one, and before
+ * `applyPlatformFilter` so the fatal-vs-inert decision reads it rather than the
+ * guess. Exported so the unit spec can drive it with INJECTED graphs: the whole
+ * fatal-vs-inert question is decided by these two functions in composition, and
+ * that is worth pinning without a registry.
+ */
+export declare function computeOptionalFlags(nodes: ResolvedNode[], requiredNames: Set<string>, log: Logger): void;
 export declare function parseSpec(raw: string): ParsedSpec;
 export declare function pickVersion(packument: Packument, range: string, preferred?: string): string | null;
 /**

package/lib/utils/install-backend-native.js

@@ -22,9 +22,9 @@
 // reported. So the DECLARATIONS are locked and the VERDICT is recomputed per
 // host at install time (see applyPlatformFilter).
 //
-// TWO INVARIANTS MAKE THAT CLAIM TRUE, and both are structural rather than
-// documented, because the first draft of this feature broke both while reading
-// as if it did not:
+// THREE INVARIANTS MAKE THAT CLAIM TRUE, and each is structural rather than
+// documented, because the first draft of this feature broke the first two while
+// reading as if it did not — and shipped without the third:
 //
 //   1. THE RESOLVE IS TARGET-BLIND. `resolveDeps` is not given the platform
 //      target at all — it cannot be, so it cannot record a target-dependent
@@ -47,6 +47,31 @@
 //      fixpoint for the same reason (refs/npm-cli/workspaces/arborist/lib/
 //      calc-dep-flags.js: "If a node is changed, we add to the queue and
 //      continue until no more changes").
+//   3. OPTIONALITY BELONGS TO THE EDGE, NOT TO THE BLOCK THE NAME WAS READ FROM.
+//      A name listed in BOTH `dependencies` and `optionalDependencies` is
+//      OPTIONAL: "entries in optionalDependencies will override entries of the
+//      same name in dependencies" (npm's package.json docs), which is why every
+//      walk over a node's dep edges here goes through {@link requiredDepEntries}
+//      instead of `Object.keys(node.dependencies)`. `@parcel/rust@2.16.4` is why
+//      it is written down: it declares all eight of its per-platform napi
+//      packages in both blocks, so a `dependencies`-only walk made
+//      `@parcel/rust-darwin-x64` REQUIRED and every Linux install of any tree
+//      containing parcel died with EBADPLATFORM — while `npm install` on the same
+//      manifest exits 0, installs
+//      `@parcel/rust-linux-x64-gnu`, and records the other seven as
+//      `"optional": true` in its own lockfile. The rule was already applied to
+//      swallowed resolve failures (`assertRequiredEdgesResolved`: "optionality
+//      lives on the edge, not on its endpoints") and missing from the two walks
+//      that decide fatal-vs-inert, which is the worst place to have half of it.
+//      It costs a lockfile field (`optionalDependencies` per entry, v4): without
+//      it the fresh-resolve path and the lockfile path would disagree about the
+//      same tree, which is the split invariant 2 exists to close.
+//      WHY THE DEFECT LOOKED LIKE IT DID NOT EXIST: the same napi shape is
+//      overwhelmingly published in ONE block — measured on the latest of `oxlint`,
+//      `esbuild` and `rollup`, all three list their per-platform bindings in
+//      `optionalDependencies` only (zero overlap), so they installed correctly
+//      throughout and every mock corpus reaches for that shape too. The block a
+//      publisher chooses is not a property this installer may assume.
 //
 // Out of scope (still deferred): peerDependencies validation,
 // lifecycle scripts, git/file specs.
@@ -74,9 +99,12 @@ const LOCKFILE_NAME = 'gjsify-lock.json';
 /**
  * v3 adds the per-entry platform declaration (`os`/`cpu`/`libc`) plus
  * `optional`, which together let a foreign-platform package be recorded without
- * being installed. v2 lockfiles are still READ (see {@link readLockfile}).
+ * being installed. v4 adds the per-entry `optionalDependencies` map, without
+ * which the optionality fixpoint cannot see WHICH of an entry's edges are
+ * optional and a name declared in both blocks comes out required (header note,
+ * invariant 3). Older lockfiles are still READ (see {@link readLockfile}).
  */
-const LOCKFILE_VERSION = 3;
+const LOCKFILE_VERSION = 4;
 /**
  * Lockfile versions this CLI can read. A v2 lockfile is a valid pin set that
  * simply predates the platform fields; rejecting it (the old
@@ -84,8 +112,19 @@ const LOCKFILE_VERSION = 3;
  * the following fresh resolve bump every `^`-range to the newest in-range
  * version — the exact silent churn lockfile preservation exists to prevent, on
  * every user's first install after upgrading the CLI.
+ *
+ * READING an older file is not the same as TRUSTING it for everything: only the
+ * current version short-circuits the resolve (see the branch below), so a v2/v3
+ * file seeds version preservation and is then rewritten. `--immutable` is the one
+ * path that must consume what it was handed verbatim, so there — and only there —
+ * a pre-v4 file keeps its pre-v4 edge fidelity: a both-blocks optional dep is
+ * judged required, exactly as before this fix. That is a strictly unchanged
+ * outcome rather than a new failure, and one plain `gjsify install` upgrades the
+ * file. Failing `--immutable` on an old-but-readable lockfile instead would break
+ * every CI whose committed file predates this CLI, including this repo's own
+ * (still v2).
  */
-const READABLE_LOCKFILE_VERSIONS = new Set([2, LOCKFILE_VERSION]);
+const READABLE_LOCKFILE_VERSIONS = new Set([2, 3, LOCKFILE_VERSION]);
 export async function installPackagesNative(opts) {
     // Fail clearly on an unsupported Node major BEFORE touching the ABI-locked
     // native deps — otherwise they SIGSEGV mid-extract with no actionable message.
@@ -161,11 +200,18 @@ async function installPackagesNativeLocked(opts, npmrc, log) {
     else {
         // A resolve has to run (new/changed/removed dep, or no lockfile yet).
         //
-        // A pre-v3 lockfile lands here too, even when it matches the request:
-        // its entries carry no platform declarations, so consuming it verbatim
-        // would keep installing the foreign-platform tree forever with nothing
-        // on disk to recompute the verdict from. One resolve — version-
-        // preserving, per the seeding below, so nothing bumps — upgrades it.
+        // A pre-v4 lockfile lands here too, even when it matches the request,
+        // because each bump added something the verdict is recomputed FROM and a
+        // file that lacks it cannot be consumed verbatim: pre-v3 entries carry no
+        // platform declaration (so the foreign-platform tree would keep installing
+        // forever), pre-v4 entries carry no `optionalDependencies` map (so a name
+        // declared in both blocks looks required and its incompatible siblings
+        // fail the install — the `@parcel/rust` shape, header note invariant 3).
+        // One resolve — version-preserving, per the seeding below, so nothing
+        // bumps — upgrades the file. That matters beyond tidiness here: the
+        // lockfile is written BEFORE the platform filter runs, so the failing
+        // install left a v3 file behind that would otherwise reproduce its own
+        // EBADPLATFORM on every later run without ever resolving again.
         //
         // Unless --refresh-lockfile was passed, seed it with the versions
         // already pinned in the existing lockfile so unchanged deps keep their
@@ -641,7 +687,13 @@ optionalSpecs) {
                     name: `${edge.name}@${version}`,
                 });
                 if (!skipDeps) {
-                    for (const [depName, depRange] of Object.entries(node.dependencies)) {
+                    // REQUIRED edges only — a name this package also lists in
+                    // `optionalDependencies` is queued by the loop below instead,
+                    // once, as optional (header note, invariant 3). Queuing it here
+                    // as well would place it with a `required: true` forward guess,
+                    // making a resolve failure fatal and (via the fixpoint) its
+                    // incompatible platform siblings fatal too.
+                    for (const [depName, depRange] of requiredDepEntries(node)) {
                         queue.push({
                             from: installPath,
                             name: depName,
@@ -764,6 +816,38 @@ function requiredTopLevelNames(specs, optionalSpecs) {
     }
     return names;
 }
+/**
+ * A node's REQUIRED dependency edges: its `dependencies`, minus every name its
+ * `optionalDependencies` also lists. The one place that decides what kind an edge
+ * is — both the resolve walk and the optionality fixpoint read it, so the two
+ * cannot drift.
+ *
+ * THE SUBTRACTION IS npm's RULE, not a policy of ours: "entries in
+ * optionalDependencies will override entries of the same name in dependencies, so
+ * it's usually best to only put in one place" (npm's package.json docs). Measured
+ * on `@parcel/rust@2.16.4`, which lists all eight per-platform napi packages in
+ * both blocks: `npm install` exits 0, installs `@parcel/rust-linux-x64-gnu` only,
+ * and writes `"optional": true` for all eight in its `package-lock.json`.
+ *
+ * WHY IT IS NOT MERELY A DEDUP: the kind decides what an incompatible
+ * `os`/`cpu`/`libc` MEANS (`applyPlatformFilter` — fatal vs. inert) and whether a
+ * failed resolve is tolerated. Reading `dependencies` alone therefore does not
+ * just visit a name twice, it promotes a foreign-platform binary to a required
+ * dependency and fails installs npm completes.
+ *
+ * The inverse direction is deliberately NOT symmetric: a name in
+ * `optionalDependencies` alone is optional (no `dependencies` entry to override),
+ * which is what {@link resolveDeps}'s second queue loop covers.
+ */
+export function requiredDepEntries(node) {
+    const entries = [];
+    for (const [name, range] of Object.entries(node.dependencies)) {
+        if (name in node.optionalDependencies)
+            continue;
+        entries.push([name, range]);
+    }
+    return entries;
+}
 /**
  * Recompute every node's `optional` flag as a FIXPOINT over the placed graph.
  * The only writer of the final flag; whatever the nodes arrive carrying is an
@@ -771,9 +855,10 @@ function requiredTopLevelNames(specs, optionalSpecs) {
  * back out of a file on the lockfile path) and is overwritten unconditionally.
  *
  * DEFINITION: a node is REQUIRED iff it is reachable from `requiredNames`
- * through `dependencies` edges alone; every other node is optional. Optionality
- * is therefore INHERITED — a plain dependency OF an optional package is still
- * optional — which is what npm's `optionalSet` computes.
+ * through REQUIRED edges alone ({@link requiredDepEntries} — `dependencies` minus
+ * the names `optionalDependencies` overrides); every other node is optional.
+ * Optionality is therefore INHERITED — a plain dependency OF an optional package
+ * is still optional — which is what npm's `optionalSet` computes.
  *
  * WHY A FIXPOINT AND NOT A ONE-SHOT PROMOTION AT THE REUSE SITE (the reviewed
  * defect): the walk queues a node's own dep edges at the moment it is placed,
@@ -788,23 +873,29 @@ function requiredTopLevelNames(specs, optionalSpecs) {
  * refs/npm-cli/workspaces/arborist/lib/calc-dep-flags.js: "If a node is changed,
  * we add to the queue and continue until no more changes."
  *
- * PATH-INDEPENDENCE IS THE OTHER REQUIREMENT, and it is why the walk reads
- * `dependencies` ONLY. A lockfile entry records `dependencies` and nothing else
- * (an `optionalDependencies` map is not persisted), so consulting
- * `node.optionalDependencies` here would make the fresh-resolve path and the
- * lockfile path compute different flags for the same tree — precisely the split
- * this pass exists to close. The cost is one npm quirk we do not reproduce: a
- * publisher listing the same name in BOTH blocks means "optional" to npm, and
- * comes out required here. That shape is vanishingly rare in practice (the
- * platform-binary packages this feature is about — rollup, lightningcss,
- * esbuild, fsevents — all list their optional deps in one block only), and
- * erring toward REQUIRED errs toward the loud failure, not the silent one.
+ * PATH-INDEPENDENCE IS THE OTHER REQUIREMENT, and it is why the lockfile carries
+ * an `optionalDependencies` map per entry (v4). The walk USED to read
+ * `dependencies` only, for exactly that reason — a lockfile entry recorded nothing
+ * else, so consulting `node.optionalDependencies` would have made the two paths
+ * compute different flags for the same tree. The premise was fixable and the
+ * consequence was not: a publisher listing the same name in BOTH blocks means
+ * "optional" to npm, came out REQUIRED here, and the shape is not rare — it is
+ * `@parcel/rust@2.16.4` (all eight per-platform napi packages in both blocks), so
+ * every Linux install of any tree containing parcel failed with EBADPLATFORM on
+ * `@parcel/rust-darwin-x64` while `npm install` thinned the same tree and exited
+ * 0. "Erring toward REQUIRED errs toward the loud failure" is true and was the
+ * wrong trade: the loud failure was not a real one, and no `--force` lifts it
+ * (nor should it). So the declaration is persisted and both paths subtract it.
+ * Reading a pre-v4 lockfile leaves the map empty, which reproduces the old
+ * behaviour for that file alone — see READABLE_LOCKFILE_VERSIONS.
  *
  * Runs before `writeLockfile` so the persisted flag is the final one, and before
  * `applyPlatformFilter` so the fatal-vs-inert decision reads it rather than the
- * guess.
+ * guess. Exported so the unit spec can drive it with INJECTED graphs: the whole
+ * fatal-vs-inert question is decided by these two functions in composition, and
+ * that is worth pinning without a registry.
  */
-function computeOptionalFlags(nodes, requiredNames, log) {
+export function computeOptionalFlags(nodes, requiredNames, log) {
     const byPath = new Map();
     for (const node of nodes)
         byPath.set(node.installPath, node);
@@ -833,7 +924,7 @@ function computeOptionalFlags(nodes, requiredNames, log) {
         const node = byPath.get(installPath);
         if (!node)
             continue;
-        for (const depName of Object.keys(node.dependencies)) {
+        for (const [depName] of requiredDepEntries(node)) {
             // Resolve the edge the way the REQUESTER will at runtime — through
             // the ancestor `node_modules` chain — so a nested copy is credited
             // to the requester that nested it and the hoisted one is not
@@ -904,8 +995,14 @@ function assertRequiredEdgesResolved(nodes, skippedEdges) {
             continue;
         // A REQUIRED package's own optionalDependency stays optional whatever
         // the package's flag says: optionality lives on the edge, not on its
-        // endpoints. This branch is what keeps a darwin-only `fsevents` under a
-        // required `chokidar` from failing every Linux install.
+        // endpoints (header note, invariant 3 — the same rule
+        // {@link requiredDepEntries} applies to the two graph walks). This branch
+        // is what keeps a darwin-only `fsevents` under a required `chokidar` from
+        // failing every Linux install.
+        //
+        // Membership, not `requiredDepEntries`: the failed edge may name something
+        // no longer in `dependencies` at all, and what is being asked here is
+        // whether the requester declared THIS name optional.
         //
         // Safe on both paths because `skippedEdges` is only ever non-empty on
         // the fresh-resolve path, where `optionalDependencies` is populated; the
@@ -1137,6 +1234,11 @@ function writeLockfile(lockfilePath, specs, nodes) {
             resolved: node.tarballUrl,
             integrity: node.integrity,
             dependencies: Object.keys(node.dependencies).length > 0 ? node.dependencies : undefined,
+            // The EDGE KINDS, for the same reason the platform declaration is
+            // here: `computeOptionalFlags` runs on the lockfile path too and
+            // cannot recompute what the file does not carry (v4, header note
+            // invariant 3). Omitted when empty, which is most packages.
+            optionalDependencies: Object.keys(node.optionalDependencies).length > 0 ? node.optionalDependencies : undefined,
             bin: node.bin,
             // The DECLARATION, never the verdict: `inert` is per-host and
             // deliberately absent from the file (a lockfile that recorded which
@@ -1208,7 +1310,12 @@ function lockfileToNodes(lockfile) {
             integrity: entry.integrity,
             installPath,
             dependencies: entry.dependencies ?? {},
-            optionalDependencies: {},
+            // Empty for a pre-v4 entry, which is why such a file never
+            // short-circuits the resolve: with no edge kinds recorded, a name the
+            // publisher put in both blocks reads as required here (the pre-fix
+            // behaviour). `--immutable` is the one path that consumes it anyway —
+            // see READABLE_LOCKFILE_VERSIONS.
+            optionalDependencies: entry.optionalDependencies ?? {},
             bin: entry.bin,
             // Rebuilt from the recorded declaration so `applyPlatformFilter`
             // reaches the SAME verdict on this path as on the fresh-resolve

package/lib/utils/system-gi.d.ts

@@ -0,0 +1,71 @@
+/** Injectable host facts — the darwin branch is testable from Linux. */
+export interface SystemGiOptions {
+    /** `process.platform` value; defaults to the running process. */
+    platform?: string;
+    /** Environment to read `GI_TYPELIB_PATH` / `PKG_CONFIG_PATH` from; defaults to `process.env`. */
+    env?: Record<string, string | undefined>;
+    /** Directory-existence predicate; defaults to a `statSync` probe. */
+    existsDir?: (dir: string) => boolean;
+    /** `pkg-config`'s `.pc` search directories; defaults to {@link pkgConfigSearchDirs}. */
+    searchDirs?: (env: Record<string, string | undefined>) => string[];
+}
+/**
+ * Split an OS search-path variable, dropping empty segments.
+ */
+export declare function splitSearchPath(value: string | undefined, separator?: string): string[];
+/**
+ * `pkg-config`'s OWN configured `.pc` search path plus `$PKG_CONFIG_PATH`. Every
+ * entry is a `<libdir>/pkgconfig` (or `<datadir>/pkgconfig`) directory, so its
+ * parent is a candidate libdir — which is how a prefix nobody hardcoded is
+ * found. Measured on the reported host: `pc_path` =
+ * `/usr/local/lib/pkgconfig:/usr/local/share/pkgconfig:/usr/lib/pkgconfig:…`,
+ * whose first parent is exactly the `/usr/local/lib` that resolves every leaf.
+ *
+ * `spawnSync` reports a missing executable as `result.error`, not by throwing —
+ * an absent `pkg-config` is expected on a runtime-only GTK install, so it is a
+ * checked return value here and not an exception path. (`@gjsify/child_process`
+ * matches Node here deliberately; see its `spawnSync` note.)
+ */
+export declare function pkgConfigSearchDirs(env: Record<string, string | undefined>): string[];
+/**
+ * Directories holding the host's system GObject-Introspection shared libraries —
+ * most specific first, deduplicated, each verified on disk.
+ *
+ * Three sources, in precedence order:
+ *   1. `GI_TYPELIB_PATH` — the host stating outright where typelibs live; the
+ *      libraries are the sibling `dirname()`. Accepted on directory existence
+ *      alone: an explicit statement is not second-guessed.
+ *   2. `pkg-config`'s `.pc` search path → each `<dir>/pkgconfig`'s parent. The
+ *      general mechanism (any prefix, including a custom one).
+ *   3. {@link PROBED_GI_LIBDIRS} — the standard macOS prefixes, for the common
+ *      case where GTK is installed and pkg-config is not.
+ * Sources 2 and 3 are GUESSES at a prefix, so each must show the
+ * `girepository-1.0/` marker before it is believed.
+ *
+ * Empty off darwin, and that is a statement about LOADERS, not about GI. Linux
+ * resolves these leaves through `ld.so`'s system-wide configured cache
+ * (`/etc/ld.so.conf.d`), which a package install populates — nothing per-process
+ * is needed. dyld is the one loader that neither consults a system-wide config
+ * NOR re-reads its search path after launch, which is why darwin needs the
+ * variable set at launch and nobody else does.
+ *
+ * win32 is deliberately absent rather than proven unnecessary: `PATH` is the DLL
+ * search path, a Windows GTK distribution puts its `bin` there itself, and
+ * Windows re-reads that path at every `LoadLibrary` — so if a system GTK ever
+ * turns out not to be on it, the repair is a `PATH` prepend (which
+ * {@link buildNativeEnv} already does for the prebuilds), never a second
+ * variable. Untested there.
+ *
+ * @returns absolute directories, or `[]` when this platform's loader needs none
+ */
+export declare function systemGiLibraryDirs({ platform, env, existsDir, searchDirs, }?: SystemGiOptions): string[];
+/**
+ * Whether `current` (a split `DYLD_FALLBACK_LIBRARY_PATH`) already covers every
+ * directory in `wanted` — the "nothing to do" test.
+ *
+ * Kept in the port even though this CLI's consumer does not branch on it: the
+ * mirror's value is that the two files are the SAME file, and a surface that
+ * drifts by one export is a mirror nobody can check. `system-gi.spec.ts` pins
+ * both.
+ */
+export declare function pathCovers(wanted: readonly string[], current: readonly string[]): boolean;