@orkestrel/scaffold 0.0.107 → 0.0.109

package/dist/src/core/index.d.ts

@@ -132,7 +132,7 @@ export declare const ARTIFACT_TEMPLATES: Readonly<{
         entry: "import * as entry from {{specifier}}\nimport { describe, expect, it } from 'vitest'\n\ndescribe({{label}}, () => {\n\tit('has no starter exports', () => {\n\t\texpect(Object.keys(entry)).toStrictEqual([])\n\t})\n})\n";
         bin: "import { describe, expect, it } from 'vitest'\n\ndescribe('bin entry', () => {\n\tit('has no starter exports', async () => {\n{{import}}\n\t\texpect(Object.keys(entry)).toStrictEqual([])\n\t})\n})\n";
         distribution: Readonly<{
-            module: "{{types}}import type { SpawnSyncReturns } from 'node:child_process'\nimport type { TestContext } from 'vitest'\nimport { spawnSync } from 'node:child_process'\nimport {\n\texistsSync,\n\tmkdirSync,\n\tmkdtempSync,\n\treaddirSync,\n\treadFileSync,\n\trmSync,\n\tstatSync,\n\twriteFileSync,\n} from 'node:fs'\n{{transport}}import { createRequire } from 'node:module'\nimport { tmpdir } from 'node:os'\nimport { dirname, join, relative as relativePath, resolve, sep } from 'node:path'\nimport { fileURLToPath, pathToFileURL } from 'node:url'\nimport { isDeepStrictEqual } from 'node:util'\nimport { parseSync } from 'vite'\n{{launcher}}\n/** Defines the lifecycle and installed consumer read by a distribution proof. */\nexport interface DistributionSuiteInterface {\n\treadonly scratch: string\n\tstart(): void\n\tread(context: TestContext): DistributionStage\n\tdestroy(): void\n}\n\n/** Holds the observed and required values for one distribution assertion. */\nexport interface DistributionObservation {\n\treadonly actual: unknown\n\treadonly expected: unknown\n}\n\n/** Defines one independently registered distribution observation. */\nexport interface DistributionCase {\n\treadonly label: string\n\treadonly observe: (\n\t\tcontext: TestContext,\n\t) => DistributionObservation | Promise<DistributionObservation>\n}\n\n/** Holds the installed export map's classified publications. */\nexport interface DistributionClassification {\n\treadonly entries: readonly DistributionEntry[]\n\treadonly subpaths: readonly string[]\n\treadonly undeclared: readonly string[]\n\treadonly excluded: readonly string[]\n\treadonly targets: readonly string[]\n}\n\n/** Names the workspace whose packed artifact the proof consumes. */\nexport const DISTRIBUTION_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..')\n/** Names the npm executable on the running host. */\nexport const DISTRIBUTION_NPM = process.platform === 'win32' ? 'npm.cmd' : 'npm'\n// The compiler this workspace installs, run as a command rather than called in\n// process: the command and its plain-text diagnostics are the same across the\n// compiler majors this toolchain supports, and its in-process API is not. It is\n// resolved from the workspace under proof, so a consumer of the packed artifact is\n// checked by the same compiler that workspace's own `check` script runs.\n/** Names the compiler installed by the workspace under proof. */\nexport const DISTRIBUTION_COMPILER = createRequire(join(DISTRIBUTION_ROOT, 'package.json')).resolve(\n\t'typescript/bin/tsc',\n)\n// Windows needs a shell to launch a `.cmd`: Node refuses one directly since the\n// batch-argument hardening, and `spawnSync` returns `EINVAL` with a null status\n// rather than an exit code a caller can read. Every following argument is a literal or\n// a path this file built, so the shell has nothing to escape.\n/** Selects the Windows command-shell route required by the npm shim. */\nexport const DISTRIBUTION_SHELL = process.platform === 'win32'\n// `prepublishOnly` runs this proof as `npm run test:distribution -- --mode release`,\n// and the root configuration's project factories carry that mode into this project.\n// Release is the publish gate, so evidence it cannot obtain fails there and skips\n// everywhere else: a gate that passes on missing evidence proves nothing.\n/** Indicates whether missing prerequisites must fail the publish gate. */\nexport const DISTRIBUTION_RELEASE = import.meta.env?.MODE === 'release'\n// The built output directory convention a browser face may publish from. Every\n// selection reads this prefix off the export target and never off the subpath name. A\n// workspace whose only published face is the browser one publishes that face at the\n// root subpath, so a rule keyed on the subpath name drives a browser bundle through\n// Node and the miss is silent.\n/** Names the conventional output prefix for a browser publication. */\nexport const DISTRIBUTION_BROWSER_OUTPUT = './dist/src/browser/'\n/** Names the unpublished subpath used as a resolution control. */\nexport const DISTRIBUTION_ABSENT_SUBPATH = '/no-subpath-is-published-under-this-name'\n// A compiler diagnostic that says where it is: the path relative to the directory\n// the compiler ran in, the 1-based line and column, the code, and the message. The\n// diagnostics are the verdict rather than the exit code, which differs between the\n// compiler majors this toolchain supports, so a reported line matching nothing here\n// came from something other than a check of a consumer module.\n/** Matches the location prefix of a consumer compiler diagnostic. */\nexport const DISTRIBUTION_DIAGNOSTIC_PATTERN = /^(.+?)\\(\\d+,\\d+\\): error TS\\d+: /u\n/** Lists the bounded registry-readiness command arguments. */\nexport const DISTRIBUTION_PING = Object.freeze([\n\t'ping',\n\t'--fetch-retries=0',\n\t'--fetch-timeout=5000',\n\t'--loglevel=silent',\n])\n/** Names the consumer entry that imports an installed module. */\nexport const DISTRIBUTION_ESM_DRIVER = 'drive.mjs'\n/** Names the consumer entry that requires an installed module. */\nexport const DISTRIBUTION_CJS_DRIVER = 'drive.cjs'\n/** Defines the isolated consumer package manifest. */\nexport const DISTRIBUTION_CONSUMER_MANIFEST =\n\t'{ \"name\": \"distribution-consumer\", \"private\": true, \"type\": \"module\" }\\n'\n/** Reads the names exported by an installed ESM entry. */\nexport const DISTRIBUTION_ESM_DRIVER_SOURCE = `const entry = await import(process.argv[2])\nprocess.stdout.write(JSON.stringify(Object.keys(entry).sort()))\n`\n/** Reads the names exported by an installed CommonJS entry. */\nexport const DISTRIBUTION_CJS_DRIVER_SOURCE = `const entry = require(process.argv[2])\nprocess.stdout.write(JSON.stringify(Object.keys(entry).sort()))\n`\n\n// The extensions a JavaScript handler loads as modules. Node loads a native addon\n// through its addon handler instead, so that extension is named separately.\n/** Lists extensions loaded as JavaScript modules. */\nexport const DISTRIBUTION_MODULE_EXTENSIONS = Object.freeze(['.js', '.mjs', '.cjs'])\n/** Names the extension loaded by the native-addon handler. */\nexport const DISTRIBUTION_ADDON_EXTENSION = '.node'\n// The extensions a declaration file carries. A `require` condition declares\n// `.d.cts` and an ESM-only one `.d.mts`, so the `.d.ts` spelling alone does not\n// name them.\n/** Lists the supported TypeScript declaration extensions. */\nexport const DISTRIBUTION_DECLARATION_EXTENSIONS = Object.freeze(['.d.ts', '.d.cts', '.d.mts'])\n/** Names the module format of a typed consumer. */\nexport type DistributionFormat = 'module' | 'commonjs'\n\n// The Node import target is resolved with the conditions that driver supplies. The\n// CommonJS compile probe is selected from its declaration's format, and its runtime\n// drive loads the same subpath through Node's require resolver. Vite's production\n// client build enables its module and browser conditions.\n/** Defines the conditions each runtime uses to resolve an entry. */\nexport const DISTRIBUTION_RUNTIME_CONDITIONS = Object.freeze({\n\tmodule: Object.freeze(['node-addons', 'node', 'import', 'module-sync']),\n\tcommonjs: Object.freeze(['node-addons', 'node', 'require', 'module-sync']),\n\tbrowser: Object.freeze(['module', 'browser', 'production', 'import']),\n})\n// TypeScript's Node resolutions add `node` to the format condition. Its bundler\n// resolution does not, so a browser drive compares against the declaration a bundler\n// consumer reads rather than borrowing the Node declaration.\n/** Defines the declaration conditions used by bundler consumers. */\nexport const DISTRIBUTION_BUNDLER_CONDITIONS = Object.freeze({\n\tmodule: Object.freeze(['types', 'import']),\n\tcommonjs: Object.freeze(['types', 'require']),\n})\n/** Defines the declaration conditions paired with each runtime. */\nexport const DISTRIBUTION_DECLARATION_CONDITIONS = Object.freeze({\n\tmodule: Object.freeze(['types', 'node', 'import']),\n\tcommonjs: Object.freeze(['types', 'node', 'require']),\n\tbrowser: DISTRIBUTION_BUNDLER_CONDITIONS.module,\n})\n\n/** Describes the compiler options and conditions for one consumer resolution. */\nexport interface DistributionResolution {\n\treadonly label: string\n\treadonly resolution: string\n\treadonly module: string\n\treadonly conditions: Readonly<Record<DistributionFormat, readonly string[]>>\n}\n\n/** Holds the target selected by package condition resolution. */\nexport interface DistributionTargetResult {\n\treadonly target: string\n}\n\n// Each compile driver carries the compiler options its scratch project sets and\n// the conditions TypeScript applies for that resolution and importing format. A\n// `require`-only subpath therefore stays in each CommonJS probe that can resolve it.\n// The option values are the spellings the project file takes, so nothing here needs\n// the compiler's own API to name them.\n/** Lists the compiler resolutions driven against installed declarations. */\nexport const DISTRIBUTION_RESOLUTIONS: readonly DistributionResolution[] = Object.freeze([\n\t{\n\t\tlabel: 'node16',\n\t\tresolution: 'node16',\n\t\tmodule: 'node16',\n\t\tconditions: DISTRIBUTION_DECLARATION_CONDITIONS,\n\t},\n\t{\n\t\tlabel: 'nodenext',\n\t\tresolution: 'nodenext',\n\t\tmodule: 'nodenext',\n\t\tconditions: DISTRIBUTION_DECLARATION_CONDITIONS,\n\t},\n\t{\n\t\tlabel: 'bundler',\n\t\tresolution: 'bundler',\n\t\tmodule: 'esnext',\n\t\tconditions: DISTRIBUTION_BUNDLER_CONDITIONS,\n\t},\n])\n\n// The driver a bundled consumer reads declarations under. A browser application\n// compiles through a bundler, so the browser drive answers under this one alone,\n// and naming it here is what keeps that selection tied to the driver it selects.\n/** Selects the compiler resolution used by a browser consumer. */\nexport const DISTRIBUTION_BROWSER_RESOLUTION = DISTRIBUTION_RESOLUTIONS.find(\n\t(candidate) => candidate.label === 'bundler',\n)\nif (DISTRIBUTION_BROWSER_RESOLUTION === undefined)\n\tthrow new Error(\"DISTRIBUTION_RESOLUTIONS carries no 'bundler' row\")\n\n/** Pairs consumer source extensions with their module formats. */\nexport const DISTRIBUTION_FORMATS: ReadonlyArray<\n\treadonly [extension: string, format: DistributionFormat]\n> = Object.freeze([\n\t['ts', 'module'],\n\t['cts', 'commonjs'],\n])\n\n// One published subpath, resolved to what this proof can drive: the specifier a\n// consumer writes, whether the declarations its consumer formats resolve at all,\n// whether the exports map answers the browser condition with a target of its own,\n// whether it answers `import` and `require` at all, and whether the target that\n// `require` answers with is one that a CommonJS consumer loads.\n/** Describes one published subpath and its runtime and declaration capabilities. */\nexport interface DistributionEntry {\n\treadonly subpath: string\n\treadonly specifier: string\n\treadonly mapping: unknown\n\treadonly declaration: {\n\t\treadonly importable: boolean\n\t\treadonly requirable: boolean\n\t\treadonly browsable: boolean\n\t}\n\treadonly browsable: boolean\n\treadonly importable: boolean\n\treadonly requirable: boolean\n\treadonly loadable: boolean\n}\n\n// The installed tree every claim is read from. Every subpath the exports map names\n// lands in exactly one of `entries`, `undeclared`, and `excluded`, so a subpath this\n// proof cannot drive is reported rather than dropped.\n/** Holds the installed consumer and the partition of its published subpaths. */\nexport interface DistributionStage {\n\treadonly consumer: string\n\treadonly installed: string\n\treadonly archives: readonly string[]\n\treadonly entries: readonly DistributionEntry[]\n\treadonly subpaths: readonly string[]\n\treadonly undeclared: readonly string[]\n\treadonly excluded: readonly string[]\n\treadonly targets: readonly string[]\n}\n\n/**\n * Checks whether a value is a non-null object other than an array.\n *\n * @param value - The value to inspect.\n * @returns True if the value is a record; false otherwise.\n */\nexport function isDistributionRecord(value: unknown): value is Readonly<Record<string, unknown>> {\n\treturn typeof value === 'object' && value !== null && !Array.isArray(value)\n}\n\n/**\n * Checks whether a value is an array of strings.\n *\n * @param value - The value to inspect.\n * @returns True if every array member is a string; false otherwise.\n */\nexport function isDistributionNames(value: unknown): value is readonly string[] {\n\treturn Array.isArray(value) && value.every((name) => typeof name === 'string')\n}\n\n// A fallback list, which is what Node reads an array in an exports entry as. The\n// narrowing is what the following walkers need: `Array.isArray` widens an `unknown`\n// member to `any`, and an entry read that way is not read at all.\n/**\n * Checks whether a value is a fallback array.\n *\n * @param value - The value to inspect.\n * @returns True if the value is an array; false otherwise.\n */\nexport function isDistributionList(value: unknown): value is readonly unknown[] {\n\treturn Array.isArray(value)\n}\n\n// Whether a string is a valid package target. Node rejects a target outside the\n// package and a target containing a dot, parent, or node_modules segment during\n// package-target resolution. A later module-resolution failure is not the same\n// thing: an array falls through the former and keeps the latter.\n/**\n * Checks whether a relative package target contains only admitted segments.\n *\n * @param target - The package-relative target.\n * @returns True if the target passes package-target validation; false otherwise.\n */\nexport function matchesDistributionPackageTarget(target: string): boolean {\n\tif (!target.startsWith('./')) return false\n\tconst refused = ['.', '..', 'node_modules']\n\treturn target\n\t\t.slice(2)\n\t\t.split(/[\\\\/]/u)\n\t\t.every((segment) => {\n\t\t\ttry {\n\t\t\t\treturn !refused.includes(decodeURIComponent(segment).toLowerCase())\n\t\t\t} catch {\n\t\t\t\treturn !refused.includes(segment.toLowerCase())\n\t\t\t}\n\t\t})\n}\n\n/**\n * Reads and parses a JSON file.\n *\n * @param path - The file to read.\n * @returns The parsed value. Throws when reading or parsing fails.\n */\nexport function readDistributionJSON(path: string): unknown {\n\tconst parsed: unknown = JSON.parse(readFileSync(path, 'utf8'))\n\treturn parsed\n}\n\n/**\n * Reads the package name from a manifest.\n *\n * @param path - The manifest to read.\n * @returns The package name. Throws when the manifest has no string name.\n */\nexport function readDistributionManifestName(path: string): string {\n\tconst manifest = readDistributionJSON(path)\n\tif (!isDistributionRecord(manifest) || typeof manifest.name !== 'string') {\n\t\tthrow new Error(`The manifest at ${path} declares no package name`)\n\t}\n\treturn manifest.name\n}\n\n/**\n * Writes a consumer file after creating its parent directory.\n *\n * @param path - The file to write.\n * @param content - The text to write.\n */\nexport function writeDistributionFile(path: string, content: string): void {\n\tmkdirSync(dirname(path), { recursive: true })\n\twriteFileSync(path, content)\n}\n\n/**\n * Combines the output streams of a completed command.\n *\n * @param result - The completed command.\n * @returns The trimmed diagnostic text.\n */\nexport function readDistributionOutput(result: SpawnSyncReturns<string>): string {\n\treturn `${result.stdout ?? ''}${result.stderr ?? ''}`.trim()\n}\n\n/**\n * Runs npm with a cache inside the owned scratch directory.\n *\n * @param args - The npm arguments.\n * @param cwd - The working directory.\n * @param scratch - The owned scratch root.\n * @returns The command status and captured streams.\n */\nexport function runDistributionNpm(\n\targs: readonly string[],\n\tcwd: string,\n\tscratch: string,\n): SpawnSyncReturns<string> {\n\treturn spawnSync(DISTRIBUTION_NPM, [...args], {\n\t\tcwd,\n\t\tencoding: 'utf8',\n\t\tenv: { ...process.env, npm_config_cache: join(scratch, 'cache') },\n\t\tshell: DISTRIBUTION_SHELL,\n\t\twindowsHide: true,\n\t})\n}\n\n/**\n * Runs a JavaScript entry with the running Node executable.\n *\n * @param args - The Node arguments.\n * @param cwd - The working directory.\n * @returns The command status and captured streams.\n */\nexport function runDistributionNode(\n\targs: readonly string[],\n\tcwd: string,\n): SpawnSyncReturns<string> {\n\treturn spawnSync(process.execPath, [...args], { cwd, encoding: 'utf8', windowsHide: true })\n}\n\n// Node's own condition matching, read in declaration order.\n/**\n * Resolves a package target through conditions and fallback arrays.\n *\n * @param entry - The exports-map entry.\n * @param conditions - The active resolution conditions.\n * @returns The selected target, or undefined when no branch resolves.\n */\nexport function resolveDistributionPackageTarget(\n\tentry: unknown,\n\tconditions: readonly string[],\n): DistributionTargetResult | undefined {\n\tif (typeof entry === 'string') return { target: entry }\n\tif (isDistributionList(entry)) {\n\t\tfor (const member of entry) {\n\t\t\tconst resolved = resolveDistributionPackageTarget(member, conditions)\n\t\t\tif (resolved !== undefined && matchesDistributionPackageTarget(resolved.target))\n\t\t\t\treturn resolved\n\t\t}\n\t\treturn undefined\n\t}\n\tif (!isDistributionRecord(entry)) return undefined\n\tfor (const [condition, nested] of Object.entries(entry)) {\n\t\tif (condition !== 'default' && !conditions.includes(condition)) continue\n\t\tconst resolved = resolveDistributionPackageTarget(nested, conditions)\n\t\tif (resolved !== undefined) return resolved\n\t}\n\treturn undefined\n}\n\n// A flat entry, a condition-nested entry, and a fallback list all resolve through\n// one walker. An entry may declare `types` beside `default` at its top level\n// rather than inside `import`, so a fixed `entry.import.types` lookup is not\n// equivalent to condition resolution.\n/**\n * Resolves the path selected by an exports-map entry.\n *\n * @param entry - The exports-map entry.\n * @param conditions - The active resolution conditions.\n * @returns The selected path, or undefined when no branch resolves.\n */\nexport function resolveDistributionTarget(\n\tentry: unknown,\n\tconditions: readonly string[],\n): string | undefined {\n\treturn resolveDistributionPackageTarget(entry, conditions)?.target\n}\n\n// Whether a path is a physical file. TypeScript's file-existence check refuses a\n// directory at the same spelling and continues to the outer package scope.\n/**\n * Checks whether a path names a physical file.\n *\n * @param path - The filesystem path.\n * @returns True if the path names a file; false otherwise.\n */\nexport function matchesDistributionFile(path: string): boolean {\n\ttry {\n\t\treturn statSync(path).isFile()\n\t} catch {\n\t\treturn false\n\t}\n}\n\n// TypeScript resolves a declaration target by accepting an existing declaration\n// directly or by substituting beside a JavaScript target. A missing target leaves\n// the containing condition or fallback list unresolved, so the walk continues.\n/**\n * Resolves an existing declaration beside a package target.\n *\n * @param target - The package-relative target.\n * @param installed - The installed package root.\n * @returns The declaration target, or undefined when no declaration exists.\n */\nexport function targetToDistributionDeclaration(\n\ttarget: string,\n\tinstalled: string,\n): string | undefined {\n\tif (!matchesDistributionPackageTarget(target)) return undefined\n\tconst declaration = target.endsWith('.cjs')\n\t\t? `${target.slice(0, -4)}.d.cts`\n\t\t: target.endsWith('.mjs')\n\t\t\t? `${target.slice(0, -4)}.d.mts`\n\t\t\t: target.endsWith('.js')\n\t\t\t\t? `${target.slice(0, -3)}.d.ts`\n\t\t\t\t: target\n\tif (declaration === target && !matchesDistributionDeclaration(target)) return undefined\n\treturn matchesDistributionFile(join(installed, declaration)) ? declaration : undefined\n}\n\n// The declaration TypeScript resolves through one importing format's conditions.\n// Condition objects keep manifest order, and arrays keep fallback order.\n/**\n * Resolves an existing declaration through consumer conditions.\n *\n * @param entry - The exports-map entry.\n * @param conditions - The active declaration conditions.\n * @param installed - The installed package root.\n * @returns The declaration target, or undefined when no branch resolves.\n */\nexport function resolveDistributionDeclaration(\n\tentry: unknown,\n\tconditions: readonly string[],\n\tinstalled: string,\n): string | undefined {\n\tif (typeof entry === 'string') return targetToDistributionDeclaration(entry, installed)\n\tif (isDistributionList(entry)) {\n\t\tfor (const member of entry) {\n\t\t\tconst resolved = resolveDistributionDeclaration(member, conditions, installed)\n\t\t\tif (resolved !== undefined) return resolved\n\t\t}\n\t\treturn undefined\n\t}\n\tif (!isDistributionRecord(entry)) return undefined\n\tfor (const [condition, nested] of Object.entries(entry)) {\n\t\tif (condition !== 'default' && !conditions.includes(condition)) continue\n\t\tconst resolved = resolveDistributionDeclaration(nested, conditions, installed)\n\t\tif (resolved !== undefined) return resolved\n\t}\n\treturn undefined\n}\n\n// The nearest package scope that decides a `.d.ts` declaration's module format. A\n// physical nested manifest starts a scope even when it omits `type` or cannot be\n// parsed. A directory at that spelling is not a manifest, so the walk continues.\n/**\n * Reads the nearest package scope for a target inside an installed package.\n *\n * @param installed - The installed package root.\n * @param target - The package-relative target.\n * @returns The manifest type, or undefined when the nearest scope omits it or cannot be read.\n */\nexport function readDistributionPackageType(installed: string, target: string): unknown {\n\t// One `dirname` per path segment reaches the root from any path. The walk ends at the\n\t// installed package, so no scope above it is consulted.\n\tconst start = dirname(join(installed, target))\n\tconst chain = start\n\t\t.split(/[\\\\/]/u)\n\t\t.reduce<string[]>((climbed) => [...climbed, dirname(climbed.at(-1) ?? start)], [start])\n\tconst end = chain.indexOf(installed)\n\tconst scope = chain\n\t\t.slice(0, end === -1 ? chain.length : end + 1)\n\t\t.find((directory) => matchesDistributionFile(join(directory, 'package.json')))\n\tif (scope === undefined) return undefined\n\ttry {\n\t\tconst manifest = readDistributionJSON(join(scope, 'package.json'))\n\t\treturn isDistributionRecord(manifest) ? manifest.type : undefined\n\t} catch {\n\t\treturn undefined\n\t}\n}\n\n/**\n * Checks whether an entry publishes a distinct or conventional browser target.\n *\n * @param entry - The exports-map entry.\n * @returns True if the entry requires a browser drive; false otherwise.\n */\nexport function resolvesDistributionBrowser(entry: unknown): boolean {\n\tconst module = resolveDistributionTarget(entry, DISTRIBUTION_RUNTIME_CONDITIONS.browser)\n\tif (module !== undefined && module.startsWith(DISTRIBUTION_BROWSER_OUTPUT)) return true\n\tif (module === undefined) return false\n\tconst imported = resolveDistributionTarget(entry, DISTRIBUTION_RUNTIME_CONDITIONS.module)\n\tconst required = resolveDistributionTarget(entry, DISTRIBUTION_RUNTIME_CONDITIONS.commonjs)\n\treturn module !== imported && module !== required\n}\n\n// Whether the target selected by Node's CommonJS conditions is a module require can\n// load. A JavaScript target takes its own nearest package scope. Native addons and\n// extensionless targets have their own CommonJS handlers.\n/**\n * Checks whether Node require can load an entry selected by its conditions.\n *\n * @param entry - The exports-map entry.\n * @param installed - The installed package root.\n * @returns True if the target has a CommonJS-compatible format; false otherwise.\n */\nexport function resolvesDistributionCommonJS(entry: unknown, installed: string): boolean {\n\tconst target = resolveDistributionTarget(entry, DISTRIBUTION_RUNTIME_CONDITIONS.commonjs)\n\tif (target === undefined) return false\n\tconst name = target.slice(target.lastIndexOf('/') + 1)\n\tif (name.endsWith('.cjs')) return true\n\tif (name.endsWith('.mjs')) return false\n\tif (name.endsWith('.node')) return true\n\tif (!name.includes('.')) return true\n\treturn name.endsWith('.js') && readDistributionPackageType(installed, target) !== 'module'\n}\n\n// Whether the declaration selected by a typed CommonJS consumer admits that entry.\n// A `.d.cts` declaration admits and a `.d.mts` declaration refuses. A `.d.ts`\n// declaration takes its own nearest package scope.\n/**\n * Checks whether an entry resolves a CommonJS-compatible declaration.\n *\n * @param entry - The exports-map entry.\n * @param installed - The installed package root.\n * @returns True if the selected declaration admits CommonJS consumption; false otherwise.\n */\nexport function declaresDistributionCommonJS(entry: unknown, installed: string): boolean {\n\tconst declaration = resolveDistributionDeclaration(\n\t\tentry,\n\t\tDISTRIBUTION_DECLARATION_CONDITIONS.commonjs,\n\t\tinstalled,\n\t)\n\tif (declaration === undefined) return false\n\tif (declaration.endsWith('.d.cts')) return true\n\tif (declaration.endsWith('.d.mts')) return false\n\treturn (\n\t\tdeclaration.endsWith('.d.ts') &&\n\t\treadDistributionPackageType(installed, declaration) !== 'module'\n\t)\n}\n\n// Every target an entry names under any condition. A fallback list omits members\n// Node rejects during package-target validation, because no reader can take them.\n/**\n * Collects the targets an entry publishes under every condition.\n *\n * @param entry - The exports-map entry.\n * @returns The targets, excluding invalid members of fallback arrays.\n */\nexport function collectDistributionTargets(entry: unknown): readonly string[] {\n\tif (typeof entry === 'string') return [entry]\n\tif (isDistributionList(entry))\n\t\treturn entry.flatMap(collectDistributionTargets).filter(matchesDistributionPackageTarget)\n\tif (!isDistributionRecord(entry)) return []\n\treturn Object.values(entry).flatMap((nested) => collectDistributionTargets(nested))\n}\n\n// Whether a target is a file a runtime loads for its names, which is what a\n// declaration is owed for. The extension on the target's own file name decides it,\n// and a name carrying no extension is code: `require` reads such a file through its\n// JavaScript handler, so an extensionless target loads and publishes names. Node\n// loads `.node` through its native-addon handler. Every other extension is an asset\n// a consumer reads rather than imports — a stylesheet, a WebAssembly binary, the\n// `\"./package.json\"` manifest pointer, and a declaration alike.\n// The cost is an extensionless file published for a reader, such as a `LICENSE`:\n// that target reports undeclared until it is given an extension or a declaration.\n/**\n * Checks whether a target names a runtime module rather than an asset.\n *\n * @param target - The package-relative target.\n * @returns True if the target has a module extension or no extension; false otherwise.\n */\nexport function matchesDistributionModule(target: string): boolean {\n\tconst name = target.slice(target.lastIndexOf('/') + 1)\n\tconst dot = name.lastIndexOf('.')\n\tif (name.endsWith(DISTRIBUTION_ADDON_EXTENSION)) return true\n\treturn dot === -1 || DISTRIBUTION_MODULE_EXTENSIONS.includes(name.slice(dot))\n}\n\n// Whether a resolved target is a declaration rather than the JavaScript a\n// `default` branch answers with when the entry declares no `types` condition.\n/**\n * Checks whether a target names a TypeScript declaration.\n *\n * @param target - The package-relative target.\n * @returns True if the target has a declaration extension; false otherwise.\n */\nexport function matchesDistributionDeclaration(target: string): boolean {\n\treturn DISTRIBUTION_DECLARATION_EXTENSIONS.some((extension) => target.endsWith(extension))\n}\n\n// The declarations the Node module, Node CommonJS, and browser drives compare\n// against. Each field uses the conditions of the TypeScript consumer paired with\n// that runtime. A JavaScript target resolves through TypeScript's adjacent\n// declaration substitution rather than standing in for the declaration itself.\n/**\n * Reads the declarations paired with Node and browser consumers.\n *\n * @param entry - The exports-map entry.\n * @param installed - The installed package root.\n * @returns The declaration selected by each consumer format.\n */\nexport function readDistributionDeclaration(\n\tentry: unknown,\n\tinstalled: string,\n): {\n\treadonly module: string | undefined\n\treadonly commonjs: string | undefined\n\treadonly browser: string | undefined\n} {\n\treturn {\n\t\tmodule: resolveDistributionDeclaration(\n\t\t\tentry,\n\t\t\tDISTRIBUTION_DECLARATION_CONDITIONS.module,\n\t\t\tinstalled,\n\t\t),\n\t\tcommonjs: resolveDistributionDeclaration(\n\t\t\tentry,\n\t\t\tDISTRIBUTION_DECLARATION_CONDITIONS.commonjs,\n\t\t\tinstalled,\n\t\t),\n\t\tbrowser: resolveDistributionDeclaration(\n\t\t\tentry,\n\t\t\tDISTRIBUTION_DECLARATION_CONDITIONS.browser,\n\t\t\tinstalled,\n\t\t),\n\t}\n}\n\n// The entries one compile driver can resolve under its own conditions.\n/**\n * Filters entries to those a consumer can resolve.\n *\n * @param entries - The installed entries.\n * @param conditions - The active consumer conditions.\n * @returns The matching entries in their original order.\n */\nexport function filterDistributionEntries(\n\tentries: readonly DistributionEntry[],\n\tconditions: readonly string[],\n): readonly DistributionEntry[] {\n\treturn entries.filter(\n\t\t(entry) =>\n\t\t\tresolveDistributionTarget(entry.mapping, conditions) !== undefined &&\n\t\t\t(!conditions.includes('require') || entry.loadable),\n\t)\n}\n\n// The compile drivers whose conditions reach one entry under one importing format.\n// A driver that resolves no target for that entry compiles nothing, so a consumer\n// written under it would report a resolution failure this package never made.\n/**\n * Filters compiler resolutions to those that can read an entry.\n *\n * @param entry - The installed entry.\n * @param format - The consumer module format.\n * @returns The matching compiler resolutions.\n */\nexport function filterDistributionResolutions(\n\tentry: DistributionEntry,\n\tformat: DistributionFormat,\n): readonly DistributionResolution[] {\n\treturn DISTRIBUTION_RESOLUTIONS.filter(\n\t\t(driver) => filterDistributionEntries([entry], driver.conditions[format]).length > 0,\n\t)\n}\n\n// Requirable entries that declare CommonJS support but a typed CommonJS consumer\n// cannot compile against. A default branch resolving under the require condition\n// set makes no CommonJS claim.\n/**\n * Filters entries whose require target lacks a compatible declaration.\n *\n * @param entries - The installed entries.\n * @param installed - The installed package root.\n * @returns The entries a CommonJS consumer cannot typecheck.\n */\nexport function filterDistributionUntypable(\n\tentries: readonly DistributionEntry[],\n\tinstalled: string,\n): readonly DistributionEntry[] {\n\treturn entries.filter(\n\t\t(entry) =>\n\t\t\tentry.requirable &&\n\t\t\tisDistributionRecord(entry.mapping) &&\n\t\t\tObject.hasOwn(entry.mapping, 'require') &&\n\t\t\t!declaresDistributionCommonJS(entry.mapping, installed),\n\t)\n}\n\n// One surface comparison, written as the consumer module that proves it: the\n// installed entry that consumer imports, the file extension fixing its importing\n// format, the names a real runtime published off it, and the driver whose scratch\n// project compiles it.\n/** Describes the runtime names and declaration resolution compared for one entry. */\nexport interface DistributionSurface {\n\treadonly entry: DistributionEntry\n\treadonly extension: string\n\treadonly published: readonly string[]\n\treadonly driver: DistributionResolution\n}\n\n// A scratch project over named consumer modules, written beside them so their own\n// resolution reaches the installed package. Nothing is emitted and no ambient types\n// are pulled in, so what the check reads is the installed declarations alone.\n/**\n * Writes a compiler project for a consumer probe.\n *\n * @param stage - The installed consumer.\n * @param name - The project filename suffix.\n * @param driver - The compiler resolution.\n * @param files - The consumer source files.\n * @returns The absolute project path.\n */\nexport function writeDistributionProject(\n\tstage: DistributionStage,\n\tname: string,\n\tdriver: DistributionResolution,\n\tfiles: readonly string[],\n): string {\n\tconst path = join(stage.consumer, `tsconfig.${name}.json`)\n\tconst project = {\n\t\tcompilerOptions: {\n\t\t\tmodule: driver.module,\n\t\t\tmoduleResolution: driver.resolution,\n\t\t\tnoEmit: true,\n\t\t\tskipLibCheck: true,\n\t\t\tstrict: true,\n\t\t\ttarget: 'esnext',\n\t\t\ttypes: [],\n\t\t},\n\t\tfiles: [...files],\n\t}\n\twriteDistributionFile(path, `${JSON.stringify(project, undefined, '\\t')}\\n`)\n\treturn path\n}\n\n// The diagnostics the compiler this workspace installs reports for one scratch\n// project. The compiler runs as a command, so nothing here reaches an API that\n// moves between its majors, and the located lines it prints are the verdict rather\n// than the exit code, which moves between them. A line carrying no location, a line\n// naming the scratch project rather than a consumer module, and anything at all on\n// the error stream are faults of this proof rather than of the package under proof,\n// so each is raised where it happens instead of counted against the package.\n/**\n * Checks a consumer project with the installed TypeScript compiler.\n *\n * @param stage - The installed consumer.\n * @param project - The compiler project path.\n * @returns The located compiler diagnostics. Throws on a tool or project failure.\n */\nexport function checkDistributionProject(\n\tstage: DistributionStage,\n\tproject: string,\n): readonly string[] {\n\tconst result = runDistributionNode(\n\t\t[DISTRIBUTION_COMPILER, '--noEmit', '--pretty', 'false', '-p', project],\n\t\tstage.consumer,\n\t)\n\tconst refused = `${result.stderr ?? ''}`.trim()\n\tif (refused.length > 0) {\n\t\tthrow new Error(`The consumer compiler wrote ${refused} to its error stream`)\n\t}\n\tconst lines = `${result.stdout ?? ''}`.split(/\\r\\n|\\n/u).filter((line) => line.trim().length > 0)\n\t// An elaborated diagnostic prints its detail on indented lines under its own\n\t// first line, so each of those joins the diagnostic it elaborates. The first line\n\t// has no diagnostic above it to join, so it opens one whatever its indentation.\n\tconst heads = lines.flatMap((line, index) => (index === 0 || !/^\\s/u.test(line) ? [index] : []))\n\tconst reported = heads.map((head, position) => {\n\t\tconst line = lines[head] ?? ''\n\t\tconst located = DISTRIBUTION_DIAGNOSTIC_PATTERN.exec(line)?.[1]\n\t\tif (located === undefined) {\n\t\t\tthrow new Error(`The consumer compiler reported ${line}, which names no location`)\n\t\t}\n\t\tif (resolve(stage.consumer, located) === project) {\n\t\t\tthrow new Error(`The scratch project is itself at fault: ${line}`)\n\t\t}\n\t\treturn [\n\t\t\tline,\n\t\t\t...lines.slice(head + 1, heads[position + 1] ?? lines.length).map((detail) => detail.trim()),\n\t\t].join(' ')\n\t})\n\tif (reported.length === 0 && result.status !== 0) {\n\t\tthrow new Error(`The consumer compiler refused the project: ${readDistributionOutput(result)}`)\n\t}\n\treturn reported\n}\n\n// One installed entry's published names checked against its own declarations by\n// the compiler this workspace installs, in the direction each divergence surfaces\n// under. The runtime's key list is written into the consumer as a literal, so the\n// published side comes from a real process and the declared side from the\n// declarations that process's package ships, and the two can disagree. A name the\n// declarations carry and the runtime does not lands on `declared`. A name the\n// runtime carries and the declarations do not, and a name the declarations publish\n// as a type alone, land on `surfaced`: a variable widens into the type\n// `declared` annotates, and only `surfaced` reads the literal's own keys back.\n// Each names the member it is about, so the failure says which export moved.\n/**\n * Checks runtime export names against their installed declarations.\n *\n * @param stage - The installed consumer.\n * @param surface - The publication and declaration pair.\n * @returns The diagnostics labelled by compiler resolution.\n */\nexport function checkDistributionSurface(\n\tstage: DistributionStage,\n\tsurface: DistributionSurface,\n): readonly string[] {\n\tconst slug = surface.entry.subpath.replaceAll(/[^\\w]+/gu, '-')\n\tconst name = `surface.${surface.driver.label}${slug}.${surface.extension}`\n\tconst module = `${name}`\n\tconst keys = surface.published.map((key) => `${JSON.stringify(key)}: true`).join(', ')\n\twriteDistributionFile(\n\t\tjoin(stage.consumer, module),\n\t\t`import * as entry from ${JSON.stringify(surface.entry.specifier)}\nexport const published = {${keys.length === 0 ? '' : ` ${keys} `}} as const\nexport const declared: Record<keyof typeof entry, true> = published\nexport const surfaced: Record<keyof typeof published, true> = declared\n`,\n\t)\n\tconst project = writeDistributionProject(stage, name, surface.driver, [`./${module}`])\n\treturn checkDistributionProject(stage, project).map((line) => `${surface.driver.label}: ${line}`)\n}\n\n// One consumer module importing every installed entry, written where its own\n// resolution finds the installed package.\n/**\n * Writes a consumer importing the requested public specifiers.\n *\n * @param stage - The installed consumer.\n * @param path - The consumer-relative source path.\n * @param specifiers - The public imports to resolve.\n */\nexport function writeDistributionConsumerProbe(\n\tstage: DistributionStage,\n\tpath: string,\n\tspecifiers: readonly string[],\n): void {\n\tconst modules = specifiers.map((specifier, index) => ({\n\t\tbinding: `entry${String(index)}`,\n\t\tspecifier,\n\t}))\n\tconst bindings = modules.map(\n\t\t({ binding, specifier }) => `import * as ${binding} from ${JSON.stringify(specifier)}`,\n\t)\n\tconst names = modules.map(({ binding }) => binding)\n\tconst source = `${bindings.join('\\n')}\\nexport const surface = [${names.join(', ')}]\\n`\n\twriteDistributionFile(join(stage.consumer, path), source)\n}\n\n// The runtime key set a real process reads off one installed entry under one\n// condition. The driver is a file rather than an `--eval` string, so the specifier\n// travels as an argument and nothing needs escaping.\n/**\n * Reads the names a real Node process loads from an installed entry.\n *\n * @param stage - The installed consumer.\n * @param specifier - The public package specifier.\n * @param driver - The consumer driver filename.\n * @returns The exported names. Throws when loading or decoding fails.\n */\nexport function driveDistributionRuntime(\n\tstage: DistributionStage,\n\tspecifier: string,\n\tdriver: string,\n): readonly string[] {\n\tconst result = runDistributionNode([join(stage.consumer, driver), specifier], stage.consumer)\n\tif (result.status !== 0) {\n\t\tthrow new Error(\n\t\t\t`Loading ${specifier} from the consumer failed: ${readDistributionOutput(result)}`,\n\t\t)\n\t}\n\tconst published: unknown = JSON.parse(result.stdout)\n\tif (!isDistributionNames(published))\n\t\tthrow new Error(`The driver printed no name list for ${specifier}`)\n\treturn published\n}\n{{helpers}}\n// Pack this workspace, install the archive into an isolated consumer, and read the\n// published surface back off the installed tree. Every later claim reads this\n// result, so a failure here is raised where it happens rather than once per entry.\n/**\n * Packs the workspace and installs its archive into an isolated consumer.\n *\n * @param scratch - The owned scratch root.\n * @returns The installed consumer and classified exports.\n * @throws Thrown when packing or installation fails.\n */\nexport function buildDistributionStage(scratch: string): DistributionStage {\n\tconst packed = join(scratch, 'packed')\n\tconst consumer = join(scratch, 'consumer')\n\tmkdirSync(packed, { recursive: true })\n\tconst pack = runDistributionNpm(\n\t\t['pack', '--ignore-scripts', '--pack-destination', packed],\n\t\tDISTRIBUTION_ROOT,\n\t\tscratch,\n\t)\n\tif (pack.status !== 0)\n\t\tthrow new Error(`npm pack refused this workspace: ${readDistributionOutput(pack)}`)\n\tconst archives = readdirSync(packed).filter((name) => name.endsWith('.tgz'))\n\tconst archive = archives[0]\n\tif (archives.length !== 1 || archive === undefined) {\n\t\tthrow new Error(`npm pack wrote no single archive: ${archives.join(', ')}`)\n\t}\n\twriteDistributionFile(join(consumer, 'package.json'), DISTRIBUTION_CONSUMER_MANIFEST)\n\twriteDistributionFile(join(consumer, DISTRIBUTION_ESM_DRIVER), DISTRIBUTION_ESM_DRIVER_SOURCE)\n\twriteDistributionFile(join(consumer, DISTRIBUTION_CJS_DRIVER), DISTRIBUTION_CJS_DRIVER_SOURCE)\n\tconst install = runDistributionNpm(\n\t\t['install', '--ignore-scripts', '--no-audit', '--no-fund', join(packed, archive)],\n\t\tconsumer,\n\t\tscratch,\n\t)\n\tif (install.status !== 0) {\n\t\tthrow new Error(`Installing the packed archive failed: ${readDistributionOutput(install)}`)\n\t}\n\tconst name = readDistributionManifestName(join(DISTRIBUTION_ROOT, 'package.json'))\n\tconst installed = join(consumer, 'node_modules', ...name.split('/'))\n\tconst manifest = readDistributionJSON(join(installed, 'package.json'))\n\tif (!isDistributionRecord(manifest) || !isDistributionRecord(manifest.exports)) {\n\t\tthrow new Error('The installed manifest publishes no exports map')\n\t}\n\treturn { consumer, installed, archives, ...classifyDistributionStage(manifest, installed, name) }\n}\n\n// One file's run: the scratch directory and the staged consumer, which is absent when the\n// registry could not be reached.\n/** Binds an owned scratch directory to its optional installed consumer. */\nexport interface DistributionRun {\n\treadonly scratch: string\n\treadonly stage: DistributionStage | undefined\n}\n\n// The run the start hook binds once for this file and the stop hook releases.\n/** Owns the staged consumer shared by one distribution proof. */\nexport class DistributionSuite implements DistributionSuiteInterface {\n\t#run: DistributionRun | undefined\n\n\tget scratch(): string {\n\t\tif (this.#run === undefined) {\n\t\t\tthrow new Error('The distribution setup has not allocated its scratch directory')\n\t\t}\n\t\treturn this.#run.scratch\n\t}\n\n\tread(context: TestContext): DistributionStage {\n\t\tconst stage = this.#run?.stage\n\t\tif (stage === undefined) {\n\t\t\treturn context.skip('`npm ping` did not answer, so nothing was packed or installed')\n\t\t}\n\t\treturn stage\n\t}\n\n\tstart(): void {\n\t\tif (this.#run !== undefined) {\n\t\t\tthrow new Error('The distribution setup has already allocated its scratch directory')\n\t\t}\n\t\tconst scratch = mkdtempSync(join(tmpdir(), 'distribution-'))\n\t\tthis.#run = { scratch, stage: openDistributionStage(scratch) }\n\t}\n\n\tdestroy(): void {\n\t\tif (this.#run !== undefined) {\n\t\t\trmSync(this.#run.scratch, { force: true, recursive: true, maxRetries: 3, retryDelay: 100 })\n\t\t}\n\t\tthis.#run = undefined\n\t}\n}\n\n// Installing the packed archive resolves its own runtime dependencies, so an\n// unreachable registry leaves nothing to measure. Under release that is the gate\n// failing; anywhere else the suite skips and names the mechanism it wanted.\n/**\n * Opens an installed consumer after checking registry readiness.\n *\n * @param scratch - The owned scratch root.\n * @returns The installed consumer, or undefined when an ordinary run cannot reach the registry.\n * @throws Thrown in release mode or when staging fails, after removing scratch.\n */\nexport function openDistributionStage(scratch: string): DistributionStage | undefined {\n\ttry {\n\t\tmkdirSync(join(scratch, 'cache'), { recursive: true })\n\t\tif (runDistributionNpm(DISTRIBUTION_PING, DISTRIBUTION_ROOT, scratch).status !== 0) {\n\t\t\tif (!DISTRIBUTION_RELEASE) return undefined\n\t\t\tthrow new Error(\n\t\t\t\t'The release gate requires a reachable npm registry, and npm ping did not answer',\n\t\t\t)\n\t\t}\n\t\treturn buildDistributionStage(scratch)\n\t} catch (error) {\n\t\trmSync(scratch, {\n\t\t\tforce: true,\n\t\t\trecursive: true,\n\t\t\tmaxRetries: 3,\n\t\t\tretryDelay: 100,\n\t\t})\n\t\tthrow error\n\t}\n}\n\n/**\n * Partitions an installed exports map into driven, undeclared, and excluded subpaths.\n *\n * @param manifest - The installed package manifest.\n * @param installed - The installed package root.\n * @param name - The published package name.\n * @returns The classified entries and complete target population.\n * @throws Thrown when the exports map is absent.\n */\nexport function classifyDistributionStage(\n\tmanifest: Readonly<Record<string, unknown>>,\n\tinstalled: string,\n\tname: string,\n): DistributionClassification {\n\tif (!isDistributionRecord(manifest.exports))\n\t\tthrow new Error('The installed manifest publishes no exports map')\n\tconst readings = Object.entries(manifest.exports).map(([subpath, mapping]) => {\n\t\tconst files = collectDistributionTargets(mapping)\n\t\tconst declaration = readDistributionDeclaration(mapping, installed)\n\t\t// A subpath resolving no declaration is partitioned rather than dropped. It is a\n\t\t// defect when a runtime loads one of its targets for names, because a consumer\n\t\t// importing it compiles against nothing under `node16`. It is an excluded\n\t\t// publication otherwise: the `\"./package.json\"` manifest pointer and a stylesheet\n\t\t// are published for a reader rather than an importer.\n\t\tif (\n\t\t\tdeclaration.module === undefined &&\n\t\t\tdeclaration.commonjs === undefined &&\n\t\t\tdeclaration.browser === undefined\n\t\t) {\n\t\t\treturn { subpath, files, entry: undefined }\n\t\t}\n\t\tconst importTarget = resolveDistributionTarget(mapping, DISTRIBUTION_RUNTIME_CONDITIONS.module)\n\t\tconst requireTarget = resolveDistributionTarget(\n\t\t\tmapping,\n\t\t\tDISTRIBUTION_RUNTIME_CONDITIONS.commonjs,\n\t\t)\n\t\tconst browserTarget = resolveDistributionTarget(\n\t\t\tmapping,\n\t\t\tDISTRIBUTION_RUNTIME_CONDITIONS.browser,\n\t\t)\n\t\tconst browsable = resolvesDistributionBrowser(mapping)\n\t\tconst shadowed = browsable && requireTarget === browserTarget\n\t\tconst requirable = requireTarget !== undefined && !shadowed\n\t\tconst loadable = requirable && resolvesDistributionCommonJS(mapping, installed)\n\t\tconst entry: DistributionEntry = {\n\t\t\tsubpath,\n\t\t\tspecifier: subpath === '.' ? name : `${name}${subpath.slice(1)}`,\n\t\t\tmapping,\n\t\t\tdeclaration: {\n\t\t\t\timportable: declaration.module !== undefined,\n\t\t\t\trequirable: declaration.commonjs !== undefined,\n\t\t\t\tbrowsable: declaration.browser !== undefined,\n\t\t\t},\n\t\t\tbrowsable,\n\t\t\timportable: importTarget !== undefined && !(browsable && importTarget === browserTarget),\n\t\t\trequirable,\n\t\t\tloadable,\n\t\t}\n\t\treturn { subpath, files, entry }\n\t})\n\tconst entries = readings.flatMap(({ entry }) => (entry === undefined ? [] : [entry]))\n\tconst targets = readings.flatMap(({ files }) => files)\n\tconst subpaths = readings.map(({ subpath }) => subpath)\n\tconst undeclared = readings\n\t\t.filter(({ entry, files }) => entry === undefined && files.some(matchesDistributionModule))\n\t\t.map(({ subpath }) => subpath)\n\tconst excluded = readings\n\t\t.filter(({ entry, files }) => entry === undefined && !files.some(matchesDistributionModule))\n\t\t.map(({ subpath }) => subpath)\n\treturn { entries, subpaths, undeclared, excluded, targets }\n}\n\n/**\n * Creates the lifecycle boundary used by generated distribution proofs.\n * @returns The suite interface backed by an owned run.\n */\nexport function createDistributionSuite(): DistributionSuiteInterface {\n\treturn new DistributionSuite()\n}\n\n/**\n * Collects physical files beneath an installed output directory.\n * @param directory - The output directory to walk.\n * @returns The installed files, or an empty list when the directory is absent.\n */\nexport function collectDistributionFiles(directory: string): readonly string[] {\n\tif (!existsSync(directory)) return []\n\treturn readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {\n\t\tconst path = join(directory, entry.name)\n\t\treturn entry.isDirectory() ? collectDistributionFiles(path) : entry.isFile() ? [path] : []\n\t})\n}\n\n/**\n * Reads the source environment owning an installed output path.\n * @param installed - The installed package root.\n * @param path - The output file.\n * @returns The source environment, or undefined outside a JavaScript face.\n */\nexport function readDistributionFace(installed: string, path: string): string | undefined {\n\tconst [output, axis, face] = relativePath(installed, path).split(sep)\n\treturn output === 'dist'\n\t\t? axis === 'src'\n\t\t\t? face\n\t\t\t: axis === 'bin'\n\t\t\t\t? 'bin'\n\t\t\t\t: undefined\n\t\t: undefined\n}\n\n/**\n * Scans installed JavaScript maps for sources copied from another environment.\n * @param installed - The installed package root.\n * @returns The copied sources and unreadable maps.\n * @throws Thrown when a code-bearing output has no readable map of its own.\n */\nexport function scanDistributionSourceMaps(installed: string): readonly string[] {\n\tconst files = collectDistributionFiles(join(installed, 'dist')).filter(\n\t\t(path) => readDistributionFace(installed, path) !== undefined,\n\t)\n\tconst outputs = files\n\t\t.filter((path) => /\\.(?:js|cjs|mjs)$/u.test(path))\n\t\t.map((path) => {\n\t\t\tconst parsed = parseSync(path, readFileSync(path, 'utf8'))\n\t\t\tconst code = parsed.program.body.some(\n\t\t\t\t(statement) =>\n\t\t\t\t\tstatement.type !== 'EmptyStatement' &&\n\t\t\t\t\t!(\n\t\t\t\t\t\tstatement.type === 'ExportNamedDeclaration' &&\n\t\t\t\t\t\tstatement.declaration === null &&\n\t\t\t\t\t\tstatement.specifiers.length === 0 &&\n\t\t\t\t\t\tstatement.source === null\n\t\t\t\t\t),\n\t\t\t)\n\t\t\tconst reference = parsed.comments\n\t\t\t\t.flatMap((comment) => {\n\t\t\t\t\tconst match = /^[@#]\\s*sourceMappingURL=(\\S+)\\s*$/u.exec(comment.value)\n\t\t\t\t\treturn match?.[1] === undefined ? [] : [match[1]]\n\t\t\t\t})\n\t\t\t\t.at(-1)\n\t\t\ttry {\n\t\t\t\tconst inline = reference?.startsWith('data:') === true\n\t\t\t\tconst target = inline\n\t\t\t\t\t? path\n\t\t\t\t\t: reference === undefined\n\t\t\t\t\t\t? `${path}.map`\n\t\t\t\t\t\t: fileURLToPath(new URL(reference.replaceAll('\\\\', '/'), pathToFileURL(path)))\n\t\t\t\treturn {\n\t\t\t\t\tpath: target,\n\t\t\t\t\tface: readDistributionFace(installed, path),\n\t\t\t\t\tcode,\n\t\t\t\t\treference: inline ? reference : undefined,\n\t\t\t\t}\n\t\t\t} catch {\n\t\t\t\tthrow new Error(`Unreadable source maps for ${path}`)\n\t\t\t}\n\t\t})\n\tconst maps = [\n\t\t...outputs.filter(\n\t\t\t({ path, code, reference }) => code || reference !== undefined || existsSync(path),\n\t\t),\n\t\t...files\n\t\t\t.filter(\n\t\t\t\t(path) =>\n\t\t\t\t\t/\\.(?:js|cjs|mjs)\\.map$/u.test(path) && !outputs.some((output) => output.path === path),\n\t\t\t)\n\t\t\t.map((path) => ({\n\t\t\t\tpath,\n\t\t\t\tface: readDistributionFace(installed, path),\n\t\t\t\tcode: false,\n\t\t\t\treference: undefined,\n\t\t\t})),\n\t]\n\tif (maps.length === 0)\n\t\tconsole.info('No built JavaScript face holds code, so no source map is required')\n\treturn maps.flatMap(({ path, face, code, reference }) => {\n\t\tconst label = relativePath(installed, path).split(sep).join('/')\n\t\ttry {\n\t\t\tconst payload =\n\t\t\t\treference === undefined\n\t\t\t\t\t? undefined\n\t\t\t\t\t: /^data:application\\/json(?:;charset=[^;,]+)?(;base64)?,(.*)$/iu.exec(reference)\n\t\t\tconst map: unknown =\n\t\t\t\treference === undefined\n\t\t\t\t\t? readDistributionJSON(path)\n\t\t\t\t\t: payload?.[2] === undefined\n\t\t\t\t\t\t? undefined\n\t\t\t\t\t\t: JSON.parse(\n\t\t\t\t\t\t\t\tpayload[1] === undefined\n\t\t\t\t\t\t\t\t\t? decodeURIComponent(payload[2])\n\t\t\t\t\t\t\t\t\t: Buffer.from(payload[2], 'base64').toString('utf8'),\n\t\t\t\t\t\t\t)\n\t\t\tif (\n\t\t\t\t!isDistributionRecord(map) ||\n\t\t\t\t!isDistributionNames(map.sources) ||\n\t\t\t\t(map.sourceRoot !== undefined && typeof map.sourceRoot !== 'string')\n\t\t\t) {\n\t\t\t\tthrow new Error('Unreadable source map')\n\t\t\t}\n\t\t\tconst root = typeof map.sourceRoot === 'string' ? map.sourceRoot : ''\n\t\t\tconst directory = root.startsWith('file:')\n\t\t\t\t? fileURLToPath(new URL(root))\n\t\t\t\t: resolve(dirname(path), root.replaceAll('\\\\', '/'))\n\t\t\tconst sources = map.sources.map((source) =>\n\t\t\t\trelativePath(\n\t\t\t\t\tresolve(installed),\n\t\t\t\t\tsource.startsWith('file:')\n\t\t\t\t\t\t? fileURLToPath(new URL(source))\n\t\t\t\t\t\t: resolve(directory, source.replaceAll('\\\\', '/')),\n\t\t\t\t)\n\t\t\t\t\t.split(sep)\n\t\t\t\t\t.join('/'),\n\t\t\t)\n\t\t\tconst copied = sources.filter(\n\t\t\t\t(source) => source.startsWith('src/') && !source.startsWith(`src/${face}/`),\n\t\t\t)\n\t\t\treturn [\n\t\t\t\t...copied.map((source) => `${label}: ${source}`),\n\t\t\t\t...(sources.some((source) => source.startsWith(`src/${face}/`))\n\t\t\t\t\t? []\n\t\t\t\t\t: [`${label}: unreadable source map (no src/${face}/ source)`]),\n\t\t\t]\n\t\t} catch {\n\t\t\tif (code) throw new Error(`Unreadable source maps for ${path}`)\n\t\t\treturn [`${label}: unreadable source map`]\n\t\t}\n\t})\n}\n\n/**\n * Reads top-level names declared by a roll-up, including unexported declarations.\n * @param path - The installed declaration file.\n * @returns The declared names. Refuses syntax errors and unreadable binding patterns.\n */\nexport function readDistributionNames(path: string): readonly string[] {\n\tconst source = parseSync(path, readFileSync(path, 'utf8'))\n\tif (source.errors.length > 0) throw new Error(`Unreadable declarations at ${path}`)\n\treturn source.program.body.flatMap((statement) => {\n\t\tconst declaration =\n\t\t\tstatement.type === 'ExportNamedDeclaration' || statement.type === 'ExportDefaultDeclaration'\n\t\t\t\t? statement.declaration\n\t\t\t\t: statement\n\t\tif (declaration === null) return []\n\t\tif (declaration.type === 'VariableDeclaration') {\n\t\t\treturn declaration.declarations.map((binding) => {\n\t\t\t\tif (binding.id.type !== 'Identifier')\n\t\t\t\t\tthrow new Error(`Unreadable declaration binding at ${path}`)\n\t\t\t\treturn binding.id.name\n\t\t\t})\n\t\t}\n\t\tif (\n\t\t\tdeclaration.type === 'ClassDeclaration' ||\n\t\t\tdeclaration.type === 'FunctionDeclaration' ||\n\t\t\tdeclaration.type === 'TSDeclareFunction' ||\n\t\t\tdeclaration.type === 'TSInterfaceDeclaration' ||\n\t\t\tdeclaration.type === 'TSTypeAliasDeclaration' ||\n\t\t\tdeclaration.type === 'TSEnumDeclaration' ||\n\t\t\tdeclaration.type === 'TSModuleDeclaration'\n\t\t) {\n\t\t\treturn declaration.id?.type === 'Identifier' ? [declaration.id.name] : []\n\t\t}\n\t\treturn []\n\t})\n}\n\n/**\n * Checks whether a source entry exports names, following local star exports.\n * @param path - The source entry to inspect.\n * @param ancestors - The entries already visited on this export path.\n * @returns True if the entry exports a name; false otherwise.\n */\nexport function matchesDistributionSourceExports(\n\tpath: string,\n\tancestors: readonly string[] = [],\n): boolean {\n\tif (ancestors.includes(path)) return false\n\tconst source = parseSync(path, readFileSync(path, 'utf8'))\n\tif (source.errors.length > 0) throw new Error(`Unreadable source exports at ${path}`)\n\treturn source.program.body.some((statement) => {\n\t\tif (statement.type === 'ExportDefaultDeclaration') return ancestors.length === 0\n\t\tif (statement.type === 'ExportNamedDeclaration')\n\t\t\treturn (\n\t\t\t\tstatement.declaration !== null ||\n\t\t\t\tstatement.specifiers.some((specifier) => {\n\t\t\t\t\tconst name =\n\t\t\t\t\t\tspecifier.exported.type === 'Identifier'\n\t\t\t\t\t\t\t? specifier.exported.name\n\t\t\t\t\t\t\t: specifier.exported.value\n\t\t\t\t\treturn ancestors.length === 0 || name !== 'default'\n\t\t\t\t})\n\t\t\t)\n\t\tif (statement.type !== 'ExportAllDeclaration') return false\n\t\tif (statement.exported !== null || !statement.source.value.startsWith('.')) return true\n\t\tconst target = resolve(dirname(path), statement.source.value.replace(/\\.js$/u, '.ts'))\n\t\treturn matchesDistributionSourceExports(target, [...ancestors, path])\n\t})\n}\n\n/**\n * Scans installed declaration faces for names declared by multiple environments.\n * @param installed - The installed package root.\n * @param source - The workspace holding the source entries being published.\n * @returns The repeated names with their declaring faces.\n * @throws Thrown when a source entry exports names but its roll-up declares none.\n */\nexport function scanDistributionDeclarations(\n\tinstalled: string,\n\tsource: string = DISTRIBUTION_ROOT,\n): readonly string[] {\n\tconst declarations = collectDistributionFiles(join(installed, 'dist'))\n\t\t.filter(matchesDistributionDeclaration)\n\t\t.map((path) => ({\n\t\t\tpath,\n\t\t\tface: readDistributionFace(installed, path),\n\t\t\tnames: readDistributionNames(path),\n\t\t}))\n\tconst entries = collectDistributionFiles(join(source, 'src')).filter((path) => {\n\t\tconst parts = relativePath(source, path).split(sep)\n\t\treturn parts.length === 3 && parts[2] === 'index.ts'\n\t})\n\tconst published = entries.filter((path) => matchesDistributionSourceExports(path))\n\tfor (const path of published) {\n\t\tconst face = relativePath(source, path).split(sep)[1]\n\t\tif (!declarations.some((entry) => entry.face === face && entry.names.length > 0))\n\t\t\tthrow new Error(\n\t\t\t\t`The ${face} source entry exports names but its declaration roll-up declares none`,\n\t\t\t)\n\t}\n\tif (published.length === 0)\n\t\tconsole.info('No source entry exports names, so no declaration names are required')\n\tconst names = [...new Set(declarations.flatMap((entry) => entry.names))].sort()\n\treturn names.flatMap((name) => {\n\t\tconst faces = [\n\t\t\t...new Set(\n\t\t\t\tdeclarations\n\t\t\t\t\t.filter((entry) => entry.names.includes(name))\n\t\t\t\t\t.map((entry) => entry.face)\n\t\t\t\t\t.filter((face) => face !== undefined),\n\t\t\t),\n\t\t].sort()\n\t\treturn faces.length > 1 ? [`${name}: ${faces.join(', ')}`] : []\n\t})\n}\n\n/**\n * Checks the installed manifest against npm's normalization in an owned scratch copy.\n * @param installed - The installed package root, read only.\n * @param scratch - The suite's owned scratch root and npm cache parent.\n * @returns The top-level keys changed by npm. Refuses an unsuccessful npm command.\n */\nexport function checkDistributionManifest(installed: string, scratch: string): readonly string[] {\n\tconst directory = mkdtempSync(join(scratch, 'manifest-'))\n\ttry {\n\t\tconst path = join(directory, 'package.json')\n\t\twriteFileSync(path, readFileSync(join(installed, 'package.json')))\n\t\tconst before = readDistributionJSON(path)\n\t\tconst result = runDistributionNpm(['pkg', 'fix'], directory, scratch)\n\t\tif (result.status !== 0)\n\t\t\tthrow new Error(`npm pkg fix failed: ${readDistributionOutput(result)}`)\n\t\tconst after = readDistributionJSON(path)\n\t\tif (!isDistributionRecord(before) || !isDistributionRecord(after))\n\t\t\tthrow new Error('Unreadable manifest')\n\t\treturn [...new Set([...Object.keys(before), ...Object.keys(after)])]\n\t\t\t.filter((key) => !isDeepStrictEqual(before[key], after[key]))\n\t\t\t.sort()\n\t} finally {\n\t\trmSync(directory, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 })\n\t}\n}\n\n/**\n * Builds independently registered observations over the suite's installed consumer.\n * @param suite - The lifecycle shared by the proof's hooks and observations.\n * @returns The case rows whose observations each require one assertion.\n */\nexport function buildDistributionCases(\n\tsuite: DistributionSuiteInterface,\n): readonly DistributionCase[] {\n\treturn [\n\t\t{\n\t\t\tlabel: 'classifies synthetic export mappings without a registry stage',\n\t\t\tobserve: () => {\n\t\t\t\tconst root = join(suite.scratch, 'classifiers')\n\t\t\t\twriteDistributionFile(\n\t\t\t\t\tjoin(root, 'package.json'),\n\t\t\t\t\tJSON.stringify({\n\t\t\t\t\t\ttype: 'commonjs',\n\t\t\t\t\t\texports: {\n\t\t\t\t\t\t\tcondition: { browser: './b.js', default: './n.js' },\n\t\t\t\t\t\t\tconvention: { default: './dist/src/browser/index.js' },\n\t\t\t\t\t\t\tuniversal: { default: './shared.js' },\n\t\t\t\t\t\t\t'import-shared': {\n\t\t\t\t\t\t\t\tbrowser: './shared.mjs',\n\t\t\t\t\t\t\t\timport: './shared.mjs',\n\t\t\t\t\t\t\t\tdefault: './node.js',\n\t\t\t\t\t\t\t},\n\t\t\t\t\t\t\t'require-shared': {\n\t\t\t\t\t\t\t\tbrowser: './shared.cjs',\n\t\t\t\t\t\t\t\trequire: './shared.cjs',\n\t\t\t\t\t\t\t\tdefault: './node.js',\n\t\t\t\t\t\t\t},\n\t\t\t\t\t\t\tnode: { node: './node.js', default: './node.js' },\n\t\t\t\t\t\t\tsilent: { 'module-sync': './x.cjs', import: './x.mjs' },\n\t\t\t\t\t\t\tmodule: { require: './x.mjs' },\n\t\t\t\t\t\t\t'nested-module': { require: './module/x.js' },\n\t\t\t\t\t\t\t'nested-commonjs': { require: './commonjs/x.js' },\n\t\t\t\t\t\t\tesm: { import: './x.mjs' },\n\t\t\t\t\t\t},\n\t\t\t\t\t}),\n\t\t\t\t)\n\t\t\t\twriteDistributionFile(join(root, 'module/package.json'), '{ \"type\": \"module\" }\\n')\n\t\t\t\twriteDistributionFile(join(root, 'commonjs/package.json'), '{ \"type\": \"commonjs\" }\\n')\n\t\t\t\tconst manifest = readDistributionJSON(join(root, 'package.json'))\n\t\t\t\tif (!isDistributionRecord(manifest) || !isDistributionRecord(manifest.exports)) {\n\t\t\t\t\tthrow new Error('The classifier fixture declares no exports map')\n\t\t\t\t}\n\t\t\t\tconst mappings = manifest.exports\n\n\t\t\t\treturn {\n\t\t\t\t\tactual: {\n\t\t\t\t\t\tbrowser: {\n\t\t\t\t\t\t\tcondition: resolvesDistributionBrowser(mappings.condition),\n\t\t\t\t\t\t\tconvention: resolvesDistributionBrowser(mappings.convention),\n\t\t\t\t\t\t\tuniversal: resolvesDistributionBrowser(mappings.universal),\n\t\t\t\t\t\t\timport: resolvesDistributionBrowser(mappings['import-shared']),\n\t\t\t\t\t\t\trequire: resolvesDistributionBrowser(mappings['require-shared']),\n\t\t\t\t\t\t\tnode: resolvesDistributionBrowser(mappings.node),\n\t\t\t\t\t\t},\n\t\t\t\t\t\tcommonjs: {\n\t\t\t\t\t\t\tsilent: resolvesDistributionCommonJS(mappings.silent, root),\n\t\t\t\t\t\t\tmodule: resolvesDistributionCommonJS(mappings.module, root),\n\t\t\t\t\t\t\tnestedModule: resolvesDistributionCommonJS(mappings['nested-module'], root),\n\t\t\t\t\t\t\tnestedCommonJS: resolvesDistributionCommonJS(mappings['nested-commonjs'], root),\n\t\t\t\t\t\t\tesm: resolvesDistributionCommonJS(mappings.esm, root),\n\t\t\t\t\t\t},\n\t\t\t\t\t},\n\t\t\t\t\texpected: {\n\t\t\t\t\t\tbrowser: {\n\t\t\t\t\t\t\tcondition: true,\n\t\t\t\t\t\t\tconvention: true,\n\t\t\t\t\t\t\tuniversal: false,\n\t\t\t\t\t\t\timport: false,\n\t\t\t\t\t\t\trequire: false,\n\t\t\t\t\t\t\tnode: false,\n\t\t\t\t\t\t},\n\t\t\t\t\t\tcommonjs: {\n\t\t\t\t\t\t\tsilent: true,\n\t\t\t\t\t\t\tmodule: false,\n\t\t\t\t\t\t\tnestedModule: false,\n\t\t\t\t\t\t\tnestedCommonJS: true,\n\t\t\t\t\t\t\tesm: false,\n\t\t\t\t\t\t},\n\t\t\t\t\t},\n\t\t\t\t}\n\t\t\t},\n\t\t},\n\t\t{\n\t\t\tlabel: 'keeps installed JavaScript sources in their own environment [requires the registry]',\n\t\t\tobserve: (context) => {\n\t\t\t\tconst stage = suite.read(context)\n\t\t\t\treturn { actual: scanDistributionSourceMaps(stage.installed), expected: [] }\n\t\t\t},\n\t\t},\n\t\t{\n\t\t\tlabel: 'declares each installed name in one environment [requires the registry]',\n\t\t\tobserve: (context) => {\n\t\t\t\tconst stage = suite.read(context)\n\t\t\t\tconst faces = new Set(\n\t\t\t\t\tcollectDistributionFiles(join(stage.installed, 'dist'))\n\t\t\t\t\t\t.filter(matchesDistributionDeclaration)\n\t\t\t\t\t\t.map((path) => readDistributionFace(stage.installed, path))\n\t\t\t\t\t\t.filter((face) => face !== undefined),\n\t\t\t\t)\n\t\t\t\tconst findings = scanDistributionDeclarations(stage.installed)\n\t\t\t\tif (faces.size <= 1)\n\t\t\t\t\tconsole.info(\n\t\t\t\t\t\t'Fewer than two declaration faces are installed, so no cross-face copy exists',\n\t\t\t\t\t)\n\t\t\t\treturn { actual: findings, expected: [] }\n\t\t\t},\n\t\t},\n\t\t{\n\t\t\tlabel: 'keeps the installed manifest fixed under npm pkg fix [requires the registry]',\n\t\t\tobserve: (context) => ({\n\t\t\t\tactual: checkDistributionManifest(suite.read(context).installed, suite.scratch),\n\t\t\t\texpected: [],\n\t\t\t}),\n\t\t},\n\t\t{\n\t\t\tlabel: 'packs one archive and installs it in isolation [requires the registry]',\n\t\t\tobserve: (context) => {\n\t\t\t\tconst stage = suite.read(context)\n\t\t\t\treturn {\n\t\t\t\t\tactual: {\n\t\t\t\t\t\tarchives: stage.archives.length,\n\t\t\t\t\t\tinstalled: existsSync(join(stage.installed, 'package.json')),\n\t\t\t\t\t\tentries: stage.entries.length > 0,\n\t\t\t\t\t},\n\t\t\t\t\texpected: { archives: 1, installed: true, entries: true },\n\t\t\t\t}\n\t\t\t},\n\t\t},\n\t\t{\n\t\t\tlabel: 'ships every relative target its exports map names [requires the registry]',\n\t\t\tobserve: (context) => {\n\t\t\t\tconst stage = suite.read(context)\n\t\t\t\tconst relative = stage.targets.filter((target) => target.startsWith('./'))\n\t\t\t\treturn {\n\t\t\t\t\tactual: {\n\t\t\t\t\t\tpopulated: relative.length > 0,\n\t\t\t\t\t\tmissing: relative.filter((target) => !existsSync(join(stage.installed, target))),\n\t\t\t\t\t},\n\t\t\t\t\texpected: { populated: true, missing: [] },\n\t\t\t\t}\n\t\t\t},\n\t\t},\n\t\t{\n\t\t\tlabel: 'declares types for every module it publishes [requires the registry]',\n\t\t\tobserve: (context) => {\n\t\t\t\tconst stage = suite.read(context)\n\t\t\t\tconst partitioned = [\n\t\t\t\t\t...stage.entries.map((entry) => entry.subpath),\n\t\t\t\t\t...stage.undeclared,\n\t\t\t\t\t...stage.excluded,\n\t\t\t\t]\n\t\t\t\treturn {\n\t\t\t\t\tactual: {\n\t\t\t\t\t\tundeclared: stage.undeclared,\n\t\t\t\t\t\tpartitioned: partitioned.sort(),\n\t\t\t\t\t\tunreachable: stage.entries\n\t\t\t\t\t\t\t.filter((entry) => !entry.importable && !entry.requirable && !entry.browsable)\n\t\t\t\t\t\t\t.map((entry) => entry.subpath),\n\t\t\t\t\t\tuntypable: filterDistributionUntypable(stage.entries, stage.installed).map(\n\t\t\t\t\t\t\t(entry) => entry.subpath,\n\t\t\t\t\t\t),\n\t\t\t\t\t},\n\t\t\t\t\texpected: {\n\t\t\t\t\t\tundeclared: [],\n\t\t\t\t\t\tpartitioned: [...stage.subpaths].sort(),\n\t\t\t\t\t\tunreachable: [],\n\t\t\t\t\t\tuntypable: [],\n\t\t\t\t\t},\n\t\t\t\t}\n\t\t\t},\n\t\t},\n\t\t{\n\t\t\tlabel: 'refuses a subpath its exports map does not name [requires the registry]',\n\t\t\tobserve: (context) => {\n\t\t\t\tconst stage = suite.read(context)\n\t\t\t\tconst name = readDistributionManifestName(join(stage.installed, 'package.json'))\n\t\t\t\tconst result = runDistributionNode(\n\t\t\t\t\t[join(stage.consumer, DISTRIBUTION_ESM_DRIVER), `${name}${DISTRIBUTION_ABSENT_SUBPATH}`],\n\t\t\t\t\tstage.consumer,\n\t\t\t\t)\n\t\t\t\treturn {\n\t\t\t\t\tactual: {\n\t\t\t\t\t\trefused: result.status !== 0,\n\t\t\t\t\t\tcoded: readDistributionOutput(result).includes('ERR_PACKAGE_PATH_NOT_EXPORTED'),\n\t\t\t\t\t},\n\t\t\t\t\texpected: { refused: true, coded: true },\n\t\t\t\t}\n\t\t\t},\n\t\t},\n\t\t{\n\t\t\tlabel: 'compiles a consumer under every module resolution [requires the registry]',\n\t\t\tobserve: (context) => {\n\t\t\t\tconst stage = suite.read(context)\n\t\t\t\tconst name = readDistributionManifestName(join(stage.installed, 'package.json'))\n\t\t\t\tconst readings = DISTRIBUTION_RESOLUTIONS.flatMap((driver) =>\n\t\t\t\t\tDISTRIBUTION_FORMATS.flatMap(([extension, format]) => {\n\t\t\t\t\t\tconst written = filterDistributionEntries(stage.entries, driver.conditions[format])\n\t\t\t\t\t\tif (written.length === 0) return []\n\t\t\t\t\t\tconst label = `${driver.label}.${extension}`\n\t\t\t\t\t\tconst probe = `probe.${label}`\n\t\t\t\t\t\tconst specifiers = written.map((entry) => entry.specifier)\n\t\t\t\t\t\twriteDistributionConsumerProbe(stage, probe, specifiers)\n\t\t\t\t\t\tconst project = writeDistributionProject(stage, probe, driver, [`./${probe}`])\n\t\t\t\t\t\tconst messages = checkDistributionProject(stage, project).map(\n\t\t\t\t\t\t\t(message) => `${label}: ${message}`,\n\t\t\t\t\t\t)\n\t\t\t\t\t\tconst control = `control.${label}`\n\t\t\t\t\t\twriteDistributionConsumerProbe(stage, control, [\n\t\t\t\t\t\t\t`${name}${DISTRIBUTION_ABSENT_SUBPATH}`,\n\t\t\t\t\t\t])\n\t\t\t\t\t\tconst refused = writeDistributionProject(stage, control, driver, [`./${control}`])\n\t\t\t\t\t\treturn [\n\t\t\t\t\t\t\t{\n\t\t\t\t\t\t\t\tmessages,\n\t\t\t\t\t\t\t\tsilent: checkDistributionProject(stage, refused).length === 0 ? [label] : [],\n\t\t\t\t\t\t\t},\n\t\t\t\t\t\t]\n\t\t\t\t\t}),\n\t\t\t\t)\n\t\t\t\treturn {\n\t\t\t\t\tactual: {\n\t\t\t\t\t\tmessages: readings.flatMap(({ messages }) => messages),\n\t\t\t\t\t\tsilent: readings.flatMap(({ silent }) => silent),\n\t\t\t\t\t},\n\t\t\t\t\texpected: { messages: [], silent: [] },\n\t\t\t\t}\n\t\t\t},\n\t\t},\n\t\t{\n\t\t\tlabel: 'publishes what it declares to a Node import, and no more',\n\t\t\tobserve: (context) => {\n\t\t\t\tconst stage = suite.read(context)\n\t\t\t\tconst entries = stage.entries.filter((entry) => entry.importable)\n\t\t\t\tif (entries.length === 0) return context.skip('No installed entry supports Node import')\n\t\t\t\tconst readings = entries.map((entry) => {\n\t\t\t\t\tif (!entry.declaration.importable)\n\t\t\t\t\t\tthrow new Error(`${entry.subpath} publishes no import declaration`)\n\t\t\t\t\tconst published = driveDistributionRuntime(\n\t\t\t\t\t\tstage,\n\t\t\t\t\t\tentry.specifier,\n\t\t\t\t\t\tDISTRIBUTION_ESM_DRIVER,\n\t\t\t\t\t)\n\t\t\t\t\tconst drivers = filterDistributionResolutions(entry, 'module')\n\t\t\t\t\treturn {\n\t\t\t\t\t\tentry: entry.subpath,\n\t\t\t\t\t\tdriven: drivers.length > 0,\n\t\t\t\t\t\treported: drivers.flatMap((driver) =>\n\t\t\t\t\t\t\tcheckDistributionSurface(stage, { entry, extension: 'ts', published, driver }),\n\t\t\t\t\t\t),\n\t\t\t\t\t}\n\t\t\t\t})\n\t\t\t\treturn {\n\t\t\t\t\tactual: readings,\n\t\t\t\t\texpected: entries.map((entry) => ({ entry: entry.subpath, driven: true, reported: [] })),\n\t\t\t\t}\n\t\t\t},\n\t\t},\n\t\t{\n\t\t\tlabel: 'publishes what it declares to a Node require, and no more',\n\t\t\tobserve: (context) => {\n\t\t\t\tconst stage = suite.read(context)\n\t\t\t\tconst entries = stage.entries.filter((entry) => entry.requirable)\n\t\t\t\tif (entries.length === 0) return context.skip('No installed entry supports Node require')\n\t\t\t\tconst readings = entries.map((entry) => {\n\t\t\t\t\tif (!entry.declaration.requirable)\n\t\t\t\t\t\tthrow new Error(`${entry.subpath} publishes no require declaration`)\n\t\t\t\t\tconst published = driveDistributionRuntime(\n\t\t\t\t\t\tstage,\n\t\t\t\t\t\tentry.specifier,\n\t\t\t\t\t\tDISTRIBUTION_CJS_DRIVER,\n\t\t\t\t\t)\n\t\t\t\t\tconst drivers = filterDistributionResolutions(entry, 'commonjs')\n\t\t\t\t\treturn {\n\t\t\t\t\t\tentry: entry.subpath,\n\t\t\t\t\t\tdriven: drivers.length > 0,\n\t\t\t\t\t\treported: drivers.flatMap((driver) =>\n\t\t\t\t\t\t\tcheckDistributionSurface(stage, { entry, extension: 'cts', published, driver }),\n\t\t\t\t\t\t),\n\t\t\t\t\t}\n\t\t\t\t})\n\t\t\t\treturn {\n\t\t\t\t\tactual: readings,\n\t\t\t\t\texpected: entries.map((entry) => ({ entry: entry.subpath, driven: true, reported: [] })),\n\t\t\t\t}\n\t\t\t},\n\t\t},\n\t]\n}\n";
+            module: "{{types}}import type { SpawnSyncReturns } from 'node:child_process'\nimport type { TestContext } from 'vitest'\nimport { spawnSync } from 'node:child_process'\nimport {\n\texistsSync,\n\tmkdirSync,\n\tmkdtempSync,\n\treaddirSync,\n\treadFileSync,\n\trmSync,\n\tstatSync,\n\twriteFileSync,\n} from 'node:fs'\n{{transport}}import { createRequire } from 'node:module'\nimport { tmpdir } from 'node:os'\nimport { dirname, join, relative as relativePath, resolve, sep } from 'node:path'\nimport { fileURLToPath, pathToFileURL } from 'node:url'\nimport { isDeepStrictEqual } from 'node:util'\nimport { parseSync } from 'vite'\n{{launcher}}\n/** Defines the lifecycle and installed consumer read by a distribution proof. */\nexport interface DistributionSuiteInterface {\n\treadonly scratch: string\n\tstart(): void\n\tread(context: TestContext): DistributionStage\n\tdestroy(): void\n}\n\n/** Holds the observed and required values for one distribution assertion. */\nexport interface DistributionObservation {\n\treadonly actual: unknown\n\treadonly expected: unknown\n}\n\n/** Defines one independently registered distribution observation. */\nexport interface DistributionCase {\n\treadonly label: string\n\treadonly observe: (\n\t\tcontext: TestContext,\n\t) => DistributionObservation | Promise<DistributionObservation>\n}\n\n/** Holds the installed export map's classified publications. */\nexport interface DistributionClassification {\n\treadonly entries: readonly DistributionEntry[]\n\treadonly subpaths: readonly string[]\n\treadonly undeclared: readonly string[]\n\treadonly excluded: readonly string[]\n\treadonly targets: readonly string[]\n}\n\n/** Names the workspace whose packed artifact the proof consumes. */\nexport const DISTRIBUTION_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..')\n/** Names the npm executable on the running host. */\nexport const DISTRIBUTION_NPM = process.platform === 'win32' ? 'npm.cmd' : 'npm'\n// The compiler this workspace installs, run as a command rather than called in\n// process: the command and its plain-text diagnostics are the same across the\n// compiler majors this toolchain supports, and its in-process API is not. It is\n// resolved from the workspace under proof, so a consumer of the packed artifact is\n// checked by the same compiler that workspace's own `check` script runs. TypeScript 7 exports\n// `package.json` but not `bin/tsc`, so the path is joined from the manifest's directory.\n/** Names the TypeScript manifest installed by the workspace under proof. */\nexport const DISTRIBUTION_TYPESCRIPT = createRequire(\n\tjoin(DISTRIBUTION_ROOT, 'package.json'),\n).resolve('typescript/package.json')\n/** Names the compiler installed by the workspace under proof. */\nexport const DISTRIBUTION_COMPILER = join(dirname(DISTRIBUTION_TYPESCRIPT), 'bin', 'tsc')\n// Windows needs a shell to launch a `.cmd`: Node refuses one directly since the\n// batch-argument hardening, and `spawnSync` returns `EINVAL` with a null status\n// rather than an exit code a caller can read. Every following argument is a literal or\n// a path this file built, so the shell has nothing to escape.\n/** Selects the Windows command-shell route required by the npm shim. */\nexport const DISTRIBUTION_SHELL = process.platform === 'win32'\n// `prepublishOnly` runs this proof as `npm run test:distribution -- --mode release`,\n// and the root configuration's project factories carry that mode into this project.\n// Release is the publish gate, so evidence it cannot obtain fails there and skips\n// everywhere else: a gate that passes on missing evidence proves nothing.\n/** Indicates whether missing prerequisites must fail the publish gate. */\nexport const DISTRIBUTION_RELEASE = import.meta.env?.MODE === 'release'\n// The built output directory convention a browser face may publish from. Every\n// selection reads this prefix off the export target and never off the subpath name. A\n// workspace whose only published face is the browser one publishes that face at the\n// root subpath, so a rule keyed on the subpath name drives a browser bundle through\n// Node and the miss is silent.\n/** Names the conventional output prefix for a browser publication. */\nexport const DISTRIBUTION_BROWSER_OUTPUT = './dist/src/browser/'\n/** Names the unpublished subpath used as a resolution control. */\nexport const DISTRIBUTION_ABSENT_SUBPATH = '/no-subpath-is-published-under-this-name'\n// A compiler diagnostic that says where it is: the path relative to the directory\n// the compiler ran in, the 1-based line and column, the code, and the message. The\n// diagnostics are the verdict rather than the exit code, which differs between the\n// compiler majors this toolchain supports, so a reported line matching nothing here\n// came from something other than a check of a consumer module.\n/** Matches the location prefix of a consumer compiler diagnostic. */\nexport const DISTRIBUTION_DIAGNOSTIC_PATTERN = /^(.+?)\\(\\d+,\\d+\\): error TS\\d+: /u\n/** Lists the bounded registry-readiness command arguments. */\nexport const DISTRIBUTION_PING = Object.freeze([\n\t'ping',\n\t'--fetch-retries=0',\n\t'--fetch-timeout=5000',\n\t'--loglevel=silent',\n])\n/** Names the consumer entry that imports an installed module. */\nexport const DISTRIBUTION_ESM_DRIVER = 'drive.mjs'\n/** Names the consumer entry that requires an installed module. */\nexport const DISTRIBUTION_CJS_DRIVER = 'drive.cjs'\n/** Defines the isolated consumer package manifest. */\nexport const DISTRIBUTION_CONSUMER_MANIFEST =\n\t'{ \"name\": \"distribution-consumer\", \"private\": true, \"type\": \"module\" }\\n'\n/** Reads the names exported by an installed ESM entry. */\nexport const DISTRIBUTION_ESM_DRIVER_SOURCE = `const entry = await import(process.argv[2])\nprocess.stdout.write(JSON.stringify(Object.keys(entry).sort()))\n`\n/** Reads the names exported by an installed CommonJS entry. */\nexport const DISTRIBUTION_CJS_DRIVER_SOURCE = `const entry = require(process.argv[2])\nprocess.stdout.write(JSON.stringify(Object.keys(entry).sort()))\n`\n\n// The extensions a JavaScript handler loads as modules. Node loads a native addon\n// through its addon handler instead, so that extension is named separately.\n/** Lists extensions loaded as JavaScript modules. */\nexport const DISTRIBUTION_MODULE_EXTENSIONS = Object.freeze(['.js', '.mjs', '.cjs'])\n/** Names the extension loaded by the native-addon handler. */\nexport const DISTRIBUTION_ADDON_EXTENSION = '.node'\n// The extensions a declaration file carries. A `require` condition declares\n// `.d.cts` and an ESM-only one `.d.mts`, so the `.d.ts` spelling alone does not\n// name them.\n/** Lists the supported TypeScript declaration extensions. */\nexport const DISTRIBUTION_DECLARATION_EXTENSIONS = Object.freeze(['.d.ts', '.d.cts', '.d.mts'])\n/** Names the module format of a typed consumer. */\nexport type DistributionFormat = 'module' | 'commonjs'\n\n// The Node import target is resolved with the conditions that driver supplies. The\n// CommonJS compile probe is selected from its declaration's format, and its runtime\n// drive loads the same subpath through Node's require resolver. Vite's production\n// client build enables its module and browser conditions.\n/** Defines the conditions each runtime uses to resolve an entry. */\nexport const DISTRIBUTION_RUNTIME_CONDITIONS = Object.freeze({\n\tmodule: Object.freeze(['node-addons', 'node', 'import', 'module-sync']),\n\tcommonjs: Object.freeze(['node-addons', 'node', 'require', 'module-sync']),\n\tbrowser: Object.freeze(['module', 'browser', 'production', 'import']),\n})\n// TypeScript's Node resolutions add `node` to the format condition. Its bundler\n// resolution does not, so a browser drive compares against the declaration a bundler\n// consumer reads rather than borrowing the Node declaration.\n/** Defines the declaration conditions used by bundler consumers. */\nexport const DISTRIBUTION_BUNDLER_CONDITIONS = Object.freeze({\n\tmodule: Object.freeze(['types', 'import']),\n\tcommonjs: Object.freeze(['types', 'require']),\n})\n/** Defines the declaration conditions paired with each runtime. */\nexport const DISTRIBUTION_DECLARATION_CONDITIONS = Object.freeze({\n\tmodule: Object.freeze(['types', 'node', 'import']),\n\tcommonjs: Object.freeze(['types', 'node', 'require']),\n\tbrowser: DISTRIBUTION_BUNDLER_CONDITIONS.module,\n})\n\n/** Describes the compiler options and conditions for one consumer resolution. */\nexport interface DistributionResolution {\n\treadonly label: string\n\treadonly resolution: string\n\treadonly module: string\n\treadonly conditions: Readonly<Record<DistributionFormat, readonly string[]>>\n}\n\n/** Holds the target selected by package condition resolution. */\nexport interface DistributionTargetResult {\n\treadonly target: string\n}\n\n// Each compile driver carries the compiler options its scratch project sets and\n// the conditions TypeScript applies for that resolution and importing format. A\n// `require`-only subpath therefore stays in each CommonJS probe that can resolve it.\n// The option values are the spellings the project file takes, so nothing here needs\n// the compiler's own API to name them.\n/** Lists the compiler resolutions driven against installed declarations. */\nexport const DISTRIBUTION_RESOLUTIONS: readonly DistributionResolution[] = Object.freeze([\n\t{\n\t\tlabel: 'node16',\n\t\tresolution: 'node16',\n\t\tmodule: 'node16',\n\t\tconditions: DISTRIBUTION_DECLARATION_CONDITIONS,\n\t},\n\t{\n\t\tlabel: 'nodenext',\n\t\tresolution: 'nodenext',\n\t\tmodule: 'nodenext',\n\t\tconditions: DISTRIBUTION_DECLARATION_CONDITIONS,\n\t},\n\t{\n\t\tlabel: 'bundler',\n\t\tresolution: 'bundler',\n\t\tmodule: 'esnext',\n\t\tconditions: DISTRIBUTION_BUNDLER_CONDITIONS,\n\t},\n])\n\n// The driver a bundled consumer reads declarations under. A browser application\n// compiles through a bundler, so the browser drive answers under this one alone,\n// and naming it here is what keeps that selection tied to the driver it selects.\n/** Selects the compiler resolution used by a browser consumer. */\nexport const DISTRIBUTION_BROWSER_RESOLUTION = DISTRIBUTION_RESOLUTIONS.find(\n\t(candidate) => candidate.label === 'bundler',\n)\nif (DISTRIBUTION_BROWSER_RESOLUTION === undefined)\n\tthrow new Error(\"DISTRIBUTION_RESOLUTIONS carries no 'bundler' row\")\n\n/** Pairs consumer source extensions with their module formats. */\nexport const DISTRIBUTION_FORMATS: ReadonlyArray<\n\treadonly [extension: string, format: DistributionFormat]\n> = Object.freeze([\n\t['ts', 'module'],\n\t['cts', 'commonjs'],\n])\n\n// One published subpath, resolved to what this proof can drive: the specifier a\n// consumer writes, whether the declarations its consumer formats resolve at all,\n// whether the exports map answers the browser condition with a target of its own,\n// whether it answers `import` and `require` at all, and whether the target that\n// `require` answers with is one that a CommonJS consumer loads.\n/** Describes one published subpath and its runtime and declaration capabilities. */\nexport interface DistributionEntry {\n\treadonly subpath: string\n\treadonly specifier: string\n\treadonly mapping: unknown\n\treadonly declaration: {\n\t\treadonly importable: boolean\n\t\treadonly requirable: boolean\n\t\treadonly browsable: boolean\n\t}\n\treadonly browsable: boolean\n\treadonly importable: boolean\n\treadonly requirable: boolean\n\treadonly loadable: boolean\n}\n\n// The installed tree every claim is read from. Every subpath the exports map names\n// lands in exactly one of `entries`, `undeclared`, and `excluded`, so a subpath this\n// proof cannot drive is reported rather than dropped.\n/** Holds the installed consumer and the partition of its published subpaths. */\nexport interface DistributionStage {\n\treadonly consumer: string\n\treadonly installed: string\n\treadonly archives: readonly string[]\n\treadonly entries: readonly DistributionEntry[]\n\treadonly subpaths: readonly string[]\n\treadonly undeclared: readonly string[]\n\treadonly excluded: readonly string[]\n\treadonly targets: readonly string[]\n}\n\n/**\n * Checks whether a value is a non-null object other than an array.\n *\n * @param value - The value to inspect.\n * @returns True if the value is a record; false otherwise.\n */\nexport function isDistributionRecord(value: unknown): value is Readonly<Record<string, unknown>> {\n\treturn typeof value === 'object' && value !== null && !Array.isArray(value)\n}\n\n/**\n * Checks whether a value is an array of strings.\n *\n * @param value - The value to inspect.\n * @returns True if every array member is a string; false otherwise.\n */\nexport function isDistributionNames(value: unknown): value is readonly string[] {\n\treturn Array.isArray(value) && value.every((name) => typeof name === 'string')\n}\n\n// A fallback list, which is what Node reads an array in an exports entry as. The\n// narrowing is what the following walkers need: `Array.isArray` widens an `unknown`\n// member to `any`, and an entry read that way is not read at all.\n/**\n * Checks whether a value is a fallback array.\n *\n * @param value - The value to inspect.\n * @returns True if the value is an array; false otherwise.\n */\nexport function isDistributionList(value: unknown): value is readonly unknown[] {\n\treturn Array.isArray(value)\n}\n\n// Whether a string is a valid package target. Node rejects a target outside the\n// package and a target containing a dot, parent, or node_modules segment during\n// package-target resolution. A later module-resolution failure is not the same\n// thing: an array falls through the former and keeps the latter.\n/**\n * Checks whether a relative package target contains only admitted segments.\n *\n * @param target - The package-relative target.\n * @returns True if the target passes package-target validation; false otherwise.\n */\nexport function matchesDistributionPackageTarget(target: string): boolean {\n\tif (!target.startsWith('./')) return false\n\tconst refused = ['.', '..', 'node_modules']\n\treturn target\n\t\t.slice(2)\n\t\t.split(/[\\\\/]/u)\n\t\t.every((segment) => {\n\t\t\ttry {\n\t\t\t\treturn !refused.includes(decodeURIComponent(segment).toLowerCase())\n\t\t\t} catch {\n\t\t\t\treturn !refused.includes(segment.toLowerCase())\n\t\t\t}\n\t\t})\n}\n\n/**\n * Reads and parses a JSON file.\n *\n * @param path - The file to read.\n * @returns The parsed value. Throws when reading or parsing fails.\n */\nexport function readDistributionJSON(path: string): unknown {\n\tconst parsed: unknown = JSON.parse(readFileSync(path, 'utf8'))\n\treturn parsed\n}\n\n/**\n * Reads the package name from a manifest.\n *\n * @param path - The manifest to read.\n * @returns The package name. Throws when the manifest has no string name.\n */\nexport function readDistributionManifestName(path: string): string {\n\tconst manifest = readDistributionJSON(path)\n\tif (!isDistributionRecord(manifest) || typeof manifest.name !== 'string') {\n\t\tthrow new Error(`The manifest at ${path} declares no package name`)\n\t}\n\treturn manifest.name\n}\n\n// A host carries a package's required peers at its own root. A consumer that carries none leaves\n// npm to place them, and npm can then resolve an optional peer of a peer to a release the\n// package's own range refuses, so the consumer declares them as a host would.\n/**\n * Reads the peers a host must carry: every peer dependency its metadata does not mark optional.\n *\n * @param path - The manifest to read.\n * @returns Each required peer's name mapped to its declared range.\n */\nexport function readDistributionPeers(path: string): Readonly<Record<string, string>> {\n\tconst manifest = readDistributionJSON(path)\n\tif (!isDistributionRecord(manifest) || !isDistributionRecord(manifest.peerDependencies)) {\n\t\treturn {}\n\t}\n\tconst meta = isDistributionRecord(manifest.peerDependenciesMeta)\n\t\t? manifest.peerDependenciesMeta\n\t\t: undefined\n\tconst peers = Object.entries(manifest.peerDependencies).filter(\n\t\t(entry): entry is [string, string] => typeof entry[1] === 'string',\n\t)\n\treturn Object.fromEntries(\n\t\tpeers.filter(([name]) => {\n\t\t\tconst entry = meta?.[name]\n\t\t\treturn !isDistributionRecord(entry) || entry.optional !== true\n\t\t}),\n\t)\n}\n\n/**\n * Writes the consumer manifest, declaring the required peers as dependencies.\n *\n * @param peers - Each required peer's name mapped to its declared range.\n * @returns The manifest text; the bare manifest when the package declares no required peer.\n */\nexport function createDistributionConsumerManifest(\n\tpeers: Readonly<Record<string, string>>,\n): string {\n\tconst manifest: unknown = JSON.parse(DISTRIBUTION_CONSUMER_MANIFEST)\n\tif (Object.keys(peers).length === 0 || !isDistributionRecord(manifest)) {\n\t\treturn DISTRIBUTION_CONSUMER_MANIFEST\n\t}\n\treturn `${JSON.stringify({ ...manifest, dependencies: peers })}\\n`\n}\n\n/**\n * Writes a consumer file after creating its parent directory.\n *\n * @param path - The file to write.\n * @param content - The text to write.\n */\nexport function writeDistributionFile(path: string, content: string): void {\n\tmkdirSync(dirname(path), { recursive: true })\n\twriteFileSync(path, content)\n}\n\n/**\n * Combines the output streams of a completed command.\n *\n * @param result - The completed command.\n * @returns The trimmed diagnostic text.\n */\nexport function readDistributionOutput(result: SpawnSyncReturns<string>): string {\n\treturn `${result.stdout ?? ''}${result.stderr ?? ''}`.trim()\n}\n\n/**\n * Runs npm with a cache inside the owned scratch directory.\n *\n * @param args - The npm arguments.\n * @param cwd - The working directory.\n * @param scratch - The owned scratch root.\n * @returns The command status and captured streams.\n */\nexport function runDistributionNpm(\n\targs: readonly string[],\n\tcwd: string,\n\tscratch: string,\n): SpawnSyncReturns<string> {\n\treturn spawnSync(DISTRIBUTION_NPM, [...args], {\n\t\tcwd,\n\t\tencoding: 'utf8',\n\t\tenv: { ...process.env, npm_config_cache: join(scratch, 'cache') },\n\t\tshell: DISTRIBUTION_SHELL,\n\t\twindowsHide: true,\n\t})\n}\n\n/**\n * Runs a JavaScript entry with the running Node executable.\n *\n * @param args - The Node arguments.\n * @param cwd - The working directory.\n * @returns The command status and captured streams.\n */\nexport function runDistributionNode(\n\targs: readonly string[],\n\tcwd: string,\n): SpawnSyncReturns<string> {\n\treturn spawnSync(process.execPath, [...args], { cwd, encoding: 'utf8', windowsHide: true })\n}\n\n// Node's own condition matching, read in declaration order.\n/**\n * Resolves a package target through conditions and fallback arrays.\n *\n * @param entry - The exports-map entry.\n * @param conditions - The active resolution conditions.\n * @returns The selected target, or undefined when no branch resolves.\n */\nexport function resolveDistributionPackageTarget(\n\tentry: unknown,\n\tconditions: readonly string[],\n): DistributionTargetResult | undefined {\n\tif (typeof entry === 'string') return { target: entry }\n\tif (isDistributionList(entry)) {\n\t\tfor (const member of entry) {\n\t\t\tconst resolved = resolveDistributionPackageTarget(member, conditions)\n\t\t\tif (resolved !== undefined && matchesDistributionPackageTarget(resolved.target))\n\t\t\t\treturn resolved\n\t\t}\n\t\treturn undefined\n\t}\n\tif (!isDistributionRecord(entry)) return undefined\n\tfor (const [condition, nested] of Object.entries(entry)) {\n\t\tif (condition !== 'default' && !conditions.includes(condition)) continue\n\t\tconst resolved = resolveDistributionPackageTarget(nested, conditions)\n\t\tif (resolved !== undefined) return resolved\n\t}\n\treturn undefined\n}\n\n// A flat entry, a condition-nested entry, and a fallback list all resolve through\n// one walker. An entry may declare `types` beside `default` at its top level\n// rather than inside `import`, so a fixed `entry.import.types` lookup is not\n// equivalent to condition resolution.\n/**\n * Resolves the path selected by an exports-map entry.\n *\n * @param entry - The exports-map entry.\n * @param conditions - The active resolution conditions.\n * @returns The selected path, or undefined when no branch resolves.\n */\nexport function resolveDistributionTarget(\n\tentry: unknown,\n\tconditions: readonly string[],\n): string | undefined {\n\treturn resolveDistributionPackageTarget(entry, conditions)?.target\n}\n\n// Whether a path is a physical file. TypeScript's file-existence check refuses a\n// directory at the same spelling and continues to the outer package scope.\n/**\n * Checks whether a path names a physical file.\n *\n * @param path - The filesystem path.\n * @returns True if the path names a file; false otherwise.\n */\nexport function matchesDistributionFile(path: string): boolean {\n\ttry {\n\t\treturn statSync(path).isFile()\n\t} catch {\n\t\treturn false\n\t}\n}\n\n// TypeScript resolves a declaration target by accepting an existing declaration\n// directly or by substituting beside a JavaScript target. A missing target leaves\n// the containing condition or fallback list unresolved, so the walk continues.\n/**\n * Resolves an existing declaration beside a package target.\n *\n * @param target - The package-relative target.\n * @param installed - The installed package root.\n * @returns The declaration target, or undefined when no declaration exists.\n */\nexport function targetToDistributionDeclaration(\n\ttarget: string,\n\tinstalled: string,\n): string | undefined {\n\tif (!matchesDistributionPackageTarget(target)) return undefined\n\tconst declaration = target.endsWith('.cjs')\n\t\t? `${target.slice(0, -4)}.d.cts`\n\t\t: target.endsWith('.mjs')\n\t\t\t? `${target.slice(0, -4)}.d.mts`\n\t\t\t: target.endsWith('.js')\n\t\t\t\t? `${target.slice(0, -3)}.d.ts`\n\t\t\t\t: target\n\tif (declaration === target && !matchesDistributionDeclaration(target)) return undefined\n\treturn matchesDistributionFile(join(installed, declaration)) ? declaration : undefined\n}\n\n// The declaration TypeScript resolves through one importing format's conditions.\n// Condition objects keep manifest order, and arrays keep fallback order.\n/**\n * Resolves an existing declaration through consumer conditions.\n *\n * @param entry - The exports-map entry.\n * @param conditions - The active declaration conditions.\n * @param installed - The installed package root.\n * @returns The declaration target, or undefined when no branch resolves.\n */\nexport function resolveDistributionDeclaration(\n\tentry: unknown,\n\tconditions: readonly string[],\n\tinstalled: string,\n): string | undefined {\n\tif (typeof entry === 'string') return targetToDistributionDeclaration(entry, installed)\n\tif (isDistributionList(entry)) {\n\t\tfor (const member of entry) {\n\t\t\tconst resolved = resolveDistributionDeclaration(member, conditions, installed)\n\t\t\tif (resolved !== undefined) return resolved\n\t\t}\n\t\treturn undefined\n\t}\n\tif (!isDistributionRecord(entry)) return undefined\n\tfor (const [condition, nested] of Object.entries(entry)) {\n\t\tif (condition !== 'default' && !conditions.includes(condition)) continue\n\t\tconst resolved = resolveDistributionDeclaration(nested, conditions, installed)\n\t\tif (resolved !== undefined) return resolved\n\t}\n\treturn undefined\n}\n\n// The nearest package scope that decides a `.d.ts` declaration's module format. A\n// physical nested manifest starts a scope even when it omits `type` or cannot be\n// parsed. A directory at that spelling is not a manifest, so the walk continues.\n/**\n * Reads the nearest package scope for a target inside an installed package.\n *\n * @param installed - The installed package root.\n * @param target - The package-relative target.\n * @returns The manifest type, or undefined when the nearest scope omits it or cannot be read.\n */\nexport function readDistributionPackageType(installed: string, target: string): unknown {\n\t// One `dirname` per path segment reaches the root from any path. The walk ends at the\n\t// installed package, so no scope above it is consulted.\n\tconst start = dirname(join(installed, target))\n\tconst chain = start\n\t\t.split(/[\\\\/]/u)\n\t\t.reduce<string[]>((climbed) => [...climbed, dirname(climbed.at(-1) ?? start)], [start])\n\tconst end = chain.indexOf(installed)\n\tconst scope = chain\n\t\t.slice(0, end === -1 ? chain.length : end + 1)\n\t\t.find((directory) => matchesDistributionFile(join(directory, 'package.json')))\n\tif (scope === undefined) return undefined\n\ttry {\n\t\tconst manifest = readDistributionJSON(join(scope, 'package.json'))\n\t\treturn isDistributionRecord(manifest) ? manifest.type : undefined\n\t} catch {\n\t\treturn undefined\n\t}\n}\n\n/**\n * Checks whether an entry publishes a distinct or conventional browser target.\n *\n * @param entry - The exports-map entry.\n * @returns True if the entry requires a browser drive; false otherwise.\n */\nexport function resolvesDistributionBrowser(entry: unknown): boolean {\n\tconst module = resolveDistributionTarget(entry, DISTRIBUTION_RUNTIME_CONDITIONS.browser)\n\tif (module !== undefined && module.startsWith(DISTRIBUTION_BROWSER_OUTPUT)) return true\n\tif (module === undefined) return false\n\tconst imported = resolveDistributionTarget(entry, DISTRIBUTION_RUNTIME_CONDITIONS.module)\n\tconst required = resolveDistributionTarget(entry, DISTRIBUTION_RUNTIME_CONDITIONS.commonjs)\n\treturn module !== imported && module !== required\n}\n\n// Whether the target selected by Node's CommonJS conditions is a module require can\n// load. A JavaScript target takes its own nearest package scope. Native addons and\n// extensionless targets have their own CommonJS handlers.\n/**\n * Checks whether Node require can load an entry selected by its conditions.\n *\n * @param entry - The exports-map entry.\n * @param installed - The installed package root.\n * @returns True if the target has a CommonJS-compatible format; false otherwise.\n */\nexport function resolvesDistributionCommonJS(entry: unknown, installed: string): boolean {\n\tconst target = resolveDistributionTarget(entry, DISTRIBUTION_RUNTIME_CONDITIONS.commonjs)\n\tif (target === undefined) return false\n\tconst name = target.slice(target.lastIndexOf('/') + 1)\n\tif (name.endsWith('.cjs')) return true\n\tif (name.endsWith('.mjs')) return false\n\tif (name.endsWith('.node')) return true\n\tif (!name.includes('.')) return true\n\treturn name.endsWith('.js') && readDistributionPackageType(installed, target) !== 'module'\n}\n\n// Whether the declaration selected by a typed CommonJS consumer admits that entry.\n// A `.d.cts` declaration admits and a `.d.mts` declaration refuses. A `.d.ts`\n// declaration takes its own nearest package scope.\n/**\n * Checks whether an entry resolves a CommonJS-compatible declaration.\n *\n * @param entry - The exports-map entry.\n * @param installed - The installed package root.\n * @returns True if the selected declaration admits CommonJS consumption; false otherwise.\n */\nexport function declaresDistributionCommonJS(entry: unknown, installed: string): boolean {\n\tconst declaration = resolveDistributionDeclaration(\n\t\tentry,\n\t\tDISTRIBUTION_DECLARATION_CONDITIONS.commonjs,\n\t\tinstalled,\n\t)\n\tif (declaration === undefined) return false\n\tif (declaration.endsWith('.d.cts')) return true\n\tif (declaration.endsWith('.d.mts')) return false\n\treturn (\n\t\tdeclaration.endsWith('.d.ts') &&\n\t\treadDistributionPackageType(installed, declaration) !== 'module'\n\t)\n}\n\n// Every target an entry names under any condition. A fallback list omits members\n// Node rejects during package-target validation, because no reader can take them.\n/**\n * Collects the targets an entry publishes under every condition.\n *\n * @param entry - The exports-map entry.\n * @returns The targets, excluding invalid members of fallback arrays.\n */\nexport function collectDistributionTargets(entry: unknown): readonly string[] {\n\tif (typeof entry === 'string') return [entry]\n\tif (isDistributionList(entry))\n\t\treturn entry.flatMap(collectDistributionTargets).filter(matchesDistributionPackageTarget)\n\tif (!isDistributionRecord(entry)) return []\n\treturn Object.values(entry).flatMap((nested) => collectDistributionTargets(nested))\n}\n\n// Whether a target is a file a runtime loads for its names, which is what a\n// declaration is owed for. The extension on the target's own file name decides it,\n// and a name carrying no extension is code: `require` reads such a file through its\n// JavaScript handler, so an extensionless target loads and publishes names. Node\n// loads `.node` through its native-addon handler. Every other extension is an asset\n// a consumer reads rather than imports — a stylesheet, a WebAssembly binary, the\n// `\"./package.json\"` manifest pointer, and a declaration alike.\n// The cost is an extensionless file published for a reader, such as a `LICENSE`:\n// that target reports undeclared until it is given an extension or a declaration.\n/**\n * Checks whether a target names a runtime module rather than an asset.\n *\n * @param target - The package-relative target.\n * @returns True if the target has a module extension or no extension; false otherwise.\n */\nexport function matchesDistributionModule(target: string): boolean {\n\tconst name = target.slice(target.lastIndexOf('/') + 1)\n\tconst dot = name.lastIndexOf('.')\n\tif (name.endsWith(DISTRIBUTION_ADDON_EXTENSION)) return true\n\treturn dot === -1 || DISTRIBUTION_MODULE_EXTENSIONS.includes(name.slice(dot))\n}\n\n// Whether a resolved target is a declaration rather than the JavaScript a\n// `default` branch answers with when the entry declares no `types` condition.\n/**\n * Checks whether a target names a TypeScript declaration.\n *\n * @param target - The package-relative target.\n * @returns True if the target has a declaration extension; false otherwise.\n */\nexport function matchesDistributionDeclaration(target: string): boolean {\n\treturn DISTRIBUTION_DECLARATION_EXTENSIONS.some((extension) => target.endsWith(extension))\n}\n\n// The declarations the Node module, Node CommonJS, and browser drives compare\n// against. Each field uses the conditions of the TypeScript consumer paired with\n// that runtime. A JavaScript target resolves through TypeScript's adjacent\n// declaration substitution rather than standing in for the declaration itself.\n/**\n * Reads the declarations paired with Node and browser consumers.\n *\n * @param entry - The exports-map entry.\n * @param installed - The installed package root.\n * @returns The declaration selected by each consumer format.\n */\nexport function readDistributionDeclaration(\n\tentry: unknown,\n\tinstalled: string,\n): {\n\treadonly module: string | undefined\n\treadonly commonjs: string | undefined\n\treadonly browser: string | undefined\n} {\n\treturn {\n\t\tmodule: resolveDistributionDeclaration(\n\t\t\tentry,\n\t\t\tDISTRIBUTION_DECLARATION_CONDITIONS.module,\n\t\t\tinstalled,\n\t\t),\n\t\tcommonjs: resolveDistributionDeclaration(\n\t\t\tentry,\n\t\t\tDISTRIBUTION_DECLARATION_CONDITIONS.commonjs,\n\t\t\tinstalled,\n\t\t),\n\t\tbrowser: resolveDistributionDeclaration(\n\t\t\tentry,\n\t\t\tDISTRIBUTION_DECLARATION_CONDITIONS.browser,\n\t\t\tinstalled,\n\t\t),\n\t}\n}\n\n// The entries one compile driver can resolve under its own conditions.\n/**\n * Filters entries to those a consumer can resolve.\n *\n * @param entries - The installed entries.\n * @param conditions - The active consumer conditions.\n * @returns The matching entries in their original order.\n */\nexport function filterDistributionEntries(\n\tentries: readonly DistributionEntry[],\n\tconditions: readonly string[],\n): readonly DistributionEntry[] {\n\treturn entries.filter(\n\t\t(entry) =>\n\t\t\tresolveDistributionTarget(entry.mapping, conditions) !== undefined &&\n\t\t\t(!conditions.includes('require') || entry.loadable),\n\t)\n}\n\n// The compile drivers whose conditions reach one entry under one importing format.\n// A driver that resolves no target for that entry compiles nothing, so a consumer\n// written under it would report a resolution failure this package never made.\n/**\n * Filters compiler resolutions to those that can read an entry.\n *\n * @param entry - The installed entry.\n * @param format - The consumer module format.\n * @returns The matching compiler resolutions.\n */\nexport function filterDistributionResolutions(\n\tentry: DistributionEntry,\n\tformat: DistributionFormat,\n): readonly DistributionResolution[] {\n\treturn DISTRIBUTION_RESOLUTIONS.filter(\n\t\t(driver) => filterDistributionEntries([entry], driver.conditions[format]).length > 0,\n\t)\n}\n\n// Requirable entries that declare CommonJS support but a typed CommonJS consumer\n// cannot compile against. A default branch resolving under the require condition\n// set makes no CommonJS claim.\n/**\n * Filters entries whose require target lacks a compatible declaration.\n *\n * @param entries - The installed entries.\n * @param installed - The installed package root.\n * @returns The entries a CommonJS consumer cannot typecheck.\n */\nexport function filterDistributionUntypable(\n\tentries: readonly DistributionEntry[],\n\tinstalled: string,\n): readonly DistributionEntry[] {\n\treturn entries.filter(\n\t\t(entry) =>\n\t\t\tentry.requirable &&\n\t\t\tisDistributionRecord(entry.mapping) &&\n\t\t\tObject.hasOwn(entry.mapping, 'require') &&\n\t\t\t!declaresDistributionCommonJS(entry.mapping, installed),\n\t)\n}\n\n// One surface comparison, written as the consumer module that proves it: the\n// installed entry that consumer imports, the file extension fixing its importing\n// format, the names a real runtime published off it, and the driver whose scratch\n// project compiles it.\n/** Describes the runtime names and declaration resolution compared for one entry. */\nexport interface DistributionSurface {\n\treadonly entry: DistributionEntry\n\treadonly extension: string\n\treadonly published: readonly string[]\n\treadonly driver: DistributionResolution\n}\n\n// A scratch project over named consumer modules, written beside them so their own\n// resolution reaches the installed package. Nothing is emitted and no ambient types\n// are pulled in, so what the check reads is the installed declarations alone.\n/**\n * Writes a compiler project for a consumer probe.\n *\n * @param stage - The installed consumer.\n * @param name - The project filename suffix.\n * @param driver - The compiler resolution.\n * @param files - The consumer source files.\n * @returns The absolute project path.\n */\nexport function writeDistributionProject(\n\tstage: DistributionStage,\n\tname: string,\n\tdriver: DistributionResolution,\n\tfiles: readonly string[],\n): string {\n\tconst path = join(stage.consumer, `tsconfig.${name}.json`)\n\tconst project = {\n\t\tcompilerOptions: {\n\t\t\tmodule: driver.module,\n\t\t\tmoduleResolution: driver.resolution,\n\t\t\tnoEmit: true,\n\t\t\tskipLibCheck: true,\n\t\t\tstrict: true,\n\t\t\ttarget: 'esnext',\n\t\t\ttypes: [],\n\t\t},\n\t\tfiles: [...files],\n\t}\n\twriteDistributionFile(path, `${JSON.stringify(project, undefined, '\\t')}\\n`)\n\treturn path\n}\n\n// The diagnostics the compiler this workspace installs reports for one scratch\n// project. The compiler runs as a command, so nothing here reaches an API that\n// moves between its majors, and the located lines it prints are the verdict rather\n// than the exit code, which moves between them. A line carrying no location, a line\n// naming the scratch project rather than a consumer module, and anything at all on\n// the error stream are faults of this proof rather than of the package under proof,\n// so each is raised where it happens instead of counted against the package.\n/**\n * Checks a consumer project with the installed TypeScript compiler.\n *\n * @param stage - The installed consumer.\n * @param project - The compiler project path.\n * @returns The located compiler diagnostics. Throws on a tool or project failure.\n */\nexport function checkDistributionProject(\n\tstage: DistributionStage,\n\tproject: string,\n): readonly string[] {\n\tconst result = runDistributionNode(\n\t\t[DISTRIBUTION_COMPILER, '--noEmit', '--pretty', 'false', '-p', project],\n\t\tstage.consumer,\n\t)\n\tconst refused = `${result.stderr ?? ''}`.trim()\n\tif (refused.length > 0) {\n\t\tthrow new Error(`The consumer compiler wrote ${refused} to its error stream`)\n\t}\n\tconst lines = `${result.stdout ?? ''}`.split(/\\r\\n|\\n/u).filter((line) => line.trim().length > 0)\n\t// An elaborated diagnostic prints its detail on indented lines under its own\n\t// first line, so each of those joins the diagnostic it elaborates. The first line\n\t// has no diagnostic above it to join, so it opens one whatever its indentation.\n\tconst heads = lines.flatMap((line, index) => (index === 0 || !/^\\s/u.test(line) ? [index] : []))\n\tconst reported = heads.map((head, position) => {\n\t\tconst line = lines[head] ?? ''\n\t\tconst located = DISTRIBUTION_DIAGNOSTIC_PATTERN.exec(line)?.[1]\n\t\tif (located === undefined) {\n\t\t\tthrow new Error(`The consumer compiler reported ${line}, which names no location`)\n\t\t}\n\t\tif (resolve(stage.consumer, located) === project) {\n\t\t\tthrow new Error(`The scratch project is itself at fault: ${line}`)\n\t\t}\n\t\treturn [\n\t\t\tline,\n\t\t\t...lines.slice(head + 1, heads[position + 1] ?? lines.length).map((detail) => detail.trim()),\n\t\t].join(' ')\n\t})\n\tif (reported.length === 0 && result.status !== 0) {\n\t\tthrow new Error(`The consumer compiler refused the project: ${readDistributionOutput(result)}`)\n\t}\n\treturn reported\n}\n\n// One installed entry's published names checked against its own declarations by\n// the compiler this workspace installs, in the direction each divergence surfaces\n// under. The runtime's key list is written into the consumer as a literal, so the\n// published side comes from a real process and the declared side from the\n// declarations that process's package ships, and the two can disagree. A name the\n// declarations carry and the runtime does not lands on `declared`. A name the\n// runtime carries and the declarations do not, and a name the declarations publish\n// as a type alone, land on `surfaced`: a variable widens into the type\n// `declared` annotates, and only `surfaced` reads the literal's own keys back.\n// Each names the member it is about, so the failure says which export moved.\n/**\n * Checks runtime export names against their installed declarations.\n *\n * @param stage - The installed consumer.\n * @param surface - The publication and declaration pair.\n * @returns The diagnostics labelled by compiler resolution.\n */\nexport function checkDistributionSurface(\n\tstage: DistributionStage,\n\tsurface: DistributionSurface,\n): readonly string[] {\n\tconst slug = surface.entry.subpath.replaceAll(/[^\\w]+/gu, '-')\n\tconst name = `surface.${surface.driver.label}${slug}.${surface.extension}`\n\tconst module = `${name}`\n\tconst keys = surface.published.map((key) => `${JSON.stringify(key)}: true`).join(', ')\n\twriteDistributionFile(\n\t\tjoin(stage.consumer, module),\n\t\t`import * as entry from ${JSON.stringify(surface.entry.specifier)}\nexport const published = {${keys.length === 0 ? '' : ` ${keys} `}} as const\nexport const declared: Record<keyof typeof entry, true> = published\nexport const surfaced: Record<keyof typeof published, true> = declared\n`,\n\t)\n\tconst project = writeDistributionProject(stage, name, surface.driver, [`./${module}`])\n\treturn checkDistributionProject(stage, project).map((line) => `${surface.driver.label}: ${line}`)\n}\n\n// One consumer module importing every installed entry, written where its own\n// resolution finds the installed package.\n/**\n * Writes a consumer importing the requested public specifiers.\n *\n * @param stage - The installed consumer.\n * @param path - The consumer-relative source path.\n * @param specifiers - The public imports to resolve.\n */\nexport function writeDistributionConsumerProbe(\n\tstage: DistributionStage,\n\tpath: string,\n\tspecifiers: readonly string[],\n): void {\n\tconst modules = specifiers.map((specifier, index) => ({\n\t\tbinding: `entry${String(index)}`,\n\t\tspecifier,\n\t}))\n\tconst bindings = modules.map(\n\t\t({ binding, specifier }) => `import * as ${binding} from ${JSON.stringify(specifier)}`,\n\t)\n\tconst names = modules.map(({ binding }) => binding)\n\tconst source = `${bindings.join('\\n')}\\nexport const surface = [${names.join(', ')}]\\n`\n\twriteDistributionFile(join(stage.consumer, path), source)\n}\n\n// The runtime key set a real process reads off one installed entry under one\n// condition. The driver is a file rather than an `--eval` string, so the specifier\n// travels as an argument and nothing needs escaping.\n/**\n * Reads the names a real Node process loads from an installed entry.\n *\n * @param stage - The installed consumer.\n * @param specifier - The public package specifier.\n * @param driver - The consumer driver filename.\n * @returns The exported names. Throws when loading or decoding fails.\n */\nexport function driveDistributionRuntime(\n\tstage: DistributionStage,\n\tspecifier: string,\n\tdriver: string,\n): readonly string[] {\n\tconst result = runDistributionNode([join(stage.consumer, driver), specifier], stage.consumer)\n\tif (result.status !== 0) {\n\t\tthrow new Error(\n\t\t\t`Loading ${specifier} from the consumer failed: ${readDistributionOutput(result)}`,\n\t\t)\n\t}\n\tconst published: unknown = JSON.parse(result.stdout)\n\tif (!isDistributionNames(published))\n\t\tthrow new Error(`The driver printed no name list for ${specifier}`)\n\treturn published\n}\n{{helpers}}\n// Pack this workspace, install the archive into an isolated consumer, and read the\n// published surface back off the installed tree. Every later claim reads this\n// result, so a failure here is raised where it happens rather than once per entry.\n/**\n * Packs the workspace and installs its archive into an isolated consumer.\n *\n * @param scratch - The owned scratch root.\n * @returns The installed consumer and classified exports.\n * @throws Thrown when packing or installation fails.\n */\nexport function buildDistributionStage(scratch: string): DistributionStage {\n\tconst packed = join(scratch, 'packed')\n\tconst consumer = join(scratch, 'consumer')\n\tmkdirSync(packed, { recursive: true })\n\tconst pack = runDistributionNpm(\n\t\t['pack', '--ignore-scripts', '--pack-destination', packed],\n\t\tDISTRIBUTION_ROOT,\n\t\tscratch,\n\t)\n\tif (pack.status !== 0)\n\t\tthrow new Error(`npm pack refused this workspace: ${readDistributionOutput(pack)}`)\n\tconst archives = readdirSync(packed).filter((name) => name.endsWith('.tgz'))\n\tconst archive = archives[0]\n\tif (archives.length !== 1 || archive === undefined) {\n\t\tthrow new Error(`npm pack wrote no single archive: ${archives.join(', ')}`)\n\t}\n\tconst peers = readDistributionPeers(join(DISTRIBUTION_ROOT, 'package.json'))\n\twriteDistributionFile(join(consumer, 'package.json'), createDistributionConsumerManifest(peers))\n\twriteDistributionFile(join(consumer, DISTRIBUTION_ESM_DRIVER), DISTRIBUTION_ESM_DRIVER_SOURCE)\n\twriteDistributionFile(join(consumer, DISTRIBUTION_CJS_DRIVER), DISTRIBUTION_CJS_DRIVER_SOURCE)\n\tconst install = runDistributionNpm(\n\t\t['install', '--ignore-scripts', '--no-audit', '--no-fund', join(packed, archive)],\n\t\tconsumer,\n\t\tscratch,\n\t)\n\tif (install.status !== 0) {\n\t\tthrow new Error(`Installing the packed archive failed: ${readDistributionOutput(install)}`)\n\t}\n\tconst name = readDistributionManifestName(join(DISTRIBUTION_ROOT, 'package.json'))\n\tconst installed = join(consumer, 'node_modules', ...name.split('/'))\n\tconst manifest = readDistributionJSON(join(installed, 'package.json'))\n\tif (!isDistributionRecord(manifest) || !isDistributionRecord(manifest.exports)) {\n\t\tthrow new Error('The installed manifest publishes no exports map')\n\t}\n\treturn { consumer, installed, archives, ...classifyDistributionStage(manifest, installed, name) }\n}\n\n// One file's run: the scratch directory and the staged consumer, which is absent when the\n// registry could not be reached.\n/** Binds an owned scratch directory to its optional installed consumer. */\nexport interface DistributionRun {\n\treadonly scratch: string\n\treadonly stage: DistributionStage | undefined\n}\n\n// The run the start hook binds once for this file and the stop hook releases.\n/** Owns the staged consumer shared by one distribution proof. */\nexport class DistributionSuite implements DistributionSuiteInterface {\n\t#run: DistributionRun | undefined\n\n\tget scratch(): string {\n\t\tif (this.#run === undefined) {\n\t\t\tthrow new Error('The distribution setup has not allocated its scratch directory')\n\t\t}\n\t\treturn this.#run.scratch\n\t}\n\n\tread(context: TestContext): DistributionStage {\n\t\tconst stage = this.#run?.stage\n\t\tif (stage === undefined) {\n\t\t\treturn context.skip('`npm ping` did not answer, so nothing was packed or installed')\n\t\t}\n\t\treturn stage\n\t}\n\n\tstart(): void {\n\t\tif (this.#run !== undefined) {\n\t\t\tthrow new Error('The distribution setup has already allocated its scratch directory')\n\t\t}\n\t\tconst scratch = mkdtempSync(join(tmpdir(), 'distribution-'))\n\t\tthis.#run = { scratch, stage: openDistributionStage(scratch) }\n\t}\n\n\tdestroy(): void {\n\t\tif (this.#run !== undefined) {\n\t\t\trmSync(this.#run.scratch, { force: true, recursive: true, maxRetries: 3, retryDelay: 100 })\n\t\t}\n\t\tthis.#run = undefined\n\t}\n}\n\n// Installing the packed archive resolves its own runtime dependencies, so an\n// unreachable registry leaves nothing to measure. Under release that is the gate\n// failing; anywhere else the suite skips and names the mechanism it wanted.\n/**\n * Opens an installed consumer after checking registry readiness.\n *\n * @param scratch - The owned scratch root.\n * @returns The installed consumer, or undefined when an ordinary run cannot reach the registry.\n * @throws Thrown in release mode or when staging fails, after removing scratch.\n */\nexport function openDistributionStage(scratch: string): DistributionStage | undefined {\n\ttry {\n\t\tmkdirSync(join(scratch, 'cache'), { recursive: true })\n\t\tif (runDistributionNpm(DISTRIBUTION_PING, DISTRIBUTION_ROOT, scratch).status !== 0) {\n\t\t\tif (!DISTRIBUTION_RELEASE) return undefined\n\t\t\tthrow new Error(\n\t\t\t\t'The release gate requires a reachable npm registry, and npm ping did not answer',\n\t\t\t)\n\t\t}\n\t\treturn buildDistributionStage(scratch)\n\t} catch (error) {\n\t\trmSync(scratch, {\n\t\t\tforce: true,\n\t\t\trecursive: true,\n\t\t\tmaxRetries: 3,\n\t\t\tretryDelay: 100,\n\t\t})\n\t\tthrow error\n\t}\n}\n\n/**\n * Partitions an installed exports map into driven, undeclared, and excluded subpaths.\n *\n * @param manifest - The installed package manifest.\n * @param installed - The installed package root.\n * @param name - The published package name.\n * @returns The classified entries and complete target population.\n * @throws Thrown when the exports map is absent.\n */\nexport function classifyDistributionStage(\n\tmanifest: Readonly<Record<string, unknown>>,\n\tinstalled: string,\n\tname: string,\n): DistributionClassification {\n\tif (!isDistributionRecord(manifest.exports))\n\t\tthrow new Error('The installed manifest publishes no exports map')\n\tconst readings = Object.entries(manifest.exports).map(([subpath, mapping]) => {\n\t\tconst files = collectDistributionTargets(mapping)\n\t\tconst declaration = readDistributionDeclaration(mapping, installed)\n\t\t// A subpath resolving no declaration is partitioned rather than dropped. It is a\n\t\t// defect when a runtime loads one of its targets for names, because a consumer\n\t\t// importing it compiles against nothing under `node16`. It is an excluded\n\t\t// publication otherwise: the `\"./package.json\"` manifest pointer and a stylesheet\n\t\t// are published for a reader rather than an importer.\n\t\tif (\n\t\t\tdeclaration.module === undefined &&\n\t\t\tdeclaration.commonjs === undefined &&\n\t\t\tdeclaration.browser === undefined\n\t\t) {\n\t\t\treturn { subpath, files, entry: undefined }\n\t\t}\n\t\tconst importTarget = resolveDistributionTarget(mapping, DISTRIBUTION_RUNTIME_CONDITIONS.module)\n\t\tconst requireTarget = resolveDistributionTarget(\n\t\t\tmapping,\n\t\t\tDISTRIBUTION_RUNTIME_CONDITIONS.commonjs,\n\t\t)\n\t\tconst browserTarget = resolveDistributionTarget(\n\t\t\tmapping,\n\t\t\tDISTRIBUTION_RUNTIME_CONDITIONS.browser,\n\t\t)\n\t\tconst browsable = resolvesDistributionBrowser(mapping)\n\t\tconst shadowed = browsable && requireTarget === browserTarget\n\t\tconst requirable = requireTarget !== undefined && !shadowed\n\t\tconst loadable = requirable && resolvesDistributionCommonJS(mapping, installed)\n\t\tconst entry: DistributionEntry = {\n\t\t\tsubpath,\n\t\t\tspecifier: subpath === '.' ? name : `${name}${subpath.slice(1)}`,\n\t\t\tmapping,\n\t\t\tdeclaration: {\n\t\t\t\timportable: declaration.module !== undefined,\n\t\t\t\trequirable: declaration.commonjs !== undefined,\n\t\t\t\tbrowsable: declaration.browser !== undefined,\n\t\t\t},\n\t\t\tbrowsable,\n\t\t\timportable: importTarget !== undefined && !(browsable && importTarget === browserTarget),\n\t\t\trequirable,\n\t\t\tloadable,\n\t\t}\n\t\treturn { subpath, files, entry }\n\t})\n\tconst entries = readings.flatMap(({ entry }) => (entry === undefined ? [] : [entry]))\n\tconst targets = readings.flatMap(({ files }) => files)\n\tconst subpaths = readings.map(({ subpath }) => subpath)\n\tconst undeclared = readings\n\t\t.filter(({ entry, files }) => entry === undefined && files.some(matchesDistributionModule))\n\t\t.map(({ subpath }) => subpath)\n\tconst excluded = readings\n\t\t.filter(({ entry, files }) => entry === undefined && !files.some(matchesDistributionModule))\n\t\t.map(({ subpath }) => subpath)\n\treturn { entries, subpaths, undeclared, excluded, targets }\n}\n\n/**\n * Creates the lifecycle boundary used by generated distribution proofs.\n * @returns The suite interface backed by an owned run.\n */\nexport function createDistributionSuite(): DistributionSuiteInterface {\n\treturn new DistributionSuite()\n}\n\n/**\n * Collects physical files beneath an installed output directory.\n * @param directory - The output directory to walk.\n * @returns The installed files, or an empty list when the directory is absent.\n */\nexport function collectDistributionFiles(directory: string): readonly string[] {\n\tif (!existsSync(directory)) return []\n\treturn readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {\n\t\tconst path = join(directory, entry.name)\n\t\treturn entry.isDirectory() ? collectDistributionFiles(path) : entry.isFile() ? [path] : []\n\t})\n}\n\n/**\n * Reads the source environment owning an installed output path.\n * @param installed - The installed package root.\n * @param path - The output file.\n * @returns The source environment, or undefined outside a JavaScript face.\n */\nexport function readDistributionFace(installed: string, path: string): string | undefined {\n\tconst [output, axis, face] = relativePath(installed, path).split(sep)\n\treturn output === 'dist'\n\t\t? axis === 'src'\n\t\t\t? face\n\t\t\t: axis === 'bin'\n\t\t\t\t? 'bin'\n\t\t\t\t: undefined\n\t\t: undefined\n}\n\n/**\n * Scans installed JavaScript maps for sources copied from another environment.\n * @param installed - The installed package root.\n * @returns The copied sources and unreadable maps.\n * @throws Thrown when a code-bearing output has no readable map of its own.\n */\nexport function scanDistributionSourceMaps(installed: string): readonly string[] {\n\tconst files = collectDistributionFiles(join(installed, 'dist')).filter(\n\t\t(path) => readDistributionFace(installed, path) !== undefined,\n\t)\n\tconst outputs = files\n\t\t.filter((path) => /\\.(?:js|cjs|mjs)$/u.test(path))\n\t\t.map((path) => {\n\t\t\tconst parsed = parseSync(path, readFileSync(path, 'utf8'))\n\t\t\tconst code = parsed.program.body.some(\n\t\t\t\t(statement) =>\n\t\t\t\t\tstatement.type !== 'EmptyStatement' &&\n\t\t\t\t\t!(\n\t\t\t\t\t\tstatement.type === 'ExportNamedDeclaration' &&\n\t\t\t\t\t\tstatement.declaration === null &&\n\t\t\t\t\t\tstatement.specifiers.length === 0 &&\n\t\t\t\t\t\tstatement.source === null\n\t\t\t\t\t),\n\t\t\t)\n\t\t\tconst reference = parsed.comments\n\t\t\t\t.flatMap((comment) => {\n\t\t\t\t\tconst match = /^[@#]\\s*sourceMappingURL=(\\S+)\\s*$/u.exec(comment.value)\n\t\t\t\t\treturn match?.[1] === undefined ? [] : [match[1]]\n\t\t\t\t})\n\t\t\t\t.at(-1)\n\t\t\ttry {\n\t\t\t\tconst inline = reference?.startsWith('data:') === true\n\t\t\t\tconst target = inline\n\t\t\t\t\t? path\n\t\t\t\t\t: reference === undefined\n\t\t\t\t\t\t? `${path}.map`\n\t\t\t\t\t\t: fileURLToPath(new URL(reference.replaceAll('\\\\', '/'), pathToFileURL(path)))\n\t\t\t\treturn {\n\t\t\t\t\tpath: target,\n\t\t\t\t\tface: readDistributionFace(installed, path),\n\t\t\t\t\tcode,\n\t\t\t\t\treference: inline ? reference : undefined,\n\t\t\t\t}\n\t\t\t} catch {\n\t\t\t\tthrow new Error(`Unreadable source maps for ${path}`)\n\t\t\t}\n\t\t})\n\tconst maps = [\n\t\t...outputs.filter(\n\t\t\t({ path, code, reference }) => code || reference !== undefined || existsSync(path),\n\t\t),\n\t\t...files\n\t\t\t.filter(\n\t\t\t\t(path) =>\n\t\t\t\t\t/\\.(?:js|cjs|mjs)\\.map$/u.test(path) && !outputs.some((output) => output.path === path),\n\t\t\t)\n\t\t\t.map((path) => ({\n\t\t\t\tpath,\n\t\t\t\tface: readDistributionFace(installed, path),\n\t\t\t\tcode: false,\n\t\t\t\treference: undefined,\n\t\t\t})),\n\t]\n\tif (maps.length === 0)\n\t\tconsole.info('No built JavaScript face holds code, so no source map is required')\n\treturn maps.flatMap(({ path, face, code, reference }) => {\n\t\tconst label = relativePath(installed, path).split(sep).join('/')\n\t\ttry {\n\t\t\tconst payload =\n\t\t\t\treference === undefined\n\t\t\t\t\t? undefined\n\t\t\t\t\t: /^data:application\\/json(?:;charset=[^;,]+)?(;base64)?,(.*)$/iu.exec(reference)\n\t\t\tconst map: unknown =\n\t\t\t\treference === undefined\n\t\t\t\t\t? readDistributionJSON(path)\n\t\t\t\t\t: payload?.[2] === undefined\n\t\t\t\t\t\t? undefined\n\t\t\t\t\t\t: JSON.parse(\n\t\t\t\t\t\t\t\tpayload[1] === undefined\n\t\t\t\t\t\t\t\t\t? decodeURIComponent(payload[2])\n\t\t\t\t\t\t\t\t\t: Buffer.from(payload[2], 'base64').toString('utf8'),\n\t\t\t\t\t\t\t)\n\t\t\tif (\n\t\t\t\t!isDistributionRecord(map) ||\n\t\t\t\t!isDistributionNames(map.sources) ||\n\t\t\t\t(map.sourceRoot !== undefined && typeof map.sourceRoot !== 'string')\n\t\t\t) {\n\t\t\t\tthrow new Error('Unreadable source map')\n\t\t\t}\n\t\t\tconst root = typeof map.sourceRoot === 'string' ? map.sourceRoot : ''\n\t\t\tconst directory = root.startsWith('file:')\n\t\t\t\t? fileURLToPath(new URL(root))\n\t\t\t\t: resolve(dirname(path), root.replaceAll('\\\\', '/'))\n\t\t\tconst sources = map.sources.map((source) =>\n\t\t\t\trelativePath(\n\t\t\t\t\tresolve(installed),\n\t\t\t\t\tsource.startsWith('file:')\n\t\t\t\t\t\t? fileURLToPath(new URL(source))\n\t\t\t\t\t\t: resolve(directory, source.replaceAll('\\\\', '/')),\n\t\t\t\t)\n\t\t\t\t\t.split(sep)\n\t\t\t\t\t.join('/'),\n\t\t\t)\n\t\t\tconst copied = sources.filter(\n\t\t\t\t(source) => source.startsWith('src/') && !source.startsWith(`src/${face}/`),\n\t\t\t)\n\t\t\treturn [\n\t\t\t\t...copied.map((source) => `${label}: ${source}`),\n\t\t\t\t...(sources.some((source) => source.startsWith(`src/${face}/`))\n\t\t\t\t\t? []\n\t\t\t\t\t: [`${label}: unreadable source map (no src/${face}/ source)`]),\n\t\t\t]\n\t\t} catch {\n\t\t\tif (code) throw new Error(`Unreadable source maps for ${path}`)\n\t\t\treturn [`${label}: unreadable source map`]\n\t\t}\n\t})\n}\n\n/**\n * Reads top-level names declared by a roll-up, including unexported declarations.\n * @param path - The installed declaration file.\n * @returns The declared names. Refuses syntax errors and unreadable binding patterns.\n */\nexport function readDistributionNames(path: string): readonly string[] {\n\tconst source = parseSync(path, readFileSync(path, 'utf8'))\n\tif (source.errors.length > 0) throw new Error(`Unreadable declarations at ${path}`)\n\treturn source.program.body.flatMap((statement) => {\n\t\tconst declaration =\n\t\t\tstatement.type === 'ExportNamedDeclaration' || statement.type === 'ExportDefaultDeclaration'\n\t\t\t\t? statement.declaration\n\t\t\t\t: statement\n\t\tif (declaration === null) return []\n\t\tif (declaration.type === 'VariableDeclaration') {\n\t\t\treturn declaration.declarations.map((binding) => {\n\t\t\t\tif (binding.id.type !== 'Identifier')\n\t\t\t\t\tthrow new Error(`Unreadable declaration binding at ${path}`)\n\t\t\t\treturn binding.id.name\n\t\t\t})\n\t\t}\n\t\tif (\n\t\t\tdeclaration.type === 'ClassDeclaration' ||\n\t\t\tdeclaration.type === 'FunctionDeclaration' ||\n\t\t\tdeclaration.type === 'TSDeclareFunction' ||\n\t\t\tdeclaration.type === 'TSInterfaceDeclaration' ||\n\t\t\tdeclaration.type === 'TSTypeAliasDeclaration' ||\n\t\t\tdeclaration.type === 'TSEnumDeclaration' ||\n\t\t\tdeclaration.type === 'TSModuleDeclaration'\n\t\t) {\n\t\t\treturn declaration.id?.type === 'Identifier' ? [declaration.id.name] : []\n\t\t}\n\t\treturn []\n\t})\n}\n\n/**\n * Checks whether a source entry exports names, following local star exports.\n * @param path - The source entry to inspect.\n * @param ancestors - The entries already visited on this export path.\n * @returns True if the entry exports a name; false otherwise.\n */\nexport function matchesDistributionSourceExports(\n\tpath: string,\n\tancestors: readonly string[] = [],\n): boolean {\n\tif (ancestors.includes(path)) return false\n\tconst source = parseSync(path, readFileSync(path, 'utf8'))\n\tif (source.errors.length > 0) throw new Error(`Unreadable source exports at ${path}`)\n\treturn source.program.body.some((statement) => {\n\t\tif (statement.type === 'ExportDefaultDeclaration') return ancestors.length === 0\n\t\tif (statement.type === 'ExportNamedDeclaration')\n\t\t\treturn (\n\t\t\t\tstatement.declaration !== null ||\n\t\t\t\tstatement.specifiers.some((specifier) => {\n\t\t\t\t\tconst name =\n\t\t\t\t\t\tspecifier.exported.type === 'Identifier'\n\t\t\t\t\t\t\t? specifier.exported.name\n\t\t\t\t\t\t\t: specifier.exported.value\n\t\t\t\t\treturn ancestors.length === 0 || name !== 'default'\n\t\t\t\t})\n\t\t\t)\n\t\tif (statement.type !== 'ExportAllDeclaration') return false\n\t\tif (statement.exported !== null || !statement.source.value.startsWith('.')) return true\n\t\tconst target = resolve(dirname(path), statement.source.value.replace(/\\.js$/u, '.ts'))\n\t\treturn matchesDistributionSourceExports(target, [...ancestors, path])\n\t})\n}\n\n/**\n * Scans installed declaration faces for names declared by multiple environments.\n * @param installed - The installed package root.\n * @param source - The workspace holding the source entries being published.\n * @returns The repeated names with their declaring faces.\n * @throws Thrown when a source entry exports names but its roll-up declares none.\n */\nexport function scanDistributionDeclarations(\n\tinstalled: string,\n\tsource: string = DISTRIBUTION_ROOT,\n): readonly string[] {\n\tconst declarations = collectDistributionFiles(join(installed, 'dist'))\n\t\t.filter(matchesDistributionDeclaration)\n\t\t.map((path) => ({\n\t\t\tpath,\n\t\t\tface: readDistributionFace(installed, path),\n\t\t\tnames: readDistributionNames(path),\n\t\t}))\n\tconst entries = collectDistributionFiles(join(source, 'src')).filter((path) => {\n\t\tconst parts = relativePath(source, path).split(sep)\n\t\treturn parts.length === 3 && parts[2] === 'index.ts'\n\t})\n\tconst published = entries.filter((path) => matchesDistributionSourceExports(path))\n\tfor (const path of published) {\n\t\tconst face = relativePath(source, path).split(sep)[1]\n\t\tif (!declarations.some((entry) => entry.face === face && entry.names.length > 0))\n\t\t\tthrow new Error(\n\t\t\t\t`The ${face} source entry exports names but its declaration roll-up declares none`,\n\t\t\t)\n\t}\n\tif (published.length === 0)\n\t\tconsole.info('No source entry exports names, so no declaration names are required')\n\tconst names = [...new Set(declarations.flatMap((entry) => entry.names))].sort()\n\treturn names.flatMap((name) => {\n\t\tconst faces = [\n\t\t\t...new Set(\n\t\t\t\tdeclarations\n\t\t\t\t\t.filter((entry) => entry.names.includes(name))\n\t\t\t\t\t.map((entry) => entry.face)\n\t\t\t\t\t.filter((face) => face !== undefined),\n\t\t\t),\n\t\t].sort()\n\t\treturn faces.length > 1 ? [`${name}: ${faces.join(', ')}`] : []\n\t})\n}\n\n/**\n * Checks the installed manifest against npm's normalization in an owned scratch copy.\n * @param installed - The installed package root, read only.\n * @param scratch - The suite's owned scratch root and npm cache parent.\n * @returns The top-level keys changed by npm. Refuses an unsuccessful npm command.\n */\nexport function checkDistributionManifest(installed: string, scratch: string): readonly string[] {\n\tconst directory = mkdtempSync(join(scratch, 'manifest-'))\n\ttry {\n\t\tconst path = join(directory, 'package.json')\n\t\twriteFileSync(path, readFileSync(join(installed, 'package.json')))\n\t\tconst before = readDistributionJSON(path)\n\t\tconst result = runDistributionNpm(['pkg', 'fix'], directory, scratch)\n\t\tif (result.status !== 0)\n\t\t\tthrow new Error(`npm pkg fix failed: ${readDistributionOutput(result)}`)\n\t\tconst after = readDistributionJSON(path)\n\t\tif (!isDistributionRecord(before) || !isDistributionRecord(after))\n\t\t\tthrow new Error('Unreadable manifest')\n\t\treturn [...new Set([...Object.keys(before), ...Object.keys(after)])]\n\t\t\t.filter((key) => !isDeepStrictEqual(before[key], after[key]))\n\t\t\t.sort()\n\t} finally {\n\t\trmSync(directory, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 })\n\t}\n}\n\n/**\n * Builds independently registered observations over the suite's installed consumer.\n * @param suite - The lifecycle shared by the proof's hooks and observations.\n * @returns The case rows whose observations each require one assertion.\n */\nexport function buildDistributionCases(\n\tsuite: DistributionSuiteInterface,\n): readonly DistributionCase[] {\n\treturn [\n\t\t{\n\t\t\tlabel: 'classifies synthetic export mappings without a registry stage',\n\t\t\tobserve: () => {\n\t\t\t\tconst root = join(suite.scratch, 'classifiers')\n\t\t\t\twriteDistributionFile(\n\t\t\t\t\tjoin(root, 'package.json'),\n\t\t\t\t\tJSON.stringify({\n\t\t\t\t\t\ttype: 'commonjs',\n\t\t\t\t\t\texports: {\n\t\t\t\t\t\t\tcondition: { browser: './b.js', default: './n.js' },\n\t\t\t\t\t\t\tconvention: { default: './dist/src/browser/index.js' },\n\t\t\t\t\t\t\tuniversal: { default: './shared.js' },\n\t\t\t\t\t\t\t'import-shared': {\n\t\t\t\t\t\t\t\tbrowser: './shared.mjs',\n\t\t\t\t\t\t\t\timport: './shared.mjs',\n\t\t\t\t\t\t\t\tdefault: './node.js',\n\t\t\t\t\t\t\t},\n\t\t\t\t\t\t\t'require-shared': {\n\t\t\t\t\t\t\t\tbrowser: './shared.cjs',\n\t\t\t\t\t\t\t\trequire: './shared.cjs',\n\t\t\t\t\t\t\t\tdefault: './node.js',\n\t\t\t\t\t\t\t},\n\t\t\t\t\t\t\tnode: { node: './node.js', default: './node.js' },\n\t\t\t\t\t\t\tsilent: { 'module-sync': './x.cjs', import: './x.mjs' },\n\t\t\t\t\t\t\tmodule: { require: './x.mjs' },\n\t\t\t\t\t\t\t'nested-module': { require: './module/x.js' },\n\t\t\t\t\t\t\t'nested-commonjs': { require: './commonjs/x.js' },\n\t\t\t\t\t\t\tesm: { import: './x.mjs' },\n\t\t\t\t\t\t},\n\t\t\t\t\t}),\n\t\t\t\t)\n\t\t\t\twriteDistributionFile(join(root, 'module/package.json'), '{ \"type\": \"module\" }\\n')\n\t\t\t\twriteDistributionFile(join(root, 'commonjs/package.json'), '{ \"type\": \"commonjs\" }\\n')\n\t\t\t\tconst manifest = readDistributionJSON(join(root, 'package.json'))\n\t\t\t\tif (!isDistributionRecord(manifest) || !isDistributionRecord(manifest.exports)) {\n\t\t\t\t\tthrow new Error('The classifier fixture declares no exports map')\n\t\t\t\t}\n\t\t\t\tconst mappings = manifest.exports\n\n\t\t\t\treturn {\n\t\t\t\t\tactual: {\n\t\t\t\t\t\tbrowser: {\n\t\t\t\t\t\t\tcondition: resolvesDistributionBrowser(mappings.condition),\n\t\t\t\t\t\t\tconvention: resolvesDistributionBrowser(mappings.convention),\n\t\t\t\t\t\t\tuniversal: resolvesDistributionBrowser(mappings.universal),\n\t\t\t\t\t\t\timport: resolvesDistributionBrowser(mappings['import-shared']),\n\t\t\t\t\t\t\trequire: resolvesDistributionBrowser(mappings['require-shared']),\n\t\t\t\t\t\t\tnode: resolvesDistributionBrowser(mappings.node),\n\t\t\t\t\t\t},\n\t\t\t\t\t\tcommonjs: {\n\t\t\t\t\t\t\tsilent: resolvesDistributionCommonJS(mappings.silent, root),\n\t\t\t\t\t\t\tmodule: resolvesDistributionCommonJS(mappings.module, root),\n\t\t\t\t\t\t\tnestedModule: resolvesDistributionCommonJS(mappings['nested-module'], root),\n\t\t\t\t\t\t\tnestedCommonJS: resolvesDistributionCommonJS(mappings['nested-commonjs'], root),\n\t\t\t\t\t\t\tesm: resolvesDistributionCommonJS(mappings.esm, root),\n\t\t\t\t\t\t},\n\t\t\t\t\t},\n\t\t\t\t\texpected: {\n\t\t\t\t\t\tbrowser: {\n\t\t\t\t\t\t\tcondition: true,\n\t\t\t\t\t\t\tconvention: true,\n\t\t\t\t\t\t\tuniversal: false,\n\t\t\t\t\t\t\timport: false,\n\t\t\t\t\t\t\trequire: false,\n\t\t\t\t\t\t\tnode: false,\n\t\t\t\t\t\t},\n\t\t\t\t\t\tcommonjs: {\n\t\t\t\t\t\t\tsilent: true,\n\t\t\t\t\t\t\tmodule: false,\n\t\t\t\t\t\t\tnestedModule: false,\n\t\t\t\t\t\t\tnestedCommonJS: true,\n\t\t\t\t\t\t\tesm: false,\n\t\t\t\t\t\t},\n\t\t\t\t\t},\n\t\t\t\t}\n\t\t\t},\n\t\t},\n\t\t{\n\t\t\tlabel: 'keeps installed JavaScript sources in their own environment [requires the registry]',\n\t\t\tobserve: (context) => {\n\t\t\t\tconst stage = suite.read(context)\n\t\t\t\treturn { actual: scanDistributionSourceMaps(stage.installed), expected: [] }\n\t\t\t},\n\t\t},\n\t\t{\n\t\t\tlabel: 'declares each installed name in one environment [requires the registry]',\n\t\t\tobserve: (context) => {\n\t\t\t\tconst stage = suite.read(context)\n\t\t\t\tconst faces = new Set(\n\t\t\t\t\tcollectDistributionFiles(join(stage.installed, 'dist'))\n\t\t\t\t\t\t.filter(matchesDistributionDeclaration)\n\t\t\t\t\t\t.map((path) => readDistributionFace(stage.installed, path))\n\t\t\t\t\t\t.filter((face) => face !== undefined),\n\t\t\t\t)\n\t\t\t\tconst findings = scanDistributionDeclarations(stage.installed)\n\t\t\t\tif (faces.size <= 1)\n\t\t\t\t\tconsole.info(\n\t\t\t\t\t\t'Fewer than two declaration faces are installed, so no cross-face copy exists',\n\t\t\t\t\t)\n\t\t\t\treturn { actual: findings, expected: [] }\n\t\t\t},\n\t\t},\n\t\t{\n\t\t\tlabel: 'keeps the installed manifest fixed under npm pkg fix [requires the registry]',\n\t\t\tobserve: (context) => ({\n\t\t\t\tactual: checkDistributionManifest(suite.read(context).installed, suite.scratch),\n\t\t\t\texpected: [],\n\t\t\t}),\n\t\t},\n\t\t{\n\t\t\tlabel: 'packs one archive and installs it in isolation [requires the registry]',\n\t\t\tobserve: (context) => {\n\t\t\t\tconst stage = suite.read(context)\n\t\t\t\treturn {\n\t\t\t\t\tactual: {\n\t\t\t\t\t\tarchives: stage.archives.length,\n\t\t\t\t\t\tinstalled: existsSync(join(stage.installed, 'package.json')),\n\t\t\t\t\t\tentries: stage.entries.length > 0,\n\t\t\t\t\t},\n\t\t\t\t\texpected: { archives: 1, installed: true, entries: true },\n\t\t\t\t}\n\t\t\t},\n\t\t},\n\t\t{\n\t\t\tlabel: 'ships every relative target its exports map names [requires the registry]',\n\t\t\tobserve: (context) => {\n\t\t\t\tconst stage = suite.read(context)\n\t\t\t\tconst relative = stage.targets.filter((target) => target.startsWith('./'))\n\t\t\t\treturn {\n\t\t\t\t\tactual: {\n\t\t\t\t\t\tpopulated: relative.length > 0,\n\t\t\t\t\t\tmissing: relative.filter((target) => !existsSync(join(stage.installed, target))),\n\t\t\t\t\t},\n\t\t\t\t\texpected: { populated: true, missing: [] },\n\t\t\t\t}\n\t\t\t},\n\t\t},\n\t\t{\n\t\t\tlabel: 'declares types for every module it publishes [requires the registry]',\n\t\t\tobserve: (context) => {\n\t\t\t\tconst stage = suite.read(context)\n\t\t\t\tconst partitioned = [\n\t\t\t\t\t...stage.entries.map((entry) => entry.subpath),\n\t\t\t\t\t...stage.undeclared,\n\t\t\t\t\t...stage.excluded,\n\t\t\t\t]\n\t\t\t\treturn {\n\t\t\t\t\tactual: {\n\t\t\t\t\t\tundeclared: stage.undeclared,\n\t\t\t\t\t\tpartitioned: partitioned.sort(),\n\t\t\t\t\t\tunreachable: stage.entries\n\t\t\t\t\t\t\t.filter((entry) => !entry.importable && !entry.requirable && !entry.browsable)\n\t\t\t\t\t\t\t.map((entry) => entry.subpath),\n\t\t\t\t\t\tuntypable: filterDistributionUntypable(stage.entries, stage.installed).map(\n\t\t\t\t\t\t\t(entry) => entry.subpath,\n\t\t\t\t\t\t),\n\t\t\t\t\t},\n\t\t\t\t\texpected: {\n\t\t\t\t\t\tundeclared: [],\n\t\t\t\t\t\tpartitioned: [...stage.subpaths].sort(),\n\t\t\t\t\t\tunreachable: [],\n\t\t\t\t\t\tuntypable: [],\n\t\t\t\t\t},\n\t\t\t\t}\n\t\t\t},\n\t\t},\n\t\t{\n\t\t\tlabel: 'refuses a subpath its exports map does not name [requires the registry]',\n\t\t\tobserve: (context) => {\n\t\t\t\tconst stage = suite.read(context)\n\t\t\t\tconst name = readDistributionManifestName(join(stage.installed, 'package.json'))\n\t\t\t\tconst result = runDistributionNode(\n\t\t\t\t\t[join(stage.consumer, DISTRIBUTION_ESM_DRIVER), `${name}${DISTRIBUTION_ABSENT_SUBPATH}`],\n\t\t\t\t\tstage.consumer,\n\t\t\t\t)\n\t\t\t\treturn {\n\t\t\t\t\tactual: {\n\t\t\t\t\t\trefused: result.status !== 0,\n\t\t\t\t\t\tcoded: readDistributionOutput(result).includes('ERR_PACKAGE_PATH_NOT_EXPORTED'),\n\t\t\t\t\t},\n\t\t\t\t\texpected: { refused: true, coded: true },\n\t\t\t\t}\n\t\t\t},\n\t\t},\n\t\t{\n\t\t\tlabel: 'compiles a consumer under every module resolution [requires the registry]',\n\t\t\tobserve: (context) => {\n\t\t\t\tconst stage = suite.read(context)\n\t\t\t\tconst name = readDistributionManifestName(join(stage.installed, 'package.json'))\n\t\t\t\tconst readings = DISTRIBUTION_RESOLUTIONS.flatMap((driver) =>\n\t\t\t\t\tDISTRIBUTION_FORMATS.flatMap(([extension, format]) => {\n\t\t\t\t\t\tconst written = filterDistributionEntries(stage.entries, driver.conditions[format])\n\t\t\t\t\t\tif (written.length === 0) return []\n\t\t\t\t\t\tconst label = `${driver.label}.${extension}`\n\t\t\t\t\t\tconst probe = `probe.${label}`\n\t\t\t\t\t\tconst specifiers = written.map((entry) => entry.specifier)\n\t\t\t\t\t\twriteDistributionConsumerProbe(stage, probe, specifiers)\n\t\t\t\t\t\tconst project = writeDistributionProject(stage, probe, driver, [`./${probe}`])\n\t\t\t\t\t\tconst messages = checkDistributionProject(stage, project).map(\n\t\t\t\t\t\t\t(message) => `${label}: ${message}`,\n\t\t\t\t\t\t)\n\t\t\t\t\t\tconst control = `control.${label}`\n\t\t\t\t\t\twriteDistributionConsumerProbe(stage, control, [\n\t\t\t\t\t\t\t`${name}${DISTRIBUTION_ABSENT_SUBPATH}`,\n\t\t\t\t\t\t])\n\t\t\t\t\t\tconst refused = writeDistributionProject(stage, control, driver, [`./${control}`])\n\t\t\t\t\t\treturn [\n\t\t\t\t\t\t\t{\n\t\t\t\t\t\t\t\tmessages,\n\t\t\t\t\t\t\t\tsilent: checkDistributionProject(stage, refused).length === 0 ? [label] : [],\n\t\t\t\t\t\t\t},\n\t\t\t\t\t\t]\n\t\t\t\t\t}),\n\t\t\t\t)\n\t\t\t\treturn {\n\t\t\t\t\tactual: {\n\t\t\t\t\t\tmessages: readings.flatMap(({ messages }) => messages),\n\t\t\t\t\t\tsilent: readings.flatMap(({ silent }) => silent),\n\t\t\t\t\t},\n\t\t\t\t\texpected: { messages: [], silent: [] },\n\t\t\t\t}\n\t\t\t},\n\t\t},\n\t\t{\n\t\t\tlabel: 'publishes what it declares to a Node import, and no more',\n\t\t\tobserve: (context) => {\n\t\t\t\tconst stage = suite.read(context)\n\t\t\t\tconst entries = stage.entries.filter((entry) => entry.importable)\n\t\t\t\tif (entries.length === 0) return context.skip('No installed entry supports Node import')\n\t\t\t\tconst readings = entries.map((entry) => {\n\t\t\t\t\tif (!entry.declaration.importable)\n\t\t\t\t\t\tthrow new Error(`${entry.subpath} publishes no import declaration`)\n\t\t\t\t\tconst published = driveDistributionRuntime(\n\t\t\t\t\t\tstage,\n\t\t\t\t\t\tentry.specifier,\n\t\t\t\t\t\tDISTRIBUTION_ESM_DRIVER,\n\t\t\t\t\t)\n\t\t\t\t\tconst drivers = filterDistributionResolutions(entry, 'module')\n\t\t\t\t\treturn {\n\t\t\t\t\t\tentry: entry.subpath,\n\t\t\t\t\t\tdriven: drivers.length > 0,\n\t\t\t\t\t\treported: drivers.flatMap((driver) =>\n\t\t\t\t\t\t\tcheckDistributionSurface(stage, { entry, extension: 'ts', published, driver }),\n\t\t\t\t\t\t),\n\t\t\t\t\t}\n\t\t\t\t})\n\t\t\t\treturn {\n\t\t\t\t\tactual: readings,\n\t\t\t\t\texpected: entries.map((entry) => ({ entry: entry.subpath, driven: true, reported: [] })),\n\t\t\t\t}\n\t\t\t},\n\t\t},\n\t\t{\n\t\t\tlabel: 'publishes what it declares to a Node require, and no more',\n\t\t\tobserve: (context) => {\n\t\t\t\tconst stage = suite.read(context)\n\t\t\t\tconst entries = stage.entries.filter((entry) => entry.requirable)\n\t\t\t\tif (entries.length === 0) return context.skip('No installed entry supports Node require')\n\t\t\t\tconst readings = entries.map((entry) => {\n\t\t\t\t\tif (!entry.declaration.requirable)\n\t\t\t\t\t\tthrow new Error(`${entry.subpath} publishes no require declaration`)\n\t\t\t\t\tconst published = driveDistributionRuntime(\n\t\t\t\t\t\tstage,\n\t\t\t\t\t\tentry.specifier,\n\t\t\t\t\t\tDISTRIBUTION_CJS_DRIVER,\n\t\t\t\t\t)\n\t\t\t\t\tconst drivers = filterDistributionResolutions(entry, 'commonjs')\n\t\t\t\t\treturn {\n\t\t\t\t\t\tentry: entry.subpath,\n\t\t\t\t\t\tdriven: drivers.length > 0,\n\t\t\t\t\t\treported: drivers.flatMap((driver) =>\n\t\t\t\t\t\t\tcheckDistributionSurface(stage, { entry, extension: 'cts', published, driver }),\n\t\t\t\t\t\t),\n\t\t\t\t\t}\n\t\t\t\t})\n\t\t\t\treturn {\n\t\t\t\t\tactual: readings,\n\t\t\t\t\texpected: entries.map((entry) => ({ entry: entry.subpath, driven: true, reported: [] })),\n\t\t\t\t}\n\t\t\t},\n\t\t},\n\t]\n}\n";
             proof: "import {\n\t// These exports remain available to proofs emitted by earlier scaffold releases.\n\tbuildDistributionCases,\n\t{{import}}createDistributionSuite,\n} from './setupDistribution.js'\nimport { afterAll, beforeAll, describe, expect, it } from 'vitest'\n\nconst DISTRIBUTION_SUITE = createDistributionSuite()\n\nbeforeAll(() => DISTRIBUTION_SUITE.start())\n\nafterAll(() => DISTRIBUTION_SUITE.destroy())\n\ndescribe('installed package consumer', () => {\n\tfor (const row of buildDistributionCases(DISTRIBUTION_SUITE)) {\n\t\tit(`${row.label}`, async (context) => {\n\t\t\tconst observation = await row.observe(context)\n\t\t\texpect(observation.actual).toStrictEqual(observation.expected)\n\t\t})\n\t}\n{{guard}}{{drive}}})\n";
             transport: "import { createServer } from 'node:http'\n";
             types: "import type { PlaywrightProviderOptions } from '@vitest/browser-playwright'\nimport type { Browser } from 'playwright'\n";
@@ -272,7 +272,7 @@ export declare const AXES: readonly Axis[];
 /** Names the workspace axis an extension occupies. */
 export declare type Axis = 'src' | 'app';
 
-/** Holds the tooling versions scaffold and every generated workspace share. */
+/** Holds the baseline tooling versions, before framework holds apply. */
 export declare const BASE_DEV_DEPENDENCIES: Readonly<Record<string, string>>;
 
 /** Lists the configuration files a workspace that ships its own executable adds, frozen. */
@@ -381,8 +381,10 @@ export declare function blueprintToConfigArtifacts(blueprint: Blueprint): readon
  * @returns The merged set, sorted by package name.
  *
  * @remarks
- * The shared toolchain is the baseline every generated workspace carries, and
- * each declared axis adds the set its host needs. A declared extra or peer is
+ * The shared toolchain is the baseline every generated workspace carries.
+ * A selected browser framework applies its toolchain hold before the host-specific sets.
+ * Vue faces on either axis select TypeScript 6.0.3; other workspaces select TypeScript 7.0.2.
+ * Each declared axis adds the set its host needs. A declared extra or peer is
  * applied after those, so a workspace that pins a range for a package the
  * conditional sets also name gets the range it declared. An extra that restates
  * a shared toolchain pin never reaches here, because the gate refuses it. A peer
@@ -397,6 +399,11 @@ export declare function blueprintToConfigArtifacts(blueprint: Blueprint): readon
  * to drive. A workspace {@link BROWSE_UPSTREAM} names receives nothing either, because
  * `@orkestrel/browser` depends on it at runtime and the declaration would close a cycle.
  *
+ * A journey axis with a browser application receives {@link CAPTURE_DEV_DEPENDENCIES}.
+ * A workspace {@link CAPTURE_UPSTREAM} names receives no capture seed, because it is capture
+ * itself or a member of capture's runtime closure. A browser source, styles surface, or browser
+ * setup alone selects no capture dependency.
+ *
  * A peer is declared here as well as under `peerDependencies`, because a peer is
  * not installed by the workspace that declares it and developing against one
  * requires it present. A runtime dependency is the opposite case and is removed:
@@ -677,7 +684,8 @@ export declare function blueprintToOrchestrationArtifacts(blueprint: Blueprint):
  * Projects a blueprint into the project labels its root Vitest configuration registers.
  *
  * @param blueprint - The workspace specification.
- * @returns Project labels in registration order, including wrapper-registered sheet faces.
+ * @returns Project labels in registration order, including wrapper-registered sheet faces and
+ * the probe benchmark variant.
  *
  * @example
  * ```ts
@@ -816,6 +824,9 @@ export declare function blueprintToRootVite(blueprint: Blueprint): string;
  * The configuration paths interpolated here are the same ones `SRC_MATRIX` and
  * `APP_MATRIX` list as each environment's configuration files, so a rename in
  * either matrix is a rename in both places.
+ * A browser application's journey axis adds `journey` (`capture journey`) and `capture`
+ * (`capture frames`) beside `test:journey`. The scoped commands take an explicit selection;
+ * the whole-suite `test:journey` invocation remains in the test chain.
  *
  * @example
  * ```ts
@@ -900,6 +911,19 @@ export declare function blueprintToSourceArtifacts(blueprint: Blueprint): readon
  */
 export declare function blueprintToTestArtifacts(blueprint: Blueprint): readonly ContentArtifact[];
 
+/**
+ * Projects a blueprint into the toolchain holds its browser frameworks require.
+ * @param blueprint - The workspace specification.
+ * @returns The held tools for selected browser framework faces; empty without a framework.
+ * @example
+ * ```ts
+ * import { blueprintToToolchainHolds, createBlueprint } from '@orkestrel/scaffold'
+ *
+ * blueprintToToolchainHolds(createBlueprint('router', { src: ['core'] })) // {}
+ * ```
+ */
+export declare function blueprintToToolchainHolds(blueprint: Blueprint): Readonly<Record<string, ToolchainHold>>;
+
 /**
  * Projects a blueprint into the manifest scripts a region write may replace.
  *
@@ -913,6 +937,8 @@ export declare function blueprintToTestArtifacts(blueprint: Blueprint): readonly
  * rewrites, and one carrying skills adds `test:skills`. Publishing adds the pack and publication lifecycle scripts.
  * Sheet and framework faces add their check and build scripts, application frameworks add dev scripts,
  * and selected showcases and journeys add their mode scripts.
+ * A browser application's journey axis also adds `journey` and `capture`. Their generated
+ * commands are writable and have no predecessor forms; customized values remain caller-owned.
  * Aggregate test scripts and
  * maintainer-owned gate chains stay outside the region.
  *
@@ -1028,6 +1054,41 @@ export declare function bytesToHex(bytes: Uint8Array): string;
  */
 export declare const CANON_PATHS: readonly string[];
 
+/**
+ * Names the development dependency a browser application's journey axis adds.
+ *
+ * @remarks
+ * Scaffold does not install this package, so its range is a seed. The planner withholds it
+ * from the workspaces {@link CAPTURE_UPSTREAM} lists.
+ *
+ * @example
+ * ```ts
+ * import { CAPTURE_DEV_DEPENDENCIES } from '@orkestrel/scaffold'
+ *
+ * CAPTURE_DEV_DEPENDENCIES['@orkestrel/capture'] // '^0.0.1'
+ * ```
+ */
+export declare const CAPTURE_DEV_DEPENDENCIES: Readonly<Record<string, string>>;
+
+/**
+ * Lists the capture package and its fleet runtime dependency closure, frozen.
+ *
+ * @remarks
+ * The sorted list includes `@orkestrel/capture` and its transitive `@orkestrel/*` dependencies
+ * and peers, read from capture's installed manifests, and moves with the capture pin.
+ * A listed workspace cannot receive the capture development dependency without closing a cycle.
+ * Scaffold does not install capture, so the proof checks planning against this list; the
+ * installed closure-equality proof lands when scaffold installs capture.
+ *
+ * @example
+ * ```ts
+ * import { CAPTURE_UPSTREAM } from '@orkestrel/scaffold'
+ *
+ * CAPTURE_UPSTREAM.includes('@orkestrel/process') // true
+ * ```
+ */
+export declare const CAPTURE_UPSTREAM: readonly string[];
+
 /**
  * Names the agent file whose marker-bounded package table the catalog verb alone owns.
  *
@@ -1048,21 +1109,21 @@ export declare const CATALOG_AGENT_PATH = ".claude/agents/orkestrel.md";
  * Names the marker closing the package table inside {@link CATALOG_AGENT_PATH}.
  *
  * @remarks
- * It pairs with {@link CATALOG_OPENING_MARKER}; a file missing either marker is
+ * It pairs with {@link CATALOG_START_MARKER}; a file missing either marker is
  * refused rather than rewritten.
  */
-export declare const CATALOG_CLOSING_MARKER = "<!-- /orkestrel:catalog -->";
+export declare const CATALOG_END_MARKER = "<!-- /orkestrel:catalog -->";
 
 /**
  * Names the marker opening the package table inside {@link CATALOG_AGENT_PATH}.
  *
  * @remarks
  * The catalog verb rewrites the region between this marker and
- * {@link CATALOG_CLOSING_MARKER} and leaves every other byte of the file alone,
+ * {@link CATALOG_END_MARKER} and leaves every other byte of the file alone,
  * so the writer and every proof that reads the rendered file read the pair from
  * here rather than repeating a literal that only agrees by inspection.
  */
-export declare const CATALOG_OPENING_MARKER = "<!-- orkestrel:catalog -->";
+export declare const CATALOG_START_MARKER = "<!-- orkestrel:catalog -->";
 
 /**
  * Represents one package row of the fleet catalog.
@@ -1219,7 +1280,7 @@ export declare interface CompileFailure {
  * records the coded reason beside them; the stages after a failed one never run,
  * so the records stop where the compile stopped.
  *
- * The compile fails closed on one rule: a scaffolding carries a plan exactly
+ * The compile fails closed on one rule: a compile result carries a plan exactly
  * when no question blocks. A refused blueprint is answered rather than raised,
  * so a caller reads the refusal from the value it asked for.
  *
@@ -1244,10 +1305,10 @@ export declare interface CompileFailure {
  * import { Compiler, createBlueprint } from '@orkestrel/scaffold'
  *
  * const compiler = new Compiler()
- * const scaffolding = compiler.compile(createBlueprint('router', { src: ['core'] }))
+ * const result = compiler.compile(createBlueprint('router', { src: ['core'] }))
  *
- * scaffolding.plan?.artifacts // every planned file, in group order
- * scaffolding.stages // one CompileRecord per stage that ran
+ * result.plan?.artifacts // every planned file, in group order
+ * result.stages // one CompileRecord per stage that ran
  * compiler.destroy()
  * ```
  */
@@ -1274,7 +1335,7 @@ export declare class Compiler implements CompilerInterface {
       *
       * @param blueprint - The workspace specification to compile.
       * @param groups - The artifact groups to cover; every group when absent.
-      * @returns The scaffolding, carrying a plan only when the gate passed.
+      * @returns The compile result, carrying a plan only when the gate passed.
       * @throws {@link ScaffoldError} coded `INVALID` when an argument is not the
           * exact shape, and `DESTROYED` when the compiler has been torn down.
           *
@@ -1300,7 +1361,7 @@ export declare class Compiler implements CompilerInterface {
           * new Compiler().compile(blueprint, ['manifest']).plan?.artifacts.length // 1
           * ```
           */
-      compile(blueprint: Blueprint, groups?: readonly Group[]): Scaffolding;
+      compile(blueprint: Blueprint, groups?: readonly Group[]): CompileResult;
       /**
        * Compiles a blueprint and compares its plan to a target's current content.
        *
@@ -1362,9 +1423,26 @@ export declare class Compiler implements CompilerInterface {
           readonly failure?: CompileFailure;
       }
 
+      /**
+       * Represents the replayable outcome of one compile.
+       *
+       * @remarks
+       * `plan` is present exactly when the compile completed, so it is also the
+       * completeness test, and `result.plan.blueprint` carries the blueprint it
+       * was compiled from. A gated compile returns the questions that closed the gate
+       * and the stage records up to it, and no plan; the caller still holds the
+       * blueprint it passed in, so repeating it at this level would be one fact stored
+       * twice and free to disagree with itself.
+       */
+      export declare interface CompileResult {
+          readonly plan?: Plan;
+          readonly questions: readonly Question[];
+          readonly stages: readonly CompileRecord[];
+      }
+
       /** Represents the compiler's observation channel. */
       export declare type CompilerEventMap = {
-          readonly compile: readonly [scaffolding: Scaffolding];
+          readonly compile: readonly [result: CompileResult];
           readonly audit: readonly [audit: Audit];
           readonly block: readonly [questions: readonly Question[]];
           readonly error: readonly [error: unknown];
@@ -1379,9 +1457,9 @@ export declare class Compiler implements CompilerInterface {
            *
            * @param blueprint - The workspace specification to compile.
            * @param groups - The artifact groups to cover; every group when absent.
-           * @returns The scaffolding, carrying a plan only when the gate passed.
+           * @returns The compile result, carrying a plan only when the gate passed.
            */
-          compile(blueprint: Blueprint, groups?: readonly Group[]): Scaffolding;
+          compile(blueprint: Blueprint, groups?: readonly Group[]): CompileResult;
           /**
            * Compiles a blueprint and compares its plan to a target's current content.
            *
@@ -1513,9 +1591,9 @@ export declare class Compiler implements CompilerInterface {
                   core: "export function appCore(override?: UserConfig): UserConfig {\n\tconst project: UserConfig = {\n\t\tresolve,\n\t\tpublicDir: false,\n\t\tplugins: [environmentBoundary('app/core')],\n\t\ttest: {\n\t\t\tname: { label: 'app:core', color: 'cyan' },\n\t\t\tinclude: ['tests/app/core/**/*.test.ts'],\n\t\t\tsetupFiles: ['./tests/setup.ts'],\n\t\t\tenvironment: 'node',\n\t\t\tbrowser: { enabled: false },\n\t\t},\n\t}\n\treturn mergeOverride(project, override)\n}\n";
                   browser: "export function appBrowser(override?: UserConfig): UserConfig {\n\tconst output = 'dist/app/browser'\n\tconst project: UserConfig = {\n\t\tresolve,\n\t\toptimizeDeps,\n\t\tplugins: [outputBoundary(output), environmentBoundary('app/browser')],\n\t\troot: resolveWorkspacePath('app/browser'),\n\t\tpublicDir: false,\n\t\tbuild: {\n\t\t\tassetsInlineLimit: 0,\n\t\t\temptyOutDir: true,\n\t\t\toutDir: resolveWorkspacePath(output),\n\t\t\trolldownOptions: {\n\t\t\t\tonLog: enforceBuildLog,\n\t\t\t\tinput: resolveWorkspacePath('app/browser/index.html'),\n\t\t\t},\n\t\t},\n\t\ttest: {\n\t\t\tname: { label: 'app:browser', color: 'blue' },\n\t\t\troot: resolveWorkspacePath('.'),\n\t\t\tdir: resolveWorkspacePath('.'),\n\t\t\tinclude: ['tests/app/browser/**/*.test.ts'],\n{{journeyExclude}}\t\t\tsetupFiles: ['./tests/setup.ts', './tests/setupBrowser.ts'],\n\t\t\tbrowser: {\n\t\t\t\tenabled: true,\n\t\t\t\tprovider: playwright(browserOptions),\n\t\t\t\tcommands,\n\t\t\t\tinstances: [{ browser: 'chromium', headless: true }],\n\t\t\t},\n\t\t\tfileParallelism: false,\n\t\t\tsequence: { groupOrder: 1 },\n\t\t},\n\t}\n\treturn mergeOverride(project, override)\n}\n{{showcaseFactory}}{{journeyFactory}}";
                   vue: "export function appVue(override?: UserConfig): UserConfig {\n\tconst output = 'dist/app/vue'\n\tconst browser = appBrowser()\n\tconst project: UserConfig = {\n\t\t...browser,\n\t\toptimizeDeps: { include: [...optimizeDeps.include, 'vue'] },\n\t\tplugins: [outputBoundary(output), environmentBoundary('app/vue'), vue()],\n\t\troot: resolveWorkspacePath('app/vue'),\n\t\tbuild: {\n\t\t\t...browser.build,\n\t\t\toutDir: resolveWorkspacePath(output),\n\t\t\trolldownOptions: {\n\t\t\t\t...browser.build?.rolldownOptions,\n\t\t\t\tinput: resolveWorkspacePath('app/vue/index.html'),\n\t\t\t},\n\t\t},\n\t\ttest: {\n\t\t\t...browser.test,\n\t\t\tname: { label: 'app:vue', color: 'magenta' },\n\t\t\tbrowser: {\n\t\t\t\t...browser.test?.browser,\n\t\t\t\tinstances: (browser.test?.browser?.instances ?? []).map(\n\t\t\t\t\t({ name: _name, ...instance }) => instance,\n\t\t\t\t),\n\t\t\t},\n\t\t\tinclude: ['tests/app/vue/**/*.test.ts'],\n{{journeyExclude}}\t\t},\n\t}\n\treturn mergeOverride(project, override)\n}\n";
-                  journey: "\n// Replace the journey fields directly: merging would concatenate the ordinary include\n// and retain the exclusion of the journey suite.\nexport function appJourney(\n\tvariant: JourneyVariant,\n\tvariants: readonly JourneyVariant[],\n\tmode?: string,\n): UserConfig {\n\tconst application = resolveApplication(mode, applications)\n\tconst browser = applications[application]()\n\tconst project: UserConfig = {\n\t\t...browser,\n\t\ttest: {\n\t\t\t...browser.test,\n\t\t\tname: { label: `journey:${variant.name}`, color: 'green' },\n\t\t\tinclude: [`tests/app/${application}/integration.test.ts`],\n\t\t\texclude: [],\n\t\t\tprovide: { variant: variant.name, variants, capture },\n\t\t\tbrowser: {\n\t\t\t\t...browser.test?.browser,\n\t\t\t\tenabled: true,\n\t\t\t\tviewport: { width: variant.width, height: variant.height },\n\t\t\t\tinstances: (browser.test?.browser?.instances ?? []).map(\n\t\t\t\t\t({ name: _name, ...instance }) => instance,\n\t\t\t\t),\n\t\t\t},\n\t\t},\n\t}\n\treturn mergeOverride(project)\n}\n";
+                  journey: "\n// Replace the journey fields directly: merging would concatenate the ordinary include\n// and retain the exclusion of the journey suite.\nexport function appJourney(\n\tvariant: JourneyVariant,\n\tvariants: readonly JourneyVariant[],\n\tmode?: string,\n\toverride?: UserConfig,\n): UserConfig {\n\tconst application = resolveApplication(mode, applications)\n\tconst browser = applications[application]()\n\tconst project: UserConfig = {\n\t\t...browser,\n\t\ttest: {\n\t\t\t...browser.test,\n\t\t\tname: { label: `journey:${variant.name}`, color: 'green' },\n\t\t\tinclude: [`tests/app/${application}/integration.test.ts`],\n\t\t\texclude: [],\n\t\t\tprovide: { variant: variant.name, variants, capture },\n\t\t\tbrowser: {\n\t\t\t\t...browser.test?.browser,\n\t\t\t\tenabled: true,\n\t\t\t\tviewport: { width: variant.width, height: variant.height },\n\t\t\t\tinstances: (browser.test?.browser?.instances ?? []).map(\n\t\t\t\t\t({ name: _name, ...instance }) => instance,\n\t\t\t\t),\n\t\t\t},\n\t\t},\n\t}\n\treturn mergeOverride(project, override)\n}\n";
                   showcase: "\nconst showcaseStamp: PluginOption = {\n\tname: 'orkestrel-showcase-html',\n\tenforce: 'post',\n\tgenerateBundle(_, bundle) {\n\t\tfor (const file of Object.values(bundle)) {\n\t\t\tif (\n\t\t\t\tfile.type === 'asset' &&\n\t\t\t\ttypeof file.source === 'string' &&\n\t\t\t\tfile.fileName.endsWith('.html')\n\t\t\t) {\n\t\t\t\tfile.source = stampPage(file.source)\n\t\t\t}\n\t\t}\n\t},\n}\n\nfunction createShowcaseNaming(application: string): PluginOption {\n\treturn {\n\t\tname: 'orkestrel-showcase-name',\n\t\tenforce: 'post',\n\t\twriteBundle(options) {\n\t\t\tif (options.dir === undefined) throw new Error('The showcase output is absent.')\n\t\t\trenameSync(\n\t\t\t\tresolvePath(options.dir, 'index.html'),\n\t\t\t\tresolvePath(options.dir, application + '.html'),\n\t\t\t)\n\t\t},\n\t}\n}\n\nexport function appShowcase(mode: string, override?: UserConfig): UserConfig {\n\tconst application = resolveApplication(mode, applications)\n\tconst output = 'showcase'\n\tconst showcase: UserConfig = {\n\t\tplugins: [\n\t\t\toutputBoundary(output),\n\t\t\tviteSingleFile({\n\t\t\t\tremoveViteModuleLoader: true,\n\t\t\t\tuseRecommendedBuildConfig: true,\n\t\t\t}),\n\t\t\tshowcaseStamp,\n\t\t\tcreateShowcaseNaming(application),\n\t\t],\n\t\tbuild: {\n\t\t\t// The `appBrowser` factory sets `assetsInlineLimit` to 0, so every asset becomes\n\t\t\t// its own file, and 4096 is Vite's own default put back. The `viteSingleFile`\n\t\t\t// plugin overwrites the value while the `useRecommendedBuildConfig` option stays\n\t\t\t// true, so this line takes effect only in a workspace that turns that option off.\n\t\t\tassetsInlineLimit: 4096,\n\t\t\tcssMinify: 'lightningcss',\n\t\t\temptyOutDir: false,\n\t\t\tminify: 'oxc',\n\t\t\tmodulePreload: false,\n\t\t\toutDir: resolveWorkspacePath(output),\n\t\t\treportCompressedSize: false,\n\t\t\tsourcemap: false,\n\t\t\ttarget: 'esnext',\n\t\t},\n\t}\n\treturn applications[application](mergeOverride(showcase, override))\n}\n";
-                  server: "function resolveAppFilename(): string {\n\treturn 'main.cjs'\n}\n\nfunction resolveAppExternal(id: string): boolean {\n\treturn id.startsWith('node:')\n}\n\nexport function appServer(override?: UserConfig): UserConfig {\n\tconst project: UserConfig = {\n\t\tresolve,\n\t\tpublicDir: false,\n\t\tplugins: [outputBoundary('dist/app/server'), environmentBoundary('app/server')],\n\t\tbuild: {\n\t\t\temptyOutDir: true,\n\t\t\tlib: {\n\t\t\t\tentry: resolveWorkspacePath('app/server/main.ts'),\n\t\t\t\tformats: ['cjs'],\n\t\t\t\tfileName: resolveAppFilename,\n\t\t\t},\n\t\t\toutDir: resolveWorkspacePath('dist/app/server'),\n\t\t\ttarget: 'node22',\n\t\t\trolldownOptions: {\n\t\t\t\tonLog: enforceBuildLog,\n\t\t\t\texternal: resolveAppExternal,\n\t\t\t},\n\t\t},\n\t\ttest: {\n\t\t\tname: { label: 'app:server', color: 'green' },\n\t\t\tinclude: ['tests/app/server/**/*.test.ts'],\n\t\t\tsetupFiles: ['./tests/setup.ts', './tests/setupServer.ts'],\n\t\t\tenvironment: 'node',\n\t\t\tbrowser: { enabled: false },\n\t\t},\n\t}\n\treturn mergeOverride(project, override)\n}\n";
+                  server: "function resolveAppFilename(): string {\n\treturn 'main.cjs'\n}\n\nfunction resolveAppExternal(id: string): boolean {\n\treturn id.startsWith('node:')\n}\n\nexport function appServer(override?: UserConfig): UserConfig {\n\tconst project: UserConfig = {\n\t\tresolve,\n\t\tpublicDir: false,\n\t\tplugins: [outputBoundary('dist/app/server'), environmentBoundary('app/server')],\n\t\tbuild: {\n\t\t\temptyOutDir: true,\n\t\t\tlib: {\n\t\t\t\tentry: resolveWorkspacePath('app/server/main.ts'),\n\t\t\t\tformats: ['cjs'],\n\t\t\t\tfileName: resolveAppFilename,\n\t\t\t},\n\t\t\toutDir: resolveWorkspacePath('dist/app/server'),\n\t\t\ttarget: 'node22',\n\t\t\trolldownOptions: {\n\t\t\t\tonLog: enforceBuildLog,\n\t\t\t\texternal: resolveAppExternal,\n\t\t\t},\n\t\t},\n\t\ttest: {\n\t\t\tname: { label: 'app:server', color: 'green' },\n\t\t\tinclude: ['tests/app/server/**/*.test.ts'],\n\t\t\tsetupFiles: ['./tests/setup.ts', './tests/setupServer.ts'],\n\t\t\tenvironment: 'node',\n\t\t\tbrowser: { enabled: false },\n\t\t},\n\t}\n\t// Fills the missing codeSplitting of each merged output with false and adds no output,\n\t// so an override's output list keeps its own members and their order. A member that\n\t// already supplies a value is returned as written, found by property lookup, so a value\n\t// an inherited getter supplies survives.\n\tconst merged = mergeOverride(project, override)\n\tconst rolldown = merged.build?.rolldownOptions\n\tconst output = rolldown?.output\n\tconst unsplit = { codeSplitting: false }\n\treturn {\n\t\t...merged,\n\t\tbuild: {\n\t\t\t...merged.build,\n\t\t\trolldownOptions: {\n\t\t\t\t...rolldown,\n\t\t\t\toutput: Array.isArray(output)\n\t\t\t\t\t? output.map((member) =>\n\t\t\t\t\t\t\tmember.codeSplitting === undefined ? { ...member, ...unsplit } : member,\n\t\t\t\t\t\t)\n\t\t\t\t\t: output?.codeSplitting === undefined\n\t\t\t\t\t\t? { ...output, ...unsplit }\n\t\t\t\t\t\t: output,\n\t\t\t},\n\t\t},\n\t}\n}\n";
               }>;
               policy: "export function policy(override?: UserConfig): UserConfig {\n\tconst project: UserConfig = {\n\t\tresolve,\n\t\ttest: {\n\t\t\tname: { label: 'policy', color: 'white' },\n\t\t\tinclude: ['tests/policy.test.ts'],\n\t\t\tsetupFiles: ['./tests/setup.ts'],\n\t\t\tenvironment: 'node',\n\t\t\tbrowser: { enabled: false },\n\t\t},\n\t}\n\treturn mergeOverride(project, override)\n}\n";
               config: "export function config(override?: UserConfig): UserConfig {\n\tconst project: UserConfig = {\n\t\tresolve,\n\t\ttest: {\n\t\t\tname: { label: 'config', color: 'yellow' },\n\t\t\tinclude: ['tests/config.test.ts'],\n\t\t\tsetupFiles: ['./tests/setup.ts'],\n\t\t\tenvironment: 'node',\n\t\t\tbrowser: { enabled: false },\n\t\t\t// A config test validates every target wrapper, spawns the real linter twice under\n\t\t\t// 15-second child caps, and rolls one face up through the compiler and the extractor it\n\t\t\t// spawns, so this budget clears the capped pair with room for a contended host.\n\t\t\ttestTimeout: 60_000,\n\t\t},\n\t}\n\treturn mergeOverride(project, override)\n}\n";
@@ -1526,9 +1604,9 @@ export declare class Compiler implements CompilerInterface {
               tree: "// The laws this package states about its own real tree.\n// Standalone Node proof; reads the tree without a build, install, or service.\nexport function tree(override?: UserConfig): UserConfig {\n\tconst project: UserConfig = {\n\t\tresolve,\n\t\ttest: {\n\t\t\tname: { label: 'tree', color: 'magenta' },\n\t\t\tinclude: ['tests/tree.test.ts'],\n\t\t\tsetupFiles: ['./tests/setup.ts', './tests/setupServer.ts'],\n\t\t\tpool: 'threads',\n\t\t\tisolate: false,\n\t\t\tenvironment: 'node',\n\t\t\tbrowser: { enabled: false },\n\t\t},\n\t}\n\treturn mergeOverride(project, override)\n}\n";
               conformance: "// Where this package drifts from the official tooling it stays compatible with.\n// The subject is this package, so the proof is hermetic and stays in `npm test`.\nexport function conformance(override?: UserConfig): UserConfig {\n\tconst project: UserConfig = {\n\t\tresolve,\n\t\ttest: {\n\t\t\tname: { label: 'conformance', color: 'magenta' },\n\t\t\tinclude: ['tests/conformance.test.ts'],\n\t\t\tsetupFiles: ['./tests/setup.ts', './tests/setupServer.ts'],\n\t\t\tpool: 'threads',\n\t\t\tisolate: false,\n\t\t\tenvironment: 'node',\n\t\t\tbrowser: { enabled: false },\n\t\t},\n\t}\n\treturn mergeOverride(project, override)\n}\n";
               service: "// The caller prepares the live external services before this project.\n// `tests/setupService.ts` verifies readiness, and the project stays out of `npm test`\n// because a real service answers it.\nexport function service(override?: UserConfig): UserConfig {\n\tconst project: UserConfig = {\n\t\tresolve,\n\t\ttest: {\n\t\t\tname: { label: 'service', color: 'red' },\n\t\t\tinclude: ['tests/service/**/*.test.ts'],\n\t\t\tsetupFiles: ['./tests/setup.ts', './tests/setupService.ts'],\n\t\t\tenvironment: 'node',\n\t\t\tbrowser: { enabled: false },\n\t\t\ttestTimeout: 120_000,\n\t\t\thookTimeout: 120_000,\n\t\t\tfileParallelism: false,\n\t\t\tsequence: { groupOrder: 1 },\n\t\t},\n\t}\n\treturn mergeOverride(project, override)\n}\n";
-              studies: "// Authored study proofs run installed packages through bounded subprocesses and protocol fixtures,\n// so this project is isolated in its own gate script, test:studies.\nexport function studies(override?: UserConfig): UserConfig {\n\tconst project: UserConfig = {\n\t\tresolve,\n\t\ttest: {\n\t\t\tname: { label: 'studies', color: 'red' },\n\t\t\tinclude: ['tests/studies/**/*.test.ts'],\n\t\t\tsetupFiles: ['./tests/setup.ts'],\n\t\t\tenvironment: 'node',\n\t\t\tbrowser: { enabled: false },\n\t\t\ttestTimeout: 120_000,\n\t\t\thookTimeout: 120_000,\n\t\t\tfileParallelism: false,\n\t\t\tsequence: { groupOrder: 1 },\n\t\t},\n\t}\n\treturn mergeOverride(project, override)\n}\n";
+              studies: "// The @orkestrel/study engine drives these proofs, running installed packages through bounded\n// subprocesses and protocol fixtures, so this project is isolated in its own gate script,\n// test:studies.\nexport function studies(override?: UserConfig): UserConfig {\n\tconst project: UserConfig = {\n\t\tresolve,\n\t\ttest: {\n\t\t\tname: { label: 'studies', color: 'red' },\n\t\t\tinclude: ['tests/studies/**/*.test.ts'],\n\t\t\tsetupFiles: ['./tests/setup.ts'],\n\t\t\tenvironment: 'node',\n\t\t\tbrowser: { enabled: false },\n\t\t\ttestTimeout: 120_000,\n\t\t\thookTimeout: 120_000,\n\t\t\tfileParallelism: false,\n\t\t\tsequence: { groupOrder: 1 },\n\t\t},\n\t}\n\treturn mergeOverride(project, override)\n}\n";
               distribution: "export function distribution(override?: UserConfig): UserConfig {\n\tconst project: UserConfig = {\n\t\tresolve,\n\t\ttest: {\n\t\t\tname: { label: 'distribution', color: 'cyan' },\n\t\t\tinclude: ['tests/distribution.test.ts'],\n\t\t\tsetupFiles: ['./tests/setup.ts'],\n\t\t\tenvironment: 'node',\n\t\t\ttestTimeout: 120_000,\n\t\t\thookTimeout: 120_000,\n\t\t\tfileParallelism: false,\n\t\t\tsequence: { groupOrder: 1 },\n\t\t},\n\t}\n\treturn mergeOverride(project, override)\n}\n";
-              probe: "// A workbench, not a proof. No gate selects this project. Run in test mode by the\n// `test:probe` script, it collects `tmp/probes/**/*.test.ts`. Run in benchmark mode by the\n// `test:bench` script, the same workbench also collects `tests/**/*.test.ts` for a `bench` block,\n// so a suite may carry a bench beside its ordinary tests without a second project. The mode\n// guard around each `bench` call keeps it out of test mode, so it never executes there.\nexport function probe(override?: UserConfig): UserConfig {\n\tconst project: UserConfig = {\n\t\tresolve,\n\t\ttest: {\n\t\t\tname: { label: 'probe', color: 'black' },\n\t\t\tinclude: ['tmp/probes/**/*.test.ts'],\n\t\t\tsetupFiles: ['./tests/setup.ts'],\n\t\t\tenvironment: 'node',\n\t\t\tbrowser: { enabled: false },\n\t\t\tfileParallelism: false,\n\t\t\tsequence: { groupOrder: 1 },\n\t\t\tpool: 'threads',\n\t\t\tbenchmark: { include: ['tmp/probes/**/*.test.ts', 'tests/**/*.test.ts'] },\n\t\t},\n\t}\n\treturn mergeOverride(project, override)\n}\n";
+              probe: "// A workbench, not a proof. No gate selects this project. Run in test mode by the\n// `test:probe` script, it collects `tmp/probes/**/*.test.ts`. Run in benchmark mode by the\n// `test:bench` script, it collects `*.bench.ts` files under `tmp/probes` and `tests`.\n// Each benchmark is a regular test that uses its context's `bench` fixture and awaits\n// `bench(name, options, fn).run()` or `bench.compare(...)`.\nexport function probe(override?: UserConfig): UserConfig {\n\tconst project: UserConfig = {\n\t\tresolve,\n\t\ttest: {\n\t\t\tname: { label: 'probe', color: 'black' },\n\t\t\tinclude: ['tmp/probes/**/*.test.ts'],\n\t\t\tsetupFiles: ['./tests/setup.ts'],\n\t\t\tenvironment: 'node',\n\t\t\tbrowser: { enabled: false },\n\t\t\tfileParallelism: false,\n\t\t\tsequence: { groupOrder: 1 },\n\t\t\tpool: 'threads',\n\t\t\tbenchmark: { include: ['tmp/probes/**/*.bench.ts', 'tests/**/*.bench.ts'] },\n\t\t},\n\t}\n\treturn mergeOverride(project, override)\n}\n";
               integration: Readonly<{
                   sheet: "export function integration(override?: UserConfig): UserConfig {\n\tconst project: UserConfig = {\n\t\ttest: {\n\t\t\tinclude: ['tests/integration.test.ts'],\n{{global}}\t\t},\n\t}\n\treturn sheetProject('integration', mergeOverride(project, override))\n}\n";
                   module: "export function integration(override?: UserConfig): UserConfig {\n\tconst project: UserConfig = {\n\t\tresolve,\n\t\ttest: {\n\t\t\tname: { label: 'integration', color: 'blue' },\n\t\t\tinclude: ['tests/integration.test.ts'],\n\t\t\tsetupFiles: ['./tests/setup.ts'],\n{{global}}\t\t\tenvironment: 'node',\n\t\t},\n\t}\n\treturn mergeOverride(project, override)\n}\n";
@@ -3763,23 +3841,6 @@ export declare class Compiler implements CompilerInterface {
        /** Names the coded reasons a scaffold error is raised. */
        export declare type ScaffoldErrorCode = 'INVALID' | 'BLOCKED' | 'DESTROYED' | 'TARGET' | 'WRITE' | 'FETCH';
 
-       /**
-        * Represents the replayable outcome of one compile.
-        *
-        * @remarks
-        * `plan` is present exactly when the compile completed, so it is also the
-        * completeness test, and `scaffolding.plan.blueprint` carries the blueprint it
-        * was compiled from. A gated compile returns the questions that closed the gate
-        * and the stage records up to it, and no plan; the caller still holds the
-        * blueprint it passed in, so repeating it at this level would be one fact stored
-        * twice and free to disagree with itself.
-        */
-       export declare interface Scaffolding {
-           readonly plan?: Plan;
-           readonly questions: readonly Question[];
-           readonly stages: readonly CompileRecord[];
-       }
-
        /**
         * Scans manifest text for its strings and object braces, in order.
         *
@@ -4077,6 +4138,29 @@ export declare class Compiler implements CompilerInterface {
        /** Names the themes build entry marker. */
        export declare const THEMES_ENTRY_PATH = "src/styles/themes/sheet.ts";
 
+       /**
+        * Holds foreign tool ranges required by selected browser frameworks, frozen.
+        *
+        * @remarks
+        * A selected framework overrides the baseline floor with its held range. `audit` names the hold
+        * where it would report a newer served major and reports a declaration past that hold. The
+        * constants proof ties the held range to the baseline manifest and the framework's planned range.
+        */
+       export declare const TOOLCHAIN_HOLDS: Readonly<Record<string, ToolchainHold>>;
+
+       /**
+        * Represents one foreign tool range required by a browser framework.
+        *
+        * @remarks
+        * `framework` selects the workspaces the hold applies to. `range` supplies their development
+        * floor, and `reason` names why that framework cannot use the baseline toolchain.
+        */
+       export declare interface ToolchainHold {
+           readonly framework: Framework;
+           readonly range: string;
+           readonly reason: string;
+       }
+
        /** Names the real-tree proof whose presence makes a workspace `tree`. */
        export declare const TREE_TEST_PATH = "tests/tree.test.ts";