@ttsc/graph 0.30.4 → 0.31.1

package/lib/model/TtscGraphProtocol.js.map

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

package/lib/model/TtscGraphReadonly.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Recursively readonly view of compiler graph records and arrays.
+ *
+ * @evidence contracts/common.md#principled-implementation Recursive mapped properties and array elements prevent typed consumers from mutating nested snapshot facts.
+ * @evidence contracts/common.md#clear-and-simple-design One view type preserves the wire DTO shapes while expressing snapshot ownership separately from mutable result projections.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Readonly applies to nested arrays and records rather than only the outer graph array.
+ * @evidence contracts/common.md#meaningful-documentation Native prose names compiler records and arrays as the supported view boundary.
+ * @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 type TtscGraphReadonly<T> = T extends readonly (infer Element)[] ? readonly TtscGraphReadonly<Element>[] : T extends object ? {
+    readonly [Key in keyof T]: TtscGraphReadonly<T[Key]>;
+} : T;

package/lib/model/TtscGraphReadonly.js

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

package/lib/model/TtscGraphReadonly.js.map

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

package/lib/model/TtscGraphRequestOptions.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Per-call controls for a native graph refresh.
+ *
+ * @evidence contracts/common.md#principled-implementation An optional AbortSignal represents caller cancellation independently of shared project identity.
+ * @evidence contracts/common.md#clear-and-simple-design One field carries the only per-request lifecycle control without duplicating constructor options.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Cancellation is a supported caller signal rather than an idle reset or hidden timeout.
+ * @evidence contracts/common.md#meaningful-documentation The member comment explains that cancellation also retires the native session.
+ * @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 TtscGraphRequestOptions {
+    /** Cancel this refresh and retire its native session. */
+    signal?: AbortSignal;
+}

package/lib/model/TtscGraphRequestOptions.js

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

package/lib/model/TtscGraphRequestOptions.js.map

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

package/lib/model/TtscGraphSession.d.ts

@@ -1,36 +1,32 @@
 import { TtscGraphMemory } from "./TtscGraphMemory";
-/** Construction options for a resident native graph session. */
-export interface TtscGraphSessionOptions {
-    /** Project root passed to `ttscgraph serve`. */
-    cwd: string;
-    /** Project tsconfig passed to `ttscgraph serve`. */
-    tsconfig: string;
-    /** Absolute native binary path, resolved from `cwd` when omitted. */
-    binary?: string;
-}
-/** Per-call controls for a native graph refresh. */
-export interface TtscGraphRequestOptions {
-    /** Cancel this refresh and retire its native session. */
-    signal?: AbortSignal;
-}
+import type { TtscGraphRequestOptions } from "./TtscGraphRequestOptions";
+import type { TtscGraphSessionOptions } from "./TtscGraphSessionOptions";
 /**
  * Resident bridge to `ttscgraph serve`.
  *
- * Every graph request first asks the native session for the current disk
- * snapshot. Unchanged requests reuse the existing {@link TtscGraphMemory}; an
- * edited source reuses tsgo's resident Program through `driver.Session`, while
- * config and root-file-set changes force a safe full reload.
+ * Requests admitted before a freshness check starts share that check and its
+ * snapshot. Later arrivals require another check. Unchanged requests reuse the
+ * existing {@link TtscGraphMemory}; an edited source reuses tsgo's resident
+ * Program through `driver.Session`, while config and root-file-set changes
+ * force a safe full reload.
+ *
+ * Cold publisher discovery, proof validation and direct publisher commands run
+ * through the SDK's asynchronous owner. Request-group cancellation and session
+ * shutdown join those producers before a later admission can publish.
+ *
+ * @evidence contracts/common.md#principled-implementation Validated versioned responses and atomic shard transactions preserve generation consistency while serialized requests correlate native replies by id.
+ * @evidence contracts/common.md#clear-and-simple-design This facade owns project/binary and artifact sidecars; the state owns queue/model/shards, the protocol owns generated decoding and the line adapter owns the native child.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Compatible full dumps remain an explicit protocol fallback; malformed or mismatched responses retire the child rather than producing partial trusted facts.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain resident reuse, reload boundaries and artifact ownership, while public methods describe request and shutdown behavior.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms graph delegates admission and refresh to the state owner; this facade describes project, binary and artifact sidecar identity.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work graph owns coordination of model/producer reuse and its invalidation decisions.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources graph/close own actual acquisition and retirement; the class declaration describes the owner without a separate lifecycle operation.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Native project resolution and process control are reviewed through graph and close, including their private helpers.
  */
 export declare class TtscGraphSession {
     private readonly cwd;
     private readonly tsconfig;
     private readonly binary;
-    private child;
-    private nextId;
-    private readonly pending;
-    private queue;
-    private current;
-    private shardStore;
     /**
      * The artifact answer the resident child was last handed, and the state of
      * the inputs it came from.
@@ -41,6 +37,7 @@ export declare class TtscGraphSession {
      * session can notice.
      */
     private artifacts;
+    private readonly resolver;
     /**
      * One resident `@ttsc/lint` sidecar per plugin binary, opened lazily.
      *
@@ -51,21 +48,70 @@ export declare class TtscGraphSession {
      * binary answering for the same project.
      */
     private readonly daemons;
-    private closed;
+    private readonly daemonIdentities;
+    private readonly state;
+    private readonly shutdown;
+    private readonly retiredDaemons;
     constructor(options: TtscGraphSessionOptions);
-    /** Return a graph for the current disk snapshot, serialized per tool call. */
+    /**
+     * Return a graph refreshed after this caller's admission.
+     *
+     * Callers already waiting when a check starts share it. Cancellation rejects
+     * only that caller. The last cancellation aborts shared work; an outstanding
+     * native request then retires its peer. Closed sessions reject new requests
+     * and do not respawn.
+     *
+     * @evidence contracts/common.md#principled-implementation The state groups only callers admitted before its refresh starts, so every returned snapshot was validated after that caller's admission; independent cancellation cannot settle siblings.
+     * @evidence contracts/common.md#clear-and-simple-design The state owner handles admission, cancellation, response semantics and model replacement; facade callbacks synchronize artifacts and open the actual native transport.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts A cancelled or closed request cannot be fulfilled from fabricated empty facts or restart a disposed session.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states admission-based snapshot sharing, independent cancellation and closed-session behavior.
+     * @evidence contracts/portability.md#os-neutral-implementation Native binary resolution, argv spawning and Node termination APIs own host differences; project coordinates are never passed through a shell.
+     * @evidence contracts/performance.md#efficient-algorithms An admission group validates artifact inputs and a native frame once, then shares its model among live callers; changed frames additionally validate shards and rebuild indexes.
+     * @evidence contracts/performance.md#reuse-equivalent-work Only callers admitted before validation starts share that validation. Later groups check again; unchanged responses reuse current memory, while changed generations replace it and changed artifacts are republished before requesting facts.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources The session owns one graph child, current model, shard map and current publisher sidecars; republishing retires removed publishers, while pending/queued demand grows with submitted requests and completion/cancellation remove registrations.
+     */
     graph(options?: TtscGraphRequestOptions): Promise<TtscGraphMemory>;
-    /** Close the native session. Safe to call more than once. */
-    close(): void;
-    private refresh;
-    private assertResponseSemantics;
+    /**
+     * Close the native session. Safe to call more than once.
+     *
+     * Retires artifact sidecars, discovery worker and supervised publisher
+     * commands, and rejects pending native requests. Queued requests observe the
+     * closed state before they can create another child.
+     *
+     * @evidence contracts/common.md#principled-implementation The closed flag precedes sidecar disposal and child failure, so every pending or subsequent native operation observes retired ownership.
+     * @evidence contracts/common.md#clear-and-simple-design The explicit close path reuses failChild/failPending cleanup instead of a second cancellation implementation.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Disposing a session cannot trigger a compensating respawn or pretend outstanding requests succeeded.
+     * @evidence contracts/common.md#meaningful-documentation Native prose documents idempotence, pending rejection and queued-request behavior.
+     * @evidence contracts/portability.md#os-neutral-implementation Node child termination ends stdin, signals the process and escalates after a grace period without platform shell commands.
+     * @evidence contracts/performance.md#efficient-algorithms Shutdown visits sidecars and pending replies once; a delayed force-kill timer is cancelled when the child exits.
+     * @evidence contracts/performance.md#reuse-equivalent-work Closure ends this owner's permission to reuse native Program, model and sidecars; subsequent graph calls reject.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources Shutdown aborts discovery and publisher commands, joins the resolver and sidecars, and drops opaque proofs. Native readers and reply listeners are removed, model/shards are released with child retirement, and graph-peer termination owns its finite grace timer.
+     */
+    close(): Promise<void>;
+    /**
+     * Re-derive the artifact set when the documents or configuration behind it
+     * moved, before the request that would otherwise answer with the old one.
+     *
+     * A resident session is invalidated by the compiler's own build universe, and
+     * none of this is in it: the documents a rule reads are not Program inputs,
+     * which is the property that keeps a Markdown edit from costing a typecheck.
+     * The cost of that property is that nothing else notices the edit at all, so
+     * this is what notices it.
+     *
+     * Only the overlay is replaced. The child is not restarted and the Program is
+     * not reloaded — the native session compares the file it is handed against
+     * the one it applied, and re-projects the resident program when they differ.
+     *
+     * Asked of sidecars this session keeps open, and awaited rather than blocking
+     * the event loop. A republish still costs the rule a Program — the daemon is
+     * told to drop its warm one, because the sources a claim activates against
+     * have been edited too — but not a process, a plugin load and a configuration
+     * evaluation per verb. An already-cancelled request does not start one.
+     */
     private republishArtifacts;
     /** The open sidecar for one plugin, opened on first use. */
     private daemon;
-    private request;
-    private ensureChild;
-    private onLine;
-    private failChild;
-    private failPending;
-    private settlePending;
+    /** Keep failures visible to shutdown, releasing fulfilled historical owners. */
+    private retireDaemon;
+    private open;
 }