ttsc 0.30.4 → 0.31.0

package/src/plugin/internal/CapabilityPluginResult.ts

@@ -0,0 +1,99 @@
+import type {
+  ITtscCapabilityPlugin,
+  ITtscCapabilityPluginResolution,
+} from "../ITtscCapabilityPlugin";
+
+/**
+ * Project capability selection and the resolver's caught unavailable outcome.
+ * These operations consume supplied discovery values; they neither acquire
+ * runtime authority nor establish the validity of a descriptor's observations.
+ *
+ * @evidence contracts/common.md#principled-implementation Exact true declarations select nonempty binaries in input order; caught task failures remain unavailable rather than reusable empty success.
+ * @evidence contracts/common.md#clear-and-simple-design One internal concern owns selection and degraded result construction, without moving authority acquisition into its catch.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Supplied values are not native proof and no runtime, evaluator or compiler is substituted.
+ * @evidence contracts/common.md#meaningful-documentation Native prose separates supplied selection policy from discovery, authority and later freshness.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation The namespace groups data-selection and outcome functions; its initialization performs no native path, filesystem or process operation.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms The namespace itself defines members without computing a selection or executing a task; each operation owns its processing choices.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work The namespace owns no computed answer or reusable cache; resolver authority and persistence remain outside it.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The namespace owns no retained result collection, native handle or task lifecycle.
+ */
+export namespace CapabilityPluginResult {
+  /**
+   * Select declarations while forwarding the complete manifest and opted-in
+   * project context. Returned objects are fresh; their string values are kept.
+   *
+   * @evidence contracts/common.md#principled-implementation Only exact true declarations and nonempty binaries qualify; context requires its own true declaration and nonnull input.
+   * @evidence contracts/common.md#clear-and-simple-design One ordered filter and projection preserve the existing result shape.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Selection never narrows the complete supplied manifest or invents acquired context.
+   * @evidence contracts/common.md#meaningful-documentation Native prose identifies fresh result objects and the separate context gate.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation Binary, manifest and context strings are forwarded unchanged as supplied data; selection neither interprets native paths nor acquires a process or filesystem observation.
+   * @evidence contracts/performance.md#efficient-algorithms For P supplied entries and Q admitted entries, one filter scans P and one map projects Q, with an intermediate Q-reference array and Q fresh result objects. Declaration lookups are ordinary property access; manifest/context strings are referenced rather than parsed or copied.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work This projection decides no discovery freshness or expensive-computation reuse; the resolver owns those premises and this operation constructs fresh results each time.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources Returned storage grows with Q admitted entries and retains supplied string values until its caller releases it. The operation stores no history, cache, callback or native handle beyond the returned caller-owned objects.
+   */
+  export function select(
+    resolution: {
+      manifest: string;
+      projectContext: string | null;
+      plugins: readonly {
+        binary: string;
+        capabilities: Record<string, boolean>;
+      }[];
+    },
+    capability: string,
+  ): ITtscCapabilityPlugin[] {
+    return resolution.plugins
+      .filter(
+        (plugin) =>
+          plugin.binary !== "" && plugin.capabilities[capability] === true,
+      )
+      .map((plugin) => ({
+        binary: plugin.binary,
+        manifest: resolution.manifest,
+        ...(plugin.capabilities.projectContextArgs === true &&
+        resolution.projectContext !== null
+          ? { projectContext: resolution.projectContext }
+          : {}),
+      }));
+  }
+
+  /**
+   * Construct fresh degraded absence with no reusable freshness claim.
+   *
+   * @evidence contracts/common.md#principled-implementation Unavailability always returns false freshness and an empty selection.
+   * @evidence contracts/common.md#clear-and-simple-design A single constructor owns this existing outcome shape.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Degraded absence is not evidence of missing publishers.
+   * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes unavailable from resolved empty success.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation This constructor creates status data and a false predicate without native paths, I/O or platform decisions.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms Fixed empty-result construction performs no input traversal or processing-strategy choice.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work A fresh degraded result supplies no reusable computation or validity decision; its predicate is always false.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The caller owns plain returned data and a predicate capturing no external state; the constructor retains no collection, task or native handle.
+   */
+  export function unavailable(): ITtscCapabilityPluginResolution {
+    return { isCurrent: () => false, plugins: [], status: "unavailable" };
+  }
+
+  /**
+   * Preserve the resolver's plugin-load/publication catch boundary. Callers
+   * acquire authority, inspect caches and resolve tools before supplying this
+   * task, so exceptions from those earlier operations remain outside it.
+   *
+   * @evidence contracts/common.md#principled-implementation Successful tasks retain the exact returned resolution; any exception inside the supplied task becomes unavailable.
+   * @evidence contracts/common.md#clear-and-simple-design One synchronous task boundary preserves the existing try/catch without wrapping prior acquisition.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The callback is the actual load/publication operation, not a replacement runtime or native producer.
+   * @evidence contracts/common.md#meaningful-documentation Native prose states which exceptions are caught and which caller operations precede it.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation Catching the supplied task's exception prescribes no native path or process representation; actual runtime and filesystem effects remain in the resolver task.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms This wrapper chooses an outcome for one synchronous task, not that task's discovery, hashing, serialization or build algorithm. Its cost includes the full task, and no constant-time or bounded-native-work claim is made.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work The wrapper neither retries nor caches the task and decides no equivalence or freshness; those policies remain with the supplied resolver operation.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The wrapper retains neither the task nor its result after returning and acquires no handle or lease; any native resource lifetime and returned freshness closure remain with the task and caller.
+   */
+  export function fromTask(
+    task: () => ITtscCapabilityPluginResolution,
+  ): ITtscCapabilityPluginResolution {
+    try {
+      return task();
+    } catch {
+      return unavailable();
+    }
+  }
+}

package/src/plugin/internal/CapabilityResolutionFormat.ts

@@ -0,0 +1,248 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+import { SidecarEnvironment } from "../../compiler/internal/sharedHost/SidecarEnvironment";
+import { runtimeExecutableIdentity } from "../../internal/runtimeExecutableIdentity";
+import { SourceBuildCacheLayout } from "./source/SourceBuildCacheLayout";
+import { resolveSourceBuildCachePaths } from "./source/resolveSourceBuildCachePaths";
+
+/**
+ * The on-disk format of the capability-resolution cache, shared by its reader
+ * and writer so both agree on the entry's location, version tag, and how a
+ * plugin source's metadata signature is taken. What proves an entry still
+ * describes the project is the host inputs' states and the plugin sources'
+ * states, each by the rule its producer applies.
+ *
+ * @evidence contracts/common.md#principled-implementation Reader and writer share format/key and source-metadata witness rules. Metadata acceleration requires a matching device and older reported mtime, relying on native metadata/clock semantics rather than certifying arbitrary timestamp restoration or content mutation.
+ * @evidence contracts/common.md#clear-and-simple-design The namespace owns format identity and witness construction, while entry acceptance and answer production stay with their reader/writer.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Version tags and NUL delimiters encode the persistence contract; unavailable clock/device evidence causes full content proof rather than guessed reuse.
+ * @evidence contracts/common.md#meaningful-documentation Native JSDoc explains format evolution, unforgeable path separation and clock proof premises in separate paragraphs; function/tag spacing follows the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Native path joins, cache-root resolution and bigint stat device identities preserve OS-neutral filesystem behavior; clock witnesses are matched per device rather than assumed from platform names.
+ * @evidence contracts/performance.md#efficient-algorithms Key construction orders and serializes environment/name bytes, streams runtime content and delegates native ancestor/manifest/cache-layout selection. Clock witnesses create/query/remove a probe, and each source witness queries native metadata and formats numeric text; path/native/text costs remain distinct from source-content proof owned by the reader.
+ * @evidence contracts/performance.md#reuse-equivalent-work Project/version keys share one answer across requested capabilities; digest reuse additionally requires matching signature and device-clock separation.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Clock probes are call-owned and removed in finally; cache entries belong to the source-cache pruning owner rather than a process-global answer collection. Failed probe removal can leave a small file and is best effort.
+ */
+export namespace CapabilityResolutionFormat {
+  /**
+   * Cache format tag.
+   *
+   * Moves when the entry shape or the validation rule changes, so an older
+   * entry is discarded rather than read under new rules. The current format
+   * proves the directories the binaries were keyed on by the build's own rule
+   * and records only the answer of a load whose descriptors supplied the
+   * explicit external-read declaration. This is a producer premise, not
+   * detection of every omitted read. Its key includes the complete descriptor
+   * environment and runtime content identity, since either can change a
+   * factory's capability declarations. It requires an explicit completed
+   * runtime observation envelope, so a partial side channel cannot authorize an
+   * answer for reuse, and the shared module recorder's independent completion
+   * proof, including its public require.resolve hook capability. Mapped import
+   * candidates retain their pre-resolution witnesses; entries from before that
+   * producer rule must be discovered again even when their later hashes match.
+   */
+  const FORMAT = "ttsc-capability-resolution-v7";
+
+  /**
+   * The character that joins fields a path could otherwise forge.
+   *
+   * A path cannot contain it, which is the whole reason it is the separator:
+   * with a space, a file named `a 1 2` states the same string as a one-byte
+   * file named `a`, and an edit to either would read as no edit at all. Built
+   * rather than written literally, because a source file carrying a raw NUL is
+   * one Git classifies as binary — which silently exempts it from this
+   * repository's end-of-line contract and leaves it with no textual diff for a
+   * reviewer.
+   */
+  const SEPARATOR = String.fromCharCode(0);
+
+  /**
+   * The version string an entry records: the format tag joined with the ttsc
+   * version, so a ttsc upgrade invalidates every entry written by another one.
+   *
+   * @evidence contracts/common.md#principled-implementation Joining the format revision and product version rejects entries written under a different producer or validation contract.
+   * @evidence contracts/common.md#clear-and-simple-design A shared function prevents reader and writer from constructing competing version identities.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The revision literal is cache protocol identity rather than an expected fixture version.
+   * @evidence contracts/common.md#meaningful-documentation Native JSDoc states the version-change invalidation effect, with descriptive and acknowledgment paragraphs separated under the documentation skill.
+   *
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation This pure cache-version string has no native path, process or platform interpretation; namespace filesystem operations own that obligation.
+   *
+   * @evidence contracts/performance.md#efficient-algorithms One concatenation constructs a string proportional to the supplied version length, without intermediate parsing.
+   *
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work This pure identity formatter owns no expensive computation cache or reusable attempt.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources It returns caller-owned text and acquires no retained population or resource.
+   */
+  export function formatVersion(version: string): string {
+    return `${FORMAT}:${version}`;
+  }
+
+  /**
+   * Where the entry for this project lives, or `null` when no cache root can be
+   * resolved or the descriptor runtime cannot be identified.
+   *
+   * Keyed on the project rather than on the capability: the walk it replaces
+   * discovers every configured plugin, so one entry answers for all of them and
+   * a second consumer can reuse that entry for another capability, while still
+   * paying its authority and freshness checks. The complete environment and
+   * runtime content proof distinguish evaluation authorities even when project
+   * file content stays unchanged.
+   *
+   * @evidence contracts/common.md#principled-implementation SHA-256 over project/config identity, canonical descriptor environment and actual executable content/lexical/physical proof selects an authority-specific entry; unproved runtime/storage returns null rather than trusting restored metadata.
+   * @evidence contracts/common.md#clear-and-simple-design Cache-root policy is delegated once and this function adds only the capability-entry key and layout.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The NUL separator prevents ambiguous path-field concatenation; fallback means uncached resolution rather than a guessed answer.
+   * @evidence contracts/common.md#meaningful-documentation Native JSDoc explains null storage and project-wide reuse across capabilities; descriptive/tag separation follows the documentation skill.
+   * @evidence contracts/portability.md#os-neutral-implementation path.resolve/path.join and the source cache owner implement OS-neutral native path construction; runtime selection reads the supplied environment with Windows case-insensitive name semantics.
+   * @evidence contracts/performance.md#efficient-algorithms Environment ordering has O(e log e) comparisons whose name bytes matter; full environment/path/identity text is serialized and hashed. Executable content uses a fixed read buffer, but native metadata/path and escaping identity text remain. Delegated root selection can walk ancestors/read manifests/inspect cache layout; no plugin-source directory scan is performed here.
+   * @evidence contracts/performance.md#reuse-equivalent-work All capabilities for the same project identity use one entry because discovery computes their complete plugin set together.
+   *
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The locator retains no handle or cache entry; its executable-proof owner attempts transient descriptor closure and refuses unproved observations on failure. Environment/serialized identity text is call-owned and the returned path does not pin future authority; persistence/pruning own stored lifetime.
+   */
+  export function resolutionFile(options: {
+    /** Invocation directory included in the project-entry key. */
+    cwd: string;
+
+    /** Selected config identity supplied by capability discovery. */
+    tsconfig: string;
+
+    /** Effective environment selecting workspace-local or explicit storage. */
+    env?: NodeJS.ProcessEnv;
+  }): string | null {
+    const environment = SidecarEnvironment.merge(options.env ?? process.env);
+    const runtime =
+      SidecarEnvironment.read(environment, "TTSC_NODE_BINARY") ??
+      process.execPath;
+    if (!path.isAbsolute(runtime)) return null;
+    let root: string;
+    let runtimeIdentity: string;
+    try {
+      const observed = runtimeExecutableIdentity(runtime);
+      if (observed === undefined) return null;
+      runtimeIdentity = observed;
+      root = resolveSourceBuildCachePaths(
+        path.resolve(options.cwd),
+        undefined,
+        environment,
+      ).root;
+    } catch {
+      return null;
+    }
+    const key = crypto
+      .createHash("sha256")
+      .update(path.resolve(options.cwd))
+      .update(SEPARATOR)
+      .update(options.tsconfig)
+      .update(SEPARATOR)
+      .update(
+        JSON.stringify(
+          Object.entries(environment)
+            .filter(
+              (entry): entry is [string, string] => entry[1] !== undefined,
+            )
+            .sort(([left], [right]) =>
+              left < right ? -1 : left > right ? 1 : 0,
+            ),
+        ),
+      )
+      .update(SEPARATOR)
+      .update(runtimeIdentity)
+      .digest("hex");
+    return path.join(
+      root,
+      SourceBuildCacheLayout.CAPABILITY_CACHE_DIRNAME,
+      `${key}.json`,
+    );
+  }
+
+  /**
+   * A clock reference for plugin source signatures, minted by a write of the
+   * cache's own beside the entry: the modification stamp a fresh probe file got
+   * there, by the device that reported it.
+   *
+   * A stamp strictly older than the same device's fresh reference satisfies
+   * this cache's separation policy. Reuse still assumes the filesystem's
+   * reported metadata reflects writes; the comparison cannot certify arbitrary
+   * timestamp restoration or future clock behavior. The probe is the cache's
+   * own file, named for this call, and removal is attempted at once, so
+   * concurrent readers never lend each other a reference. A failed write, or a
+   * plugin source on another device, leaves nothing separable, and the proof
+   * reads the files.
+   *
+   * @param entry The entry file, whose directory the probe is written in.
+   * @evidence contracts/common.md#principled-implementation A unique freshly-written file supplies its native device/mtime reference; acquisition failure clears the witness, and the source observer requires a matching device and strictly older reported stamp under the metadata policy.
+   * @evidence contracts/common.md#clear-and-simple-design The function returns only device-to-stamp evidence and owns its transient probe from creation through cleanup.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Random probe identity avoids borrowing a concurrent call's witness; failed acquisition does not substitute wall-clock guesses for device evidence.
+   * @evidence contracts/common.md#meaningful-documentation Native JSDoc explains ended ticks, cross-device refusal and probe lifetime in separate paragraphs; tag separation follows the documentation skill.
+   * @evidence contracts/portability.md#os-neutral-implementation Native joins and bigint lstat use the actual filesystem's device/stamp values; no fixed timestamp precision or OS-specific temp path is assumed.
+   * @evidence contracts/performance.md#efficient-algorithms Probe path/UUID/hrtime text construction and mkdir/write/lstat/removal queries produce a witness without reading plugin source bytes; native path/directory work remains and is not bounded by source count.
+   *
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work Each proof needs a fresh clock reference; sharing an earlier probe would defeat the rollback/separation premise.
+   *
+   * @evidence contracts/performance.md#bound-retention-and-release-resources The unique call-owned probe is removed in finally even after acquisition failure; removal is best effort and the returned map contains at most its single observed device.
+   */
+  export function clockReference(entry: string): ReadonlyMap<bigint, bigint> {
+    const references = new Map<bigint, bigint>();
+    const probe = path.join(
+      path.dirname(entry),
+      `clock-${process.pid}-${crypto.randomUUID()}.probe`,
+    );
+    try {
+      fs.mkdirSync(path.dirname(probe), { recursive: true });
+      fs.writeFileSync(probe, `${process.hrtime.bigint()}\n`);
+      const stats = fs.lstatSync(probe, { bigint: true });
+      references.set(stats.dev, stats.mtimeNs);
+    } catch {
+      references.clear();
+    } finally {
+      try {
+        fs.rmSync(probe, { force: true });
+      } catch {
+        // A leftover probe contains this call's hrtime text, not source data.
+      }
+    }
+    return references;
+  }
+
+  /**
+   * One plugin source file's metadata signature, and whether its stamp is
+   * separable from `reference`, for `pluginSourceFilesSignature`.
+   *
+   * The files the digest reads are regular files (`collectPluginSourceFiles`),
+   * so these fields are the observer's metadata signature. Native metadata
+   * reflecting a write/replacement is a reuse premise; the signature is not
+   * itself a content hash or proof against arbitrary timestamp restoration.
+   *
+   * @param reference The clock reference minted for this proof.
+   * @evidence contracts/common.md#principled-implementation lstat device/inode/link/mode/size/timestamps form the regular-file metadata signature; strict mtime-before-reference marks separation for a matching device under the cache's native metadata policy, without observing content.
+   * @evidence contracts/common.md#clear-and-simple-design A closure carries one proof's device references and maps each requested file to signature/separation together.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Unreadable files return no witness, and unmatched device or same/newer stamps cannot authorize digest reuse.
+   * @evidence contracts/common.md#meaningful-documentation Native JSDoc states the regular-file premise and reference origin, with separate acknowledgment prose following the documentation skill.
+   * @evidence contracts/portability.md#os-neutral-implementation Metadata comes from native bigint lstat and actual device IDs; separators join numeric fields only and no host path is manually parsed.
+   * @evidence contracts/performance.md#efficient-algorithms Each invocation performs native path/lstat work and formats seven bigint fields without reading content; fixed field count does not remove native lookup or numeric-text costs.
+   * @evidence contracts/performance.md#reuse-equivalent-work The closure reuses one reference map across files in the same proof, while each file's current metadata is read anew.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources The closure retains the supplied reference map until its consumer releases it; clockReference supplies at most one entry, but arbitrary callers can supply larger or mutable maps. No file handle/global source population is retained and reference immutability is a caller premise.
+   */
+  export function sourceEvidence(
+    reference: ReadonlyMap<bigint, bigint>,
+  ): (file: string) => { separable: boolean; signature: string } | undefined {
+    return (file) => {
+      try {
+        const stats = fs.lstatSync(file, { bigint: true });
+        const minted = reference.get(stats.dev);
+        return {
+          separable: minted !== undefined && stats.mtimeNs < minted,
+          signature: [
+            stats.dev,
+            stats.ino,
+            stats.nlink,
+            stats.mode,
+            stats.size,
+            stats.mtimeNs,
+            stats.ctimeNs,
+          ].join(":"),
+        };
+      } catch {
+        return undefined;
+      }
+    };
+  }
+}

package/src/plugin/internal/ITtscCapabilityPluginSource.ts

@@ -0,0 +1,37 @@
+/**
+ * One plugin source directory as the capability-resolution cache records it:
+ * the state the load reported for it, and, when the entry's writer could vouch
+ * for it, the digest of its files with the metadata signature they were read
+ * under.
+ *
+ * The state is what the cached binary path stands for, and a read proves it by
+ * the build's own rule (`pluginSourceStateHolds`). Reading every file of a
+ * plugin's module is costly for a large module, on every read, so a read whose
+ * signature still matches, and is still separable from a clock reference minted
+ * then, hands the recorded digest to the proof instead, and only the build
+ * environment is read again. `digest` and `signature` are recorded together or
+ * not at all.
+ *
+ * @evidence contracts/common.md#principled-implementation The authoritative source state remains required; optional digest/signature are a jointly recorded acceleration witness accepted only under the reader's metadata and clock proof.
+ * @evidence contracts/common.md#clear-and-simple-design The record separates the build identity from optional file-read reuse evidence instead of treating metadata alone as the source state.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Absent witnesses require the full source proof; a matching timestamp alone is not fabricated permission to reuse the binary state.
+ * @evidence contracts/common.md#meaningful-documentation Native JSDoc explains paired optional fields, read/write proof responsibility and the clock-separation premise; member and tag separation follow the documentation skill.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources A type declaration acquires and holds no runtime resource.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms A type declaration chooses no processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A type declaration computes nothing, so there is no work to share.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation This type declaration describes a data shape only; it opens no file, builds no path and branches on no platform.
+ */
+export interface ITtscCapabilityPluginSource {
+  /** The directory's state, as `pluginSourceState` reports it. */
+  state: string;
+
+  /** The digest of the directory's files, as `pluginSourceDigest` reads it. */
+  digest?: string;
+
+  /**
+   * The metadata signature of exactly those files
+   * (`pluginSourceFilesSignature`), taken before and after the digest was read
+   * and equal both times, with every stamp separable.
+   */
+  signature?: string;
+}

package/src/plugin/internal/ITtscCapabilityResolutionEntry.ts

@@ -0,0 +1,57 @@
+import type { ITtscCapabilityPluginSource } from "./ITtscCapabilityPluginSource";
+import type { ITtscCapabilityResolutionPlugin } from "./ITtscCapabilityResolutionPlugin";
+
+/**
+ * The answer `resolveCapabilityPlugins` produced for one project, and the exact
+ * recorded premises the reader rechecks before reusing it.
+ *
+ * The answer is serializable: a binary path, a capability map, a manifest
+ * string — which is why it is cached here and not one layer down.
+ * `loadProjectPlugins` returns live plugin descriptors the compiler drives, and
+ * writing those to disk would be caching a different, much larger thing.
+ *
+ * @evidence contracts/common.md#principled-implementation A serializable answer is paired with evaluation-time input hashes/realpaths, plugin build states and format/version identity so reuse can be refused when any premise changes.
+ * @evidence contracts/common.md#clear-and-simple-design The cache entry contains the narrow capability answer and its proof data, leaving live descriptor execution state out of persistence.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The reader compares stored source states against the shared selected-source/environment recipe rather than accepting an existing executable alone. Metadata-assisted digest reuse remains conditional on its observation premises; executable existence does not authenticate its bytes.
+ * @evidence contracts/common.md#meaningful-documentation Native JSDoc explains why this answer is persisted, source/environment invalidation and verbatim manifest payloads; paragraphs, member and tag spacing follow the documentation skill.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources A type declaration acquires and holds no runtime resource.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms A type declaration chooses no processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A type declaration computes nothing, so there is no work to share.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation This type declaration describes a data shape only; it opens no file, builds no path and branches on no platform.
+ */
+export interface ITtscCapabilityResolutionEntry {
+  /** Cache format plus the ttsc build that wrote it. */
+  version: string;
+
+  /** Paths whose state decides whether this answer is still the answer. */
+  hostInputs: string[];
+
+  /** Content hash per host input, `null` for one that does not exist. */
+  hostInputHashes: Record<string, string | null>;
+
+  /** Recorded resolved-path observation per host input, or null if unavailable. */
+  hostInputRealpaths: Record<string, string | null>;
+
+  /**
+   * The state of every directory the plugin binaries were keyed on, as the load
+   * reported it (`pluginSources`: each module root, linked package, and
+   * contributor source, with the Go build environment there).
+   *
+   * An edit in the selected source population or a changed build-environment
+   * observation can change this state while the host inputs remain unchanged.
+   * The entry can still name a retained old executable, so the reader compares
+   * these states through `pluginSourceStateHolds`. Files outside the build's
+   * selected source population are not universally covered, and matching state
+   * or executable existence does not authenticate the executable's bytes.
+   */
+  pluginSources: Record<string, ITtscCapabilityPluginSource>;
+
+  /** The `--plugins-json` payload, verbatim. */
+  manifest: string;
+
+  /** The `--project-context-json` payload, or `null` when none was wanted. */
+  projectContext: string | null;
+
+  /** One entry per configured native plugin, in configured order. */
+  plugins: ITtscCapabilityResolutionPlugin[];
+}

package/src/plugin/internal/ITtscCapabilityResolutionPlugin.ts

@@ -0,0 +1,22 @@
+/**
+ * One plugin as the capability-resolution cache records it.
+ *
+ * The cache answers "which plugins declare capability X" without evaluating
+ * every descriptor again; each recorded plugin keeps what that answer needs.
+ *
+ * @evidence contracts/common.md#principled-implementation Executable path plus named boolean opt-ins preserves the capability-selection answer without retaining a live factory or descriptor graph.
+ * @evidence contracts/common.md#clear-and-simple-design Two fields expose only dispatch identity and supported behavior, with build/input validity owned by the enclosing cache entry.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Capabilities come from the descriptor's declaration rather than inference from a plugin name or binary basename.
+ * @evidence contracts/common.md#meaningful-documentation Native JSDoc describes the narrower cache purpose and absolute executable identity; member spacing and separate acknowledgment prose follow the documentation skill.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources A type declaration acquires and holds no runtime resource.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms A type declaration chooses no processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A type declaration computes nothing, so there is no work to share.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation This type declaration describes a data shape only; it opens no file, builds no path and branches on no platform.
+ */
+export interface ITtscCapabilityResolutionPlugin {
+  /** Absolute path of the plugin's native sidecar executable. */
+  binary: string;
+
+  /** The capabilities the plugin's descriptor declared, by name. */
+  capabilities: Record<string, boolean>;
+}