ttsc 0.30.3 → 0.31.0

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

@@ -0,0 +1,120 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DependencyBuildAdmission = void 0;
+const runHoldingLock_1 = require("../../../internal/runHoldingLock");
+const DependencyBuildLockProtocol_1 = require("./DependencyBuildLockProtocol");
+const acquireDependencyBuildLock_1 = require("./acquireDependencyBuildLock");
+const inspectDependencyBuildLock_1 = require("./inspectDependencyBuildLock");
+const readDependencyCache_1 = require("./readDependencyCache");
+const reclaimDependencyBuildLock_1 = require("./reclaimDependencyBuildLock");
+const releaseDependencyBuildLock_1 = require("./releaseDependencyBuildLock");
+/**
+ * Admit a dependency builder without interpreting elapsed wait as owner death.
+ *
+ * @evidence contracts/common.md#principled-implementation Inspection supplies policy-selected abandonment grounds; the contender's monotonic budget itself grants no retirement authority. Inspector stale unreadable-owner policy remains distinct from proof of process death.
+ * @evidence contracts/common.md#clear-and-simple-design Run owns acquisition and release; wait reports publication and inspected ownership without retiring a generation.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Expiration throws instead of granting reclaim authority; only an inspected abandoned fence reaches the retirement operation.
+ * @evidence contracts/common.md#meaningful-documentation Public operations distinguish admission budget from holder liveness and state the optional coordination fallback.
+ * @evidence contracts/portability.md#os-neutral-implementation Native lock operations and shared cache readers own filesystem semantics; monotonic time measures waiting independently of wall-clock changes.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms The namespace groups the run and wait operations that describe their costs.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Run and wait own cache validation and reuse admission.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Run owns the acquired lease; wait retains only local observations.
+ */
+var DependencyBuildAdmission;
+(function (DependencyBuildAdmission) {
+    /**
+     * Run one builder with a fenced lease, or reuse an accepted publication. Any
+     * acquisition exception invokes the existing uncoordinated build fallback,
+     * including failures after partial lock publication; it does not authenticate
+     * the namespace or guarantee that no held generation remains. One monotonic
+     * budget is checked across attempts and peer turnover, not as a hard deadline
+     * for native calls, building or retirement.
+     *
+     * @evidence contracts/common.md#principled-implementation Cache validation precedes acquisition and repeats after ownership; retirement receives only an inspected abandoned generation and release receives only this contender's acquired lease.
+     * @evidence contracts/common.md#clear-and-simple-design This operation owns admission, budget, cache rechecks and lease lifecycle; wait owns passive observation and runHoldingLock owns release error handling.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Contender expiration throws rather than authorizing retirement; acquisition exceptions invoke the actual build fallback instead of fabricating a hit, while inspected abandonment still follows the inspector's stale-record policy.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states the actual broad acquisition-exception fallback, partial-state possibility and checked-budget scope without certifying a hard native deadline.
+     * @evidence contracts/portability.md#os-neutral-implementation Shared native lease operations classify filesystem behavior; the timeout uses performance.now rather than OS names or wall-clock subtraction.
+     * @evidence contracts/performance.md#efficient-algorithms Each attempt adds reader marker/provenance/path/walk/identity work and native acquisition or inspection costs; fixed coordinates do not bound bytes or native latency. Polls yield instead of spinning, but native retirement and the build callback can outlast the contender budget.
+     * @evidence contracts/performance.md#reuse-equivalent-work Publication shape/presence is checked before and after acquisition under cooperative immutable-generation premises. The callback runs after an admitted miss or any acquisition exception; this operation does not independently authenticate marker observations or caller cache-key equivalence.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources runHoldingLock attempts acquired-lease release on either synchronous work outcome, ignores a false release result and suppresses thrown release errors through the supplied no-op reporter; recovery can remain necessary. No peer lease or historical observation list is retained, while build artifacts, tombstones and partial acquisition state follow their caller/protocol lifetime policies.
+     */
+    function run(cacheDir, metaPath, lockDir, build, timeoutMs = DependencyBuildLockProtocol_1.DependencyBuildLockProtocol.DEP_BUILD_LOCK_WAIT_MS) {
+        assertWaitBudget(timeoutMs);
+        const startedAt = performance.now();
+        for (;;) {
+            const reuse = (0, readDependencyCache_1.readDependencyCache)(cacheDir, metaPath);
+            if (reuse !== null)
+                return reuse;
+            const remaining = timeoutMs - (performance.now() - startedAt);
+            if (remaining <= 0)
+                throw timeoutError(timeoutMs);
+            let lease;
+            try {
+                lease = (0, acquireDependencyBuildLock_1.acquireDependencyBuildLock)(lockDir);
+            }
+            catch {
+                return build();
+            }
+            if (lease === null) {
+                const waited = wait(cacheDir, metaPath, lockDir, Math.max(0, timeoutMs - (performance.now() - startedAt)));
+                if (waited.outcome === "built")
+                    return waited.built;
+                if (waited.outcome === "abandoned")
+                    (0, reclaimDependencyBuildLock_1.reclaimDependencyBuildLock)(lockDir, waited.fence);
+                continue;
+            }
+            const held = lease;
+            return (0, runHoldingLock_1.runHoldingLock)(() => (0, readDependencyCache_1.readDependencyCache)(cacheDir, metaPath) ?? build(), () => (0, releaseDependencyBuildLock_1.releaseDependencyBuildLock)(lockDir, held), () => undefined);
+        }
+    }
+    DependencyBuildAdmission.run = run;
+    /**
+     * Observe publication and peer state, checking the remaining contender budget
+     * after cache and ownership reads. This operation never retires a generation;
+     * native observations can outlast the budget and return a newly observed
+     * publication, release or policy-selected abandonment before its next check.
+     *
+     * @evidence contracts/common.md#principled-implementation An accepted cache record returns a built result under cooperative publication premises; released observation triggers a second read, and only inspector-selected abandonment supplies a fence rather than turning contender expiration into authority.
+     * @evidence contracts/common.md#clear-and-simple-design This passive operation reports peer state or throws on expiration without acquiring, releasing or retiring a lock.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Elapsed time is never converted into owner-death evidence and wall-clock movement cannot renew the contender budget.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states read-before-budget-check ordering and passive observation, without promising a hard native deadline or authenticating holder state.
+     * @evidence contracts/portability.md#os-neutral-implementation Native inspection owns peer identity; wall time remains only its ownerless-publication age input, while performance.now owns elapsed waiting.
+     * @evidence contracts/performance.md#efficient-algorithms Each poll delegates marker/provenance/path/walk/identity validation and native generation/owner reads and liveness or age observations. Poll count and native latency are not bounded by fixed coordinates; each sleep allocates a four-byte wait view and uses the smaller polling interval/remaining budget, without scanning lock history.
+     * @evidence contracts/performance.md#reuse-equivalent-work The shared reader checks publication shape and presence under cooperative generation premises; neither an active observation nor contender elapsed time invents a build result or independently proves caller cache-key equivalence.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources This observer owns no lease or filesystem handle and keeps only the current observation and monotonic start time.
+     */
+    function wait(cacheDir, metaPath, lockDir, timeoutMs) {
+        assertWaitBudget(timeoutMs);
+        const startedAt = performance.now();
+        for (;;) {
+            const reuse = (0, readDependencyCache_1.readDependencyCache)(cacheDir, metaPath);
+            if (reuse !== null)
+                return { outcome: "built", built: reuse };
+            const lock = (0, inspectDependencyBuildLock_1.inspectDependencyBuildLock)(lockDir, Date.now());
+            if (lock.state === "released") {
+                const built = (0, readDependencyCache_1.readDependencyCache)(cacheDir, metaPath);
+                return built !== null
+                    ? { outcome: "built", built }
+                    : { outcome: "released" };
+            }
+            if (lock.state === "abandoned")
+                return { outcome: "abandoned", reason: lock.reason, fence: lock.fence };
+            const remaining = timeoutMs - (performance.now() - startedAt);
+            if (remaining <= 0)
+                throw timeoutError(timeoutMs);
+            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, Math.min(DependencyBuildLockProtocol_1.DependencyBuildLockProtocol.DEP_BUILD_LOCK_POLL_MS, remaining));
+        }
+    }
+    DependencyBuildAdmission.wait = wait;
+})(DependencyBuildAdmission || (exports.DependencyBuildAdmission = DependencyBuildAdmission = {}));
+/** Expiration limits a contender; it never grants retirement authority. */
+function timeoutError(timeoutMs) {
+    return new Error(`ttsx: dependency build admission timed out after ${DependencyBuildLockProtocol_1.DependencyBuildLockProtocol.formatDuration(timeoutMs)}; the holding generation was not retired`);
+}
+/** Require a finite nonnegative admission budget before polling. */
+function assertWaitBudget(timeoutMs) {
+    if (!Number.isFinite(timeoutMs) || timeoutMs < 0)
+        throw new RangeError("ttsx: dependency build admission budget must be finite and nonnegative");
+}
+//# sourceMappingURL=DependencyBuildAdmission.js.map

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

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

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

@@ -0,0 +1,185 @@
+import type { OwningModuleOptions } from "./OwningModuleOptions";
+/**
+ * Generations of the ttsx dependency cache: immutable emit directories and the
+ * marker that publishes one of them.
+ *
+ * Under cooperative cache ownership and noncolliding generation ids, a build
+ * writes a fresh `gen-<id>` directory before swapping the marker. Successful
+ * publication pairs one marker with that build's emit; immutable generation
+ * retention and stable native layout remain caller premises, not a guarantee
+ * against external deletion, mutation or crash durability failure.
+ *
+ * @evidence contracts/common.md#principled-implementation Fresh generation directories and a generation-bearing marker bind one successful publication to its build under cooperative ownership and noncolliding ids, avoiding in-place reader generation replacement under those premises.
+ * @evidence contracts/common.md#clear-and-simple-design The namespace groups the built-project record, marker representation and generation filesystem helpers around one publication concern.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Generation identity and real emit presence replace in-place shared writes; no consumer name or expected output certifies a completed build.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs distinguish publication from immutable-retention and native-layout premises; record members explain source-root context, output records and format options without property tags.
+ * @evidence contracts/portability.md#os-neutral-implementation Native path joins and fs queries preserve host paths; the shared physical-identity resolver handles links and filesystem case capabilities without deriving them from the OS label.
+ *
+ * @evidenceExclude contracts/performance.md#efficient-algorithms This namespace defines publication helpers and records; algorithm choices belong to its individual operations and the producer.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This grouping owns no build-request cache; the generation marker and build coordinator determine when completed emit can be shared.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The namespace retains no historical generation index; the dependency container owner reclaims emitted directories.
+ */
+export declare namespace DependencyBuildGeneration {
+    /**
+     * One built dependency project, as the runtime serves files from it.
+     *
+     * @evidence contracts/common.md#principled-implementation Emit directory, producer output-to-source observations, source-root context and format pair represent one built generation; the structural record is not a completion certificate and the output list alone cannot reconstruct program membership.
+     * @evidence contracts/common.md#clear-and-simple-design Required members represent a usable build result without mixing completion-marker identity or acquisition state into serving metadata.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Explicit output ownership and owning format options avoid guessing a compiled file from its basename or authored syntax.
+     * @evidence contracts/common.md#meaningful-documentation The native purpose and spaced member comments distinguish generation location, best-effort source-root identity, output spelling and format selection without authenticating supplied fields.
+     * @evidence contracts/portability.md#os-neutral-implementation emitDir and rootDir are native filesystem paths; root resolution may retain best-effort spelling on observation failure. Outputs are relative records, while emittedSources and refusal records use producer native output keys; the output index owns their conversion and membership checks.
+     *
+     * @evidenceExclude contracts/performance.md#efficient-algorithms This build-result interface chooses no algorithm.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work The data record carries identity inputs but does not coordinate build requests or establish invalidation by itself.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The record does not independently own the generation directory's lifetime.
+     */
+    interface BuiltProject {
+        /** The generation directory holding the project's emitted JavaScript. */
+        emitDir: string;
+        /**
+         * Source-root context, physically resolved when observable, with
+         * best-effort fallback spelling.
+         */
+        rootDir: string;
+        /** The build's record of its outputs, relative to `emitDir`. */
+        outputs: readonly string[];
+        /** Actual absolute output-to-source observations from this compiler emit. */
+        emittedSources: Readonly<Record<string, readonly string[]>>;
+        /** Actual producer proof refusals, retained solely for diagnostics. */
+        emittedSourceProofFailures?: Readonly<Record<string, string>>;
+        /** The project's `module` and `target`, deciding each file's format. */
+        moduleOptions: OwningModuleOptions;
+    }
+    /**
+     * On-disk completion marker for a built dependency, shared across processes.
+     *
+     * `generation` names the exact immutable emit directory this marker describes
+     * (`<cacheDir>/gen-<generation>`). The producer writes the marker after emit
+     * presence and provenance checks, using a same-directory temporary file and
+     * rename. Successful replacement publishes one whole marker under supported
+     * native rename semantics; retained immutable generations and stable layout
+     * remain cooperative premises. Parsing this structural record alone does not
+     * prove current artifact presence, compiler success or crash durability.
+     *
+     * @evidence contracts/common.md#principled-implementation The generation names the immutable directory described by format and actual emit provenance; optional historical fields remain decodable but the current reader rejects their absence rather than inventing program membership from output names.
+     * @evidence contracts/common.md#clear-and-simple-design One completion record contains publication identity and serving metadata, leaving pid ownership and lock state to their separate records.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The marker binds a real completed generation rather than pairing old metadata with whatever mutable directory currently exists.
+     * @evidence contracts/common.md#meaningful-documentation Native paragraphs distinguish successful marker publication from artifact retention and completion authentication, and separately document historical-field absence without member acknowledgments.
+     * @evidence contracts/portability.md#os-neutral-implementation The marker carries native source-root spelling, producer native output keys and relative output names. Root resolution can fall back to best-effort spelling; hexadecimal generation basenames are joined by the reader, while native marker replacement and artifact validation belong to producer and consumer.
+     *
+     * @evidenceExclude contracts/performance.md#efficient-algorithms This serialized metadata interface defines values rather than a computation strategy.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work A record names one publication; the reader and build coordinator establish when other requests may reuse it.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Completion metadata does not independently acquire or release the generation directory.
+     */
+    interface DependencyCacheMeta {
+        /** The 128-bit hex id of the published generation directory. */
+        generation: string;
+        /**
+         * Source-root context with physical resolution when observable and
+         * best-effort fallback otherwise.
+         */
+        rootDir: string;
+        /**
+         * The project's emit-format options. Always written; a marker without it
+         * predates the field and is rebuilt rather than guessed.
+         */
+        moduleOptions?: OwningModuleOptions;
+        /**
+         * The build's record of the JavaScript it emitted, relative to the
+         * generation directory. Always written; a marker without it predates the
+         * field and is rebuilt. Actual source ownership additionally requires
+         * emittedSources from the compiler's completed write observations.
+         */
+        outputs?: readonly string[];
+        /** Actual emit provenance; historical absence requires a fresh build. */
+        emittedSources?: Readonly<Record<string, readonly string[]>>;
+        /** Optional refusal context from this generation, without ownership proof. */
+        emittedSourceProofFailures?: Readonly<Record<string, string>>;
+    }
+    /**
+     * The immutable emit directory of one build generation under `cacheDir`.
+     * Callers supply a generated or validated generation identifier.
+     *
+     * @evidence contracts/common.md#principled-implementation Prefixing a validated hex generation with gen- maps one publication identity to its immutable directory beneath the owning cache.
+     * @evidence contracts/common.md#clear-and-simple-design One path constructor keeps the writer and reader's generation layout identical.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The layout follows the generation protocol and does not special-case a project or expected emit location.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states immutable location and the caller's identifier-validation responsibility.
+     * @evidence contracts/portability.md#os-neutral-implementation path.join constructs the host-native child path; generation hex contains no native separator or drive syntax.
+     * @evidence contracts/performance.md#efficient-algorithms Joining two path components costs their character lengths without filesystem traversal.
+     *
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work This deterministic spelling helper owns no request coordinator or completed build cache.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The returned path acquires no directory or handle.
+     */
+    function dependencyGenerationDir(cacheDir: string, generation: string): string;
+    /**
+     * A fresh random 128-bit build-generation identifier, encoded as lowercase
+     * hex.
+     *
+     * @evidence contracts/common.md#principled-implementation Sixteen cryptographically random bytes supply a probabilistically distinct generation identity compatible with the lock and emit basename validators.
+     * @evidence contracts/common.md#clear-and-simple-design One generator supplies the same fixed representation to build publication and lock fencing.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Random generation identity avoids recycled pid or fixture-derived identity substitutions.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states randomness, bit width and lowercase hex encoding without claiming guaranteed uniqueness.
+     *
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation This fixed byte-to-hex calculation carries no native filesystem or process representation.
+     *
+     * @evidence contracts/performance.md#efficient-algorithms One 16-byte native cryptographic draw and hex encoding have fixed output size; native entropy latency or failure is not bounded by that byte count. No generation history is scanned.
+     *
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Every acquisition needs a new identity; reusing a prior draw would violate the generation premise.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The call returns a small identifier and retains no random buffer or native handle.
+     */
+    function newDependencyGeneration(): string;
+    /**
+     * True for a well-formed lowercase 128-bit hex build generation. This
+     * validates representation, not ownership or publication completion.
+     *
+     * @evidence contracts/common.md#principled-implementation A string guard and anchored 32-hex pattern enforce the generation representation before an untrusted marker becomes a directory component.
+     * @evidence contracts/common.md#clear-and-simple-design One type predicate shares exact syntax between marker reads and retirement without conflating syntax with ownership.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The validator recognizes the protocol grammar rather than known generation values or fixture identifiers.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states lowercase width and the limits of representation validation.
+     *
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation Hex grammar is platform-independent and performs no native path or process operation.
+     *
+     * @evidence contracts/performance.md#efficient-algorithms The anchored bounded repetition examines at most the fixed accepted width plus rejection boundary, with no unbounded backtracking.
+     *
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work A fixed-size syntax predicate supplies no expensive equivalent-request coordinator.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The predicate retains no input history or resource.
+     */
+    function isDependencyGeneration(value: unknown): value is string;
+    /**
+     * Resolve build-root metadata through the runtime's shared native identity
+     * owner.
+     *
+     * Existing roots use physical spelling. Missing paths use the surviving
+     * ancestor's observed case policy; failed identity observation retains a
+     * best-effort spelling so completed-build metadata remains usable.
+     *
+     * This root is build context, not proof of emitted source membership or
+     * recursive-cleanup authority. Exact ownership uses the compiler's captured
+     * emittedSources observations instead.
+     *
+     * @evidence contracts/common.md#principled-implementation Delegating to the launcher's shared filesystem-identity resolver aligns existing roots and its best-effort unresolved-tail rule with the served source spelling; unresolved fallback is not proof of deletion authority.
+     * @evidence contracts/common.md#clear-and-simple-design The adapter keeps runtime build metadata on the same identity policy instead of implementing another case or link resolver.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Filesystem observations establish identity; no OS-name lowercasing or source-name exception substitutes for the shared resolver.
+     * @evidence contracts/common.md#meaningful-documentation Native paragraphs distinguish root metadata from actual emitted-source proof and deletion authority, explaining physical resolution and its best-effort fallback.
+     * @evidence contracts/portability.md#os-neutral-implementation The shared resolver observes native links and surviving-ancestor case capabilities; this adapter preserves the returned native spelling.
+     * @evidence contracts/performance.md#efficient-algorithms Delegation creates a fresh identity context; path text and ancestor observations grow its maps, and native case observations may scan directory entries or invoke a Windows query. Fixed adapter steps do not bound that native work, and emitted source trees are not traversed by this adapter.
+     * @evidence contracts/performance.md#reuse-equivalent-work The delegated context shares equivalent path and case observations within this invocation, then later invocations observe current filesystem state again. This adapter adds no historical identity cache or independent validity proof.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources The delegated context owns call-local path/ancestor/case maps and native observations, including a possible Windows case-query child. Only the resulting string escapes after success or caught failure; the adapter holds no historical registry or directory handle.
+     */
+    function resolvePhysicalPath(location: string): string;
+    /**
+     * True when `directory` holds at least one emitted JavaScript file (any
+     * depth).
+     *
+     * @evidence contracts/common.md#principled-implementation Directory traversal accepts only real regular-file JavaScript extensions and descends directory entries without following symlink leaves; failed reads cannot establish a completed emit.
+     * @evidence contracts/common.md#clear-and-simple-design One existential tree predicate stops on the first qualifying file and leaves output ownership indexing to the separate build record.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The predicate observes actual emit presence rather than a marker's claim or a known filename, without treating a partial generation as published.
+     * @evidence contracts/common.md#meaningful-documentation Native prose defines JavaScript presence at any depth; the completion reader separately documents why presence alone does not establish ownership.
+     * @evidence contracts/portability.md#os-neutral-implementation Native Dirent classification and path joins preserve host filesystem semantics; suffix grammar describes JavaScript outputs rather than host case policy.
+     * @evidence contracts/performance.md#efficient-algorithms An early-exit depth-first walk visits at most E entries, with path joins and suffix tests also processing directory/name text and native listing costs. Temporary space includes all listings retained along the active recursion path, constructed path strings and depth D; it does not allocate a flattened tree.
+     *
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work The caller determines immutable generation publication; this predicate does not cache a result while a build may still be writing.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Synchronous directory reads retain no handle or history; generation storage belongs to its cache container.
+     */
+    function emittedAnything(directory: string): boolean;
+}

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

@@ -0,0 +1,153 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DependencyBuildGeneration = void 0;
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const resolvePhysicalPath_1 = require("../../../internal/pathIdentity/resolvePhysicalPath");
+/**
+ * Generations of the ttsx dependency cache: immutable emit directories and the
+ * marker that publishes one of them.
+ *
+ * Under cooperative cache ownership and noncolliding generation ids, a build
+ * writes a fresh `gen-<id>` directory before swapping the marker. Successful
+ * publication pairs one marker with that build's emit; immutable generation
+ * retention and stable native layout remain caller premises, not a guarantee
+ * against external deletion, mutation or crash durability failure.
+ *
+ * @evidence contracts/common.md#principled-implementation Fresh generation directories and a generation-bearing marker bind one successful publication to its build under cooperative ownership and noncolliding ids, avoiding in-place reader generation replacement under those premises.
+ * @evidence contracts/common.md#clear-and-simple-design The namespace groups the built-project record, marker representation and generation filesystem helpers around one publication concern.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Generation identity and real emit presence replace in-place shared writes; no consumer name or expected output certifies a completed build.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs distinguish publication from immutable-retention and native-layout premises; record members explain source-root context, output records and format options without property tags.
+ * @evidence contracts/portability.md#os-neutral-implementation Native path joins and fs queries preserve host paths; the shared physical-identity resolver handles links and filesystem case capabilities without deriving them from the OS label.
+ *
+ * @evidenceExclude contracts/performance.md#efficient-algorithms This namespace defines publication helpers and records; algorithm choices belong to its individual operations and the producer.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This grouping owns no build-request cache; the generation marker and build coordinator determine when completed emit can be shared.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The namespace retains no historical generation index; the dependency container owner reclaims emitted directories.
+ */
+var DependencyBuildGeneration;
+(function (DependencyBuildGeneration) {
+    /**
+     * The immutable emit directory of one build generation under `cacheDir`.
+     * Callers supply a generated or validated generation identifier.
+     *
+     * @evidence contracts/common.md#principled-implementation Prefixing a validated hex generation with gen- maps one publication identity to its immutable directory beneath the owning cache.
+     * @evidence contracts/common.md#clear-and-simple-design One path constructor keeps the writer and reader's generation layout identical.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The layout follows the generation protocol and does not special-case a project or expected emit location.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states immutable location and the caller's identifier-validation responsibility.
+     * @evidence contracts/portability.md#os-neutral-implementation path.join constructs the host-native child path; generation hex contains no native separator or drive syntax.
+     * @evidence contracts/performance.md#efficient-algorithms Joining two path components costs their character lengths without filesystem traversal.
+     *
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work This deterministic spelling helper owns no request coordinator or completed build cache.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The returned path acquires no directory or handle.
+     */
+    function dependencyGenerationDir(cacheDir, generation) {
+        return node_path_1.default.join(cacheDir, `gen-${generation}`);
+    }
+    DependencyBuildGeneration.dependencyGenerationDir = dependencyGenerationDir;
+    /**
+     * A fresh random 128-bit build-generation identifier, encoded as lowercase
+     * hex.
+     *
+     * @evidence contracts/common.md#principled-implementation Sixteen cryptographically random bytes supply a probabilistically distinct generation identity compatible with the lock and emit basename validators.
+     * @evidence contracts/common.md#clear-and-simple-design One generator supplies the same fixed representation to build publication and lock fencing.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Random generation identity avoids recycled pid or fixture-derived identity substitutions.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states randomness, bit width and lowercase hex encoding without claiming guaranteed uniqueness.
+     *
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation This fixed byte-to-hex calculation carries no native filesystem or process representation.
+     *
+     * @evidence contracts/performance.md#efficient-algorithms One 16-byte native cryptographic draw and hex encoding have fixed output size; native entropy latency or failure is not bounded by that byte count. No generation history is scanned.
+     *
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Every acquisition needs a new identity; reusing a prior draw would violate the generation premise.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The call returns a small identifier and retains no random buffer or native handle.
+     */
+    function newDependencyGeneration() {
+        return node_crypto_1.default.randomBytes(16).toString("hex");
+    }
+    DependencyBuildGeneration.newDependencyGeneration = newDependencyGeneration;
+    /**
+     * True for a well-formed lowercase 128-bit hex build generation. This
+     * validates representation, not ownership or publication completion.
+     *
+     * @evidence contracts/common.md#principled-implementation A string guard and anchored 32-hex pattern enforce the generation representation before an untrusted marker becomes a directory component.
+     * @evidence contracts/common.md#clear-and-simple-design One type predicate shares exact syntax between marker reads and retirement without conflating syntax with ownership.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The validator recognizes the protocol grammar rather than known generation values or fixture identifiers.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states lowercase width and the limits of representation validation.
+     *
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation Hex grammar is platform-independent and performs no native path or process operation.
+     *
+     * @evidence contracts/performance.md#efficient-algorithms The anchored bounded repetition examines at most the fixed accepted width plus rejection boundary, with no unbounded backtracking.
+     *
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work A fixed-size syntax predicate supplies no expensive equivalent-request coordinator.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The predicate retains no input history or resource.
+     */
+    function isDependencyGeneration(value) {
+        return typeof value === "string" && /^[0-9a-f]{32}$/.test(value);
+    }
+    DependencyBuildGeneration.isDependencyGeneration = isDependencyGeneration;
+    /**
+     * Resolve build-root metadata through the runtime's shared native identity
+     * owner.
+     *
+     * Existing roots use physical spelling. Missing paths use the surviving
+     * ancestor's observed case policy; failed identity observation retains a
+     * best-effort spelling so completed-build metadata remains usable.
+     *
+     * This root is build context, not proof of emitted source membership or
+     * recursive-cleanup authority. Exact ownership uses the compiler's captured
+     * emittedSources observations instead.
+     *
+     * @evidence contracts/common.md#principled-implementation Delegating to the launcher's shared filesystem-identity resolver aligns existing roots and its best-effort unresolved-tail rule with the served source spelling; unresolved fallback is not proof of deletion authority.
+     * @evidence contracts/common.md#clear-and-simple-design The adapter keeps runtime build metadata on the same identity policy instead of implementing another case or link resolver.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Filesystem observations establish identity; no OS-name lowercasing or source-name exception substitutes for the shared resolver.
+     * @evidence contracts/common.md#meaningful-documentation Native paragraphs distinguish root metadata from actual emitted-source proof and deletion authority, explaining physical resolution and its best-effort fallback.
+     * @evidence contracts/portability.md#os-neutral-implementation The shared resolver observes native links and surviving-ancestor case capabilities; this adapter preserves the returned native spelling.
+     * @evidence contracts/performance.md#efficient-algorithms Delegation creates a fresh identity context; path text and ancestor observations grow its maps, and native case observations may scan directory entries or invoke a Windows query. Fixed adapter steps do not bound that native work, and emitted source trees are not traversed by this adapter.
+     * @evidence contracts/performance.md#reuse-equivalent-work The delegated context shares equivalent path and case observations within this invocation, then later invocations observe current filesystem state again. This adapter adds no historical identity cache or independent validity proof.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources The delegated context owns call-local path/ancestor/case maps and native observations, including a possible Windows case-query child. Only the resulting string escapes after success or caught failure; the adapter holds no historical registry or directory handle.
+     */
+    function resolvePhysicalPath(location) {
+        return (0, resolvePhysicalPath_1.resolvePhysicalPath)(location);
+    }
+    DependencyBuildGeneration.resolvePhysicalPath = resolvePhysicalPath;
+    /**
+     * True when `directory` holds at least one emitted JavaScript file (any
+     * depth).
+     *
+     * @evidence contracts/common.md#principled-implementation Directory traversal accepts only real regular-file JavaScript extensions and descends directory entries without following symlink leaves; failed reads cannot establish a completed emit.
+     * @evidence contracts/common.md#clear-and-simple-design One existential tree predicate stops on the first qualifying file and leaves output ownership indexing to the separate build record.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The predicate observes actual emit presence rather than a marker's claim or a known filename, without treating a partial generation as published.
+     * @evidence contracts/common.md#meaningful-documentation Native prose defines JavaScript presence at any depth; the completion reader separately documents why presence alone does not establish ownership.
+     * @evidence contracts/portability.md#os-neutral-implementation Native Dirent classification and path joins preserve host filesystem semantics; suffix grammar describes JavaScript outputs rather than host case policy.
+     * @evidence contracts/performance.md#efficient-algorithms An early-exit depth-first walk visits at most E entries, with path joins and suffix tests also processing directory/name text and native listing costs. Temporary space includes all listings retained along the active recursion path, constructed path strings and depth D; it does not allocate a flattened tree.
+     *
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work The caller determines immutable generation publication; this predicate does not cache a result while a build may still be writing.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Synchronous directory reads retain no handle or history; generation storage belongs to its cache container.
+     */
+    function emittedAnything(directory) {
+        let entries;
+        try {
+            entries = node_fs_1.default.readdirSync(directory, { withFileTypes: true });
+        }
+        catch {
+            return false;
+        }
+        for (const entry of entries) {
+            const full = node_path_1.default.join(directory, entry.name);
+            if (entry.isDirectory()) {
+                if (emittedAnything(full)) {
+                    return true;
+                }
+            }
+            else if (entry.isFile() && /\.(?:[cm]?js)$/i.test(entry.name)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    DependencyBuildGeneration.emittedAnything = emittedAnything;
+})(DependencyBuildGeneration || (exports.DependencyBuildGeneration = DependencyBuildGeneration = {}));
+//# sourceMappingURL=DependencyBuildGeneration.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"DependencyBuildGeneration.js","sourceRoot":"","sources":["../../../../src/launcher/internal/runtime/DependencyBuildGeneration.ts"],"names":[],"mappings":";;;;;;AAAA,8DAAiC;AACjC,sDAAyB;AACzB,0DAA6B;AAE7B,4FAAwH;AAGxH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,IAAiB,yBAAyB,CAgNzC;AAhND,WAAiB,yBAAyB;IAyFxC;;;;;;;;;;;;;OAaG;IACH,SAAgB,uBAAuB,CACrC,QAAgB,EAChB,UAAkB;QAElB,OAAO,mBAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,UAAU,EAAE,CAAC,CAAC;IAClD,CAAC;IALe,0BAAA,uBAAuB,0BAKtC,CAAA;IAED;;;;;;;;;;;;;;;OAeG;IACH,SAAgB,uBAAuB;QACrC,OAAO,qBAAM,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IAChD,CAAC;IAFe,0BAAA,uBAAuB,0BAEtC,CAAA;IAED;;;;;;;;;;;;;;;OAeG;IACH,SAAgB,sBAAsB,CAAC,KAAc;QACnD,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACnE,CAAC;IAFe,0BAAA,sBAAsB,yBAErC,CAAA;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,SAAgB,mBAAmB,CAAC,QAAgB;QAClD,OAAO,IAAA,yCAA2B,EAAC,QAAQ,CAAC,CAAC;IAC/C,CAAC;IAFe,0BAAA,mBAAmB,sBAElC,CAAA;IAED;;;;;;;;;;;;;OAaG;IACH,SAAgB,eAAe,CAAC,SAAiB;QAC/C,IAAI,OAAoB,CAAC;QACzB,IAAI,CAAC;YACH,OAAO,GAAG,iBAAE,CAAC,WAAW,CAAC,SAAS,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;QAC/D,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;QACD,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC5B,MAAM,IAAI,GAAG,mBAAI,CAAC,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;YAC9C,IAAI,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;gBACxB,IAAI,eAAe,CAAC,IAAI,CAAC,EAAE,CAAC;oBAC1B,OAAO,IAAI,CAAC;gBACd,CAAC;YACH,CAAC;iBAAM,IAAI,KAAK,CAAC,MAAM,EAAE,IAAI,iBAAiB,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;gBAChE,OAAO,IAAI,CAAC;YACd,CAAC;QACH,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAlBe,0BAAA,eAAe,kBAkB9B,CAAA;AACH,CAAC,EAhNgB,yBAAyB,aAAzB,yBAAyB,GAAzB,yBAAyB,QAgNzC"}

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

@@ -0,0 +1,22 @@
+/**
+ * Opaque identity of one observed lock generation.
+ *
+ * Returned by {@link inspectDependencyBuildLock} and consumed by
+ * {@link reclaimDependencyBuildLock}, so a waiter retires exactly the generation
+ * it judged abandoned. Successor protection relies on the protocol's stable
+ * cooperative namespace and noncolliding generation identities; this structural
+ * value is not an authenticated ownership credential.
+ *
+ * @evidence contracts/common.md#principled-implementation The observed generation is the retirement fence, so an abandoned observation identifies one historical holder rather than authorizing removal of whatever holds current later.
+ * @evidence contracts/common.md#clear-and-simple-design One generation member carries the only identity the reclaim operation needs; observation labels and ownership authority stay outside the fence.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The token preserves generation identity instead of substituting a stale timeout or pid for retirement authority.
+ * @evidence contracts/common.md#meaningful-documentation Native prose connects observation and reclaim, states the namespace and generation premises and documents the unreadable-generation sentinel without field 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.
+ * @evidence contracts/portability.md#os-neutral-implementation The fence carries a lowercase hexadecimal generation or an empty unreadable sentinel, not a native path, pid or filesystem capability. The native retirement consumer applies this identity in its cooperative lock namespace; the string alone neither pins that namespace nor authenticates a holder.
+ */
+export type DependencyBuildLockFence = {
+    /** The 128-bit hex id of the observed generation; empty when unreadable. */
+    generation: string;
+};

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

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

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

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

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

@@ -0,0 +1,22 @@
+/**
+ * Acquired-generation token returned by successful lock acquisition.
+ *
+ * Produced by {@link acquireDependencyBuildLock} and consumed by
+ * {@link releaseDependencyBuildLock}. Release retires this generation and no
+ * other under a stable cooperative namespace with noncolliding generation
+ * identities. A late holder therefore targets its historical generation; the
+ * structural type itself does not authenticate acquisition or ownership.
+ *
+ * @evidence contracts/common.md#principled-implementation A lease carries the successfully acquired generation, binding finalization to that holder even if a recovery path later publishes a successor.
+ * @evidence contracts/common.md#clear-and-simple-design The single generation member separates an acquisition result from diagnostic observations; release consumes that identity under the protocol's namespace and generation premises.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Release uses the acquired identity rather than clearing a shared path or assuming the current holder is still the caller.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states producer, consumer and conditional late-finalizer safety, distinguishing the structural value from ownership authentication; the member explains its 128-bit representation without a property acknowledgment.
+ * @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.
+ * @evidence contracts/portability.md#os-neutral-implementation The lease carries a lowercase hexadecimal generation, not a native path or process-liveness representation. Native release resolves it within the cooperative lock namespace; this value is neither a filesystem handle nor an authenticated process identity.
+ */
+export type DependencyBuildLockLease = {
+    /** The 128-bit hex id of the generation this process holds. */
+    generation: string;
+};

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

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

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

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

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

@@ -0,0 +1,41 @@
+import type { DependencyBuildLockFence } from "./DependencyBuildLockFence";
+/**
+ * One observation of a dependency build lock's state.
+ *
+ * Active and abandoned states carry a generation fence; only abandoned gives
+ * grounds for recovery under the inspector's policy: a proven-gone local owner
+ * or a sufficiently old generation whose owner record was unreadable or
+ * invalid. The latter is not proof of process death. Released means no held
+ * generation was observed, not that the observer acquired the lock; sequential
+ * native reads do not constitute an atomic ownership snapshot.
+ *
+ * @evidence contracts/common.md#principled-implementation A discriminated union separates active or uncertain ownership, policy-selected recovery grounds and released absence; observed fences do not imply acquisition or an atomic ownership snapshot.
+ * @evidence contracts/common.md#clear-and-simple-design Each state carries its own diagnostic information, avoiding optional owner and reason fields with ambiguous combinations.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The representation preserves observation uncertainty and does not turn absence or a timeout label into a successful lease.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain the fence, both recovery grounds, sequential-read uncertainty and the released-versus-acquired distinction without certifying owner liveness.
+ * @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.
+ * @evidence contracts/portability.md#os-neutral-implementation State labels represent the inspector's conservative native ownership policy; owner and reason are diagnostic text, not cross-platform pid authority. The hexadecimal or unreadable fence remains separate from native paths and liveness probes, and no member pins a filesystem namespace.
+ */
+export type DependencyBuildLockObservation = {
+    /** Held or uncertain ownership that must not be reclaimed yet. */
+    state: "active";
+    /** Human-readable holder or uncertainty description for wait diagnostics. */
+    owner: string;
+    /** Observed generation; unreadable identity uses the empty sentinel. */
+    fence: DependencyBuildLockFence;
+} | {
+    /** Recoverable generation, still subject to its retirement fence. */
+    state: "abandoned";
+    /**
+     * Policy-selected recovery reason; stale unreadable records do not prove
+     * process death.
+     */
+    reason: string;
+    /** Exact historical generation recovery may attempt to retire. */
+    fence: DependencyBuildLockFence;
+} | {
+    /** No held generation was observed; acquisition is still a separate step. */
+    state: "released";
+};

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

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

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

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