@ttsc/graph 0.30.3 → 0.31.0

package/src/internal/GraphProcessTrace.ts

@@ -0,0 +1,242 @@
+import {
+  type SpawnOptions,
+  type SpawnSyncOptions,
+  spawn as nativeSpawn,
+  spawnSync as nativeSpawnSync,
+} from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { errorMonitor } from "node:events";
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * Private process observers; package entrypoints do not export this namespace.
+ * The aliases retain Node's overloads while their adapters pass arguments
+ * intact. Native executable, argv and option types stay with Node. This
+ * grouping adds no product flag, protocol field, cache, process holder or
+ * algorithm; those responsibilities remain with the adapters and their existing
+ * callers.
+ *
+ * @internal
+ */
+export namespace GraphProcessTrace {
+  export const spawn = observeSpawn as typeof nativeSpawn;
+  export const spawnSync = observeSpawnSync as typeof nativeSpawnSync;
+}
+
+/**
+ * Correlate one actual call in the coordinator's absolute scratch directory.
+ * Failed writes leave bounded integrity evidence where possible; an unwritable
+ * sink remains missing measurement data. Neither failure changes product IO.
+ *
+ * A process-local nonce and increasing ordinal distinguish calls from child PID
+ * reuse. The optional closure owns correlation and the append sink only;
+ * callers own process behavior. Node's absolute-path and append operations use
+ * the coordinator's native path spelling and process.pid identifies the writer.
+ * No fixture oracle, foreign mutation or test-helper dependency is involved.
+ * Each event carries the writer's actual process.version; that runtime string
+ * alone does not authenticate executable bytes or the loaded native image.
+ *
+ * Each event serializes its observed fields once, so temporary text follows
+ * event size. Synchronous IO is measurement overhead, not a claimed speedup.
+ * Effectful calls and writes are never deduplicated. Scalar counters and one
+ * nonce persist per module instance; each append closes its handle. Events are
+ * capped at64MiB and writer output at256MiB, plus one overwritten bounded
+ * integrity marker. The coordinator retains these files until writers join.
+ */
+function begin() {
+  const root = process.env.TTSC_E2E_TRACE;
+  if (!root || !path.isAbsolute(root)) return undefined;
+  try {
+    instance ??= randomUUID();
+  } catch {
+    return undefined;
+  }
+  const writerInstance = instance;
+  const invocation = `${writerInstance}:${++ordinal}`;
+  const file = path.join(root, `${process.pid}-${writerInstance}.jsonl`);
+  return (event: string, fields: Record<string, unknown>): void => {
+    try {
+      const line =
+        JSON.stringify({
+          ...fields,
+          schema: 1,
+          event,
+          writerPid: process.pid,
+          instance: writerInstance,
+          sequence: ++sequence,
+          at: new Date().toISOString(),
+          invocation,
+          data: {
+            ...(fields.data as Record<string, unknown> | undefined),
+            writerRuntime: process.version,
+          },
+        }) + "\n";
+      const bytes = Buffer.byteLength(line);
+      if (bytes > EVENT_LIMIT || written + bytes > WRITER_LIMIT)
+        throw new Error("trace writer byte budget exceeded");
+      fs.appendFileSync(file, line, { encoding: "utf8", mode: 0o600 });
+      written += bytes;
+    } catch {
+      try {
+        fs.writeFileSync(
+          `${file}.integrity`,
+          "trace serialization, append or byte budget failed",
+          { mode: 0o600 },
+        );
+      } catch {
+        /* Missing trace remains an integrity failure. */
+      }
+    }
+  };
+}
+
+/**
+ * Observe the supported spawn, exit and close events on the original child.
+ * errorMonitor observes errors without becoming a normal error handler. Call
+ * bounds are not exact OS creation times; close does not join descendants.
+ *
+ * Native spawn executes once with unchanged executable, argv and options and
+ * returns the original child or throws the same synchronous error. Events
+ * provide actual PID and lifecycle observations under one invocation; cwd
+ * records explicit or inherited intent without guessing native resolution.
+ * Streams, parsing, shutdown, references and normal errors stay caller-owned.
+ *
+ * Disabled observation delegates directly; enabled calls serialize argv and a
+ * fixed event population. Effectful starts are not reusable results. Once
+ * listeners retain correlation until their event or child collection; no timer,
+ * reference change, kill or independent wait is added. Existing owners release
+ * the child, and no foreign process export is patched.
+ */
+function observeSpawn(...args: Parameters<typeof nativeSpawn>) {
+  const trace = begin();
+  if (!trace) return Reflect.apply(nativeSpawn, undefined, args);
+  const options = (Array.isArray(args[1]) ? args[2] : args[1]) as
+    | SpawnOptions
+    | undefined;
+  const selected = {
+    argv: [args[0], ...(Array.isArray(args[1]) ? args[1] : [])],
+    cwd: options?.cwd === undefined ? null : String(options.cwd),
+    data: { primitive: "spawn", cwdInherited: options?.cwd === undefined },
+  };
+  const startLowerBound = new Date().toISOString();
+  trace("process-attempt", { ...selected, pid: null, startLowerBound });
+  let child: ReturnType<typeof nativeSpawn>;
+  try {
+    child = Reflect.apply(nativeSpawn, undefined, args);
+  } catch (error) {
+    trace("process-result", {
+      pid: null,
+      started: false,
+      exitObserved: false,
+      startLowerBound,
+      startUpperBound: new Date().toISOString(),
+      data: { outcome: "synchronous-spawn-error", error },
+    });
+    throw error;
+  }
+  const startUpperBound = new Date().toISOString();
+  let started = false;
+  let exitObserved = false;
+  child.once("spawn", () => {
+    started = true;
+    trace("process-start", {
+      pid: child.pid ?? null,
+      started,
+      startLowerBound,
+      startUpperBound,
+    });
+  });
+  child.once(errorMonitor, (error: Error) =>
+    trace("process-error", {
+      pid: child.pid ?? null,
+      started,
+      exitObserved,
+      error: error.message,
+      data: { code: (error as NodeJS.ErrnoException).code },
+    }),
+  );
+  child.once("exit", (status, signal) => {
+    exitObserved = true;
+    trace("process-exit", {
+      pid: child.pid ?? null,
+      started,
+      exitObserved,
+      status,
+      signal,
+    });
+  });
+  child.once("close", (status, signal) =>
+    trace("process-close", {
+      pid: child.pid ?? null,
+      started,
+      exitObserved,
+      status,
+      signal,
+    }),
+  );
+  return child;
+}
+
+/**
+ * Observe the original synchronous result without replacing file descriptors,
+ * encoding, buffers, shell options or errors. A positive returned PID records a
+ * started child; call bounds do not invent its exact creation timestamp.
+ *
+ * Actual returned PID/status/signal/error distinguish a child from a failed
+ * pre-start attempt. Executable, argv, native options and the identical result
+ * or thrown error pass through unchanged. Explicit cwd and inherited intent are
+ * distinct observations, not resolved executable identity. Downstream capture,
+ * status mapping, protocol bytes and disposal remain in their existing owners.
+ *
+ * Observation adds argv serialization and two bounded event writes per actual
+ * effectful call; captured output is not copied or reused as expected counts.
+ * One correlation remains until native return, append handles close per write
+ * and original callers still release their captures.
+ */
+function observeSpawnSync(...args: Parameters<typeof nativeSpawnSync>) {
+  const trace = begin();
+  if (!trace) return Reflect.apply(nativeSpawnSync, undefined, args);
+  const options = (Array.isArray(args[1]) ? args[2] : args[1]) as
+    | SpawnSyncOptions
+    | undefined;
+  const selected = {
+    argv: [args[0], ...(Array.isArray(args[1]) ? args[1] : [])],
+    cwd: options?.cwd === undefined ? null : String(options.cwd),
+    data: { primitive: "spawnSync", cwdInherited: options?.cwd === undefined },
+  };
+  const startLowerBound = new Date().toISOString();
+  trace("process-attempt", { ...selected, pid: null, startLowerBound });
+  let result: ReturnType<typeof nativeSpawnSync>;
+  try {
+    result = Reflect.apply(nativeSpawnSync, undefined, args);
+  } catch (error) {
+    trace("process-result", {
+      pid: null,
+      started: false,
+      exitObserved: false,
+      startLowerBound,
+      startUpperBound: new Date().toISOString(),
+      data: { outcome: "synchronous-spawn-error", error },
+    });
+    throw error;
+  }
+  trace("process-result", {
+    pid: result.pid || null,
+    started: result.pid > 0,
+    exitObserved: result.status !== null || result.signal !== null,
+    status: result.status,
+    signal: result.signal,
+    error: result.error?.message,
+    startLowerBound,
+    startUpperBound: new Date().toISOString(),
+  });
+  return result;
+}
+
+let instance: string | undefined;
+let ordinal = 0;
+let sequence = 0;
+let written = 0;
+const EVENT_LIMIT = 64 * 1024 * 1024;
+const WRITER_LIMIT = 256 * 1024 * 1024;

package/src/launcherArgs.ts

@@ -1,5 +1,21 @@
 import path from "node:path";
 
+import type { ILauncherOption } from "./ILauncherOption";
+import type { IProjectOptions } from "./IProjectOptions";
+import type { ParsedLauncherOptions } from "./ParsedLauncherOptions";
+
+/**
+ * Invalid launcher syntax or a value outside the option's supported domain.
+ *
+ * @evidence contracts/common.md#principled-implementation An Error subtype gives callers a distinct argument-failure category while preserving the original diagnostic message.
+ * @evidence contracts/common.md#clear-and-simple-design Only the error name differs; native Error owns stack and message behavior.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No global Error behavior is patched to classify launcher failures.
+ * @evidence contracts/common.md#meaningful-documentation The native headline identifies the two supported causes without restating the class name.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Argument failure representation has no filesystem or process boundary.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources an Error subclass retains only its message and stack for the catcher.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms an Error subclass that only sets its name, so it runs no algorithm.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work an Error subclass holds no computation that could be shared.
+ */
 export class GraphArgumentError extends Error {
   public constructor(message: string) {
     super(message);
@@ -7,27 +23,26 @@ export class GraphArgumentError extends Error {
   }
 }
 
-type OptionKind = "value" | "flag" | "boolean";
-
-export interface ILauncherOption {
-  key: string;
-  flags: readonly string[];
-  kind: OptionKind;
-}
-
-export type ParsedLauncherOptions = ReadonlyMap<string, string | boolean>;
-
-export interface IProjectOptions {
-  cwd: string;
-  tsconfig: string;
-}
-
 export const PROJECT_OPTIONS: readonly ILauncherOption[] = [
   { key: "cwd", flags: ["--cwd"], kind: "value" },
   { key: "tsconfig", flags: ["--tsconfig"], kind: "value" },
 ];
 
-/** Parse one complete launcher argument vector and reject every unknown token. */
+/**
+ * Parse one complete launcher argument vector and reject every unknown token.
+ *
+ * Repeated aliases replace the prior canonical value. Missing values, values on
+ * bare flags and unsupported boolean spellings throw GraphArgumentError.
+ *
+ * @evidence contracts/common.md#principled-implementation An alias map and ordered argument scan implement explicit option grammar; typed validators reject unsupported values without coercion.
+ * @evidence contracts/common.md#clear-and-simple-design Definitions own grammar while private helpers own equals syntax, nonempty text and boolean spellings.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Every token must match a configured option; unknown input is not silently accepted for a known fixture.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains repeated options and argument failures, with tags separated by a blank comment line.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Token parsing interprets no path and invokes no native process; projectOptions handles path-bearing options later.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources builds a local Map that it returns and keeps no handle.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms one pass over argv with a Map of flag aliases, linear in the argument count.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work parses one argv per launch and caches nothing.
+ */
 export function parseLauncherOptions(
   argv: readonly string[],
   definitions: readonly ILauncherOption[],
@@ -42,12 +57,18 @@ export function parseLauncherOptions(
     const arg = argv[i]!;
     const exact = flags.get(arg);
     if (exact !== undefined) {
-      if (exact.kind === "value") {
+      if (exact.kind === "value" || exact.kind === "string") {
         const value = argv[++i];
-        if (value === undefined || value.startsWith("-")) {
+        if (
+          value === undefined ||
+          (exact.kind === "value" && value.startsWith("-"))
+        ) {
           throw new GraphArgumentError(`${arg} requires a non-empty value`);
         }
-        parsed.set(exact.key, requireValue(arg, value));
+        parsed.set(
+          exact.key,
+          exact.kind === "string" ? value : requireValue(arg, value),
+        );
       } else {
         parsed.set(exact.key, true);
       }
@@ -65,13 +86,30 @@ export function parseLauncherOptions(
     if (definition.kind === "boolean") {
       parsed.set(definition.key, parseBoolean(flag, value));
     } else {
-      parsed.set(definition.key, requireValue(flag, value));
+      parsed.set(
+        definition.key,
+        definition.kind === "string" ? value : requireValue(flag, value),
+      );
     }
   }
   return parsed;
 }
 
-/** Resolve the two project-selection values shared by every launcher lane. */
+/**
+ * Resolve the two project-selection values shared by every launcher lane.
+ *
+ * Defaults are the process directory and tsconfig.json; relative cwd values are
+ * resolved before package lookup or native process invocation.
+ *
+ * @evidence contracts/common.md#principled-implementation Native path.resolve makes cwd absolute while the config retains the producer's cwd-relative convention.
+ * @evidence contracts/common.md#clear-and-simple-design One adapter owns both shared defaults for all launcher lanes.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Defaults are public launcher conventions rather than named-repository exceptions.
+ * @evidence contracts/common.md#meaningful-documentation Native prose documents defaults and resolution timing instead of only listing returned keys.
+ * @evidence contracts/portability.md#os-neutral-implementation Node path.resolve applies the host's native path rules without manually concatenating separators.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources returns a fresh value and keeps no handle or state.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms resolves two values in constant time.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work two lookups per call, nothing worth sharing.
+ */
 export function projectOptions(values: ParsedLauncherOptions): IProjectOptions {
   return {
     cwd: path.resolve(stringValue(values, "cwd") ?? process.cwd()),
@@ -79,7 +117,22 @@ export function projectOptions(values: ParsedLauncherOptions): IProjectOptions {
   };
 }
 
-/** Read a bounded non-negative integer option without JavaScript coercion. */
+/**
+ * Read a bounded non-negative integer option without JavaScript coercion.
+ *
+ * The value must be present, decimal digits and a safe integer no greater than
+ * maximum. Missing parser state is an internal error; invalid text is an
+ * argument error.
+ *
+ * @evidence contracts/common.md#principled-implementation Decimal syntax plus safe-integer and maximum checks exclude coercible nonintegers and precision loss before returning a number.
+ * @evidence contracts/common.md#clear-and-simple-design One validator owns nonnegative parsing and is reused by the positive validator.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Bounds are supplied by the option contract rather than expected fixture values.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains numeric domain and the distinction between missing state and invalid input.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Numeric option validation has no native filesystem or process operation.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources returns a number and retains nothing.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms one digit-pattern test and one Number conversion of a single option value.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work validates one option value per call.
+ */
 export function nonNegativeIntegerOption(
   values: ParsedLauncherOptions,
   key: string,
@@ -101,7 +154,20 @@ export function nonNegativeIntegerOption(
   return number;
 }
 
-/** Read a bounded positive integer option without JavaScript coercion. */
+/**
+ * Read a bounded positive integer option without JavaScript coercion.
+ *
+ * Uses the nonnegative validator and additionally rejects zero.
+ *
+ * @evidence contracts/common.md#principled-implementation Reusing safe nonnegative validation then excluding zero yields exactly the bounded positive-integer domain.
+ * @evidence contracts/common.md#clear-and-simple-design The adapter adds one domain restriction rather than duplicating numeric parsing.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Zero rejection follows the option domain, not a special expected command case.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states the additional restriction and identifies the shared validator.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation The positivity restriction is a platform-independent numeric predicate.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources returns a number and retains nothing.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms delegates to nonNegativeIntegerOption and compares the result with zero.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work validates one option value per call.
+ */
 export function positiveIntegerOption(
   values: ParsedLauncherOptions,
   key: string,

package/src/model/IArtifactDirectory.ts

@@ -0,0 +1,27 @@
+/**
+ * A directory watched on behalf of the pattern that named it.
+ *
+ * @evidence contracts/common.md#principled-implementation The absolute root and descent flag identify the conservative tree population needed to notice a declared pattern changing.
+ * @evidence contracts/common.md#clear-and-simple-design A directory watch contains only its native root and traversal choice; resolved files remain in the separate file list.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The depth decision follows wildcard path structure rather than an arbitrary maximum documentation depth.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains the recursive distinction and why a bare filename wildcard does not require a repository-wide scan.
+ * @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 IArtifactDirectory {
+  /** Absolute path of the directory to walk. */
+  path: string;
+
+  /**
+   * Whether the walk descends.
+   *
+   * Taken from wildcard path structure rather than assumed, because assuming it
+   * is expensive in exactly the case that looks harmless: a rule declaring
+   * `*.md` has the project root for its fixed prefix, and treating that as
+   * recursive would state every file in the repository before every graph
+   * request.
+   */
+  recursive: boolean;
+}

package/src/model/IArtifactInputs.ts

@@ -0,0 +1,21 @@
+import { IArtifactDirectory } from "./IArtifactDirectory";
+
+/**
+ * Paths an answer was derived from, split by how they are watched.
+ *
+ * @evidence contracts/common.md#principled-implementation Explicit files and watched directories represent edits and membership changes as distinct input populations.
+ * @evidence contracts/common.md#clear-and-simple-design Two lists carry sidecar-declared provenance without a second glob interpreter or compiler dependency model.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts An input inventory does not assert complete discovery provenance for a missing publisher.
+ * @evidence contracts/common.md#meaningful-documentation Native property prose identifies individual files and directories that notice additions and deletions.
+ * @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 IArtifactInputs {
+  /** Files stated one by one. */
+  files: string[];
+
+  /** Directories walked, which is what notices an added or deleted file. */
+  directories: IArtifactDirectory[];
+}

package/src/model/IPublishedArtifacts.ts

@@ -0,0 +1,81 @@
+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/src/model/IPublishedArtifactsResident.ts

@@ -0,0 +1,24 @@
+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/src/model/ITtscLintDaemonTarget.ts

@@ -0,0 +1,22 @@
+/**
+ * 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;
+}