ttsc 0.30.3 → 0.31.0

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

@@ -0,0 +1,83 @@
+/**
+ * The on-disk layout of the fenced dependency-build lock, and the one operation
+ * that frees it.
+ *
+ * `<lockDir>/current` is the held generation: a directory carrying its id and
+ * its owner. It is only ever freed by renaming it to its deterministic
+ * tombstone `<lockDir>/retired/<generation>`, so a late or duplicate retire of
+ * an old generation finds the tombstone occupied and fails instead of moving a
+ * successor under a stable cooperative namespace, noncolliding generation
+ * identities and retained tombstones for outstanding fences. The protocol does
+ * not authenticate a supplied identifier or pin the namespace with a filesystem
+ * handle. This mirrors the source-plugin lock protocol.
+ *
+ * @evidence contracts/common.md#principled-implementation Deterministic per-generation tombstones reject duplicate or stale retirement under the cooperative namespace, noncollision and retained-history premises; the identifier is not independently authenticated.
+ * @evidence contracts/common.md#clear-and-simple-design One namespace owns lock layout, timing constants and retirement, leaving acquisition and observation to their distinct operations.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Retirement uses the supported atomic rename protocol rather than clearing current recursively or inferring authority from a timeout alone.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains current and retired roles and conditional successor safety; constants describe policy units and individual retirement/diagnostic functions document their effects.
+ * @evidence contracts/portability.md#os-neutral-implementation Node path/fs represent the native lock layout; shared retireLockDirectory classifies missing or occupied destinations and Windows refusals eligible for retry after a sibling probe. That sample does not prove a peer holds the source, and namespace stability remains a cooperative caller premise.
+ *
+ * @evidenceExclude contracts/performance.md#efficient-algorithms This namespace groups layout and operations; the retirement and duration functions explain their own costs.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work The namespace has no completed computation cache; build sharing belongs to the lock's caller.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The grouping does not independently acquire resources; retirement states tombstone lifetime and release limitations.
+ */
+export declare namespace DependencyBuildLockProtocol {
+    /** Directory name of the held generation inside the lock directory. */
+    const DEP_BUILD_LOCK_CURRENT_DIR = "current";
+    /** Directory holding one tombstone per retired generation. */
+    const DEP_BUILD_LOCK_RETIRED_DIR = "retired";
+    /** File inside a generation directory holding its hex id. */
+    const DEP_BUILD_LOCK_GENERATION_FILE = "generation";
+    /**
+     * How long one wait of the lock protocol yields: a waiter's poll of the
+     * holder, and a retire's wait for a peer's read of the held generation to end
+     * (`retireLockDirectory`).
+     */
+    const DEP_BUILD_LOCK_POLL_MS = 50;
+    /**
+     * Elapsed-time policy threshold checked between runtime acquisition attempts;
+     * not a native IO or retirement deadline.
+     */
+    const DEP_BUILD_LOCK_WAIT_MS = 600000;
+    /** File inside a generation directory recording the holder's pid and host. */
+    const DEP_BUILD_LOCK_OWNER_FILE = "owner.json";
+    /**
+     * Retire a caller-acquired or observed `generation` by renaming `current`
+     * onto its tombstone. With stable cooperative layout, noncolliding ids and
+     * retained tombstones, an old fence cannot move a successor. The operation
+     * validates spelling but does not reread or authenticate current ownership.
+     * Invalid spelling, missing layout or an occupied destination returns false;
+     * unexpected filesystem errors propagate. Eligible Windows refusals retry
+     * after a sibling probe without an independent retirement deadline.
+     *
+     * @evidence contracts/common.md#principled-implementation A caller-acquired or observed generation selects its fixed tombstone; an occupied historical destination rejects stale rename under the stable namespace, noncollision and retained-history premises rather than authenticating a supplied string.
+     * @evidence contracts/common.md#clear-and-simple-design The operation validates the identifier and prepares retired before delegating one native rename boundary; polling behavior is supplied explicitly to the shared owner.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Missing layout returns false and unexpected errors propagate; no unconditional deletion bypasses the deterministic destination fence.
+     * @evidence contracts/common.md#meaningful-documentation Native prose describes input authority premises, actual false/error branches and sampled Windows retry eligibility instead of certifying current ownership or bounded cleanup.
+     * @evidence contracts/portability.md#os-neutral-implementation Node path/fs construct current and destination in the caller's native namespace. The shared helper isolates platform rename errors and sampled Windows retry eligibility; a successful sibling probe does not certify a peer actor or pin the source namespace.
+     * @evidence contracts/performance.md#efficient-algorithms Generation validation and path construction scale with supplied text; mkdir and delegated rename/existence/random sibling probe/removal perform native work. Each eligible retry allocates a four-byte wait view and yields 50 milliseconds, with no attempt cap or explicit retired-history scan; recursive probe removal remains delegated work.
+     *
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Retirement changes generation ownership and cannot reuse a past boolean as authority for a new effect.
+     *
+     * @evidence contracts/performance.md#bound-retention-and-release-resources Retired generations remain one tombstone each while stale fences can exist; population grows until the caller removes the container under its coordination policy. Eligible retries have no deadline and failed best-effort probe cleanup can leave sibling artifacts; false or a native exception is not a successful release.
+     */
+    function retireDependencyBuildLock(lockDir: string, generation: string): boolean;
+    /**
+     * Render a millisecond duration for lock diagnostics (`137ms`, `42s`, `9m
+     * 3s`). Nonfinite input renders unknown time; subsecond negatives clamp to
+     * zero.
+     *
+     * @evidence contracts/common.md#principled-implementation Finite milliseconds select rounded subsecond text or floored seconds/minutes with a remainder; unknown durations remain explicit instead of producing NaN diagnostic text.
+     * @evidence contracts/common.md#clear-and-simple-design Three direct numeric cases express units without locale state or a general formatting framework.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Unit thresholds are definition-based constants and do not encode expected lock ages or measurement results.
+     * @evidence contracts/common.md#meaningful-documentation Native prose provides units, examples and nonfinite/negative handling for diagnostic callers.
+     *
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation This numeric string formatter uses no native filesystem or process boundary.
+     *
+     * @evidence contracts/performance.md#efficient-algorithms Fixed arithmetic and one short string construction require constant operations independent of lock history.
+     *
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Formatting one supplied duration owns no cross-request computation coordinator.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The formatter retains no duration history or native resource.
+     */
+    function formatDuration(ms: number): string;
+}

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

@@ -0,0 +1,126 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DependencyBuildLockProtocol = void 0;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const retireLockDirectory_1 = require("../../../internal/retireLockDirectory");
+const DependencyBuildGeneration_1 = require("./DependencyBuildGeneration");
+const RuntimeFilesystem_1 = require("./RuntimeFilesystem");
+/**
+ * The on-disk layout of the fenced dependency-build lock, and the one operation
+ * that frees it.
+ *
+ * `<lockDir>/current` is the held generation: a directory carrying its id and
+ * its owner. It is only ever freed by renaming it to its deterministic
+ * tombstone `<lockDir>/retired/<generation>`, so a late or duplicate retire of
+ * an old generation finds the tombstone occupied and fails instead of moving a
+ * successor under a stable cooperative namespace, noncolliding generation
+ * identities and retained tombstones for outstanding fences. The protocol does
+ * not authenticate a supplied identifier or pin the namespace with a filesystem
+ * handle. This mirrors the source-plugin lock protocol.
+ *
+ * @evidence contracts/common.md#principled-implementation Deterministic per-generation tombstones reject duplicate or stale retirement under the cooperative namespace, noncollision and retained-history premises; the identifier is not independently authenticated.
+ * @evidence contracts/common.md#clear-and-simple-design One namespace owns lock layout, timing constants and retirement, leaving acquisition and observation to their distinct operations.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Retirement uses the supported atomic rename protocol rather than clearing current recursively or inferring authority from a timeout alone.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains current and retired roles and conditional successor safety; constants describe policy units and individual retirement/diagnostic functions document their effects.
+ * @evidence contracts/portability.md#os-neutral-implementation Node path/fs represent the native lock layout; shared retireLockDirectory classifies missing or occupied destinations and Windows refusals eligible for retry after a sibling probe. That sample does not prove a peer holds the source, and namespace stability remains a cooperative caller premise.
+ *
+ * @evidenceExclude contracts/performance.md#efficient-algorithms This namespace groups layout and operations; the retirement and duration functions explain their own costs.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work The namespace has no completed computation cache; build sharing belongs to the lock's caller.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The grouping does not independently acquire resources; retirement states tombstone lifetime and release limitations.
+ */
+var DependencyBuildLockProtocol;
+(function (DependencyBuildLockProtocol) {
+    /** Directory name of the held generation inside the lock directory. */
+    DependencyBuildLockProtocol.DEP_BUILD_LOCK_CURRENT_DIR = "current";
+    /** Directory holding one tombstone per retired generation. */
+    DependencyBuildLockProtocol.DEP_BUILD_LOCK_RETIRED_DIR = "retired";
+    /** File inside a generation directory holding its hex id. */
+    DependencyBuildLockProtocol.DEP_BUILD_LOCK_GENERATION_FILE = "generation";
+    /**
+     * How long one wait of the lock protocol yields: a waiter's poll of the
+     * holder, and a retire's wait for a peer's read of the held generation to end
+     * (`retireLockDirectory`).
+     */
+    DependencyBuildLockProtocol.DEP_BUILD_LOCK_POLL_MS = 50;
+    /**
+     * Elapsed-time policy threshold checked between runtime acquisition attempts;
+     * not a native IO or retirement deadline.
+     */
+    DependencyBuildLockProtocol.DEP_BUILD_LOCK_WAIT_MS = 600_000;
+    /** File inside a generation directory recording the holder's pid and host. */
+    DependencyBuildLockProtocol.DEP_BUILD_LOCK_OWNER_FILE = "owner.json";
+    /**
+     * Retire a caller-acquired or observed `generation` by renaming `current`
+     * onto its tombstone. With stable cooperative layout, noncolliding ids and
+     * retained tombstones, an old fence cannot move a successor. The operation
+     * validates spelling but does not reread or authenticate current ownership.
+     * Invalid spelling, missing layout or an occupied destination returns false;
+     * unexpected filesystem errors propagate. Eligible Windows refusals retry
+     * after a sibling probe without an independent retirement deadline.
+     *
+     * @evidence contracts/common.md#principled-implementation A caller-acquired or observed generation selects its fixed tombstone; an occupied historical destination rejects stale rename under the stable namespace, noncollision and retained-history premises rather than authenticating a supplied string.
+     * @evidence contracts/common.md#clear-and-simple-design The operation validates the identifier and prepares retired before delegating one native rename boundary; polling behavior is supplied explicitly to the shared owner.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Missing layout returns false and unexpected errors propagate; no unconditional deletion bypasses the deterministic destination fence.
+     * @evidence contracts/common.md#meaningful-documentation Native prose describes input authority premises, actual false/error branches and sampled Windows retry eligibility instead of certifying current ownership or bounded cleanup.
+     * @evidence contracts/portability.md#os-neutral-implementation Node path/fs construct current and destination in the caller's native namespace. The shared helper isolates platform rename errors and sampled Windows retry eligibility; a successful sibling probe does not certify a peer actor or pin the source namespace.
+     * @evidence contracts/performance.md#efficient-algorithms Generation validation and path construction scale with supplied text; mkdir and delegated rename/existence/random sibling probe/removal perform native work. Each eligible retry allocates a four-byte wait view and yields 50 milliseconds, with no attempt cap or explicit retired-history scan; recursive probe removal remains delegated work.
+     *
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Retirement changes generation ownership and cannot reuse a past boolean as authority for a new effect.
+     *
+     * @evidence contracts/performance.md#bound-retention-and-release-resources Retired generations remain one tombstone each while stale fences can exist; population grows until the caller removes the container under its coordination policy. Eligible retries have no deadline and failed best-effort probe cleanup can leave sibling artifacts; false or a native exception is not a successful release.
+     */
+    function retireDependencyBuildLock(lockDir, generation) {
+        if (!DependencyBuildGeneration_1.DependencyBuildGeneration.isDependencyGeneration(generation)) {
+            return false;
+        }
+        const retiredDir = node_path_1.default.join(lockDir, DependencyBuildLockProtocol.DEP_BUILD_LOCK_RETIRED_DIR);
+        try {
+            node_fs_1.default.mkdirSync(retiredDir);
+        }
+        catch (error) {
+            if (error.code !== "EEXIST") {
+                if (RuntimeFilesystem_1.RuntimeFilesystem.isMissingPathError(error)) {
+                    return false;
+                }
+                throw error;
+            }
+        }
+        return (0, retireLockDirectory_1.retireLockDirectory)(node_path_1.default.join(lockDir, DependencyBuildLockProtocol.DEP_BUILD_LOCK_CURRENT_DIR), node_path_1.default.join(retiredDir, generation), () => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, DependencyBuildLockProtocol.DEP_BUILD_LOCK_POLL_MS));
+    }
+    DependencyBuildLockProtocol.retireDependencyBuildLock = retireDependencyBuildLock;
+    /**
+     * Render a millisecond duration for lock diagnostics (`137ms`, `42s`, `9m
+     * 3s`). Nonfinite input renders unknown time; subsecond negatives clamp to
+     * zero.
+     *
+     * @evidence contracts/common.md#principled-implementation Finite milliseconds select rounded subsecond text or floored seconds/minutes with a remainder; unknown durations remain explicit instead of producing NaN diagnostic text.
+     * @evidence contracts/common.md#clear-and-simple-design Three direct numeric cases express units without locale state or a general formatting framework.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Unit thresholds are definition-based constants and do not encode expected lock ages or measurement results.
+     * @evidence contracts/common.md#meaningful-documentation Native prose provides units, examples and nonfinite/negative handling for diagnostic callers.
+     *
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation This numeric string formatter uses no native filesystem or process boundary.
+     *
+     * @evidence contracts/performance.md#efficient-algorithms Fixed arithmetic and one short string construction require constant operations independent of lock history.
+     *
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Formatting one supplied duration owns no cross-request computation coordinator.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The formatter retains no duration history or native resource.
+     */
+    function formatDuration(ms) {
+        if (!Number.isFinite(ms)) {
+            return "an unknown time";
+        }
+        if (ms < 1_000) {
+            return `${Math.max(0, Math.round(ms))}ms`;
+        }
+        const seconds = Math.floor(ms / 1_000);
+        const minutes = Math.floor(seconds / 60);
+        const remainder = seconds % 60;
+        return minutes === 0 ? `${seconds}s` : `${minutes}m ${remainder}s`;
+    }
+    DependencyBuildLockProtocol.formatDuration = formatDuration;
+})(DependencyBuildLockProtocol || (exports.DependencyBuildLockProtocol = DependencyBuildLockProtocol = {}));
+//# sourceMappingURL=DependencyBuildLockProtocol.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"DependencyBuildLockProtocol.js","sourceRoot":"","sources":["../../../../src/launcher/internal/runtime/DependencyBuildLockProtocol.ts"],"names":[],"mappings":";;;;;;AAAA,sDAAyB;AACzB,0DAA6B;AAE7B,+EAA4E;AAC5E,2EAAwE;AACxE,2DAAwD;AAExD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,IAAiB,2BAA2B,CA0G3C;AA1GD,WAAiB,2BAA2B;IAC1C,uEAAuE;IAC1D,sDAA0B,GAAG,SAAS,CAAC;IAEpD,8DAA8D;IACjD,sDAA0B,GAAG,SAAS,CAAC;IAEpD,6DAA6D;IAChD,0DAA8B,GAAG,YAAY,CAAC;IAE3D;;;;OAIG;IACU,kDAAsB,GAAG,EAAE,CAAC;IAEzC;;;OAGG;IACU,kDAAsB,GAAG,OAAO,CAAC;IAE9C,8EAA8E;IACjE,qDAAyB,GAAG,YAAY,CAAC;IAEtD;;;;;;;;;;;;;;;;;;;OAmBG;IACH,SAAgB,yBAAyB,CACvC,OAAe,EACf,UAAkB;QAElB,IAAI,CAAC,qDAAyB,CAAC,sBAAsB,CAAC,UAAU,CAAC,EAAE,CAAC;YAClE,OAAO,KAAK,CAAC;QACf,CAAC;QACD,MAAM,UAAU,GAAG,mBAAI,CAAC,IAAI,CAAC,OAAO,EAAE,sDAA0B,CAAC,CAAC;QAClE,IAAI,CAAC;YACH,iBAAE,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC;QAC3B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;gBACvD,IAAI,qCAAiB,CAAC,kBAAkB,CAAC,KAAK,CAAC,EAAE,CAAC;oBAChD,OAAO,KAAK,CAAC;gBACf,CAAC;gBACD,MAAM,KAAK,CAAC;YACd,CAAC;QACH,CAAC;QACD,OAAO,IAAA,yCAAmB,EACxB,mBAAI,CAAC,IAAI,CAAC,OAAO,EAAE,sDAA0B,CAAC,EAC9C,mBAAI,CAAC,IAAI,CAAC,UAAU,EAAE,UAAU,CAAC,EACjC,GAAG,EAAE,CACH,OAAO,CAAC,IAAI,CACV,IAAI,UAAU,CAAC,IAAI,iBAAiB,CAAC,CAAC,CAAC,CAAC,EACxC,CAAC,EACD,CAAC,EACD,kDAAsB,CACvB,CACJ,CAAC;IACJ,CAAC;IA7Be,4BAAA,yBAAyB,4BA6BxC,CAAA;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,SAAgB,cAAc,CAAC,EAAU;QACvC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;YACzB,OAAO,iBAAiB,CAAC;QAC3B,CAAC;QACD,IAAI,EAAE,GAAG,KAAK,EAAE,CAAC;YACf,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC;QAC5C,CAAC;QACD,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,KAAK,CAAC,CAAC;QACvC,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,EAAE,CAAC,CAAC;QACzC,MAAM,SAAS,GAAG,OAAO,GAAG,EAAE,CAAC;QAC/B,OAAO,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,GAAG,CAAC,CAAC,CAAC,GAAG,OAAO,KAAK,SAAS,GAAG,CAAC;IACrE,CAAC;IAXe,4BAAA,cAAc,iBAW7B,CAAA;AACH,CAAC,EA1GgB,2BAA2B,aAA3B,2BAA2B,GAA3B,2BAA2B,QA0G3C"}

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

@@ -0,0 +1,112 @@
+/**
+ * Select a project's owned output, falling back to a build of the requested
+ * source when the project emitted nothing or did not compile that source.
+ * Native build and output-read operations remain with the runtime owner.
+ *
+ * @evidence contracts/common.md#principled-implementation The coordinator distinguishes no owner, empty project, missing source ownership and successful serving without discarding other failures.
+ * @evidence contracts/common.md#clear-and-simple-design One internal concern groups its actual runtime dependencies and ordered selection operation.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The runtime supplies its real build and serving operations; no compiler output, fixture or alternate execution is substituted.
+ * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes output selection from the delegated native operations.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation The namespace itself groups the selection contract; its operation explains native delegation.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms This container performs no computation; serving describes its fixed dispatch and delegated costs.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work The container coordinates no reusable build; runtime dependencies own their cache validity.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The container retains no project generations, handles or tasks.
+ */
+export declare namespace OwnedProjectSource {
+    /**
+     * Actual runtime operations used in order by source ownership selection.
+     * `serve` returns null only when the build does not own the requested source;
+     * unreadable owned output and native build failures propagate as exceptions.
+     *
+     * @evidence contracts/common.md#principled-implementation Generic build and served values preserve owner identity without imposing synthetic compiler result shapes.
+     * @evidence contracts/common.md#clear-and-simple-design Named dependencies expose config lookup, project/root builds, serving and the one recoverable error classification.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts These are ordinary runtime dependencies used by production, not a test-only constructor or foreign-method replacement.
+     * @evidence contracts/common.md#meaningful-documentation Native prose specifies null ownership and exception responsibilities.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation This type declares operation signatures and performs no native access.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms The type performs no computation.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work The type retains no cached or in-flight result.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The type owns no runtime resources.
+     */
+    interface Dependencies<Build, Served> {
+        /**
+         * Find the config that owns the requested physical source, or no owner.
+         *
+         * @evidence contracts/common.md#principled-implementation The nullable config result distinguishes an owning project from absence for the exact supplied physical source.
+         * @evidence contracts/common.md#clear-and-simple-design One source argument and one nullable config result describe the runtime lookup boundary.
+         * @evidence contracts/common.md#prohibited-implementation-shortcuts The signature requires the actual lookup result rather than inventing ownership from a basename.
+         * @evidence contracts/common.md#meaningful-documentation Native prose identifies the physical source and no-owner result.
+         * @evidence contracts/portability.md#os-neutral-implementation The source and config strings carry native path values from the runtime owner without URL conversion or lexical case assumptions.
+         * @evidenceExclude contracts/performance.md#efficient-algorithms This method signature has no implementation; the runtime lookup owns its search cost.
+         * @evidenceExclude contracts/performance.md#reuse-equivalent-work The signature defines no lookup cache or validity policy.
+         * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The signature acquires no resource and establishes no retained lookup lifetime.
+         */
+        owningTsconfig(real: string): string | null;
+        /**
+         * Build the owning project through its existing policy.
+         *
+         * @evidence contracts/common.md#principled-implementation The selected config determines the generic build returned by the runtime owner; exceptions remain available to the coordinator.
+         * @evidence contracts/common.md#clear-and-simple-design One config selects one build operation without another compiler result representation.
+         * @evidence contracts/common.md#prohibited-implementation-shortcuts The returned build is supplied by the actual runtime dependency rather than synthesized here.
+         * @evidence contracts/common.md#meaningful-documentation Native prose identifies the owning project build policy.
+         * @evidence contracts/portability.md#os-neutral-implementation The config remains a native runtime path; executable selection and filesystem differences belong to the supplied build owner.
+         * @evidenceExclude contracts/performance.md#efficient-algorithms The signature performs no compilation or source traversal.
+         * @evidenceExclude contracts/performance.md#reuse-equivalent-work Runtime build caching and input validity are not defined by this signature.
+         * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Build resources and their transfer or release remain with the runtime implementation.
+         */
+        ensureProjectBuilt(tsconfig: string): Build;
+        /**
+         * Recognize only the runtime's empty-project emit error.
+         *
+         * @evidence contracts/common.md#principled-implementation A boolean classification of the actual thrown value identifies the one recoverable project-build error.
+         * @evidence contracts/common.md#clear-and-simple-design A separate predicate keeps error classification with the runtime owner.
+         * @evidence contracts/common.md#prohibited-implementation-shortcuts The unknown value is passed intact; the coordinator does not guess recovery from unrelated error text.
+         * @evidence contracts/common.md#meaningful-documentation Native prose limits recognition to the empty-project emit error.
+         * @evidenceExclude contracts/portability.md#os-neutral-implementation This signature describes error classification without a native path or process representation.
+         * @evidenceExclude contracts/performance.md#efficient-algorithms No classifier implementation or scanning algorithm is declared here.
+         * @evidenceExclude contracts/performance.md#reuse-equivalent-work The signature coordinates no reusable classification work.
+         * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The signature retains no error history or resource.
+         */
+        isEmptyProjectEmitError(error: unknown): boolean;
+        /**
+         * Serve the exact requested source from this build's ownership index.
+         *
+         * @evidence contracts/common.md#principled-implementation Build identity and the requested physical source determine a served value or null ownership, while read failures can still throw.
+         * @evidence contracts/common.md#clear-and-simple-design The build/source pair and nullable value distinguish ownership from output-read failure.
+         * @evidence contracts/common.md#prohibited-implementation-shortcuts The signature does not infer emitted output from a sibling filename or fabricate compiler output.
+         * @evidence contracts/common.md#meaningful-documentation Native prose identifies exact-source serving; the enclosing contract distinguishes null from unreadable owned output.
+         * @evidence contracts/portability.md#os-neutral-implementation The physical source passes unchanged to the runtime ownership index and output reader, which own native identity differences.
+         * @evidenceExclude contracts/performance.md#efficient-algorithms This signature performs no index lookup or output read.
+         * @evidenceExclude contracts/performance.md#reuse-equivalent-work It defines no served-output cache or reuse validity policy.
+         * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The signature does not acquire or retain build generations or output handles.
+         */
+        serve(built: Build, real: string): Served | null;
+        /**
+         * Build this exact source through the owning project's root policy.
+         *
+         * @evidence contracts/common.md#principled-implementation The owning config and exact source select the runtime's source-specific root build without changing their identities.
+         * @evidence contracts/common.md#clear-and-simple-design Two explicit path inputs expose the root-build responsibility separately from whole-project building.
+         * @evidence contracts/common.md#prohibited-implementation-shortcuts The runtime dependency supplies the actual build; this signature introduces no alternate compiler or test-only result.
+         * @evidence contracts/common.md#meaningful-documentation Native prose identifies the exact source and owning project's root policy.
+         * @evidence contracts/portability.md#os-neutral-implementation Both inputs retain native path spelling; platform-specific compilation and output placement remain with the runtime owner.
+         * @evidenceExclude contracts/performance.md#efficient-algorithms The signature implements no source selection or compilation algorithm.
+         * @evidenceExclude contracts/performance.md#reuse-equivalent-work It introduces no root-build cache or cross-request validity decision.
+         * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The runtime build implementation owns acquisition, transfer and release; no lifetime is implemented here.
+         */
+        ensureRootBuilt(tsconfig: string, real: string): Build;
+    }
+    /**
+     * Serve owned project output before requesting a source-specific root build.
+     * Only an empty-project emit error is recoverable. Both project and root
+     * serving receive the original source; missing root output is an error.
+     *
+     * @evidence contracts/common.md#principled-implementation No config returns null without building; project success short-circuits, while empty project or unowned requested output falls back to the same config and source. Other exceptions propagate unchanged.
+     * @evidence contracts/common.md#clear-and-simple-design The ordered project attempt, source ownership check and root attempt retain the runtime's original branches in one operation.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Selection uses actual supplied operations and exact source values without inferring output from basenames or replacing compiler results.
+     * @evidence contracts/common.md#meaningful-documentation Native prose identifies the recoverable error, exact source forwarding and missing-root failure.
+     * @evidence contracts/portability.md#os-neutral-implementation Paths pass unchanged to the owning runtime's config, native build and output-read operations; this coordinator performs no platform-specific parsing or fabricated filesystem observation.
+     * @evidence contracts/performance.md#efficient-algorithms Dispatch has a fixed number of calls, at most one project and one root build plus two serving attempts; delegated lookup, compiler and output-read costs remain part of the operation and are not claimed constant.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work This operation adds no memoization or in-flight coordination; the supplied runtime build owners maintain their existing validity and reuse policies.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Local build references and the returned served value transfer through synchronous calls; no history, handle or task is retained here, and build/read cleanup belongs to the supplied owners.
+     */
+    function serve<Build, Served>(real: string, dependencies: Dependencies<Build, Served>): Served | null;
+}

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

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OwnedProjectSource = void 0;
+/**
+ * Select a project's owned output, falling back to a build of the requested
+ * source when the project emitted nothing or did not compile that source.
+ * Native build and output-read operations remain with the runtime owner.
+ *
+ * @evidence contracts/common.md#principled-implementation The coordinator distinguishes no owner, empty project, missing source ownership and successful serving without discarding other failures.
+ * @evidence contracts/common.md#clear-and-simple-design One internal concern groups its actual runtime dependencies and ordered selection operation.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The runtime supplies its real build and serving operations; no compiler output, fixture or alternate execution is substituted.
+ * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes output selection from the delegated native operations.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation The namespace itself groups the selection contract; its operation explains native delegation.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms This container performs no computation; serving describes its fixed dispatch and delegated costs.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work The container coordinates no reusable build; runtime dependencies own their cache validity.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The container retains no project generations, handles or tasks.
+ */
+var OwnedProjectSource;
+(function (OwnedProjectSource) {
+    /**
+     * Serve owned project output before requesting a source-specific root build.
+     * Only an empty-project emit error is recoverable. Both project and root
+     * serving receive the original source; missing root output is an error.
+     *
+     * @evidence contracts/common.md#principled-implementation No config returns null without building; project success short-circuits, while empty project or unowned requested output falls back to the same config and source. Other exceptions propagate unchanged.
+     * @evidence contracts/common.md#clear-and-simple-design The ordered project attempt, source ownership check and root attempt retain the runtime's original branches in one operation.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Selection uses actual supplied operations and exact source values without inferring output from basenames or replacing compiler results.
+     * @evidence contracts/common.md#meaningful-documentation Native prose identifies the recoverable error, exact source forwarding and missing-root failure.
+     * @evidence contracts/portability.md#os-neutral-implementation Paths pass unchanged to the owning runtime's config, native build and output-read operations; this coordinator performs no platform-specific parsing or fabricated filesystem observation.
+     * @evidence contracts/performance.md#efficient-algorithms Dispatch has a fixed number of calls, at most one project and one root build plus two serving attempts; delegated lookup, compiler and output-read costs remain part of the operation and are not claimed constant.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work This operation adds no memoization or in-flight coordination; the supplied runtime build owners maintain their existing validity and reuse policies.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Local build references and the returned served value transfer through synchronous calls; no history, handle or task is retained here, and build/read cleanup belongs to the supplied owners.
+     */
+    function serve(real, dependencies) {
+        const tsconfig = dependencies.owningTsconfig(real);
+        if (tsconfig === null)
+            return null;
+        let built;
+        try {
+            built = dependencies.ensureProjectBuilt(tsconfig);
+        }
+        catch (error) {
+            if (!dependencies.isEmptyProjectEmitError(error))
+                throw error;
+            built = null;
+        }
+        const served = built === null ? null : dependencies.serve(built, real);
+        if (served !== null)
+            return served;
+        const root = dependencies.ensureRootBuilt(tsconfig, real);
+        const emitted = dependencies.serve(root, real);
+        if (emitted === null) {
+            throw new Error(`ttsx: the build of ${real} through ${tsconfig} emitted no JavaScript for it`);
+        }
+        return emitted;
+    }
+    OwnedProjectSource.serve = serve;
+})(OwnedProjectSource || (exports.OwnedProjectSource = OwnedProjectSource = {}));
+//# sourceMappingURL=OwnedProjectSource.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"OwnedProjectSource.js","sourceRoot":"","sources":["../../../../src/launcher/internal/runtime/OwnedProjectSource.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;GAaG;AACH,IAAiB,kBAAkB,CA6HlC;AA7HD,WAAiB,kBAAkB;IAuFjC;;;;;;;;;;;;;OAaG;IACH,SAAgB,KAAK,CACnB,IAAY,EACZ,YAAyC;QAEzC,MAAM,QAAQ,GAAG,YAAY,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;QACnD,IAAI,QAAQ,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC;QACnC,IAAI,KAAmB,CAAC;QACxB,IAAI,CAAC;YACH,KAAK,GAAG,YAAY,CAAC,kBAAkB,CAAC,QAAQ,CAAC,CAAC;QACpD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,YAAY,CAAC,uBAAuB,CAAC,KAAK,CAAC;gBAAE,MAAM,KAAK,CAAC;YAC9D,KAAK,GAAG,IAAI,CAAC;QACf,CAAC;QACD,MAAM,MAAM,GAAG,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,YAAY,CAAC,KAAK,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;QACvE,IAAI,MAAM,KAAK,IAAI;YAAE,OAAO,MAAM,CAAC;QACnC,MAAM,IAAI,GAAG,YAAY,CAAC,eAAe,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;QAC1D,MAAM,OAAO,GAAG,YAAY,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAC/C,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;YACrB,MAAM,IAAI,KAAK,CACb,sBAAsB,IAAI,YAAY,QAAQ,+BAA+B,CAC9E,CAAC;QACJ,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;IAvBe,mBAAA,KAAK,QAuBpB,CAAA;AACH,CAAC,EA7HgB,kBAAkB,aAAlB,kBAAkB,GAAlB,kBAAkB,QA6HlC"}

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

@@ -0,0 +1,21 @@
+/**
+ * The compiler options that decide the emit format of a file, as declared by
+ * the project that emitted it. Both fields matter: tsgo derives the module kind
+ * from `target` whenever `module` is absent, so carrying only `module` cannot
+ * reproduce its decision.
+ *
+ * @evidence contracts/common.md#principled-implementation Optional module and target preserve declaration absence because tsgo derives module kind from target when module is missing; defaulting either member here would lose the owning project's semantics.
+ * @evidence contracts/common.md#clear-and-simple-design The two emit-format inputs exclude unrelated compiler configuration and travel together through checked-build metadata.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The type carries actual owning-project options rather than assigning a consumer-specific CommonJS or ESM guess.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains why both fields and their absence matter, and separated member comments define the declared-value meaning without property tags.
+ * @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.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Optional module and target strings describe compiler emit-format policy, not native paths, processes or filesystem capabilities; the consuming format classifier separately owns native filename and package-scope observations.
+ */
+export interface OwningModuleOptions {
+    /** The project's `module` option as written; absent when not declared. */
+    module?: string;
+    /** The project's `target` option as written; absent when not declared. */
+    target?: string;
+}

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

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

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

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

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

@@ -0,0 +1,89 @@
+/**
+ * Own the descriptor evaluator's observation status and captured records.
+ *
+ * The final descriptor envelope carries this snapshot independently of the
+ * optional NDJSON channel. An uninstalled runtime or a failed observation
+ * cannot certify a reusable descriptor from an apparently empty channel.
+ *
+ * @evidence contracts/common.md#principled-implementation Ordered immutable record strings and an explicit completeness bit distinguish a completed empty observation from a missing or failed recorder.
+ * @evidence contracts/common.md#clear-and-simple-design This namespace groups installation, append, failure and snapshot transitions for one evaluator-owned state.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Its state is private to this module and does not replace foreign resolver methods or infer unseen inputs.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs state envelope purpose, missing-installation meaning and separation from the optional NDJSON channel.
+ *
+ * @evidenceExclude contracts/performance.md#efficient-algorithms The namespace representation groups transitions; individual functions own their algorithm choices.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Cache admission belongs to the envelope consumer rather than this representation.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Functions own acquisition and snapshots; the namespace itself does not independently retain resources.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation A namespace only groups the declarations inside it; each carries its own acknowledgments.
+ */
+export declare namespace PluginDescriptorInputObservation {
+    /**
+     * Arm observation after public runtime hooks have installed successfully.
+     * After the first begin, reinstallation neither erases records nor recovers a
+     * failed proof. Before initial installation, snapshot remains incomplete. The
+     * installer supplies require-resolution authority only after native hooks and
+     * any required owned module API adapter are installed.
+     *
+     * @evidence contracts/common.md#principled-implementation Successful hook installation establishes the observation owner's initial state; a repeated begin leaves an already invalid proof invalid.
+     * @evidence contracts/common.md#clear-and-simple-design One initialization transition belongs to the runtime installer, separate from captured records and consumer snapshots.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts State changes occur in this owned recorder rather than a foreign module or a guessed cache-success flag.
+     * @evidence contracts/common.md#meaningful-documentation Native prose identifies the installation prerequisite and repeated-call behavior with a blank line before tags.
+     *
+     * @evidenceExclude contracts/performance.md#efficient-algorithms This fixed state transition does not select a processing algorithm.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Initialization authorizes observation, not reuse of a computation.
+     *
+     * @evidence contracts/performance.md#bound-retention-and-release-resources Initialization creates no handles and preserves this helper instance's existing record population. The first begin arms completeness; subsequent begin calls leave later invalidation intact.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation begin changes only this helper instance's installed/completeness booleans; it opens no file, builds no path and calls no native or process API.
+     */
+    function begin(ownedRequireResolution?: boolean): void;
+    /**
+     * Retain ordered records for the final evaluator envelope.
+     *
+     * @evidence contracts/common.md#principled-implementation Copying each serialized record preserves the exact order and fingerprints established by the resolver producer.
+     * @evidence contracts/common.md#clear-and-simple-design Producers provide already observed records; this owner performs no second filesystem read that could pair later state with earlier evaluation.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Captured records are actual producer observations, without inferred missing edges or fallback success claims.
+     * @evidence contracts/common.md#meaningful-documentation The native purpose distinguishes retained observations from a later filesystem reconstruction, with prose separated from tags.
+     * @evidence contracts/performance.md#efficient-algorithms Appending N serialized records costs O(N) array insertions and retains their existing string values without reparsing or repeated joins.
+     *
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Recording observation results does not decide whether descriptor evaluations may share a result.
+     *
+     * @evidence contracts/performance.md#bound-retention-and-release-resources This helper instance retains immutable string values while reachable, growing with supplied records and their bytes without a fixed cap. The installed evaluator uses that population until its envelope snapshot; record adds no native handle or automatic reset.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation record appends supplied string values to module-owned state without interpreting native path spelling or opening files; producers own native observation.
+     */
+    function record(records: readonly string[]): void;
+    /**
+     * Refuse proof after an observation or channel failure. After initial begin,
+     * subsequent begin calls cannot recover completeness.
+     *
+     * @evidence contracts/common.md#principled-implementation A failed observation cannot be reconstructed from a partial record population, so invalidation remains false after initial begin for this helper instance; initialization of a previously uninstalled recorder is a distinct transition.
+     * @evidence contracts/common.md#clear-and-simple-design One failure transition avoids producer-specific success assumptions or recovery wrappers.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The flag records an actual missing proof instead of treating a swallowed native error as cacheable success.
+     * @evidence contracts/common.md#meaningful-documentation Native prose specifies monotonic invalidation and the failures that cause it, with separated tags.
+     *
+     * @evidenceExclude contracts/performance.md#efficient-algorithms A fixed boolean assignment does not own an input-processing algorithm.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work This operation records proof failure; consumers own cache admission.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Invalidating a proof neither acquires nor releases resources and does not own retained-record lifetime.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation invalidate changes a module-owned completeness boolean without native paths, files or process calls.
+     */
+    function invalidate(): void;
+    /**
+     * Copy the final status and records without exposing mutable owned state. The
+     * require-resolution bit describes installed interception authority; it does
+     * not recover a failed input observation or authorize cache reuse.
+     *
+     * @evidence contracts/common.md#principled-implementation An uninstalled recorder reports incomplete; the array copy prevents envelope consumers from changing retained observations.
+     * @evidence contracts/common.md#clear-and-simple-design One snapshot carries status and records together, so an empty successful channel cannot substitute for missing observation ownership.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Snapshot output reflects owned state without foreign mutation or invented dependency records.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states the uninstalled meaning and copy ownership, separated from acknowledgment tags.
+     * @evidence contracts/performance.md#efficient-algorithms Snapshotting N records costs O(N) references and no repeat parsing or filesystem scan.
+     *
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work The snapshot supplies proof to the owning cache policy and does not share evaluator computations itself.
+     *
+     * @evidence contracts/performance.md#bound-retention-and-release-resources The copied array transfers to the envelope consumer while the original remains with this helper instance; strings are immutable and no native handles escape.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation snapshot reads module-owned installed/completeness/record state and copies the array without interpreting native paths or calling file/process APIs.
+     */
+    function snapshot(): {
+        complete: boolean;
+        lines: string[];
+        requireResolveObserved: boolean;
+    };
+}