ttsc 0.30.4 → 0.31.0

package/src/launcher/internal/runtime/DependencyBuildGeneration.ts

@@ -0,0 +1,236 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+import { resolvePhysicalPath as resolvePhysicalPathIdentity } from "../../../internal/pathIdentity/resolvePhysicalPath";
+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 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.
+   */
+  export 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.
+   */
+  export 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.
+   */
+  export function dependencyGenerationDir(
+    cacheDir: string,
+    generation: string,
+  ): string {
+    return path.join(cacheDir, `gen-${generation}`);
+  }
+
+  /**
+   * 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.
+   */
+  export function newDependencyGeneration(): string {
+    return crypto.randomBytes(16).toString("hex");
+  }
+
+  /**
+   * 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.
+   */
+  export function isDependencyGeneration(value: unknown): value is string {
+    return typeof value === "string" && /^[0-9a-f]{32}$/.test(value);
+  }
+
+  /**
+   * 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.
+   */
+  export function resolvePhysicalPath(location: string): string {
+    return resolvePhysicalPathIdentity(location);
+  }
+
+  /**
+   * 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.
+   */
+  export function emittedAnything(directory: string): boolean {
+    let entries: fs.Dirent[];
+    try {
+      entries = fs.readdirSync(directory, { withFileTypes: true });
+    } catch {
+      return false;
+    }
+    for (const entry of entries) {
+      const full = path.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;
+  }
+}

package/src/launcher/internal/runtime/DependencyBuildLockFence.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/src/launcher/internal/runtime/DependencyBuildLockLease.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/src/launcher/internal/runtime/DependencyBuildLockObservation.ts

@@ -0,0 +1,49 @@
+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/src/launcher/internal/runtime/DependencyBuildLockProtocol.ts

@@ -0,0 +1,137 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { retireLockDirectory } from "../../../internal/retireLockDirectory";
+import { DependencyBuildGeneration } from "./DependencyBuildGeneration";
+import { RuntimeFilesystem } from "./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.
+ */
+export namespace DependencyBuildLockProtocol {
+  /** Directory name of the held generation inside the lock directory. */
+  export const DEP_BUILD_LOCK_CURRENT_DIR = "current";
+
+  /** Directory holding one tombstone per retired generation. */
+  export const DEP_BUILD_LOCK_RETIRED_DIR = "retired";
+
+  /** File inside a generation directory holding its hex id. */
+  export 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`).
+   */
+  export const DEP_BUILD_LOCK_POLL_MS = 50;
+
+  /**
+   * Elapsed-time policy threshold checked between runtime acquisition attempts;
+   * not a native IO or retirement deadline.
+   */
+  export const DEP_BUILD_LOCK_WAIT_MS = 600_000;
+
+  /** File inside a generation directory recording the holder's pid and host. */
+  export 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.
+   */
+  export function retireDependencyBuildLock(
+    lockDir: string,
+    generation: string,
+  ): boolean {
+    if (!DependencyBuildGeneration.isDependencyGeneration(generation)) {
+      return false;
+    }
+    const retiredDir = path.join(lockDir, DEP_BUILD_LOCK_RETIRED_DIR);
+    try {
+      fs.mkdirSync(retiredDir);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") {
+        if (RuntimeFilesystem.isMissingPathError(error)) {
+          return false;
+        }
+        throw error;
+      }
+    }
+    return retireLockDirectory(
+      path.join(lockDir, DEP_BUILD_LOCK_CURRENT_DIR),
+      path.join(retiredDir, generation),
+      () =>
+        Atomics.wait(
+          new Int32Array(new SharedArrayBuffer(4)),
+          0,
+          0,
+          DEP_BUILD_LOCK_POLL_MS,
+        ),
+    );
+  }
+
+  /**
+   * 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.
+   */
+  export function formatDuration(ms: number): string {
+    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`;
+  }
+}

package/src/launcher/internal/runtime/OwnedProjectSource.ts

@@ -0,0 +1,140 @@
+/**
+ * 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 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.
+   */
+  export 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.
+   */
+  export function serve<Build, Served>(
+    real: string,
+    dependencies: Dependencies<Build, Served>,
+  ): Served | null {
+    const tsconfig = dependencies.owningTsconfig(real);
+    if (tsconfig === null) return null;
+    let built: Build | null;
+    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;
+  }
+}