ttsc 0.30.4 → 0.31.1

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"PluginDescriptorInputObservation.js","sourceRoot":"","sources":["../../../../src/launcher/internal/runtime/PluginDescriptorInputObservation.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,IAAiB,gCAAgC,CAyFhD;AAzFD,WAAiB,gCAAgC;IAC/C;;;;;;;;;;;;;;;;;OAiBG;IACH,SAAgB,KAAK,CAAC,sBAAsB,GAAY,KAAK;QAC3D,IAAI,SAAS;YAAE,OAAO;QACtB,SAAS,GAAG,IAAI,CAAC;QACjB,QAAQ,GAAG,IAAI,CAAC;QAChB,sBAAsB,GAAG,sBAAsB,CAAC;IAClD,CAAC;IALe,iCAAA,KAAK,QAKpB,CAAA;IAED;;;;;;;;;;;;;OAaG;IACH,SAAgB,MAAM,CAAC,OAA0B;QAC/C,KAAK,MAAM,MAAM,IAAI,OAAO;YAAE,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACnD,CAAC;IAFe,iCAAA,MAAM,SAErB,CAAA;IAED;;;;;;;;;;;;;OAaG;IACH,SAAgB,UAAU;QACxB,QAAQ,GAAG,KAAK,CAAC;IACnB,CAAC;IAFe,iCAAA,UAAU,aAEzB,CAAA;IAED;;;;;;;;;;;;;;;OAeG;IACH,SAAgB,QAAQ;QAKtB,OAAO;YACL,QAAQ,EAAE,SAAS,IAAI,QAAQ;YAC/B,KAAK,EAAE,CAAC,GAAG,KAAK,CAAC;YACjB,sBAAsB,EAAE,SAAS,IAAI,sBAAsB;SAC5D,CAAC;IACJ,CAAC;IAVe,iCAAA,QAAQ,WAUvB,CAAA;AACH,CAAC,EAzFgB,gCAAgC,aAAhC,gCAAgC,GAAhC,gCAAgC,QAyFhD;AAED,IAAI,SAAS,GAAG,KAAK,CAAC;AACtB,IAAI,QAAQ,GAAG,KAAK,CAAC;AACrB,IAAI,sBAAsB,GAAG,KAAK,CAAC;AACnC,MAAM,KAAK,GAAa,EAAE,CAAC"}

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

@@ -0,0 +1,168 @@
+/**
+ * A directory the processes that use it own while they run, identified by one
+ * owner record per process inside it, so the directory of a run whose processes
+ * were all killed before any could remove it can be told apart from one still
+ * in use and reclaimed by another process.
+ *
+ * Records and liveness probes are observations, not process-incarnation or host
+ * authentication. Shared-cache participants must use distinct labels under the
+ * hostname comparison and preserve the selected namespace while callers
+ * coordinate admission/removal. A realpath spelling alone holds no directory
+ * handle against replacement.
+ *
+ * @evidence contracts/common.md#principled-implementation Per-host-pid records distinguish a directory with any live or uncertain owner from one whose every validated owner is provably gone; reclaiming requires evidence rather than merely old age.
+ * @evidence contracts/common.md#clear-and-simple-design One namespace owns claim, admission, relinquishment and sweeping over the same record grammar, while native process liveness remains in its dedicated predicate.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Unknown, unowned and remote-owner directories are preserved rather than deleted to satisfy a cleanup expectation; generation and runtime locks remain callers' synchronization responsibilities.
+ * @evidence contracts/common.md#meaningful-documentation Native purpose and operation comments explain ownership transitions, uncertainty, legacy records and pinned-parent sweeping; documented properties remain free of acknowledgment tags.
+ * @evidence contracts/portability.md#os-neutral-implementation Node fs/path and local-host process probes preserve native identity; sweep resolves linked parents before selecting recursive-removal paths and treats links as links.
+ *
+ * @evidenceExclude contracts/performance.md#efficient-algorithms The namespace groups lifecycle operations; each concrete operation explains its own record and directory processing cost.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Ownership effects and observations do not form a reusable result cache at this grouping boundary.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The namespace retains no owner registry in memory; individual operations define persisted-record and directory lifetime.
+ */
+export declare namespace ProcessOwnedDirectory {
+    /**
+     * One already-performed owner observation. A present numeric PID does not
+     * authenticate the original process incarnation; unknown and remote outcomes
+     * remain conservative non-absence evidence.
+     *
+     * @evidence contracts/common.md#principled-implementation Fixed record, validated owner and native-observation fields preserve the reason for a decision without turning a diagnostic into ownership authority.
+     * @evidence contracts/common.md#clear-and-simple-design A single record describes either invalid owner evidence or the existing host/process probe result.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Numeric presence is not called original-process liveness, and unknown or remote outcomes are not absence.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states incarnation uncertainty and distinguishes diagnostic provenance from policy authority.
+     * @evidence contracts/portability.md#os-neutral-implementation Owner coordinates and native errno text retain their actual host/pid boundary without a platform-specific lookup.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms This data representation selects no observation algorithm.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work A record does not cache or share process observations.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The diagnostic carries values only; callers own its sink and lifetime.
+     */
+    interface Observation {
+        /** Basename of the record actually read in the existing scan. */
+        record: string;
+        /** Validated host/pid values, absent for malformed or unreadable records. */
+        owner?: {
+            hostname: string;
+            pid: number;
+        };
+        /** Result of the existing decoding, hostname comparison or native probe. */
+        result: "invalid-record" | "remote" | "present" | "absent" | "unknown";
+        /** Native code already caught by the operation, if it supplied one. */
+        errorCode?: string;
+    }
+    /**
+     * How an owned directory relates to its owners. Only abandoned permits
+     * reclamation; unknown and unowned preserve the entry. `live` includes a
+     * recognized record whose process is not proven gone (including remote-host
+     * labels or unavailable native probes), rather than certifying execution.
+     *
+     * @evidence contracts/common.md#principled-implementation Four states separate all-proven-gone recognized records from a record not proven gone, unreadable evidence and absent records; live is conservative non-death classification, while absence cannot authorize reclamation during admission.
+     * @evidence contracts/common.md#clear-and-simple-design A literal union carries the cleanup decision without optional diagnostic fields or a second boolean that could contradict it.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Unknown or absent evidence remains distinct from deletion authority instead of being collapsed into a false live flag.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states which state allows reclamation and why unknown/unowned preserve an entry.
+     * @evidence contracts/portability.md#os-neutral-implementation States summarize native directory and local process observations without exposing platform-specific errno as ownership values.
+     *
+     * @evidenceExclude contracts/performance.md#efficient-algorithms This literal representation selects no processing algorithm.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work The state type does not coordinate requests or validate cached ownership.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources This value type acquires no owner record, directory or process.
+     */
+    type Ownership = "abandoned" | "live" | "unknown" | "unowned";
+    /**
+     * Create `directory` and record this process as its owner.
+     *
+     * @param directory The directory this process now owns.
+     * @evidence contracts/common.md#principled-implementation Recursive directory creation precedes a host-pid admission record, making a prepared run explicitly attributable to this process before other synchronized callers classify it.
+     * @evidence contracts/common.md#clear-and-simple-design Claim reuses admission's record writer instead of maintaining a second owner format.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The current pid and actual hostname establish the claim; no assumed liveness based on a directory name substitutes for its record.
+     * @evidence contracts/common.md#meaningful-documentation Native purpose and parameter identify the ownership transition; admission separately documents the persisted claim semantics.
+     * @evidence contracts/portability.md#os-neutral-implementation Node's native mkdir and fs record write use the supplied directory spelling; callers pin cleanup authority and serialize shared roots through their runtime lock.
+     * @evidence contracts/performance.md#efficient-algorithms Native creation follows path text/missing parent depth and admission constructs host/pid JSON plus its path; record count is one but text/native IO cost is not constant. No sibling runs are scanned.
+     *
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work A claim changes filesystem ownership; a prior claim result cannot replace recording the current process.
+     *
+     * @evidence contracts/performance.md#bound-retention-and-release-resources The caller owns the created directory and persisted record; a failed admission can leave a created unowned directory, which the acquiring owner must roll back when it has exclusive authority.
+     */
+    function claim(directory: string): void;
+    /**
+     * Record the process `pid` of this host as an owner of `directory`, as one
+     * that uses it and may outlive the process that claimed it, such as a program
+     * that process spawned. Each pid has its own record name; repeated admission
+     * refreshes that pid's claim. An unreadable or malformed owner record leaves
+     * the directory's ownership unknown, so cleanup cannot take it as abandoned.
+     *
+     * @param directory A directory this process claimed.
+     * @param pid The process that owns it too.
+     * @evidence contracts/common.md#principled-implementation A pid-named record stores this host and the admitted pid, allowing later validation to compare filename identity with its contents and conservatively probe the same native owner.
+     * @evidence contracts/common.md#clear-and-simple-design One writer owns the record grammar shared by initial claim and child admission; callers retain synchronization and process-transfer policy.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Actual host and pid values record supported ownership transfer without special-casing a launcher or expected cleanup result.
+     * @evidence contracts/common.md#meaningful-documentation Native prose explains child ownership, repeated admission and malformed-record conservatism; parameters distinguish directory and admitted process.
+     * @evidence contracts/portability.md#os-neutral-implementation os.hostname and Node fs establish native host-scoped process identity; record basenames use a numeric pid and path.join rather than platform-specific process-file conventions.
+     * @evidence contracts/performance.md#efficient-algorithms Admission obtains the native hostname, constructs the pid pathname and serializes/writes one record. Processing/storage follow supplied directory and host/pid text rather than a fixed byte bound, without listing other owners.
+     *
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Writing or refreshing ownership is an effect, not a previously computed result that another call can share.
+     *
+     * @evidence contracts/performance.md#bound-retention-and-release-resources Records can remain after their process exits until relinquishment or an admitted sweep. Distinct pid/run populations have no historical quota; unowned/unknown/live classification and native deletion failures can retain directories indefinitely. Repeated admission overwrites one pid record, not an independent process-incarnation lease.
+     */
+    function admit(directory: string, pid: number): void;
+    /**
+     * Relinquish the specified pid's claim while holding the runtime directory
+     * lock. Other owners and the directory itself remain untouched.
+     *
+     * @evidence contracts/common.md#principled-implementation Removing only the selected pid record ends that ownership claim without erasing another live process's authority over the same run.
+     * @evidence contracts/common.md#clear-and-simple-design One explicit record removal separates relinquishment from whole-directory cleanup.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Release does not recursively clear a shared directory or infer that other owners died with the caller.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states the required lock, selected-pid behavior and preservation of other owners.
+     * @evidence contracts/portability.md#os-neutral-implementation Native fs removal targets the numeric pid record through path.join; force handles an already absent record without relying on shell deletion behavior.
+     * @evidence contracts/performance.md#efficient-algorithms One pid-record path is constructed/removed without an owner-directory scan; supplied directory/pid text and native filesystem work still contribute cost.
+     *
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Relinquishment is an ownership effect that cannot share a previous result as a current release.
+     *
+     * @evidence contracts/performance.md#bound-retention-and-release-resources The operation removes one persisted claim; remaining claims and the run directory stay with their other owners and later reclamation policy.
+     */
+    function relinquish(directory: string, pid?: number): void;
+    /**
+     * Whether any recognized owner is not proven gone, all are proven gone, or
+     * none is recorded at all. An unreadable directory or owner record has
+     * unknown ownership. An owner on another host, or a pid something else now
+     * holds, counts as alive, since neither is provably gone
+     * (`isLocalProcessGone`). A recognized non-gone record takes precedence over
+     * malformed evidence; otherwise malformed records yield unknown before an
+     * all-gone or unowned result. These are sequential record/probe observations
+     * under the namespace and coordination premises stated by the namespace.
+     *
+     * @param legacyProcessRoot Also read the former `owner.json` record in a
+     *   manifest-less `process-<pid>-<nonce>` dependency cache directory.
+     * @evidence contracts/common.md#principled-implementation Validated pid-named records must all prove local absence for abandonment; any live/remote/recycled owner wins, malformed evidence stays unknown, and absent records remain unowned.
+     * @evidence contracts/common.md#clear-and-simple-design One scan aggregates live, uncertain and dead evidence, with record syntax and process liveness delegated to private decoding and the shared predicate.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Directory names alone do not establish ownership; the explicitly supported legacy owner record is checked against its pid-bearing directory grammar.
+     * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain unreadable, remote and recycled ownership, plus the optional legacy format rather than suggesting every nonlive-looking entry can be removed.
+     * @evidence contracts/portability.md#os-neutral-implementation Native directory/record reads and local-host pid probing preserve Windows and POSIX behavior; denied reads remain unknown rather than being classified from error-message text.
+     * @evidence contracts/performance.md#efficient-algorithms One listing examines E names and at most R owner records with early non-gone exit. Listing/path text, record-byte read/JSON parsing and native hostname/pid probes contribute cost; names and the current parsed record occupy their actual bytes rather than fixed E/R-only storage.
+     *
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Owner records and process existence can change; the caller's lock bounds a current decision, not a cached historical result.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The observation opens no retained descriptor and does not acquire or release the directory; its state transfers the decision to cleanup.
+     */
+    function ownership(directory: string, legacyProcessRoot?: boolean, observe?: (observation: Observation) => void): Ownership;
+    /**
+     * Remove the entries of `parent` whose owners are all provably gone. An entry
+     * without an owner record is left alone: its process may have created it and
+     * not yet recorded itself. Removal takes a link inside an entry as a link,
+     * never what it points at, and a failure leaves the entry to a later sweep.
+     * There is no retry scheduler or historical quota here. The physical parent
+     * spelling is observed before listing, without holding a directory handle;
+     * replacement of that physical namespace remains outside this protection.
+     *
+     * @param parent The directory holding owned entries.
+     * @param accepts Which entry names are owned directories.
+     * @param legacyProcessRoot Include the prior manifest-less owner format.
+     * @evidence contracts/common.md#principled-implementation A pinned physical parent and all-proven-dead ownership select only abandoned entries; missing, malformed and live claims are preserved, preventing alias retargeting from choosing another same-named removal target.
+     * @evidence contracts/common.md#clear-and-simple-design The sweep separates one parent snapshot, caller-defined entry selection and shared ownership classification before best-effort removal.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Failed inspection or deletion does not trigger broader cleanup; the operation never treats a caller's accepted name as proof that its owner is dead.
+     * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain unowned preservation, link treatment and later retry, with parameters identifying selection and legacy support.
+     * @evidence contracts/portability.md#os-neutral-implementation realpathSync.native selects the observed parent spelling before listing/joins, not a namespace-locking handle. Node recursive rm treats links as links, while caller coordination and namespace preservation remain necessary.
+     * @evidence contracts/performance.md#efficient-algorithms One sibling listing, each caller predicate and accepted entry's ownership scan pay name/path/record bytes, JSON/native probes and predicate work. Recursive deletion adds reclaimed entry populations and native IO; callback cost/effects and concurrent namespace changes are not bounded by the single listing.
+     *
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Abandonment and removal are current filesystem effects; a prior sweep cannot stand in for changed records or a newly dead process.
+     *
+     * @evidence contracts/performance.md#bound-retention-and-release-resources The sweep attempts abandoned-tree reclamation without broadening the selected parent. Unreadable/unowned/non-gone entries and native removal failures can persist indefinitely; only a later caller invocation retries, with no historical quota or scheduled deadline. Predicate throws and parent inspection failures can leave later entries unprocessed.
+     */
+    function sweep(parent: string, accepts?: (name: string) => boolean, legacyProcessRoot?: boolean): void;
+}

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

@@ -0,0 +1,251 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProcessOwnedDirectory = void 0;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const isLocalProcessGone_1 = require("./isLocalProcessGone");
+/**
+ * A directory the processes that use it own while they run, identified by one
+ * owner record per process inside it, so the directory of a run whose processes
+ * were all killed before any could remove it can be told apart from one still
+ * in use and reclaimed by another process.
+ *
+ * Records and liveness probes are observations, not process-incarnation or host
+ * authentication. Shared-cache participants must use distinct labels under the
+ * hostname comparison and preserve the selected namespace while callers
+ * coordinate admission/removal. A realpath spelling alone holds no directory
+ * handle against replacement.
+ *
+ * @evidence contracts/common.md#principled-implementation Per-host-pid records distinguish a directory with any live or uncertain owner from one whose every validated owner is provably gone; reclaiming requires evidence rather than merely old age.
+ * @evidence contracts/common.md#clear-and-simple-design One namespace owns claim, admission, relinquishment and sweeping over the same record grammar, while native process liveness remains in its dedicated predicate.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Unknown, unowned and remote-owner directories are preserved rather than deleted to satisfy a cleanup expectation; generation and runtime locks remain callers' synchronization responsibilities.
+ * @evidence contracts/common.md#meaningful-documentation Native purpose and operation comments explain ownership transitions, uncertainty, legacy records and pinned-parent sweeping; documented properties remain free of acknowledgment tags.
+ * @evidence contracts/portability.md#os-neutral-implementation Node fs/path and local-host process probes preserve native identity; sweep resolves linked parents before selecting recursive-removal paths and treats links as links.
+ *
+ * @evidenceExclude contracts/performance.md#efficient-algorithms The namespace groups lifecycle operations; each concrete operation explains its own record and directory processing cost.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Ownership effects and observations do not form a reusable result cache at this grouping boundary.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The namespace retains no owner registry in memory; individual operations define persisted-record and directory lifetime.
+ */
+var ProcessOwnedDirectory;
+(function (ProcessOwnedDirectory) {
+    /**
+     * Create `directory` and record this process as its owner.
+     *
+     * @param directory The directory this process now owns.
+     * @evidence contracts/common.md#principled-implementation Recursive directory creation precedes a host-pid admission record, making a prepared run explicitly attributable to this process before other synchronized callers classify it.
+     * @evidence contracts/common.md#clear-and-simple-design Claim reuses admission's record writer instead of maintaining a second owner format.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The current pid and actual hostname establish the claim; no assumed liveness based on a directory name substitutes for its record.
+     * @evidence contracts/common.md#meaningful-documentation Native purpose and parameter identify the ownership transition; admission separately documents the persisted claim semantics.
+     * @evidence contracts/portability.md#os-neutral-implementation Node's native mkdir and fs record write use the supplied directory spelling; callers pin cleanup authority and serialize shared roots through their runtime lock.
+     * @evidence contracts/performance.md#efficient-algorithms Native creation follows path text/missing parent depth and admission constructs host/pid JSON plus its path; record count is one but text/native IO cost is not constant. No sibling runs are scanned.
+     *
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work A claim changes filesystem ownership; a prior claim result cannot replace recording the current process.
+     *
+     * @evidence contracts/performance.md#bound-retention-and-release-resources The caller owns the created directory and persisted record; a failed admission can leave a created unowned directory, which the acquiring owner must roll back when it has exclusive authority.
+     */
+    function claim(directory) {
+        node_fs_1.default.mkdirSync(directory, { recursive: true });
+        admit(directory, process.pid);
+    }
+    ProcessOwnedDirectory.claim = claim;
+    /**
+     * Record the process `pid` of this host as an owner of `directory`, as one
+     * that uses it and may outlive the process that claimed it, such as a program
+     * that process spawned. Each pid has its own record name; repeated admission
+     * refreshes that pid's claim. An unreadable or malformed owner record leaves
+     * the directory's ownership unknown, so cleanup cannot take it as abandoned.
+     *
+     * @param directory A directory this process claimed.
+     * @param pid The process that owns it too.
+     * @evidence contracts/common.md#principled-implementation A pid-named record stores this host and the admitted pid, allowing later validation to compare filename identity with its contents and conservatively probe the same native owner.
+     * @evidence contracts/common.md#clear-and-simple-design One writer owns the record grammar shared by initial claim and child admission; callers retain synchronization and process-transfer policy.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Actual host and pid values record supported ownership transfer without special-casing a launcher or expected cleanup result.
+     * @evidence contracts/common.md#meaningful-documentation Native prose explains child ownership, repeated admission and malformed-record conservatism; parameters distinguish directory and admitted process.
+     * @evidence contracts/portability.md#os-neutral-implementation os.hostname and Node fs establish native host-scoped process identity; record basenames use a numeric pid and path.join rather than platform-specific process-file conventions.
+     * @evidence contracts/performance.md#efficient-algorithms Admission obtains the native hostname, constructs the pid pathname and serializes/writes one record. Processing/storage follow supplied directory and host/pid text rather than a fixed byte bound, without listing other owners.
+     *
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Writing or refreshing ownership is an effect, not a previously computed result that another call can share.
+     *
+     * @evidence contracts/performance.md#bound-retention-and-release-resources Records can remain after their process exits until relinquishment or an admitted sweep. Distinct pid/run populations have no historical quota; unowned/unknown/live classification and native deletion failures can retain directories indefinitely. Repeated admission overwrites one pid record, not an independent process-incarnation lease.
+     */
+    function admit(directory, pid) {
+        node_fs_1.default.writeFileSync(recordPath(directory, pid), JSON.stringify({ hostname: node_os_1.default.hostname(), pid }), "utf8");
+    }
+    ProcessOwnedDirectory.admit = admit;
+    /**
+     * Relinquish the specified pid's claim while holding the runtime directory
+     * lock. Other owners and the directory itself remain untouched.
+     *
+     * @evidence contracts/common.md#principled-implementation Removing only the selected pid record ends that ownership claim without erasing another live process's authority over the same run.
+     * @evidence contracts/common.md#clear-and-simple-design One explicit record removal separates relinquishment from whole-directory cleanup.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Release does not recursively clear a shared directory or infer that other owners died with the caller.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states the required lock, selected-pid behavior and preservation of other owners.
+     * @evidence contracts/portability.md#os-neutral-implementation Native fs removal targets the numeric pid record through path.join; force handles an already absent record without relying on shell deletion behavior.
+     * @evidence contracts/performance.md#efficient-algorithms One pid-record path is constructed/removed without an owner-directory scan; supplied directory/pid text and native filesystem work still contribute cost.
+     *
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Relinquishment is an ownership effect that cannot share a previous result as a current release.
+     *
+     * @evidence contracts/performance.md#bound-retention-and-release-resources The operation removes one persisted claim; remaining claims and the run directory stay with their other owners and later reclamation policy.
+     */
+    function relinquish(directory, pid = process.pid) {
+        node_fs_1.default.rmSync(recordPath(directory, pid), { force: true });
+    }
+    ProcessOwnedDirectory.relinquish = relinquish;
+    /**
+     * Whether any recognized owner is not proven gone, all are proven gone, or
+     * none is recorded at all. An unreadable directory or owner record has
+     * unknown ownership. An owner on another host, or a pid something else now
+     * holds, counts as alive, since neither is provably gone
+     * (`isLocalProcessGone`). A recognized non-gone record takes precedence over
+     * malformed evidence; otherwise malformed records yield unknown before an
+     * all-gone or unowned result. These are sequential record/probe observations
+     * under the namespace and coordination premises stated by the namespace.
+     *
+     * @param legacyProcessRoot Also read the former `owner.json` record in a
+     *   manifest-less `process-<pid>-<nonce>` dependency cache directory.
+     * @evidence contracts/common.md#principled-implementation Validated pid-named records must all prove local absence for abandonment; any live/remote/recycled owner wins, malformed evidence stays unknown, and absent records remain unowned.
+     * @evidence contracts/common.md#clear-and-simple-design One scan aggregates live, uncertain and dead evidence, with record syntax and process liveness delegated to private decoding and the shared predicate.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Directory names alone do not establish ownership; the explicitly supported legacy owner record is checked against its pid-bearing directory grammar.
+     * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain unreadable, remote and recycled ownership, plus the optional legacy format rather than suggesting every nonlive-looking entry can be removed.
+     * @evidence contracts/portability.md#os-neutral-implementation Native directory/record reads and local-host pid probing preserve Windows and POSIX behavior; denied reads remain unknown rather than being classified from error-message text.
+     * @evidence contracts/performance.md#efficient-algorithms One listing examines E names and at most R owner records with early non-gone exit. Listing/path text, record-byte read/JSON parsing and native hostname/pid probes contribute cost; names and the current parsed record occupy their actual bytes rather than fixed E/R-only storage.
+     *
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Owner records and process existence can change; the caller's lock bounds a current decision, not a cached historical result.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The observation opens no retained descriptor and does not acquire or release the directory; its state transfers the decision to cleanup.
+     */
+    function ownership(directory, legacyProcessRoot = false, observe) {
+        let names;
+        try {
+            names = node_fs_1.default.readdirSync(directory);
+        }
+        catch (error) {
+            const code = error.code;
+            return code === "ENOENT" || code === "ENOTDIR" ? "unowned" : "unknown";
+        }
+        let owned = false;
+        let unknown = false;
+        for (const name of names) {
+            if ((!name.startsWith(RECORD_PREFIX) || !name.endsWith(RECORD_SUFFIX)) &&
+                !(legacyProcessRoot && name === "owner.json"))
+                continue;
+            const owner = readRecord(node_path_1.default.join(directory, name), observe);
+            if (owner === null) {
+                unknown = true;
+                continue;
+            }
+            if (!(0, isLocalProcessGone_1.isLocalProcessGone)(owner, observe === undefined
+                ? undefined
+                : (result, errorCode) => report(observe, {
+                    record: name,
+                    owner,
+                    result,
+                    ...(errorCode === undefined ? {} : { errorCode }),
+                })))
+                return "live";
+            owned = true;
+        }
+        return unknown ? "unknown" : owned ? "abandoned" : "unowned";
+    }
+    ProcessOwnedDirectory.ownership = ownership;
+    /**
+     * Remove the entries of `parent` whose owners are all provably gone. An entry
+     * without an owner record is left alone: its process may have created it and
+     * not yet recorded itself. Removal takes a link inside an entry as a link,
+     * never what it points at, and a failure leaves the entry to a later sweep.
+     * There is no retry scheduler or historical quota here. The physical parent
+     * spelling is observed before listing, without holding a directory handle;
+     * replacement of that physical namespace remains outside this protection.
+     *
+     * @param parent The directory holding owned entries.
+     * @param accepts Which entry names are owned directories.
+     * @param legacyProcessRoot Include the prior manifest-less owner format.
+     * @evidence contracts/common.md#principled-implementation A pinned physical parent and all-proven-dead ownership select only abandoned entries; missing, malformed and live claims are preserved, preventing alias retargeting from choosing another same-named removal target.
+     * @evidence contracts/common.md#clear-and-simple-design The sweep separates one parent snapshot, caller-defined entry selection and shared ownership classification before best-effort removal.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Failed inspection or deletion does not trigger broader cleanup; the operation never treats a caller's accepted name as proof that its owner is dead.
+     * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain unowned preservation, link treatment and later retry, with parameters identifying selection and legacy support.
+     * @evidence contracts/portability.md#os-neutral-implementation realpathSync.native selects the observed parent spelling before listing/joins, not a namespace-locking handle. Node recursive rm treats links as links, while caller coordination and namespace preservation remain necessary.
+     * @evidence contracts/performance.md#efficient-algorithms One sibling listing, each caller predicate and accepted entry's ownership scan pay name/path/record bytes, JSON/native probes and predicate work. Recursive deletion adds reclaimed entry populations and native IO; callback cost/effects and concurrent namespace changes are not bounded by the single listing.
+     *
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Abandonment and removal are current filesystem effects; a prior sweep cannot stand in for changed records or a newly dead process.
+     *
+     * @evidence contracts/performance.md#bound-retention-and-release-resources The sweep attempts abandoned-tree reclamation without broadening the selected parent. Unreadable/unowned/non-gone entries and native removal failures can persist indefinitely; only a later caller invocation retries, with no historical quota or scheduled deadline. Predicate throws and parent inspection failures can leave later entries unprocessed.
+     */
+    function sweep(parent, accepts = () => true, legacyProcessRoot = false) {
+        let entries;
+        let physicalParent;
+        try {
+            // Pin a linked parent before reading any owner. A retarget between the
+            // listing and rmSync must not select a different same-named entry.
+            physicalParent = node_fs_1.default.realpathSync.native(parent);
+            entries = node_fs_1.default.readdirSync(physicalParent);
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (!accepts(entry))
+                continue;
+            const directory = node_path_1.default.join(physicalParent, entry);
+            if (ownership(directory, legacyProcessRoot) !== "abandoned")
+                continue;
+            try {
+                node_fs_1.default.rmSync(directory, { force: true, recursive: true });
+            }
+            catch {
+                // Held open or concurrently removed: a later sweep retries.
+            }
+        }
+    }
+    ProcessOwnedDirectory.sweep = sweep;
+    const RECORD_PREFIX = "owner-";
+    const RECORD_SUFFIX = ".json";
+    function recordPath(directory, pid) {
+        return node_path_1.default.join(directory, `${RECORD_PREFIX}${pid}${RECORD_SUFFIX}`);
+    }
+    function readRecord(file, observe) {
+        try {
+            const owner = JSON.parse(node_fs_1.default.readFileSync(file, "utf8"));
+            const name = node_path_1.default.basename(file);
+            const pidText = name === "owner.json"
+                ? /^process-(\d+)-[0-9a-f]+$/.exec(node_path_1.default.basename(node_path_1.default.dirname(file)))?.[1]
+                : name.slice(RECORD_PREFIX.length, name.length - RECORD_SUFFIX.length);
+            const namedPid = pidText !== undefined && /^\d+$/.test(pidText)
+                ? Number(pidText)
+                : undefined;
+            if (typeof owner.hostname !== "string" ||
+                owner.hostname.length === 0 ||
+                typeof owner.pid !== "number" ||
+                !Number.isSafeInteger(owner.pid) ||
+                owner.pid <= 0 ||
+                namedPid === undefined ||
+                owner.pid !== namedPid) {
+                report(observe, { record: name, result: "invalid-record" });
+                return null;
+            }
+            return { hostname: owner.hostname, pid: owner.pid };
+        }
+        catch (error) {
+            const code = error?.code;
+            report(observe, {
+                record: node_path_1.default.basename(file),
+                result: "invalid-record",
+                ...(typeof code === "string" ? { errorCode: code } : {}),
+            });
+            return null;
+        }
+    }
+    /** Diagnostics preserve observed values but cannot change classification. */
+    function report(observe, observation) {
+        try {
+            observe?.(observation);
+        }
+        catch {
+            // Diagnostics own no policy.
+        }
+    }
+})(ProcessOwnedDirectory || (exports.ProcessOwnedDirectory = ProcessOwnedDirectory = {}));
+//# sourceMappingURL=ProcessOwnedDirectory.js.map

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

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

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

@@ -0,0 +1,24 @@
+/**
+ * What a `module.registerHooks` resolve hook returns, as ttsx's hooks use it.
+ *
+ * This local structural view names the result fields consumed by ttsx; it is a
+ * subset of Node's current ResolveFnOutput rather than a claim that Node has no
+ * synchronous hook typings.
+ *
+ * @evidence contracts/common.md#principled-implementation URL, nullable format hint and optional shortCircuit represent the synchronous resolver's supported result distinctions without treating absent format as a guessed loader kind.
+ * @evidence contracts/common.md#clear-and-simple-design One local structural interface names the consumed URL, format and chain-control fields; Node's ResolveFnOutput also carries import attributes that this view does not describe or remove.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts This declaration represents the public hook boundary rather than exposing or replacing Node loader internals.
+ * @evidence contracts/common.md#meaningful-documentation Native purpose and typing rationale accompany separate member comments for URL representation, format deferral and chain termination.
+ * @evidence contracts/portability.md#os-neutral-implementation The result uses module URL spelling rather than native path syntax; file URL conversion is owned by hook producers so drive letters and separators are not guessed here.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources A type declaration acquires and holds no runtime resource.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms A type declaration chooses no processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A type declaration computes nothing, so there is no work to share.
+ */
+export interface ResolveResult {
+    /** The resolved module's URL/protocol spelling, not a native filename. */
+    url: string;
+    /** Format hint for the load hook; `null` or absent lets the load decide. */
+    format?: string | null;
+    /** When true, end the hook chain here instead of calling the next resolver. */
+    shortCircuit?: boolean;
+}

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

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

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

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