@ttsc/graph 0.30.3 → 0.31.0

package/lib/model/TtscLintDaemon.js

@@ -1,11 +1,9 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TtscLintDaemon = void 0;
-const node_child_process_1 = require("node:child_process");
-const node_readline_1 = __importDefault(require("node:readline"));
+const TtscGraphLinePeer_1 = require("./TtscGraphLinePeer");
+const TtscGraphNativeArguments_1 = require("./TtscGraphNativeArguments");
+const TtscLintDaemonState_1 = require("./TtscLintDaemonState");
 /**
  * A resident `@ttsc/lint` sidecar, kept open across the questions one graph
  * session asks it.
@@ -22,20 +20,26 @@ const node_readline_1 = __importDefault(require("node:readline"));
  * at all, and a daemon can die mid-session; each of those closes this one and
  * leaves the caller to spawn per verb, which is the behaviour that existed
  * before this and is still correct — only slower.
+ *
+ * @evidence contracts/common.md#principled-implementation Serialized line requests match FIFO responses; unsupported or failed daemon replies return null so callers can use the same direct verb contract.
+ * @evidence contracts/common.md#clear-and-simple-design This facade owns one sidecar's launch identity; daemon state owns FIFO replies/fallback and the shared line adapter owns its native transport.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts A failed daemon is retired rather than advertised as a successful empty artifact set.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain resident amortization and the supported direct-command fallback rather than claiming all failures are empty results.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms ask delegates FIFO processing and fallback to daemon state; this declaration describes the real sidecar launch identity.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work ask owns continued process/configuration reuse and invalidation.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources ask and close own acquisition, failure and shutdown transitions; the declaration adds no independent lifecycle operation.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Native invocation and termination decisions are acknowledged on ask and close together with private helpers.
  */
 class TtscLintDaemon {
     target;
     cwd;
     tsconfig;
-    child;
-    lines;
-    pending = [];
-    queue = Promise.resolve();
-    failed = false;
+    state;
     constructor(target, cwd, tsconfig) {
         this.target = target;
         this.cwd = cwd;
         this.tsconfig = tsconfig;
+        this.state = new TtscLintDaemonState_1.TtscLintDaemonState((events) => TtscGraphLinePeer_1.TtscGraphLinePeer.open(this.target.binary, TtscGraphNativeArguments_1.TtscGraphNativeArguments.lint(this.cwd, this.tsconfig, this.target.manifest, this.target.projectContext), events, { cwd: this.cwd, stderr: "drain" }));
     }
     /**
      * Ask one verb and return its raw JSON, or `null` when this daemon cannot
@@ -49,118 +53,36 @@ class TtscLintDaemon {
      * Requests are serialized. The daemon answers one line per request in order,
      * with nothing in the reply to address it by, so a second request in flight
      * would be matched against the first one's answer.
+     *
+     * @evidence contracts/common.md#principled-implementation A promise queue admits one request at a time because the protocol orders responses without request ids; result text preserves arbitrary JSON values.
+     * @evidence contracts/common.md#clear-and-simple-design ask delegates queue admission and reply decoding to daemon state; its configured opener supplies actual native transport and supported sidecar argv.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Null explicitly requests a direct fallback; it cannot silently masquerade as no published artifacts.
+     * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain null meaning and why requests must be serialized.
+     * @evidence contracts/performance.md#efficient-algorithms Each request writes and decodes one JSON frame; queue work is linear in serialized frame bytes with one active reply.
+     * @evidence contracts/performance.md#reuse-equivalent-work The same target/project sidecar retains process, plugin load and configuration across verbs; invalidate explicitly retires warm Program facts when input generations change.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources The daemon owns one child and reader; close settles pending replies and kills the child, while queued promises remain proportional to submitted caller demand.
+     * @evidence contracts/portability.md#os-neutral-implementation spawn passes executable and an argv vector directly with windowsHide, preserving spaces and native executable semantics without shell quoting.
      */
     ask(verb, invalidate) {
-        const run = this.queue.then(() => this.send(verb, invalidate));
-        this.queue = run.catch(() => undefined);
-        return run;
+        return this.state.ask(verb, invalidate);
     }
-    /** Stop the sidecar. Safe to call more than once, and after a failure. */
+    /**
+     * Stop the sidecar. Safe to call more than once, and after a failure.
+     *
+     * Pending replies settle null so callers can switch to the direct command.
+     *
+     * @evidence contracts/common.md#principled-implementation Marking failed before settling requests prevents new daemon work while reader and child ownership are cleared.
+     * @evidence contracts/common.md#clear-and-simple-design One shutdown operation is shared by explicit disposal and transport failure.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Shutdown does not invent a successful reply to unblock a request.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states idempotence, failure safety and the meaning of settled null replies.
+     * @evidence contracts/performance.md#efficient-algorithms Closing visits outstanding reply callbacks once and clears the reader/child references.
+     * @evidence contracts/performance.md#reuse-equivalent-work Closure retires this target's reusable process permanently; later calls return the supported direct-fallback indication.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources Both normal and failed shutdown settle pending callbacks, close readline and end/kill the owned process; the returned completion still joins stdio after process exit and rejects unknown or forced termination.
+     * @evidence contracts/portability.md#os-neutral-implementation Node stream closure and child.kill own native termination rather than platform shell commands.
+     */
     close() {
-        this.failed = true;
-        for (const settle of this.pending.splice(0))
-            settle(null);
-        this.lines?.close();
-        this.lines = undefined;
-        const child = this.child;
-        this.child = undefined;
-        if (child === undefined)
-            return;
-        child.stdin.end();
-        child.kill();
-    }
-    async send(verb, invalidate) {
-        if (this.failed)
-            return null;
-        const child = this.start();
-        if (child === undefined)
-            return null;
-        const reply = await new Promise((resolve) => {
-            this.pending.push(resolve);
-            child.stdin.write(`${JSON.stringify({ invalidate, verb })}\n`, (error) => {
-                if (error === null || error === undefined)
-                    return;
-                this.fail();
-            });
-        });
-        if (reply === null || reply.code !== 0) {
-            // A nonzero code is the sidecar declining, and this client cannot tell
-            // "unknown verb" from "the rule failed". Closing rather than retrying
-            // through the daemon is what makes the caller fall back to the direct
-            // command, where a real failure surfaces the same way it always did.
-            this.close();
-            return null;
-        }
-        return reply.result;
-    }
-    start() {
-        if (this.child !== undefined)
-            return this.child;
-        if (this.failed)
-            return undefined;
-        let child;
-        try {
-            child = (0, node_child_process_1.spawn)(this.target.binary, [
-                "lsp-serve",
-                `--cwd=${this.cwd}`,
-                `--tsconfig=${this.tsconfig}`,
-                `--plugins-json=${this.target.manifest}`,
-                ...(this.target.projectContext === undefined
-                    ? []
-                    : [`--project-context-json=${this.target.projectContext}`]),
-            ], { cwd: this.cwd, stdio: ["pipe", "pipe", "pipe"], windowsHide: true });
-        }
-        catch {
-            this.failed = true;
-            return undefined;
-        }
-        this.child = child;
-        // The sidecar's stderr is its own diagnostic channel and is not this
-        // client's to interpret; draining it keeps a chatty plugin from filling the
-        // pipe and stalling the daemon it is talking through.
-        child.stderr.resume();
-        child.on("error", () => this.fail());
-        child.on("exit", () => this.fail());
-        this.lines = node_readline_1.default.createInterface({ input: child.stdout });
-        this.lines.on("line", (line) => this.onLine(line));
-        return child;
-    }
-    onLine(line) {
-        const settle = this.pending.shift();
-        if (settle === undefined)
-            return;
-        let reply;
-        try {
-            reply = JSON.parse(line);
-        }
-        catch {
-            settle(null);
-            return;
-        }
-        settle(typeof reply.code === "number"
-            ? { code: reply.code, result: rawResult(line) }
-            : null);
-    }
-    fail() {
-        this.close();
+        return this.state.close();
     }
 }
 exports.TtscLintDaemon = TtscLintDaemon;
-/**
- * The `result` member, as the JSON text this daemon's callers parse.
- *
- * A verb's result is arbitrary JSON that the caller decodes itself, so it is
- * handed back as text rather than as a value — which is what the direct command
- * hands over, and what keeps the two paths interchangeable. The text is
- * re-serialized rather than sliced out of the line: the bytes are not identical
- * to the sidecar's own, but the value they decode to is, and no caller here
- * reads anything else.
- *
- * A reply with no `result` is `"null"`, so a caller parses a value either way
- * instead of being handed the empty string.
- */
-function rawResult(line) {
-    const parsed = JSON.parse(line);
-    return parsed.result === undefined ? "null" : JSON.stringify(parsed.result);
-}
 //# sourceMappingURL=TtscLintDaemon.js.map

package/lib/model/TtscLintDaemon.js.map

@@ -1 +1 @@
-{"version":3,"file":"TtscLintDaemon.js","sourceRoot":"","sources":["../../src/model/TtscLintDaemon.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"TtscLintDaemon.js","sourceRoot":"","sources":["../../src/model/TtscLintDaemon.ts"],"names":[],"mappings":";;;AACA,2DAAwD;AACxD,yEAAsE;AACtE,+DAA4D;AAE5D;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH;IAIqB,MAAM;IACN,GAAG;IACH,QAAQ;IALV,KAAK,CAAsB;IAE5C,YACmB,MAA6B,EAC7B,GAAW,EACX,QAAgB;sBAFhB,MAAM;mBACN,GAAG;wBACH,QAAQ;QAEzB,IAAI,CAAC,KAAK,GAAG,IAAI,yCAAmB,CAAC,CAAC,MAAM,EAAE,EAAE,CAC9C,qCAAiB,CAAC,IAAI,CACpB,IAAI,CAAC,MAAM,CAAC,MAAM,EAClB,mDAAwB,CAAC,IAAI,CAC3B,IAAI,CAAC,GAAG,EACR,IAAI,CAAC,QAAQ,EACb,IAAI,CAAC,MAAM,CAAC,QAAQ,EACpB,IAAI,CAAC,MAAM,CAAC,cAAc,CAC3B,EACD,MAAM,EACN,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,CACnC,CACF,CAAC;IACJ,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACI,GAAG,CAAC,IAAY,EAAE,UAAmB;QAC1C,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;IAC1C,CAAC;IAED;;;;;;;;;;;;;OAaG;IACI,KAAK;QACV,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IAC5B,CAAC;CACF"}

package/lib/model/TtscLintDaemonState.d.ts

@@ -0,0 +1,69 @@
+import { TtscGraphLinePeer } from "./TtscGraphLinePeer";
+/**
+ * FIFO reply correlation and direct-command fallback for one lint daemon.
+ *
+ * Replies have no request id, so admission is serialized. Null means the
+ * resident protocol cannot answer after successful retirement; callers retain
+ * their direct verb fallback. Failed joined shutdown rejects instead.
+ *
+ * @evidence contracts/common.md#principled-implementation Serialized requests and FIFO replies preserve the sidecar protocol; failed and unsupported answers permanently retire this owner.
+ * @evidence contracts/common.md#clear-and-simple-design Line parsing and queue/failure transitions are local; the declared opener owns actual process transport.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Null requests a real direct fallback, never an invented empty result or fake success.
+ * @evidence contracts/common.md#meaningful-documentation Prose explains no-id serialization and the null fallback contract; ask and close document acquisition and retirement.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms ask/close own admission, frame processing and retirement; this declaration groups their retained state.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work ask/close establish continued peer/model reuse, not the class descriptor independently.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources ask/close control acquisition and release; the class declaration adds no separate lifecycle transition.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation queues requests and parses reply lines in memory; the process is reached only through the injected opener's Connection.
+ */
+export declare class TtscLintDaemonState {
+    private readonly open;
+    private child;
+    private readonly pending;
+    private queue;
+    private failed;
+    private closing;
+    constructor(open: (events: TtscGraphLinePeer.Events) => TtscGraphLinePeer.Connection);
+    /**
+     * Ask one verb and return its raw JSON, or `null` when this daemon cannot
+     * answer it.
+     *
+     * `null` is always "ask the sidecar directly instead", never "the project has
+     * none". The two are indistinguishable downstream — an empty artifact set is
+     * the correct answer for most projects — so a daemon that cannot answer must
+     * never be allowed to look like one that answered nothing.
+     *
+     * Requests are serialized. The daemon answers one line per request in order,
+     * with nothing in the reply to address it by, so a second request in flight
+     * would be matched against the first one's answer.
+     *
+     * @evidence contracts/common.md#principled-implementation A promise queue admits one request at a time because the protocol orders responses without request ids; result text preserves arbitrary JSON values.
+     * @evidence contracts/common.md#clear-and-simple-design ask owns queue admission while send/start/onLine own transport and reply decoding.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Null explicitly requests a direct fallback; it cannot silently masquerade as no published artifacts.
+     * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain null meaning and why requests must be serialized.
+     * @evidence contracts/performance.md#efficient-algorithms Each request writes and decodes one JSON frame; queue work is linear in serialized frame bytes with one active reply.
+     * @evidence contracts/performance.md#reuse-equivalent-work The same target/project sidecar retains process, plugin load and configuration across verbs; invalidate explicitly retires warm Program facts when input generations change.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources The daemon owns one child and reader; close settles pending replies and delegates joined EOF shutdown to the actual adapter, while queued promises remain proportional to submitted caller demand.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation queues one request and parses one reply line; the process is reached only through the injected Connection.
+     */
+    ask(verb: string, invalidate: boolean): Promise<string | null>;
+    /**
+     * Stop the sidecar. Safe to call more than once, and after a failure.
+     *
+     * Reply callbacks settle null. Their asks switch to the direct command only
+     * after successful retirement; a shutdown failure propagates to the caller.
+     *
+     * @evidence contracts/common.md#principled-implementation Marking failed before settling requests prevents new daemon work while reader and child ownership are cleared.
+     * @evidence contracts/common.md#clear-and-simple-design One shutdown operation is shared by explicit disposal and transport failure.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Shutdown does not invent a successful reply to unblock a request.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states idempotence, failure safety and the meaning of settled null replies.
+     * @evidence contracts/performance.md#efficient-algorithms Closing visits outstanding reply callbacks once and clears the reader/child references.
+     * @evidence contracts/performance.md#reuse-equivalent-work Closure retires this target's reusable process permanently; later calls return the supported direct-fallback indication.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources Both normal and failed shutdown settle pending callbacks, close readline and end/kill the owned process; the returned completion still joins stdio after process exit and rejects unknown or forced termination.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation settles pending replies and closes the injected Connection; the process work lives there.
+     */
+    close(): Promise<void>;
+    private send;
+    private start;
+    private onLine;
+    private fail;
+}

package/lib/model/TtscLintDaemonState.js

@@ -0,0 +1,166 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TtscLintDaemonState = void 0;
+/**
+ * FIFO reply correlation and direct-command fallback for one lint daemon.
+ *
+ * Replies have no request id, so admission is serialized. Null means the
+ * resident protocol cannot answer after successful retirement; callers retain
+ * their direct verb fallback. Failed joined shutdown rejects instead.
+ *
+ * @evidence contracts/common.md#principled-implementation Serialized requests and FIFO replies preserve the sidecar protocol; failed and unsupported answers permanently retire this owner.
+ * @evidence contracts/common.md#clear-and-simple-design Line parsing and queue/failure transitions are local; the declared opener owns actual process transport.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Null requests a real direct fallback, never an invented empty result or fake success.
+ * @evidence contracts/common.md#meaningful-documentation Prose explains no-id serialization and the null fallback contract; ask and close document acquisition and retirement.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms ask/close own admission, frame processing and retirement; this declaration groups their retained state.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work ask/close establish continued peer/model reuse, not the class descriptor independently.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources ask/close control acquisition and release; the class declaration adds no separate lifecycle transition.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation queues requests and parses reply lines in memory; the process is reached only through the injected opener's Connection.
+ */
+class TtscLintDaemonState {
+    open;
+    child;
+    pending = [];
+    queue = Promise.resolve();
+    failed = false;
+    closing;
+    constructor(open) {
+        this.open = open;
+    }
+    /**
+     * Ask one verb and return its raw JSON, or `null` when this daemon cannot
+     * answer it.
+     *
+     * `null` is always "ask the sidecar directly instead", never "the project has
+     * none". The two are indistinguishable downstream — an empty artifact set is
+     * the correct answer for most projects — so a daemon that cannot answer must
+     * never be allowed to look like one that answered nothing.
+     *
+     * Requests are serialized. The daemon answers one line per request in order,
+     * with nothing in the reply to address it by, so a second request in flight
+     * would be matched against the first one's answer.
+     *
+     * @evidence contracts/common.md#principled-implementation A promise queue admits one request at a time because the protocol orders responses without request ids; result text preserves arbitrary JSON values.
+     * @evidence contracts/common.md#clear-and-simple-design ask owns queue admission while send/start/onLine own transport and reply decoding.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Null explicitly requests a direct fallback; it cannot silently masquerade as no published artifacts.
+     * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain null meaning and why requests must be serialized.
+     * @evidence contracts/performance.md#efficient-algorithms Each request writes and decodes one JSON frame; queue work is linear in serialized frame bytes with one active reply.
+     * @evidence contracts/performance.md#reuse-equivalent-work The same target/project sidecar retains process, plugin load and configuration across verbs; invalidate explicitly retires warm Program facts when input generations change.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources The daemon owns one child and reader; close settles pending replies and delegates joined EOF shutdown to the actual adapter, while queued promises remain proportional to submitted caller demand.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation queues one request and parses one reply line; the process is reached only through the injected Connection.
+     */
+    ask(verb, invalidate) {
+        const run = this.queue.then(() => this.send(verb, invalidate));
+        this.queue = run.catch(() => undefined);
+        return run;
+    }
+    /**
+     * Stop the sidecar. Safe to call more than once, and after a failure.
+     *
+     * Reply callbacks settle null. Their asks switch to the direct command only
+     * after successful retirement; a shutdown failure propagates to the caller.
+     *
+     * @evidence contracts/common.md#principled-implementation Marking failed before settling requests prevents new daemon work while reader and child ownership are cleared.
+     * @evidence contracts/common.md#clear-and-simple-design One shutdown operation is shared by explicit disposal and transport failure.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Shutdown does not invent a successful reply to unblock a request.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states idempotence, failure safety and the meaning of settled null replies.
+     * @evidence contracts/performance.md#efficient-algorithms Closing visits outstanding reply callbacks once and clears the reader/child references.
+     * @evidence contracts/performance.md#reuse-equivalent-work Closure retires this target's reusable process permanently; later calls return the supported direct-fallback indication.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources Both normal and failed shutdown settle pending callbacks, close readline and end/kill the owned process; the returned completion still joins stdio after process exit and rejects unknown or forced termination.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation settles pending replies and closes the injected Connection; the process work lives there.
+     */
+    close() {
+        if (this.closing !== undefined)
+            return this.closing;
+        this.failed = true;
+        for (const settle of this.pending.splice(0))
+            settle(null);
+        const child = this.child;
+        this.child = undefined;
+        this.closing = Promise.resolve(child?.close(true));
+        void this.closing.catch(() => undefined);
+        return this.closing;
+    }
+    async send(verb, invalidate) {
+        if (this.failed) {
+            await this.closing;
+            return null;
+        }
+        const child = this.start();
+        if (child === undefined)
+            return null;
+        const reply = await new Promise((resolve) => {
+            this.pending.push(resolve);
+            child.write(`${JSON.stringify({ invalidate, verb })}\n`, (error) => {
+                if (error === null || error === undefined)
+                    return;
+                this.fail();
+            });
+        });
+        if (reply === null || reply.code !== 0) {
+            // A nonzero code is the sidecar declining, and this client cannot tell
+            // "unknown verb" from "the rule failed". Closing rather than retrying
+            // through the daemon is what makes the caller fall back to the direct
+            // command, where a real failure surfaces the same way it always did.
+            await this.close();
+            return null;
+        }
+        return reply.result;
+    }
+    start() {
+        if (this.child !== undefined)
+            return this.child;
+        if (this.failed)
+            return undefined;
+        try {
+            this.child = this.open({
+                line: (line) => this.onLine(line),
+                error: () => this.fail(),
+                exit: () => this.fail(),
+            });
+            return this.child;
+        }
+        catch {
+            this.failed = true;
+            return undefined;
+        }
+    }
+    onLine(line) {
+        const settle = this.pending.shift();
+        if (settle === undefined)
+            return;
+        let reply;
+        try {
+            reply = JSON.parse(line);
+        }
+        catch {
+            settle(null);
+            return;
+        }
+        settle(typeof reply.code === "number"
+            ? { code: reply.code, result: rawResult(line) }
+            : null);
+    }
+    fail() {
+        this.close();
+    }
+}
+exports.TtscLintDaemonState = TtscLintDaemonState;
+/**
+ * The `result` member, as the JSON text this daemon's callers parse.
+ *
+ * A verb's result is arbitrary JSON that the caller decodes itself, so it is
+ * handed back as text rather than as a value — which is what the direct command
+ * hands over, and what keeps the two paths interchangeable. The text is
+ * re-serialized rather than sliced out of the line: the bytes are not identical
+ * to the sidecar's own, but the value they decode to is, and no caller here
+ * reads anything else.
+ *
+ * A reply with no `result` is `"null"`, so a caller parses a value either way
+ * instead of being handed the empty string.
+ */
+function rawResult(line) {
+    const parsed = JSON.parse(line);
+    return parsed.result === undefined ? "null" : JSON.stringify(parsed.result);
+}
+//# sourceMappingURL=TtscLintDaemonState.js.map

package/lib/model/TtscLintDaemonState.js.map

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

package/lib/model/copyGraphRecords.d.ts

@@ -0,0 +1,14 @@
+import type { TtscGraphReadonly } from "./TtscGraphReadonly";
+/**
+ * Detach frozen graph records into a caller-owned mutable DTO projection.
+ *
+ * @evidence contracts/common.md#principled-implementation structuredClone detaches every nested array and record before restoring the mutable wire DTO type at the ownership transfer.
+ * @evidence contracts/common.md#clear-and-simple-design One inverse ownership operation keeps retained snapshots separate from editable output records.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The mutable return type is backed by a detached copy rather than a cast that exposes the retained frozen snapshot.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states that this operation transfers an independent mutable DTO to its caller.
+ * @evidence contracts/performance.md#efficient-algorithms One structured clone copies the requested record population without repeated serialization or field-by-field intermediate copies.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work The store owns continued shard reuse; a mutable output requires independent ownership rather than shared result aliases.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The detached result transfers to the caller and this helper retains no historical copies.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation one structuredClone of in-memory records; no file, path or process is touched.
+ */
+export declare function copyGraphRecords<T>(value: TtscGraphReadonly<T>): T;

package/lib/model/copyGraphRecords.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.copyGraphRecords = copyGraphRecords;
+/**
+ * Detach frozen graph records into a caller-owned mutable DTO projection.
+ *
+ * @evidence contracts/common.md#principled-implementation structuredClone detaches every nested array and record before restoring the mutable wire DTO type at the ownership transfer.
+ * @evidence contracts/common.md#clear-and-simple-design One inverse ownership operation keeps retained snapshots separate from editable output records.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The mutable return type is backed by a detached copy rather than a cast that exposes the retained frozen snapshot.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states that this operation transfers an independent mutable DTO to its caller.
+ * @evidence contracts/performance.md#efficient-algorithms One structured clone copies the requested record population without repeated serialization or field-by-field intermediate copies.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work The store owns continued shard reuse; a mutable output requires independent ownership rather than shared result aliases.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The detached result transfers to the caller and this helper retains no historical copies.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation one structuredClone of in-memory records; no file, path or process is touched.
+ */
+function copyGraphRecords(value) {
+    return structuredClone(value);
+}
+//# sourceMappingURL=copyGraphRecords.js.map

package/lib/model/copyGraphRecords.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"copyGraphRecords.js","sourceRoot":"","sources":["../../src/model/copyGraphRecords.ts"],"names":[],"mappings":";;;AAEA;;;;;;;;;;;GAWG;AACH,0BAAoC,KAA2B;IAC7D,OAAO,eAAe,CAAC,KAAK,CAAM,CAAC;AACrC,CAAC"}

package/lib/model/copyGraphSnapshot.d.ts

@@ -0,0 +1,17 @@
+import type { TtscGraphReadonly } from "./TtscGraphReadonly";
+/**
+ * Copy and freeze plain graph DTO records before retaining or exposing them.
+ *
+ * The caller keeps ownership of its input. Graph DTOs contain records, arrays
+ * and primitive values, rather than mutable Map/Set or native handle objects.
+ *
+ * @evidence contracts/common.md#principled-implementation structuredClone detaches nested caller aliases before recursive freezing establishes an immutable owned fact population.
+ * @evidence contracts/common.md#clear-and-simple-design One ownership boundary is shared by model and shard storage rather than separate partial field-copy lists.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Caller-owned objects are never frozen to compensate for a borrowed snapshot alias.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states input ownership and the plain-DTO precondition, avoiding claims about mutable native collections.
+ * @evidence contracts/performance.md#efficient-algorithms One structured clone detaches the population and a WeakSet visits each owned record once during freezing; work and temporary visited storage scale with copied facts.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Model construction and shard transactions decide snapshot reuse; this ownership primitive performs one requested detachment.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Only the detached frozen result transfers to the caller; visited identities are local and no global population is retained.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation one structuredClone and a recursive freeze of in-memory records; no file, path or process is touched.
+ */
+export declare function copyGraphSnapshot<T>(value: T): TtscGraphReadonly<T>;

package/lib/model/copyGraphSnapshot.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.copyGraphSnapshot = copyGraphSnapshot;
+/**
+ * Copy and freeze plain graph DTO records before retaining or exposing them.
+ *
+ * The caller keeps ownership of its input. Graph DTOs contain records, arrays
+ * and primitive values, rather than mutable Map/Set or native handle objects.
+ *
+ * @evidence contracts/common.md#principled-implementation structuredClone detaches nested caller aliases before recursive freezing establishes an immutable owned fact population.
+ * @evidence contracts/common.md#clear-and-simple-design One ownership boundary is shared by model and shard storage rather than separate partial field-copy lists.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Caller-owned objects are never frozen to compensate for a borrowed snapshot alias.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states input ownership and the plain-DTO precondition, avoiding claims about mutable native collections.
+ * @evidence contracts/performance.md#efficient-algorithms One structured clone detaches the population and a WeakSet visits each owned record once during freezing; work and temporary visited storage scale with copied facts.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Model construction and shard transactions decide snapshot reuse; this ownership primitive performs one requested detachment.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Only the detached frozen result transfers to the caller; visited identities are local and no global population is retained.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation one structuredClone and a recursive freeze of in-memory records; no file, path or process is touched.
+ */
+function copyGraphSnapshot(value) {
+    const owned = structuredClone(value);
+    freezeRecords(owned, new WeakSet());
+    return owned;
+}
+/** Visit each owned record once, including shared or cyclic references. */
+function freezeRecords(value, visited) {
+    if (value === null || typeof value !== "object" || visited.has(value))
+        return;
+    visited.add(value);
+    for (const child of Object.values(value))
+        freezeRecords(child, visited);
+    Object.freeze(value);
+}
+//# sourceMappingURL=copyGraphSnapshot.js.map

package/lib/model/copyGraphSnapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"copyGraphSnapshot.js","sourceRoot":"","sources":["../../src/model/copyGraphSnapshot.ts"],"names":[],"mappings":";;;AAEA;;;;;;;;;;;;;;GAcG;AACH,2BAAqC,KAAQ;IAC3C,MAAM,KAAK,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC;IACrC,aAAa,CAAC,KAAK,EAAE,IAAI,OAAO,EAAU,CAAC,CAAC;IAC5C,OAAO,KAA6B,CAAC;AACvC,CAAC;AAED,2EAA2E;AAC3E,SAAS,aAAa,CAAC,KAAc,EAAE,OAAwB;IAC7D,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC;QAAE,OAAO;IAC9E,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACnB,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC;QAAE,aAAa,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IACxE,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACvB,CAAC"}

package/lib/model/loadGraph.d.ts

@@ -4,21 +4,12 @@ import { TtscGraphMemory } from "./TtscGraphMemory";
  * The dump schema version this client reads.
  *
  * Keep it equal to `DumpSchemaVersion` in
- * `packages/ttsc/internal/graph/provenance.go`. The two are hand-synchronized,
- * and `dump_schema_version_matches_the_typescript_client_test.go` reads this
- * constant out of this file and fails if the pair drifts.
+ * `packages/ttsc/internal/graph/provenance.go`. The two are hand-synchronized.
  *
  * Exported because the resident session reads the same dump body over the serve
  * protocol and has to hold it to the same number: the envelope's version and
  * the body's are independent, so a producer can speak this protocol and still
  * send a body from another schema.
- *
- * `scripts/assert-ttscgraph-release-candidate.cjs` reads this declaration out
- * of this file with a regular expression, because it runs against a packaged
- * binary in a workflow that has no reason to have built this package first.
- * Rewriting the declaration — adding a type annotation, splitting the line —
- * makes that script fail loudly rather than silently, and its message names
- * this constant; update its pattern with any such change.
  */
 export declare const DUMP_SCHEMA_VERSION = 8;
 /**
@@ -30,6 +21,15 @@ export declare const DUMP_SCHEMA_VERSION = 8;
  * Throws when the binary cannot be resolved, the dump command fails, or its
  * output is not a readable graph — the server surfaces the failure rather than
  * answering from an empty graph.
+ *
+ * @evidence contracts/common.md#principled-implementation The selected native producer builds the target project and its JSON is schema-version checked and structurally validated before model construction.
+ * @evidence contracts/common.md#clear-and-simple-design One-shot process execution, capture ownership and parse validation have separate helpers; the resident MCP path remains a different lifetime owner.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Failed resolution or native execution throws rather than returning an invented empty graph.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs state direct/viewer usage, project/binary defaults and every externally visible failure boundary.
+ * @evidence contracts/portability.md#os-neutral-implementation Native argv carries cwd, tsconfig and artifact paths without a shell; project-anchored binary resolution and permission repair account for host execution differences.
+ * @evidence contracts/performance.md#efficient-algorithms One native dump is followed by linear JSON parsing/validation and model indexing; output is file-backed rather than constrained by a guessed pipe budget.
+ * @evidence contracts/performance.md#reuse-equivalent-work Direct loads intentionally build the requested current project anew; callers needing repeated equivalent snapshots use TtscGraphSession's resident producer and model.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The operation owns two capture descriptors until the finally block disposes them; returned graph ownership transfers to the caller, while artifact storage remains process/project scoped.
  */
 export declare function loadGraph(options?: {
     /** Project root the graph is built for (default: `process.cwd()`). */
@@ -55,5 +55,14 @@ export declare function loadGraph(options?: {
  * outlives the process that wrote it — this is the one-shot path, and the JSON
  * on disk may be from any build — so the version is the first question to ask
  * of it.
+ *
+ * @evidence contracts/common.md#principled-implementation Parsing to unknown, reading schema version first and then asserting the full wire type reject mismatched producers before interpreting their shape.
+ * @evidence contracts/common.md#clear-and-simple-design This boundary owns dump decoding and validation for direct loads; model construction remains separate.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Malformed JSON and incompatible schemas do not become empty or partially trusted graph facts.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain version-before-shape ordering and why persisted dumps require independent validation.
+ * @evidence contracts/performance.md#efficient-algorithms JSON parsing and shape validation process the dump once before model indexing; cost grows with serialized bytes and graph facts.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This parser validates a supplied exchange string; loadGraph/session own producer sharing and generation identity.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Parsed data transfers to TtscGraphMemory; this operation acquires no native handle or historical cache.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Parsing serialized graph facts performs no native filesystem or process operation.
  */
 export declare function parseDump(json: string): ITtscGraphDump;