@opengsd/gsd-core 1.14.0 → 1.16.0

package/gsd-core/bin/lib/ui-frontend-evidence.cjs

@@ -7,7 +7,7 @@
  * word boundary, so a phase section naming the repo `dashboard-financeiro` matches
  * the token `dashboard` exactly like the real UI compound `micro-frontend` does.
  * That boundary rule is intentional (#3718) and must not be weakened — instead,
- * the plan gate (`computeUiPlanGate` in check-command-router.cjs) corroborates the
+ * the plan gate (`computeUiPlanGate` in gate-ui-plan.cjs) corroborates the
  * token match against the static repo tree before blocking.
  *
  * This mirrors what the sibling post-wave gate (`computeUiSafetyGate`) already
@@ -19,23 +19,58 @@
  *       of file layout;
  *   (b) any `*.tsx` / `*.jsx` / `*.vue` / `*.svelte` file in the tree — the
  *       component-framework subset of `UI_FILE_EXTENSIONS_RE`
- *       (check-command-router.cjs). The weaker members of that list (css, scss,
+ *       (gate-ui-safety.cjs). The weaker members of that list (css, scss,
  *       html, ...) are deliberately NOT static evidence: docs sites and
  *       markdown/bash/config repos routinely carry stray `.html`/`.css`, which
  *       is precisely the false-positive class #3312 reports.
+ *   (c) any `*.xaml` file, or a `*.swift` / `*.kt` / `*.dart` file whose
+ *       content carries its ecosystem's UI-framework import marker
+ *       (`import SwiftUI` / `import UIKit`, `androidx.compose`,
+ *       `package:flutter`) (#4658). Native UI projects (SwiftUI, Jetpack
+ *       Compose, Flutter, .NET MAUI) carry neither (a) nor (b), which made the
+ *       gate structurally unreachable for them. Source files match on the
+ *       IMPORT, not the extension alone — the same unambiguity bar that
+ *       justifies (b)'s subset and excludes (css, scss, html): a non-UI Swift
+ *       package (a CLI, a server) imports Foundation, not SwiftUI, and must
+ *       stay silent. `.xaml` is extension-alone for the same reason `.tsx` is —
+ *       the extension itself is unambiguous. Marker matching is case-sensitive
+ *       (imports are case-sensitive in all four ecosystems); extension
+ *       matching is case-insensitive, mirroring `UI_COMPONENT_FILE_RE`.
  *
- * All I/O failures degrade to `false` (no evidence) — never throw.
+ * #5170 (ADR-5057 §4): the detector reads typed evidence. An affirmative finding is
+ * `found`; a walk that completed without one is `none`; a `package.json` that exists but cannot be
+ * read or parsed, a directory that cannot be listed or a native source file that cannot be opened
+ * is `unreadable` WHEN no affirmative evidence was found — the gate that consumes this must not
+ * certify "no frontend" over a tree it could not look at. Never throws.
  */
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.UI_COMPONENT_FILE_RE = void 0;
+exports.NATIVE_UI_CONTENT_MARKERS = exports.NATIVE_UI_XAML_RE = exports.NATIVE_UI_SOURCE_RE = exports.UI_COMPONENT_FILE_RE = void 0;
+exports.readStaticFrontendEvidence = readStaticFrontendEvidence;
 exports.hasStaticFrontendEvidence = hasStaticFrontendEvidence;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
+const gate_evidence_cjs_1 = require("./gate-evidence.cjs");
 /** Component-framework file extensions — the static-evidence subset of UI_FILE_EXTENSIONS_RE. */
 exports.UI_COMPONENT_FILE_RE = /\.(tsx|jsx|vue|svelte)$/i;
+/** Native UI source files whose CONTENT is scanned for an import marker (#4658). */
+exports.NATIVE_UI_SOURCE_RE = /\.(swift|kt|dart)$/i;
+/** Native UI files that are evidence by extension alone — `.xaml`, the `.tsx` analogue. */
+exports.NATIVE_UI_XAML_RE = /\.xaml$/i;
+/**
+ * Per-extension UI-framework import markers for `NATIVE_UI_SOURCE_RE` files
+ * (#4658). Every marker embeds its ecosystem's import keyword, so a bare
+ * framework-name mention in prose or a comment is not evidence; the Dart
+ * marker carries both legal quote styles. Case-sensitive: imports are
+ * case-sensitive in Swift, Kotlin and Dart.
+ */
+exports.NATIVE_UI_CONTENT_MARKERS = {
+    '.swift': ['import SwiftUI', 'import UIKit'],
+    '.kt': ['import androidx.compose'],
+    '.dart': ["import 'package:flutter", 'import "package:flutter'],
+};
 /**
  * UI-framework package.json dependencies (dependencies OR devDependencies).
  * Component frameworks/renderers only — deliberately excludes meta tooling
@@ -82,23 +117,23 @@ const SKIP_DIRS = new Set([
 ]);
 /** Walk safety cap — beyond this the tree is treated as scanned (evidence decided by then). */
 const MAX_WALK_ENTRIES = 10_000;
-function packageJsonHasUiFramework(projectDir) {
-    let raw;
-    try {
-        raw = node_fs_1.default.readFileSync(node_path_1.default.join(projectDir, 'package.json'), 'utf8');
-    }
-    catch {
-        return false; // no/unreadable package.json → no evidence from this signal
-    }
+/** The first read failure of the package.json signal: `unreadable`, or `none` (absent), or `found`. */
+function packageJsonEvidence(projectDir) {
+    const read = (0, gate_evidence_cjs_1.readTextEvidence)(node_path_1.default.join(projectDir, 'package.json'));
+    if (read.kind === 'none')
+        return (0, gate_evidence_cjs_1.evidenceNone)();
+    if (read.kind === 'unreadable')
+        return (0, gate_evidence_cjs_1.evidenceUnreadable)(read.reason, read.span);
     let parsed;
     try {
-        parsed = JSON.parse(raw);
+        parsed = JSON.parse(read.value);
     }
-    catch {
-        return false; // malformed package.json → no evidence from this signal
+    catch (err) {
+        // A package.json that exists but is not valid JSON could not be read: unreadable, not "no deps".
+        return (0, gate_evidence_cjs_1.evidenceFromError)(err, 'package.json');
     }
     if (parsed === null || typeof parsed !== 'object')
-        return false;
+        return (0, gate_evidence_cjs_1.evidenceNone)();
     const pkg = parsed;
     for (const field of ['dependencies', 'devDependencies', 'peerDependencies']) {
         const deps = pkg[field];
@@ -106,52 +141,144 @@ function packageJsonHasUiFramework(projectDir) {
             continue;
         for (const name of Object.keys(deps)) {
             if (UI_FRAMEWORK_DEPS.has(name))
-                return true;
+                return (0, gate_evidence_cjs_1.evidenceFound)(true);
         }
     }
-    return false;
+    return (0, gate_evidence_cjs_1.evidenceNone)();
 }
-function treeHasComponentFile(projectDir) {
-    // Iterative BFS — bounded by MAX_WALK_ENTRIES so a pathological tree cannot
-    // stall the gate. Symlinks are never followed (withFileTypes + isDirectory).
+/**
+ * Shared bounded BFS over the project tree — the single home of the walk
+ * semantics both evidence walks depend on: SKIP_DIRS pruning, the
+ * MAX_WALK_ENTRIES entry cap (cap-hit → not found: the tree is treated as
+ * scanned and evidence stays undecided), symlinks never followed
+ * (withFileTypes Dirents). `visit` is called for every regular file with its
+ * name, full path and a `note` for a read failure it met; returning `true`
+ * stops the walk with `found`. A directory that cannot be listed is NOT
+ * silently skipped: it is noted, the walk goes on, and the caller learns that
+ * part of the tree was never seen (an absent directory is just skipped).
+ */
+function walkProjectFiles(projectDir, visit) {
+    let unreadable = null;
+    const note = (reason) => {
+        unreadable = unreadable ?? reason;
+    };
     const queue = [projectDir];
     let visited = 0;
     while (queue.length > 0 && visited < MAX_WALK_ENTRIES) {
         const dir = queue.shift();
-        let entries;
-        try {
-            entries = node_fs_1.default.readdirSync(dir, { withFileTypes: true });
-        }
-        catch {
-            continue; // unreadable directory → skip it
+        const listing = (0, gate_evidence_cjs_1.readDirEntriesEvidence)(dir);
+        if (listing.kind === 'unreadable') {
+            note(listing.reason);
+            continue;
         }
-        for (const entry of entries) {
+        if (listing.kind === 'none')
+            continue; // vanished since it was queued: nothing to see
+        for (const entry of listing.value) {
             visited++;
             if (visited >= MAX_WALK_ENTRIES)
-                return false;
+                return { found: false, unreadable };
             if (entry.isDirectory()) {
                 if (!SKIP_DIRS.has(entry.name))
                     queue.push(node_path_1.default.join(dir, entry.name));
             }
-            else if (entry.isFile() && exports.UI_COMPONENT_FILE_RE.test(entry.name)) {
-                return true;
+            else if (entry.isFile() && visit(entry.name, node_path_1.default.join(dir, entry.name), note)) {
+                return { found: true, unreadable };
             }
         }
     }
-    return false;
+    return { found: false, unreadable };
+}
+function treeComponentFileEvidence(projectDir) {
+    return walkProjectFiles(projectDir, (name) => exports.UI_COMPONENT_FILE_RE.test(name));
+}
+/**
+ * Read at most the first 64 KiB of `file` as evidence (#4658). Import sections live at
+ * the top of a source file, so a bounded prefix read keeps the gate's plan-time cost
+ * profile without reading generated monsters in full.
+ */
+function readPrefixEvidence(file) {
+    let fd;
+    try {
+        fd = node_fs_1.default.openSync(file, 'r');
+    }
+    catch (err) {
+        return (0, gate_evidence_cjs_1.evidenceFromError)(err, file);
+    }
+    try {
+        const bytes = Buffer.alloc(64 * 1024);
+        const read = node_fs_1.default.readSync(fd, bytes, 0, bytes.length, 0);
+        return (0, gate_evidence_cjs_1.evidenceFound)(bytes.toString('utf8', 0, read));
+    }
+    catch (err) {
+        return (0, gate_evidence_cjs_1.evidenceFromError)(err, file);
+    }
+    finally {
+        try {
+            node_fs_1.default.closeSync(fd);
+        }
+        catch {
+            // already closed — the evidence was read (or its failure returned) above
+        }
+    }
+}
+/**
+ * Native-UI walk over the shared bounded BFS (#4658): `.xaml` is evidence by
+ * extension alone; `.swift`/`.kt`/`.dart` are evidence only when the file's
+ * content carries its ecosystem's import marker.
+ */
+function treeNativeUiEvidence(projectDir) {
+    return walkProjectFiles(projectDir, (name, fullPath, note) => {
+        if (exports.NATIVE_UI_XAML_RE.test(name))
+            return true;
+        if (exports.NATIVE_UI_SOURCE_RE.test(name)) {
+            const markers = exports.NATIVE_UI_CONTENT_MARKERS[node_path_1.default.extname(name).toLowerCase()];
+            if (markers == null)
+                return false;
+            const prefix = readPrefixEvidence(fullPath);
+            if (prefix.kind === 'unreadable') {
+                note(prefix.reason);
+                return false;
+            }
+            return prefix.kind === 'found' && markers.some((m) => prefix.value.includes(m));
+        }
+        return false;
+    });
 }
 /**
  * Does the project tree carry static evidence of a frontend?
  *
  * @param projectDir - Absolute path to the project root (the gate's cwd).
- * @returns true when package.json declares a UI-framework dependency or the
- *          tree contains a component-framework file; false otherwise (including
- *          on any I/O failure — evidence must be affirmative).
+ * @returns `found` when package.json declares a UI-framework dependency, the tree
+ *          contains a component-framework file, or the tree contains native UI
+ *          evidence (a `.xaml` file, or a `.swift`/`.kt`/`.dart` file carrying
+ *          its ecosystem's UI import marker — #4658); otherwise `unreadable` when
+ *          any part of the tree or manifest could not be read (the absence of
+ *          evidence is then not established), else `none`. Affirmative evidence
+ *          always wins over a read failure elsewhere.
  */
-function hasStaticFrontendEvidence(projectDir) {
+function readStaticFrontendEvidence(projectDir) {
     if (typeof projectDir !== 'string' || projectDir === '')
-        return false;
-    if (packageJsonHasUiFramework(projectDir))
-        return true;
-    return treeHasComponentFile(projectDir);
+        return (0, gate_evidence_cjs_1.evidenceNone)();
+    let unreadable = null;
+    const manifest = packageJsonEvidence(projectDir);
+    if (manifest.kind === 'found')
+        return manifest;
+    if (manifest.kind === 'unreadable')
+        unreadable = manifest.reason;
+    const components = treeComponentFileEvidence(projectDir);
+    if (components.found)
+        return (0, gate_evidence_cjs_1.evidenceFound)(true);
+    unreadable = unreadable ?? components.unreadable;
+    const native = treeNativeUiEvidence(projectDir);
+    if (native.found)
+        return (0, gate_evidence_cjs_1.evidenceFound)(true);
+    unreadable = unreadable ?? native.unreadable;
+    return unreadable === null ? (0, gate_evidence_cjs_1.evidenceNone)() : (0, gate_evidence_cjs_1.evidenceUnreadable)(unreadable, projectDir);
+}
+/**
+ * The boolean projection of {@link readStaticFrontendEvidence}: true only on affirmative evidence. It
+ * reads nothing itself; a gate that must tell "no frontend" from "could not look" uses the evidence.
+ */
+function hasStaticFrontendEvidence(projectDir) {
+    return readStaticFrontendEvidence(projectDir).kind === 'found';
 }

package/gsd-core/bin/lib/undo-commit-selection.cjs

@@ -0,0 +1,131 @@
+"use strict";
+/**
+ * Undo Commit Selection — issue #4661 (absorbed into epic #4906, Phase 5).
+ *
+ * Pure scope-matching logic for `/gsd:undo --phase N` / `--plan N-M`, replacing
+ * the two hand-rolled `git log --oneline | grep -E ...` pipelines that used to
+ * live in `gsd-core/workflows/undo.md`. Those greps were unanchored substring
+ * matches against a live regex built from unvalidated user input — four
+ * documented bug classes (see #4661):
+ *
+ *   1. The id was interpolated raw into an ERE: `.` and `+` are live
+ *      metacharacters there, so a malformed or merely differently-shaped id
+ *      silently matched the WRONG phase.
+ *   2. The grep was unanchored, so a commit that only MENTIONS a scope
+ *      (`docs(99-01): explain feat(03-01): commit convention`) was wrongly
+ *      selected as a DECLARATION of it.
+ *   3. Phase-mode's `\):` suffix and plan-mode's missing suffix disagreed on
+ *      the same commit (`feat(03-01)!: breaking change`).
+ *   4. The "obvious" fix — anchoring `git log --oneline`'s record start —
+ *      is a trap: it silently drops `fixup! ...` / `Revert "..."` wrapper
+ *      commits (a worse failure, a silent partial revert) and returns zero
+ *      matches under `color.ui=always` (ANSI codes precede the sha).
+ *
+ * This module closes all four by parsing each commit subject through the
+ * SAME anchored conventional-commit grammar the changelog/PR-title gate uses
+ * (`HEADER_RE`, reused verbatim from `scripts/release-notes/conventional-title.cjs`
+ * — see the require() below), then comparing the extracted scope to the
+ * caller-supplied target id by exact STRING EQUALITY. No regex is built from
+ * user input at any point past `validatePhaseNumber` (src/security.cts),
+ * which the CLI caller (`gsd-tools.cjs query select-revert-commits`) runs
+ * BEFORE this module ever sees the id.
+ *
+ * Deliberately no `fs`/`child_process` in this file: it operates purely on
+ * `{sha, subject}` records the caller already fetched (e.g. via `git log
+ * --format=%H%x00%s`), so it is unit-testable without touching git or the
+ * filesystem.
+ *
+ * KNOWN LIMIT (documented, not a defect): `unwrapSubject` unwraps ONE level
+ * of a `fixup! `/`squash! `/`Revert "..."` wrapper. A doubly-wrapped subject
+ * (e.g. `Revert "fixup! feat(03-01): work"`) is treated as unparseable (no
+ * declared scope) after that single unwrap — it is NOT selected, never
+ * mis-selected. This bounds the module to the wrapper shapes git itself
+ * produces (`fixup!`/`squash!` from `--fixup`/`--squash`, `Revert "..."` from
+ * `git revert`), each of which wraps a single ordinary commit subject, not
+ * another wrapper.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.selectCommitsByDeclaredScope = selectCommitsByDeclaredScope;
+const node_path_1 = __importDefault(require("node:path"));
+// Reuse the exact HEADER_RE the changelog classifier and PR-title CI gate
+// already depend on (#1549) — never fork a second copy of this grammar. A
+// bare `require()` (not a TS `import ... = require(...)`) is used
+// deliberately: `scripts/` sits outside this build's `rootDir` ("src", see
+// tsconfig.build.json) and carries no `.d.ts`, so a type-checked import-equals
+// would fail module resolution (TS7016) under `strict`/`noImplicitAny`. A
+// plain `require()` resolves through Node's ambient `NodeRequire` type
+// (`(id: string) => any`) instead, sidestepping that check entirely — the
+// cast below is the only place the resulting shape is asserted.
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const conventionalTitle = require(node_path_1.default.resolve(__dirname, '..', '..', '..', 'scripts', 'release-notes', 'conventional-title.cjs'));
+const { HEADER_RE } = conventionalTitle;
+// ─── Subject unwrapping (Known limit: exactly ONE level) ──────────────────
+const FIXUP_PREFIX = 'fixup! ';
+const SQUASH_PREFIX = 'squash! ';
+const REVERT_RE = /^Revert "(.*)"$/;
+/**
+ * Strip exactly one `fixup! `/`squash! `/`Revert "..."` wrapper layer off a
+ * commit subject, returning the (possibly) unwrapped remainder. Never
+ * recurses — a doubly-wrapped subject is returned with only its outermost
+ * layer removed, which is intentionally still unparseable by `HEADER_RE` (see
+ * module doc comment).
+ */
+function unwrapSubject(subject) {
+    if (subject.startsWith(FIXUP_PREFIX))
+        return subject.slice(FIXUP_PREFIX.length);
+    if (subject.startsWith(SQUASH_PREFIX))
+        return subject.slice(SQUASH_PREFIX.length);
+    const revertMatch = REVERT_RE.exec(subject);
+    if (revertMatch)
+        return revertMatch[1];
+    return subject;
+}
+/**
+ * Parse a (possibly wrapped) commit subject into its declared conventional-
+ * commit scope, or `null` when the subject carries no parseable scope: no
+ * clean `type[(scope)][!]:` header at all, or a header with no `(scope)`
+ * group. Never regex-matches against untrusted `targetId` — this function
+ * only ever consumes the commit's OWN subject text.
+ */
+function parseDeclaredScope(subject) {
+    const unwrapped = unwrapSubject(subject);
+    const m = HEADER_RE.exec(unwrapped);
+    if (!m)
+        return null;
+    const scopeWithParens = m[2]; // e.g. "(03-01)" — includes parens, or undefined
+    if (!scopeWithParens)
+        return null;
+    // HEADER_RE's scope group is `\([^)]*\)` — always at least the two paren
+    // characters when present, so slicing them off is safe unconditionally.
+    return scopeWithParens.slice(1, -1);
+}
+/**
+ * Select commits whose DECLARED conventional-commit scope identifies
+ * `targetId`, by exact string equality (`'plan'` mode) or exact-or-phase-
+ * prefixed equality (`'phase'` mode). `targetId` is assumed ALREADY
+ * VALIDATED/NORMALIZED by the caller (e.g. via `validatePhaseNumber` from
+ * `src/security.cts`) — this function performs no validation of its own, and
+ * never builds a regex from it (string equality / `startsWith` only), so a
+ * malformed or metacharacter-laden `targetId` cannot cause a wildcard-style
+ * over-match the way the retired grep pipelines could.
+ */
+function selectCommitsByDeclaredScope(commits, targetId, mode = 'plan') {
+    const phasePrefix = `${targetId}-`;
+    const classified = commits.map(({ sha, subject }) => {
+        const parsedScope = parseDeclaredScope(subject);
+        let matched = false;
+        if (parsedScope !== null) {
+            matched = mode === 'phase'
+                ? parsedScope === targetId || parsedScope.startsWith(phasePrefix)
+                : parsedScope === targetId;
+        }
+        return { sha, subject, parsedScope, matched };
+    });
+    const selected = classified
+        .filter((c) => c.matched)
+        .map(({ sha, subject }) => ({ sha, subject }));
+    return { selected, classified };
+}

package/gsd-core/bin/lib/vendor/README.md

@@ -1,7 +1,7 @@
 # vendor/
 
-This directory holds **verbatim, unmodified** copies of third-party build
-artifacts that `gsd-core/bin/**` needs at runtime.
+This directory holds third-party artifacts that `gsd-core/bin/**` needs at
+runtime: verbatim upstream builds or reproducible bundles of unmodified upstream code.
 
 ## Why
 
@@ -15,6 +15,19 @@ in-tree instead of depending on it being installed as an npm package.
 
 ## Contents
 
+- `tap-parser.cjs` and `saxes.cjs` — standalone CJS bundles built with pinned
+  esbuild from the exact devDependency versions and their lockfile dependencies.
+  The TAP and JUnit adapters use these for report grammar and diagnostics.
+  `scripts/lib/vendor-bundle.cjs` rejects external imports other than Node
+  builtins; `lint-vendored-deps.cjs` rebuilds in memory and byte-compares both
+  code and companion `.LICENSE.txt` notices. Refresh with
+  `npm run lint:vendored-deps -- --fix`.
+  `tap-parser`'s npm metadata says BlueOak-1.0.0 while its shipped LICENSE says
+  MIT; the notices preserve both the metadata and the actual license text.
+  saxes 6.0.0 omits LICENSE from npm, so the tagged upstream license is preserved
+  verbatim in `scripts/lib/vendor-licenses/saxes-6.0.0.txt` and included in the
+  generated notices. Neither package's source is patched.
+
 - `re2js.cjs` — verbatim copy of `node_modules/re2js/build/index.cjs`
   (upstream package `re2js`, pinned version see `package.json`
   `devDependencies.re2js`). Used by `src/pattern.cts` (compiled to
@@ -30,12 +43,19 @@ in-tree instead of depending on it being installed as an npm package.
   `require()` calls of its own, and exposes `load`/`dump`/`FAILSAFE_SCHEMA`/
   `YAMLException`.
 
-## Two kinds of type twin
+## Type twins
+
+The bundled parsers use **upstream-reference** twins: declaration-only
+`export * from '<package>';` files under `src/vendor/`. TypeScript reads the
+actual upstream declarations during the build, with no hand-maintained API
+copy and no bare runtime import. The vendoring guard checks the exact forwarding
+declaration. The installed runtime needs only the bundled JavaScript.
 
 Each vendored package needs a `.d.cts` under `src/vendor/` so TypeScript can
 resolve types for a relative `./vendor/<pkg>.cjs` import from `src/**`
 (module resolution for a `.cts` source is relative to `src/`, not the
-compiled output dir). There are two kinds:
+compiled output dir). Besides the upstream-reference twins above, the prebuilt
+upstream artifacts use one of two kinds:
 
 - **upstream-verbatim** (`re2js.d.cts`) — a byte-for-byte copy of an
   upstream `.d.cts`/`.d.ts` that ships with the package. Both the
@@ -54,8 +74,8 @@ compiled output dir). There are two kinds:
 
 ## Do not hand-edit
 
-These files are **verbatim** copies of upstream build output. Never edit
-them directly — refresh them from `node_modules` instead:
+Never edit these artifacts directly. Refresh bundled packages through the
+vendoring command above. Refresh the prebuilt upstream artifacts as follows:
 
 ```
 cp node_modules/re2js/build/index.cjs gsd-core/bin/lib/vendor/re2js.cjs
@@ -68,8 +88,10 @@ cp node_modules/js-yaml/dist/js-yaml.js gsd-core/bin/lib/vendor/js-yaml.cjs
 ```
 
 `node scripts/lint-vendored-deps.cjs` fails CI if any vendored copy drifts
-byte-for-byte from its `node_modules` upstream, from its own source-side
-type twin (upstream-verbatim twins only), or from the version pinned in
+byte-for-byte from its `node_modules` upstream (for a bundled package: from
+an in-memory rebuild of the bundle and its license notices), from its own
+source-side type twin (upstream-verbatim twins only; an upstream-reference
+twin must be the exact forwarding declaration), or from the version pinned in
 `package.json` `devDependencies`. It is table-driven (`VENDORED` in that
-script) — adding a third vendored package means adding a row, not a second
+script) — adding a vendored package means adding a row, not another
 hardcoded check block (ADR-3473 §8.3, "one implementation per rule").