@ttsc/graph 0.30.4 → 0.31.1

package/lib/model/IPublishedArtifacts.d.ts

@@ -0,0 +1,76 @@
+import { type ITtscCapabilityPluginResolution } from "ttsc";
+import { IArtifactInputs } from "./IArtifactInputs";
+/**
+ * Ask the project's `@ttsc/lint` for the artifacts a citation can name, and
+ * write them where `ttscgraph dump --artifacts` reads them.
+ *
+ * A project that configures no such plugin gets `file: null`, which is the
+ * common case and not an error: the graph it produces is the graph it produced
+ * before this existed, and the dump says so by not claiming the capability.
+ *
+ * ## Why this runs here and not in the compiler host
+ *
+ * The addresses a citation names — a Markdown anchor, `prisma:Sale.price`,
+ * `POST:/orders` — are produced by parsers that live in the rule that owns
+ * them, and re-deriving any of them in the graph producer would be a second
+ * implementation of a published contract. So the units have to arrive from the
+ * rule.
+ *
+ * They cannot arrive in-process. `ttscgraph` is the shipped per-platform
+ * binary, never a per-project native host, so it can never have a linked
+ * plugin; and `packages/lint` is its own Go module that deliberately carries no
+ * requirement on the compiler host. What is left is the channel the host
+ * already has: a plugin declares a capability and its sidecar answers a verb,
+ * exactly as `lsp-hints` does. `resolveCapabilityPluginResolution` builds and
+ * locates those sidecars, and it is the seam `ttscserver` already uses for
+ * `capabilities.lsp`, published so a consumer outside the compiler can ask
+ * too.
+ *
+ * Nothing here knows what `@ttsc/evidence` is. It asks a lint install for
+ * whatever its configured rules published, and a project that configured none
+ * gets an empty answer.
+ *
+ * @evidence contracts/common.md#principled-implementation Publication carries the sidecar's artifact file and the input identity captured before asking for artifacts, so later input changes can invalidate that answer.
+ * @evidence contracts/common.md#clear-and-simple-design The result separates the producer exchange path, input inventory and freshness identity without embedding compiler Program state.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts A null file states an absent publication, not an invented artifact set or a successful compiler capability claim.
+ * @evidence contracts/common.md#meaningful-documentation Native member prose explains publication absence, independent document inputs and the fingerprint's ordering role.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources data shape only: it holds no handle, task or retained state.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms data shape only: it contains no loop or algorithm.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work data shape only: it computes nothing another request could share.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation data shape only: it touches no file, path or process.
+ */
+export interface IPublishedArtifacts {
+    /**
+     * Path to the JSON the native producer reads, or `null` when no configured
+     * plugin publishes one.
+     *
+     * `null` is a state rather than an absence, which is why it still carries
+     * {@link inputs}. A project that adds an evidence plugin while a session is
+     * running would otherwise never be reconsidered: nothing would be watched, so
+     * nothing could report that the answer had changed from "none" to "some".
+     */
+    file: string | null;
+    /**
+     * Everything the answer was derived from, as paths this process can state for
+     * itself.
+     *
+     * The artifacts describe documents the compiler's Program never read, so a
+     * source edit does not move them and a document edit does not move the code
+     * graph. Refreshing them is therefore a second invalidation with its own
+     * inputs, and these are those inputs.
+     */
+    inputs: IArtifactInputs;
+    /**
+     * The state of {@link inputs} when the answer was produced.
+     *
+     * Compared against a freshly taken one to decide whether the answer is stale.
+     * When it moved, nothing else in the session can tell: the compiler's own
+     * invalidation watches the build universe, and none of this is in it.
+     */
+    fingerprint: string;
+    /**
+     * Owning plugin discovery proof, including successful absence. Omitted by
+     * legacy callers, whose publication cannot establish discovery freshness.
+     */
+    discovery?: ITtscCapabilityPluginResolution;
+}

package/lib/model/IPublishedArtifacts.js

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

package/lib/model/IPublishedArtifacts.js.map

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

package/lib/model/IPublishedArtifactsResident.d.ts

@@ -0,0 +1,19 @@
+import type { CapabilityPluginResolver } from "ttsc";
+import type { IPublishedArtifacts } from "./IPublishedArtifacts";
+/**
+ * Publication paired with the exact resolver-owned asynchronous proof. The
+ * session releases this proof on replacement or resolver shutdown.
+ *
+ * @evidence contracts/common.md#principled-implementation The publication inputs remain separate from the exact discovery generation's opaque validity query.
+ * @evidence contracts/common.md#clear-and-simple-design Only discovery ownership differs from the synchronous publication data shape.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The original SDK authority supplies currentness rather than a consumer-reconstructed watch list.
+ * @evidence contracts/common.md#meaningful-documentation Native prose identifies asynchronous proof identity and release ownership.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms This data shape selects no computation strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work The producing and freshness operations decide whether consumers may reuse it.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The holder must release discovery after replacement; resolver close also drops all retained proofs.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation This representation performs no filesystem or process operation.
+ */
+export interface IPublishedArtifactsResident extends Omit<IPublishedArtifacts, "discovery"> {
+    /** Owning asynchronous discovery authority, released by the session. */
+    discovery: CapabilityPluginResolver.Resolution;
+}

package/lib/model/IPublishedArtifactsResident.js

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

package/lib/model/IPublishedArtifactsResident.js.map

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

package/lib/model/ITtscLintDaemonTarget.d.ts

@@ -0,0 +1,20 @@
+/**
+ * One plugin sidecar this daemon can be opened against.
+ *
+ * @evidence contracts/common.md#principled-implementation Binary, plugin manifest and optional project context identify the sidecar executable and configuration inputs for its verbs.
+ * @evidence contracts/common.md#clear-and-simple-design The target groups only launch identity while cwd and tsconfig remain session-owned coordinates.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Plugin configuration is passed through its supported manifest/context flags rather than patched into a running foreign process.
+ * @evidence contracts/common.md#meaningful-documentation Native member comments explain binary identity and the two configuration channels.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources data shape only: it holds no handle, task or retained state.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms data shape only: it contains no loop or algorithm.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work data shape only: it computes nothing another request could share.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation data shape only: it touches no file, path or process.
+ */
+export interface ITtscLintDaemonTarget {
+    /** Native plugin sidecar executable path. */
+    binary: string;
+    /** Serialized plugin manifest consumed by the sidecar. */
+    manifest: string;
+    /** Optional serialized project identity passed to context-aware rules. */
+    projectContext?: string;
+}

package/lib/model/ITtscLintDaemonTarget.js

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

package/lib/model/ITtscLintDaemonTarget.js.map

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

package/lib/model/TtscGraphLinePeer.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Native line transport shared by graph and lint resident owners.
+ *
+ * @evidence contracts/common.md#principled-implementation Node stdout line framing and explicit process events preserve the native protocols while request correlation remains with their state owners.
+ * @evidence contracts/common.md#clear-and-simple-design A connection exposes only liveness, diagnostics, writes and retirement; EOF retirement and authoritative process/stdio joining serve both state owners.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The default adapter invokes the actual binary and argv without a shell, synthetic responses or replaced foreign methods.
+ * @evidence contracts/common.md#meaningful-documentation Connection comments state line/event ownership, bounded diagnostic capture and the difference between reader retirement and process termination.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms open owns process and line setup; the namespace groups its connection protocol.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Resident state owners decide peer reuse; this namespace adds no result cache.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources open and its returned close implementation own actual child/reader acquisition and retirement.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Events, Connection and open document the native representation and operations rather than the namespace grouping them.
+ */
+export declare namespace TtscGraphLinePeer {
+    /**
+     * Events produced by a native child, addressed by its connection owner.
+     *
+     * @evidence contracts/common.md#principled-implementation Complete stdout lines, startup errors and nullable code/signal exit coordinates represent distinct Node process events.
+     * @evidence contracts/common.md#clear-and-simple-design The signature transfers only its stated process operation or event; resident state owns protocol decisions.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Node-native representations remain explicit rather than shell strings, process stand-ins or replaced foreign methods.
+     * @evidence contracts/common.md#meaningful-documentation Native member prose states event, liveness or retirement meaning needed by the state owner.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms This boundary signature defines an operation or event; open and its returned adapter implementations own the work.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work The boundary descriptor computes no reusable graph result; state coordinates continued peer reuse.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The signature acquires no handle itself; open and the returned close implementation own actual lifetime.
+     * @evidence contracts/portability.md#os-neutral-implementation Node numeric exit status, signal names, stdin callbacks and decoded line strings preserve native process semantics without assuming shell quoting or platform path spelling.
+     */
+    interface Events {
+        /**
+         * One complete stdout line.
+         *
+         * @evidence contracts/common.md#principled-implementation The callback receives a complete UTF-8 stdout line without imposing graph syntax or response correlation.
+         * @evidence contracts/common.md#clear-and-simple-design The signature transfers only its stated process operation or event; resident state owns protocol decisions.
+         * @evidence contracts/common.md#prohibited-implementation-shortcuts Node-native representations remain explicit rather than shell strings, process stand-ins or replaced foreign methods.
+         * @evidence contracts/common.md#meaningful-documentation Native member prose states event, liveness or retirement meaning needed by the state owner.
+         * @evidenceExclude contracts/performance.md#efficient-algorithms This boundary signature defines an operation or event; open and its returned adapter implementations own the work.
+         * @evidenceExclude contracts/performance.md#reuse-equivalent-work The boundary descriptor computes no reusable graph result; state coordinates continued peer reuse.
+         * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The signature acquires no handle itself; open and the returned close implementation own actual lifetime.
+         * @evidence contracts/portability.md#os-neutral-implementation Node numeric exit status, signal names, stdin callbacks and decoded line strings preserve native process semantics without assuming shell quoting or platform path spelling.
+         */
+        line(line: string): void;
+        /**
+         * Child startup or transport failure.
+         *
+         * @evidence contracts/common.md#principled-implementation The callback preserves the actual child Error as a failure event rather than a synthetic success frame.
+         * @evidence contracts/common.md#clear-and-simple-design The signature transfers only its stated process operation or event; resident state owns protocol decisions.
+         * @evidence contracts/common.md#prohibited-implementation-shortcuts Node-native representations remain explicit rather than shell strings, process stand-ins or replaced foreign methods.
+         * @evidence contracts/common.md#meaningful-documentation Native member prose states event, liveness or retirement meaning needed by the state owner.
+         * @evidenceExclude contracts/performance.md#efficient-algorithms This boundary signature defines an operation or event; open and its returned adapter implementations own the work.
+         * @evidenceExclude contracts/performance.md#reuse-equivalent-work The boundary descriptor computes no reusable graph result; state coordinates continued peer reuse.
+         * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The signature acquires no handle itself; open and the returned close implementation own actual lifetime.
+         * @evidence contracts/portability.md#os-neutral-implementation Node numeric exit status, signal names, stdin callbacks and decoded line strings preserve native process semantics without assuming shell quoting or platform path spelling.
+         */
+        error(error: Error): void;
+        /**
+         * Actual process exit; a retired reader cannot publish later lines.
+         *
+         * @evidence contracts/common.md#principled-implementation Nullable numeric code and Node signal name preserve whether a native process exited normally or by signal.
+         * @evidence contracts/common.md#clear-and-simple-design The signature transfers only its stated process operation or event; resident state owns protocol decisions.
+         * @evidence contracts/common.md#prohibited-implementation-shortcuts Node-native representations remain explicit rather than shell strings, process stand-ins or replaced foreign methods.
+         * @evidence contracts/common.md#meaningful-documentation Native member prose states event, liveness or retirement meaning needed by the state owner.
+         * @evidenceExclude contracts/performance.md#efficient-algorithms This boundary signature defines an operation or event; open and its returned adapter implementations own the work.
+         * @evidenceExclude contracts/performance.md#reuse-equivalent-work The boundary descriptor computes no reusable graph result; state coordinates continued peer reuse.
+         * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The signature acquires no handle itself; open and the returned close implementation own actual lifetime.
+         * @evidence contracts/portability.md#os-neutral-implementation Node numeric exit status, signal names, stdin callbacks and decoded line strings preserve native process semantics without assuming shell quoting or platform path spelling.
+         */
+        exit(code: number | null, signal: NodeJS.Signals | null): void;
+    }
+    /**
+     * Owned native handle used by resident state machines.
+     *
+     * @evidence contracts/common.md#principled-implementation A connection groups actual process liveness, bounded diagnostics, writes and reader/process retirement under one owned identity.
+     * @evidence contracts/common.md#clear-and-simple-design The signature transfers only its stated process operation or event; resident state owns protocol decisions.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Node-native representations remain explicit rather than shell strings, process stand-ins or replaced foreign methods.
+     * @evidence contracts/common.md#meaningful-documentation Native member prose states event, liveness or retirement meaning needed by the state owner.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms This boundary signature defines an operation or event; open and its returned adapter implementations own the work.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work The boundary descriptor computes no reusable graph result; state coordinates continued peer reuse.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The signature acquires no handle itself; open and the returned close implementation own actual lifetime.
+     * @evidence contracts/portability.md#os-neutral-implementation Node numeric exit status, signal names, stdin callbacks and decoded line strings preserve native process semantics without assuming shell quoting or platform path spelling.
+     */
+    interface Connection {
+        /**
+         * Up to the last 65,536 UTF-16 code units of diagnostics when capture is
+         * selected.
+         */
+        readonly stderr: string;
+        /**
+         * Whether the underlying child still has no exit status.
+         *
+         * @evidence contracts/common.md#principled-implementation Liveness reflects the Node child exitCode/signalCode pair; a sent kill signal alone is not a completed exit.
+         * @evidence contracts/common.md#clear-and-simple-design The signature transfers only its stated process operation or event; resident state owns protocol decisions.
+         * @evidence contracts/common.md#prohibited-implementation-shortcuts Node-native representations remain explicit rather than shell strings, process stand-ins or replaced foreign methods.
+         * @evidence contracts/common.md#meaningful-documentation Native member prose states event, liveness or retirement meaning needed by the state owner.
+         * @evidenceExclude contracts/performance.md#efficient-algorithms This boundary signature defines an operation or event; open and its returned adapter implementations own the work.
+         * @evidenceExclude contracts/performance.md#reuse-equivalent-work The boundary descriptor computes no reusable graph result; state coordinates continued peer reuse.
+         * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The signature acquires no handle itself; open and the returned close implementation own actual lifetime.
+         * @evidence contracts/portability.md#os-neutral-implementation Node numeric exit status, signal names, stdin callbacks and decoded line strings preserve native process semantics without assuming shell quoting or platform path spelling.
+         */
+        alive(): boolean;
+        /**
+         * Write one complete request; errors belong to the request owner.
+         *
+         * @evidence contracts/common.md#principled-implementation The actual stdin callback transfers write failure to its request owner without manufacturing a response.
+         * @evidence contracts/common.md#clear-and-simple-design The signature transfers only its stated process operation or event; resident state owns protocol decisions.
+         * @evidence contracts/common.md#prohibited-implementation-shortcuts Node-native representations remain explicit rather than shell strings, process stand-ins or replaced foreign methods.
+         * @evidence contracts/common.md#meaningful-documentation Native member prose states event, liveness or retirement meaning needed by the state owner.
+         * @evidenceExclude contracts/performance.md#efficient-algorithms This boundary signature defines an operation or event; open and its returned adapter implementations own the work.
+         * @evidenceExclude contracts/performance.md#reuse-equivalent-work The boundary descriptor computes no reusable graph result; state coordinates continued peer reuse.
+         * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The signature acquires no handle itself; open and the returned close implementation own actual lifetime.
+         * @evidence contracts/portability.md#os-neutral-implementation Node numeric exit status, signal names, stdin callbacks and decoded line strings preserve native process semantics without assuming shell quoting or platform path spelling.
+         */
+        write(line: string, done: (error?: Error | null) => void): void;
+        /**
+         * Detach the reader, or end stdin and await the owned process and stdio.
+         *
+         * @evidence contracts/common.md#principled-implementation Reader retirement is distinct from joined shutdown; repeated close(true) returns the same completion, which rejects unknown or forced termination.
+         * @evidence contracts/common.md#clear-and-simple-design The signature transfers only its stated process operation or event; resident state owns protocol decisions.
+         * @evidence contracts/common.md#prohibited-implementation-shortcuts Node-native representations remain explicit rather than shell strings, process stand-ins or replaced foreign methods.
+         * @evidence contracts/common.md#meaningful-documentation Native member prose states event, liveness or retirement meaning needed by the state owner.
+         * @evidenceExclude contracts/performance.md#efficient-algorithms This boundary signature defines an operation or event; open and its returned adapter implementations own the work.
+         * @evidenceExclude contracts/performance.md#reuse-equivalent-work The boundary descriptor computes no reusable graph result; state coordinates continued peer reuse.
+         * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The signature acquires no handle itself; open and the returned close implementation own actual lifetime.
+         * @evidence contracts/portability.md#os-neutral-implementation Node numeric exit status, signal names, stdin callbacks and decoded line strings preserve native process semantics without assuming shell quoting or platform path spelling.
+         */
+        close(terminate: boolean): void | Promise<void>;
+    }
+    /**
+     * Open the actual Node child and attach its reader and diagnostic drain.
+     *
+     * EOF permits the resident loop to finish. close(true) resolves only after
+     * Node joins the process and all stdio after a normal numeric exit, including
+     * a nonzero status already delivered to the request owner. A transport
+     * failure, signal, forced kill or unjoined deadline rejects instead.
+     *
+     * @evidence contracts/common.md#principled-implementation Node spawn and readline preserve executable, argv and complete lines; the close callback's private retirementError decision accepts normal numeric exit after process/stdio join while transport failure, unknown status, signal and forced termination remain failures. Exit events separately preserve failed request outcomes.
+     * @evidence contracts/common.md#clear-and-simple-design One adapter owns actual process I/O and joined EOF shutdown; its private retirementError helper qualifies completion without changing the resident state owners' protocol or diagnostic decisions.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Real process APIs retain their defaults and explicit argv; no test-only executable or response path is supplied.
+     * @evidence contracts/common.md#meaningful-documentation Prose explains EOF completion and unknown/forced failure and connection comments describe bounded stderr and retirement.
+     * @evidence contracts/performance.md#efficient-algorithms One spawn/reader setup is constant-count; writes and line decoding process frame bytes once, while captured diagnostics retain a tail of at most 65,536 UTF-16 code units and draining avoids pipe backpressure.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work This effectful opener creates one native peer; resident state determines when that peer remains reusable or must be replaced.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources The returned close owns one reader and child, detaches once and terminates at most once; a delivery deadline bounds an unread pipe after the caller yields, while child grace starts after EOF delivery. Streams drain through authoritative completion; an unjoined deadline first rejects and then releases only this connection's handles without terminating foreign pipe holders.
+     * @evidence contracts/portability.md#os-neutral-implementation Node spawn receives an executable and argv vector directly with windowsHide; Node stream/process APIs own native signals and optional cwd, without a shell or manual path normalization.
+     */
+    function open(binary: string, args: string[], events: Events, options: {
+        cwd?: string;
+        stderr: "capture" | "drain";
+    }): Connection;
+}

package/lib/model/TtscGraphLinePeer.js

@@ -0,0 +1,213 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TtscGraphLinePeer = void 0;
+const node_readline_1 = __importDefault(require("node:readline"));
+const GraphProcessTrace_1 = require("../internal/GraphProcessTrace");
+const TERMINATION_GRACE_MS = 1_000;
+/**
+ * Native line transport shared by graph and lint resident owners.
+ *
+ * @evidence contracts/common.md#principled-implementation Node stdout line framing and explicit process events preserve the native protocols while request correlation remains with their state owners.
+ * @evidence contracts/common.md#clear-and-simple-design A connection exposes only liveness, diagnostics, writes and retirement; EOF retirement and authoritative process/stdio joining serve both state owners.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The default adapter invokes the actual binary and argv without a shell, synthetic responses or replaced foreign methods.
+ * @evidence contracts/common.md#meaningful-documentation Connection comments state line/event ownership, bounded diagnostic capture and the difference between reader retirement and process termination.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms open owns process and line setup; the namespace groups its connection protocol.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Resident state owners decide peer reuse; this namespace adds no result cache.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources open and its returned close implementation own actual child/reader acquisition and retirement.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Events, Connection and open document the native representation and operations rather than the namespace grouping them.
+ */
+var TtscGraphLinePeer;
+(function (TtscGraphLinePeer) {
+    /**
+     * Open the actual Node child and attach its reader and diagnostic drain.
+     *
+     * EOF permits the resident loop to finish. close(true) resolves only after
+     * Node joins the process and all stdio after a normal numeric exit, including
+     * a nonzero status already delivered to the request owner. A transport
+     * failure, signal, forced kill or unjoined deadline rejects instead.
+     *
+     * @evidence contracts/common.md#principled-implementation Node spawn and readline preserve executable, argv and complete lines; the close callback's private retirementError decision accepts normal numeric exit after process/stdio join while transport failure, unknown status, signal and forced termination remain failures. Exit events separately preserve failed request outcomes.
+     * @evidence contracts/common.md#clear-and-simple-design One adapter owns actual process I/O and joined EOF shutdown; its private retirementError helper qualifies completion without changing the resident state owners' protocol or diagnostic decisions.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Real process APIs retain their defaults and explicit argv; no test-only executable or response path is supplied.
+     * @evidence contracts/common.md#meaningful-documentation Prose explains EOF completion and unknown/forced failure and connection comments describe bounded stderr and retirement.
+     * @evidence contracts/performance.md#efficient-algorithms One spawn/reader setup is constant-count; writes and line decoding process frame bytes once, while captured diagnostics retain a tail of at most 65,536 UTF-16 code units and draining avoids pipe backpressure.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work This effectful opener creates one native peer; resident state determines when that peer remains reusable or must be replaced.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources The returned close owns one reader and child, detaches once and terminates at most once; a delivery deadline bounds an unread pipe after the caller yields, while child grace starts after EOF delivery. Streams drain through authoritative completion; an unjoined deadline first rejects and then releases only this connection's handles without terminating foreign pipe holders.
+     * @evidence contracts/portability.md#os-neutral-implementation Node spawn receives an executable and argv vector directly with windowsHide; Node stream/process APIs own native signals and optional cwd, without a shell or manual path normalization.
+     */
+    function open(binary, args, events, options) {
+        const child = GraphProcessTrace_1.GraphProcessTrace.spawn(binary, args, {
+            ...(options.cwd === undefined ? {} : { cwd: options.cwd }),
+            stdio: ["pipe", "pipe", "pipe"],
+            windowsHide: true,
+        });
+        const lines = node_readline_1.default.createInterface({ input: child.stdout });
+        let stderr = "";
+        let readerClosed = false;
+        let terminated = false;
+        let joined = false;
+        let forced = false;
+        let joinFailed = false;
+        let failure;
+        let force;
+        let flushDeadline;
+        let deadline;
+        let resolve;
+        let reject;
+        const completion = new Promise((res, rej) => {
+            resolve = res;
+            reject = rej;
+        });
+        // Existing fire-and-forget disposal remains safe; awaiting the original
+        // promise still exposes failure instead of turning it into joined success.
+        void completion.catch(() => undefined);
+        child.on("error", (error) => {
+            failure = error;
+        });
+        for (const stream of [child.stdin, child.stdout, child.stderr])
+            stream.on("error", (error) => {
+                failure = error;
+                events.error(error);
+            });
+        child.once("close", (code, signal) => {
+            joined = true;
+            if (force !== undefined)
+                clearTimeout(force);
+            if (flushDeadline !== undefined)
+                clearTimeout(flushDeadline);
+            if (deadline !== undefined)
+                clearTimeout(deadline);
+            if (joinFailed)
+                return;
+            const error = retirementError(code, signal, forced, failure);
+            if (error !== undefined)
+                reject(error);
+            else
+                resolve();
+        });
+        const captureStderr = (chunk) => {
+            stderr = (stderr + chunk).slice(-64 * 1024);
+        };
+        if (options.stderr === "capture") {
+            child.stderr.setEncoding("utf8");
+            child.stderr.on("data", captureStderr);
+        }
+        else
+            child.stderr.resume();
+        lines.on("line", events.line);
+        child.on("error", events.error);
+        child.on("exit", events.exit);
+        const forceTerminationAndJoin = () => {
+            if (joined || deadline !== undefined)
+                return;
+            if (child.exitCode === null && child.signalCode === null) {
+                forced = true;
+                try {
+                    child.kill("SIGKILL");
+                }
+                catch (error) {
+                    failure = error instanceof Error ? error : new Error(String(error));
+                }
+            }
+            deadline = setTimeout(() => {
+                if (joined)
+                    return;
+                // Failure is final before destroying our streams can induce Node close.
+                // Foreign descendants may retain inherited pipe endpoints; release our
+                // endpoints without claiming their lifetime was joined or killing them.
+                joinFailed = true;
+                reject(new Error("@ttsc/graph: peer shutdown could not be joined"));
+                if (force !== undefined)
+                    clearTimeout(force);
+                if (flushDeadline !== undefined)
+                    clearTimeout(flushDeadline);
+                if (deadline !== undefined)
+                    clearTimeout(deadline);
+                lines.removeListener("line", events.line);
+                lines.close();
+                child.removeListener("error", events.error);
+                child.removeListener("exit", events.exit);
+                child.stderr.removeListener("data", captureStderr);
+                for (const stream of [child.stdin, child.stdout, child.stderr])
+                    stream.destroy();
+                child.unref();
+            }, TERMINATION_GRACE_MS);
+        };
+        const startTerminationGrace = () => {
+            if (flushDeadline !== undefined)
+                clearTimeout(flushDeadline);
+            if (joined || force !== undefined || deadline !== undefined)
+                return;
+            force = setTimeout(forceTerminationAndJoin, TERMINATION_GRACE_MS);
+        };
+        return {
+            get stderr() {
+                return stderr;
+            },
+            alive: () => child.exitCode === null && child.signalCode === null,
+            write: (line, done) => {
+                child.stdin.write(line, done);
+            },
+            close: (terminate) => {
+                if (!readerClosed) {
+                    readerClosed = true;
+                    lines.close();
+                }
+                if (!terminate)
+                    return;
+                if (terminated || joined)
+                    return completion;
+                terminated = true;
+                // Keep output drained until Node's close event joins both the process
+                // and inherited stdio. EOF permits the real resident loop to finish.
+                child.stdout.resume();
+                // The child cannot act on EOF until the pipe finishes. Starting its
+                // grace period before that callback charged a blocked parent event
+                // loop against a shutdown request it had not yet delivered.
+                if (!child.stdin.destroyed) {
+                    try {
+                        child.stdin.end(startTerminationGrace);
+                        // An unread pipe can prevent the EOF callback indefinitely. Start
+                        // delivery's own deadline only after synchronous caller work yields.
+                        queueMicrotask(() => {
+                            if (joined || force !== undefined || deadline !== undefined)
+                                return;
+                            flushDeadline = setTimeout(forceTerminationAndJoin, TERMINATION_GRACE_MS);
+                        });
+                    }
+                    catch (error) {
+                        failure = error instanceof Error ? error : new Error(String(error));
+                        child.stdin.destroy();
+                        startTerminationGrace();
+                    }
+                }
+                else
+                    startTerminationGrace();
+                return completion;
+            },
+        };
+    }
+    TtscGraphLinePeer.open = open;
+    /**
+     * Qualify an authoritative Node close event for resource retirement.
+     *
+     * A normal numeric exit establishes joined release regardless of the work's
+     * status. The exit callback owns that status; retirement still rejects an
+     * unknown exit, signal, forced termination or actual transport failure. This
+     * internal decision does not establish joining before Node closes stdio.
+     *
+     * @internal
+     */
+    function retirementError(code, signal, forced, failure) {
+        if (failure !== undefined)
+            return failure;
+        if (forced || code === null || signal !== null)
+            return new Error(`@ttsc/graph: peer shutdown failed (code=${String(code)}, signal=${String(signal)}, forced=${forced})`);
+        return undefined;
+    }
+    TtscGraphLinePeer.retirementError = retirementError;
+})(TtscGraphLinePeer || (exports.TtscGraphLinePeer = TtscGraphLinePeer = {}));
+//# sourceMappingURL=TtscGraphLinePeer.js.map

package/lib/model/TtscGraphLinePeer.js.map

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