ttsc 0.30.4 → 0.31.0

package/lib/launcher/internal/runtime/RuntimeLoaderCapabilities.js

@@ -0,0 +1,256 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RuntimeLoaderCapabilities = void 0;
+const node_module_1 = require("node:module");
+const node_path_1 = __importDefault(require("node:path"));
+const node_url_1 = require("node:url");
+const node_worker_threads_1 = require("node:worker_threads");
+const E2ETrace_1 = require("../../../internal/E2ETrace");
+/**
+ * What this runtime's module loader does on its own, read by asking it rather
+ * than by its version.
+ *
+ * The ttsx runtime serves TypeScript through `module.registerHooks`, the
+ * supported customization API. How far that API reaches, and how the loader
+ * shapes a CommonJS module imported from ESM, differ between Node releases in
+ * both directions, so this helper instance memoizes actual public-API probes.
+ * Main-thread temporary hooks deregister afterwards; the separate worker owns
+ * its hooks until termination. The runtime installer invokes these before its
+ * own hooks exist, so nothing they load is recorded as an input of the
+ * program.
+ *
+ * @evidence contracts/common.md#principled-implementation Public loader probes observe the actual require.resolve, namespace and hooked-import behavior instead of deriving it from a release number; each boolean selects the runtime path matching that observed capability.
+ * @evidence contracts/common.md#clear-and-simple-design One namespace owns three independent lazy capability answers and their private probes, keeping loader adaptation choices with the hook consumer.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Temporary registerHooks/deregister boundaries are supported customization, not private-loader mutation; the worker tests a real ESM-to-CommonJS path rather than a fixture version table.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain why loader differences require observation and describe each affected behavior; worker comments distinguish synchronous require from the probed import path.
+ * @evidence contracts/portability.md#os-neutral-implementation Native filenames become URLs through pathToFileURL and workers use Node APIs; no shell quoting, separator substitution or OS-name case rule implements the probes.
+ * @evidence contracts/performance.md#efficient-algorithms Three memoized probe paths delegate native resolution/module loading or Worker initialization; input path text, loader work and startup latency are not bounded by the fixed probe count. Atomics waits at most ten seconds after worker construction; that wait is not a bound on constructor or teardown latency.
+ * @evidence contracts/performance.md#reuse-equivalent-work Completed booleans serve this helper instance under the installer's stable native-loader premise; arbitrary later external hook changes are not re-probed. Propagated exceptions leave initialization unset; worker construction/failure/no-answer paths can instead memoize conservative false.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Three booleans remain with this helper instance. Main-thread temporary hooks deregister in finally; the probe namespace/cache belongs to Node. Worker termination is requested asynchronously after the answer wait, so completed teardown and release of its hooks/streams are not certified by return.
+ */
+var RuntimeLoaderCapabilities;
+(function (RuntimeLoaderCapabilities) {
+    /**
+     * Whether `require.resolve` consults resolve hooks registered with
+     * `module.registerHooks`.
+     *
+     * A runtime whose `require.resolve` does consult them resolves a TypeScript
+     * source through ttsx's own resolve hook; one that does not answers from
+     * Node's resolver alone, which knows no TypeScript source.
+     *
+     * @evidence contracts/common.md#principled-implementation A sentinel request through require.resolve observes whether the public resolve hook was actually consulted, giving the consumer grounds for its corresponding resolution lane.
+     * @evidence contracts/common.md#clear-and-simple-design The public accessor exposes one cached capability while a private probe owns registration and cleanup.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts No private Node resolver is patched and no version-specific expected answer replaces the actual supported-hook observation.
+     * @evidence contracts/common.md#meaningful-documentation Native paragraphs distinguish hook-aware and native-only resolution and explain why the distinction affects TypeScript sources.
+     * @evidence contracts/portability.md#os-neutral-implementation The probe uses a native filename converted with pathToFileURL; Node supplies synchronous module resolution on each supported host.
+     * @evidence contracts/performance.md#efficient-algorithms One sentinel request through temporary public hooks initializes the boolean; path text and delegated native resolution are initialization costs. Later calls read the helper-instance memo without another registration.
+     * @evidence contracts/performance.md#reuse-equivalent-work requireResolve stores the running loader's stable capability for subsequent consumers; a thrown probe does not store an invented answer.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources The temporary hook deregisters in finally; this helper instance retains the boolean. Node and the surrounding installed runtime own any delegated module/cache state.
+     */
+    function requireResolveConsultsHooks() {
+        requireResolve ??= probeRequireResolve();
+        return requireResolve;
+    }
+    RuntimeLoaderCapabilities.requireResolveConsultsHooks = requireResolveConsultsHooks;
+    /**
+     * Whether the namespace of a CommonJS module imported from ESM carries a
+     * `module.exports` export beside `default` and the statically detected
+     * names.
+     *
+     * @evidence contracts/common.md#principled-implementation Importing the side-effect-free CommonJS probe through public hooks observes whether the actual ESM namespace contains module.exports, so facade shape follows the running loader.
+     * @evidence contracts/common.md#clear-and-simple-design The accessor exposes only the namespace capability, with source construction and temporary hooks isolated in its private probe.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts A real namespace is inspected rather than fabricating the export from a Node version or modifying CommonJS globals.
+     * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes module.exports from default and static names, which is the fact facade callers need.
+     * @evidence contracts/portability.md#os-neutral-implementation path.join and pathToFileURL preserve native probe filenames and URL spelling; no hand-built file URL assumes drive or separator syntax.
+     * @evidence contracts/performance.md#efficient-algorithms One hooked importer delegates native CommonJS/ESM loading and namespace-key enumeration, including native path text and loader work; later calls read this helper-instance memo.
+     * @evidence contracts/performance.md#reuse-equivalent-work The namespace convention is stable for the running loader, so the cached boolean is shared by all facades; failed probing propagates rather than guessing the convention.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources The temporary hook deregisters in finally. The helper retains its boolean; Node owns the probe CommonJS/ESM cache entries, which are not explicitly evicted here.
+     */
+    function commonJsNamespaceCarriesModuleExports() {
+        moduleExportsKey ??= probeModuleExportsKey();
+        return moduleExportsKey;
+    }
+    RuntimeLoaderCapabilities.commonJsNamespaceCarriesModuleExports = commonJsNamespaceCarriesModuleExports;
+    /**
+     * Whether a CommonJS module the ESM loader evaluates from source a load hook
+     * returned exposes `require.cache` and `require.extensions` as objects.
+     *
+     * A runtime that does not (Node 22) evaluates it with a narrower `require`:
+     * no `cache`, `extensions`, or `resolve.paths`, whose calls go through the
+     * ESM loader and cannot load a module Node's CommonJS loader would load.
+     * Whenever any load hook is registered, every CommonJS module an `import`
+     * reaches takes that path there, the ones the hook passes to `nextLoad`
+     * included.
+     *
+     * @evidence contracts/common.md#principled-implementation A worker runs an actual ESM import whose hooked CommonJS body observes cache/extensions object properties; only that positive result permits the caller's unadapted lane. This does not independently test every require method or arbitrary CommonJS dependency.
+     * @evidence contracts/common.md#clear-and-simple-design The synchronous accessor hides worker coordination and returns one cached loader capability rather than exposing timing or worker state to hook consumers.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The probe registers supported hooks in its own worker and preserves public createRequire adaptation on uncertain results instead of replacing Node internals.
+     * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain narrowed require and why passthrough CommonJS imports are affected; private prose identifies the required asynchronous import path.
+     * @evidence contracts/portability.md#os-neutral-implementation Node workers and pathToFileURL handle the native execution boundary without process shell commands or platform-specific loader guesses.
+     * @evidence contracts/performance.md#efficient-algorithms Worker construction delegates native thread/startup work; one four-byte shared answer and a bounded Atomics wait coordinate this attempt. Repeated accessor calls read the helper-instance memo, including cached conservative negatives, without another worker.
+     * @evidence contracts/performance.md#reuse-equivalent-work The running Node loader's require behavior is shared across imports; a conservative negative result after failure consistently selects the facade that supplies ordinary require.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources One worker belongs to initialization and receives terminate in finally; one boolean remains afterwards. The synchronous accessor does not await termination, so completion of teardown is not independently bounded here. Opt-in observations distinguish its actual creation, termination request returning a Promise, and exit event under one probe id. No await, rejection handler or error listener changes the existing termination/unhandled-error behavior. Exit reports this worker lifecycle only and cannot establish an OS executable-lock owner.
+     */
+    function hookedCommonJsImportKeepsRequire() {
+        hookedCommonJsRequire ??= probeHookedCommonJsRequire();
+        return hookedCommonJsRequire;
+    }
+    RuntimeLoaderCapabilities.hookedCommonJsImportKeepsRequire = hookedCommonJsImportKeepsRequire;
+    let requireResolve;
+    let moduleExportsKey;
+    let hookedCommonJsRequire;
+    let probeTraceOrdinal = 0;
+    /**
+     * Ask the runtime by running the path that narrows `require`: an `import()`,
+     * whose CommonJS dependency the ESM loader evaluates from a hook's source. A
+     * synchronous `require()` path is not the asynchronous import path whose
+     * behavior this probe asks about. The import runs in a worker thread with
+     * hooks of its own that answer only the probe's two virtual modules, while
+     * this thread waits for its answer.
+     */
+    function probeHookedCommonJsRequire() {
+        const answer = new Int32Array(new SharedArrayBuffer(4));
+        let worker;
+        try {
+            worker = new node_worker_threads_1.Worker(HOOKED_COMMONJS_REQUIRE_PROBE, {
+                eval: true,
+                stderr: true,
+                stdout: true,
+                workerData: answer,
+            });
+        }
+        catch {
+            return false;
+        }
+        const workerThreadId = worker.threadId;
+        const probeId = process.env.TTSC_E2E_TRACE
+            ? String(++probeTraceOrdinal)
+            : undefined;
+        if (probeId !== undefined) {
+            try {
+                const fields = { probeId, pid: process.pid, threadId: node_worker_threads_1.threadId, workerThreadId };
+                E2ETrace_1.E2ETrace.capabilityResolution("runtime-loader-worker-created", fields);
+                worker.once("exit", (exitCode) => E2ETrace_1.E2ETrace.capabilityResolution("runtime-loader-worker-exited", {
+                    ...fields,
+                    exitCode,
+                }));
+            }
+            catch {
+                // Observer registration must not change the probe or worker errors.
+            }
+        }
+        try {
+            Atomics.wait(answer, 0, 0, HOOKED_COMMONJS_REQUIRE_PROBE_TIMEOUT_MS);
+        }
+        finally {
+            void worker.terminate();
+            if (probeId !== undefined)
+                E2ETrace_1.E2ETrace.capabilityResolution("runtime-loader-worker-terminate-requested", {
+                    probeId,
+                    pid: process.pid,
+                    threadId: node_worker_threads_1.threadId,
+                    workerThreadId,
+                });
+        }
+        // Anything but a "kept" answer counts as narrowed: the facade the runtime
+        // then uses supplies the supported public createRequire adaptation,
+        // while worker startup and requested termination remain separate costs.
+        return answer[0] === 1;
+    }
+    function probeRequireResolve() {
+        const sentinel = `./.ttsc-require-resolve-probe-${process.pid}`;
+        let consulted = false;
+        const probe = (0, node_module_1.registerHooks)({
+            resolve(specifier, context, nextResolve) {
+                if (specifier !== sentinel)
+                    return nextResolve(specifier, context);
+                consulted = true;
+                return { shortCircuit: true, url: (0, node_url_1.pathToFileURL)(__filename).href };
+            },
+        });
+        try {
+            require.resolve(sentinel);
+        }
+        catch {
+            // A runtime that never consulted the hook refuses the sentinel.
+        }
+        finally {
+            probe.deregister();
+        }
+        return consulted;
+    }
+    function probeModuleExportsKey() {
+        const module = node_path_1.default.join(__dirname, "interopProbe.js");
+        const importer = node_path_1.default.join(__dirname, `.ttsc-interop-probe-${process.pid}.mjs`);
+        const importerUrl = (0, node_url_1.pathToFileURL)(importer).href;
+        const probe = (0, node_module_1.registerHooks)({
+            resolve(specifier, context, nextResolve) {
+                return specifier === importer || specifier === importerUrl
+                    ? { shortCircuit: true, url: importerUrl }
+                    : nextResolve(specifier, context);
+            },
+            load(url, context, nextLoad) {
+                return url === importerUrl
+                    ? {
+                        format: "module",
+                        shortCircuit: true,
+                        source: `import * as namespace from ${JSON.stringify((0, node_url_1.pathToFileURL)(module).href)};\nexport default Object.keys(namespace);\n`,
+                    }
+                    : nextLoad(url, context);
+            },
+        });
+        // A probe that fails says nothing about the shape, so it is not guessed.
+        try {
+            const keys = require(importer).default;
+            return Array.isArray(keys) && keys.includes("module.exports");
+        }
+        finally {
+            probe.deregister();
+        }
+    }
+})(RuntimeLoaderCapabilities || (exports.RuntimeLoaderCapabilities = RuntimeLoaderCapabilities = {}));
+/**
+ * How long the probe waits for its worker. No startup latency is guaranteed;
+ * the answer wait is ten seconds after construction and does not bound worker
+ * creation or completed termination.
+ */
+const HOOKED_COMMONJS_REQUIRE_PROBE_TIMEOUT_MS = 10_000;
+/**
+ * The worker body of `probeHookedCommonJsRequire`: an ES module importing a
+ * CommonJS module that reports whether cache/extensions are objects, both
+ * served from source by the worker's own hooks. It stores 1 when kept, 2 when
+ * narrowed, and 3 when the import failed.
+ */
+const HOOKED_COMMONJS_REQUIRE_PROBE = `
+const { workerData } = require("node:worker_threads");
+const { registerHooks } = require("node:module");
+const path = require("node:path");
+const { pathToFileURL } = require("node:url");
+const base = path.join(__dirname, ".ttsc-hooked-require-probe-" + process.pid);
+const importer = pathToFileURL(base + ".mjs").href;
+const moduleUrl = pathToFileURL(base + ".cjs").href;
+registerHooks({
+  resolve(specifier, context, nextResolve) {
+    if (specifier === importer) return { shortCircuit: true, url: importer };
+    if (specifier === moduleUrl || specifier === base + ".cjs")
+      return { shortCircuit: true, url: moduleUrl };
+    return nextResolve(specifier, context);
+  },
+  load(url, context, nextLoad) {
+    if (url === importer)
+      return { format: "module", shortCircuit: true, source: "import kept from " + JSON.stringify(moduleUrl) + ";\\nexport default kept;\\n" };
+    if (url === moduleUrl)
+      return { format: "commonjs", shortCircuit: true, source: "module.exports = typeof require.cache === 'object' && typeof require.extensions === 'object';\\n" };
+    return nextLoad(url, context);
+  },
+});
+const answer = (value) => {
+  Atomics.store(workerData, 0, value);
+  Atomics.notify(workerData, 0);
+};
+import(importer).then((namespace) => answer(namespace.default === true ? 1 : 2), () => answer(3));
+`;
+//# sourceMappingURL=RuntimeLoaderCapabilities.js.map

package/lib/launcher/internal/runtime/RuntimeLoaderCapabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RuntimeLoaderCapabilities.js","sourceRoot":"","sources":["../../../../src/launcher/internal/runtime/RuntimeLoaderCapabilities.ts"],"names":[],"mappings":"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"}

package/lib/launcher/internal/runtime/RuntimeManifest.d.ts

@@ -0,0 +1,65 @@
+import type { OwningModuleOptions } from "./OwningModuleOptions";
+/**
+ * Checked build metadata inherited by a direct ttsx child or registered by a
+ * host that discovers roots after hook installation.
+ *
+ * The directories and actual compiler emit observations describe already-built
+ * output; the hooks use them to establish which preparation owns a source. This
+ * transport shape does not authenticate its producer or current artifact bytes;
+ * trusted preparation and immutable emit are registry/index premises.
+ *
+ * @evidence contracts/common.md#principled-implementation Native source/emit roots, actual output-to-source observations and owning format options bind serving to one checked preparation; optional entry/output-list/policy fields cannot replace the required compiler provenance.
+ * @evidence contracts/common.md#clear-and-simple-design One serializable build manifest groups serving identity and its run-owned caches, keeping loader callbacks and mutable lock state outside the transport.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Explicit entry/output ownership and plugin policy replace basename guesses or independently chosen transform behavior for later roots.
+ * @evidence contracts/common.md#meaningful-documentation The purpose and separated member comments explain trusted preparation scope, native coordinates, producer provenance, relative output separators, format defaults, caller-owned orphan storage lifetime and false-only plugin policy without member tags.
+ * @evidence contracts/portability.md#os-neutral-implementation Native root/entry/cache paths and producer-native provenance keys remain distinct from slash-separated relative outputs. Producer identity observations and consumer filesystem conversions own physical alias handling; the structural strings do not pin a namespace or certify that every root observation succeeded.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources A type declaration acquires and holds no runtime resource.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms A type declaration chooses no processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A type declaration computes nothing, so there is no work to share.
+ */
+export interface RuntimeManifest {
+    /** Project root of the entry's owning tsconfig. */
+    readonly projectRoot: string;
+    /** Source-tree root the emit mirrors (tsgo strips this prefix). */
+    readonly rootDir: string;
+    /** Directory holding the entry project's emitted JavaScript. */
+    readonly emitDir: string;
+    /**
+     * Selected TypeScript entry coordinate whose preparation created this
+     * manifest.
+     */
+    readonly entrySource?: string;
+    /** Exact JavaScript emitted for `entrySource`. */
+    readonly entryFile?: string;
+    /**
+     * The build's record of the JavaScript it emitted, relative to `emitDir` with
+     * `/` separators. This lists available outputs; actual source ownership is
+     * established by emittedSources rather than reconstructing source
+     * membership.
+     */
+    readonly outputs?: readonly string[];
+    /** Actual absolute native output-to-source observations of this checked emit. */
+    readonly emittedSources: Readonly<Record<string, readonly string[]>>;
+    /** Observed output-specific proof refusals; diagnostic context is not proof. */
+    readonly emittedSourceProofFailures?: Readonly<Record<string, string>>;
+    /**
+     * The entry tsconfig's `module` and `target`, deciding emit CJS/ESM per file.
+     * `target` is not decoration: an absent `module` makes tsgo derive the module
+     * kind from it.
+     */
+    readonly moduleOptions?: Readonly<OwningModuleOptions>;
+    /** Root directory for per-dependency build output. */
+    readonly depCacheDir: string;
+    /**
+     * Directory of lowered orphan sources under the resolved cache root, outside
+     * the run's disposable project directory. Cache collection or explicit root
+     * cleanup, rather than this manifest, determines its continued storage.
+     */
+    readonly orphanCacheDir?: string;
+    /**
+     * `false` when the run disabled transform plugins (`ttsx --no-plugins`). A
+     * TypeScript root the program reaches outside every checked build is part of
+     * the same run, so it is compiled under the same plugin policy as the entry.
+     */
+    readonly plugins?: false;
+}

package/lib/launcher/internal/runtime/RuntimeManifest.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=RuntimeManifest.js.map

package/lib/launcher/internal/runtime/RuntimeManifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RuntimeManifest.js","sourceRoot":"","sources":["../../../../src/launcher/internal/runtime/RuntimeManifest.ts"],"names":[],"mappings":""}

package/lib/launcher/internal/runtime/RuntimeManifestRegistry.d.ts

@@ -0,0 +1,95 @@
+import type { RuntimeManifest } from "./RuntimeManifest";
+/**
+ * Every checked entry emit this runtime may serve from, and the lookup that
+ * decides which of them owns a source file.
+ *
+ * A direct ttsx child inherits one manifest through `TTSX_RUNTIME_MANIFEST`;
+ * `ttsc/register` adds one per root it prepares. The inherited manifest is read
+ * lazily within this registry module instance. Successful or ordinary absent
+ * decoding is memoized; recognizable invalid-provenance errors are not cached
+ * and a later call repeats the read.
+ *
+ * An inherited manifest without actual emit provenance cannot be recovered from
+ * this process's unknown preparation inputs and is rejected explicitly.
+ * Registered callback results are copied on admission; caller mutation cannot
+ * replace the build metadata associated with an already-created ownership
+ * index.
+ *
+ * @evidence contracts/common.md#principled-implementation Inherited and registered manifests preserve preparation order; ownership indexes use actual compiler output-to-source observations, and an inherited build without valid provenance is rejected instead of inventing ownership from filenames.
+ * @evidence contracts/common.md#clear-and-simple-design One registry owns admission snapshots, environment decoding and build-to-source lookup; each manifest delegates output identity to EmitOwnershipIndex instead of duplicating reverse mapping in hooks.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Ownership follows recorded builds and filesystem identity, not basename guesses or a fallback to unchecked source execution.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain inherited versus discovered roots, caller-independent admission, lookup precedence and immutable-build index reuse; members remain separately documented without property tags.
+ * @evidence contracts/portability.md#os-neutral-implementation Native fs reads and the shared real-path resolver feed EmitOwnershipIndex's filesystem identity boundary; protocol output separators remain manifest data rather than native case assumptions.
+ * @evidence contracts/performance.md#efficient-algorithms Admission copies and validates output/provenance/refusal entries and path text; inherited decoding reads uncapped JSON bytes and snapshots metadata. Lookup scans M manifests and delegates first-use index construction and native query work. Successful/ordinary absent environment decoding is memoized, while invalid-provenance throws can repeat those costs.
+ * @evidence contracts/performance.md#reuse-equivalent-work Each admitted build has an owned frozen metadata snapshot and one WeakMap index; the ordered manifest view is shared until another admission invalidates it, while newly prepared roots receive distinct snapshots and indexes.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources This registry instance retains its inherited snapshot, every registered root and ordered view without eviction; metadata/provenance/refusal bytes and index state grow with preparations while the instance remains reachable. It owns no directory handle or artifact deletion policy.
+ */
+export declare namespace RuntimeManifestRegistry {
+    /**
+     * Admit one checked preparation in order, detached from its caller's object.
+     * The registry copies and freezes the metadata, output names and source
+     * associations without freezing the caller's values. Later caller mutation
+     * cannot change the build served by an existing ownership index.
+     *
+     * Invalid metadata throws before admission; this function neither builds the
+     * project nor proves that its producer's source observations are
+     * trustworthy.
+     *
+     * @evidence contracts/common.md#principled-implementation Admission validates the manifest grammar and captures all serving metadata, output names, format options and source arrays as owned frozen values, so a cached index cannot be paired with a later caller replacement.
+     * @evidence contracts/common.md#clear-and-simple-design One explicit admission operation owns the transfer from a callback result to stable registry metadata; index construction and actual producer observation remain with their existing owners.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Only owned copies are frozen; neither a foreign object mutation nor a filename-based fallback supplies missing build provenance.
+     * @evidence contracts/common.md#meaningful-documentation Separate native paragraphs explain copying, order, caller mutation, validation failure and the distinction between representation and trustworthy producer observations.
+     * @evidence contracts/portability.md#os-neutral-implementation Admission preserves validated native path strings exactly; absolute filename grammar is delegated to RuntimeEmitProvenance without case folding or separator conversion.
+     * @evidence contracts/performance.md#efficient-algorithms Snapshot copying and validation visit output, provenance/source and refusal entries, with path/text processing and temporary entry-pair/array allocations. One snapshot is appended without rescanning older builds; fixed top-level field count does not bound association bytes.
+     * @evidence contracts/performance.md#reuse-equivalent-work An admitted snapshot supplies one stable identity to every ownership lookup; admission invalidates only the combined manifest view, and never reuses a previous build's callback result as a new preparation.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources This registry instance retains one owned metadata snapshot per preparation without eviction, growing with output/provenance/refusal entries and text while reachable. Supported caller arrays are copied rather than retained, and no native handle is acquired.
+     */
+    function registerManifest(manifest: RuntimeManifest): void;
+    /**
+     * Every checked entry emit available to this runtime, in ownership order. An
+     * unreadable or malformed inherited manifest contributes no entry.
+     *
+     * A recognizable build manifest without valid emit provenance throws an
+     * unsupported-manifest error rather than silently changing its serving lane.
+     * The returned view and build metadata are owned frozen snapshots, shared
+     * until a later registration adds another checked preparation.
+     *
+     * @evidence contracts/common.md#principled-implementation The inherited checked build precedes roots prepared here; malformed JSON contributes no manifest, while a recognizable build without actual emit provenance fails explicitly because its original preparation inputs are unavailable.
+     * @evidence contracts/common.md#clear-and-simple-design The accessor assembles and shares one ordered view of owned manifest snapshots without exposing its mutable registration array or lazy environment decoding.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The accessor supplies only the supported inherited and registered lanes and does not invent an unchecked fallback manifest.
+     * @evidence contracts/common.md#meaningful-documentation Native prose defines ordering, unreadable/malformed absence, explicit missing-provenance failure and frozen-view lifetime rather than merely repeating the return type.
+     * @evidence contracts/portability.md#os-neutral-implementation The inherited path is read through Node fs; returned manifests retain native build paths and protocol output spelling without separator or case conversion here.
+     * @evidence contracts/performance.md#efficient-algorithms View construction copies M manifest references on first access or after registration invalidates it. First inherited decoding also reads uncapped JSON and validates/copies entry/path text; successful or ordinary absent decoding is memoized, but recognizable invalid-provenance throws repeat the read on later calls.
+     * @evidence contracts/performance.md#reuse-equivalent-work Lazy decoding shares successful or ordinary absent inherited state within this module instance, not a process-wide registry singleton. Registration invalidates the ordered view without changing earlier snapshots; rejected provenance is not memoized.
+     *
+     * @evidence contracts/performance.md#bound-retention-and-release-resources First access acquires the instance-owned inherited snapshot/absence and frozen ordered view; registration replaces the view while callers may retain older returned arrays. Current metadata stays registry-owned without eviction, and this accessor opens no retained descriptor or running task.
+     */
+    function runtimeManifests(): readonly RuntimeManifest[];
+    /**
+     * Find the manifest whose checked build emitted `real`, and that emit.
+     *
+     * A manifest's prepared root is matched first, by its recorded source, so a
+     * root keeps precedence over other preparations. Every match, including that
+     * root, requires the ownership index's actual compiler output-to-source
+     * observations and physical source identity. A file no manifest compiled gets
+     * `null` and belongs to another lane, however many emitted files share its
+     * name. Producer observations and immutable emit are trusted preparation
+     * premises, not authenticated current contents; unavailable or ambiguous
+     * provenance and native identity failures can throw rather than return null.
+     *
+     * @evidence contracts/common.md#principled-implementation A prepared entry gets first ownership lookup, but every match must come from actual emitted-source observations in its build index; neither recorded entry filenames nor matching output stems prove source membership.
+     * @evidence contracts/common.md#clear-and-simple-design Two explicit passes separate entry precedence from general build ownership, with one index helper owning memoized reverse mapping.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts No basename fallback or unchecked-file substitution stands in for proof that a selected manifest compiled the requested source.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states prepared-entry precedence, trusted preparation premises, null lane selection and possible provenance/native identity exceptions without certifying current contents.
+     * @evidence contracts/portability.md#os-neutral-implementation realPath selects prepared-entry precedence and EmitOwnershipIndex establishes native source identity from the compiler observation; filename existence and OS-name case folding cannot certify ownership.
+     * @evidence contracts/performance.md#efficient-algorithms Two manifest passes enforce precedence without sorting, adding entry realpath and native source-query/text work. First use constructs each index from output/provenance/refusal entries with native output identity observations; inherited read/snapshot costs also apply before the passes. Later queries reuse that association index, not its native alias observations.
+     * @evidence contracts/performance.md#reuse-equivalent-work Immutable prepared emit permits one preindexed association record per manifest across import specifiers; query aliases remain fresh and a newly prepared build supplies a distinct manifest identity.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources WeakMap indexes follow retained manifest objects; this registry instance keeps registered snapshots and their association/refusal text without eviction while reachable. Current alias observations are call-local rather than a queried-spelling history; artifact storage and immutable-retention policy belong to preparation owners.
+     */
+    function findEntryEmit(real: string): {
+        /** Proven owning output; a later missing file remains an output read error. */
+        emittedFile: string;
+        /** Checked build whose recorded associations established this ownership. */
+        manifest: RuntimeManifest;
+    } | null;
+}