ttsc 0.30.3 → 0.31.0

package/src/plugin/internal/load/moduleResolutionBaseSelects.ts

@@ -0,0 +1,59 @@
+import { RESOLUTION_INPUT_RECORDER_PATH } from "./RESOLUTION_INPUT_RECORDER_PATH";
+
+/**
+ * Whether a module-resolution base is the one a completed resolution selected:
+ * the resolved file is the base itself, one of the spellings a resolution
+ * probes for it (its `extensions`, its manifest, an index file, a TypeScript
+ * source a JavaScript specifier is served from), or lies inside the base as a
+ * directory.
+ *
+ * A bare specifier is looked up in every search root in order
+ * (`require.resolve.paths`), and the lookup stops at the first root whose
+ * package it selects. Candidates in the roots after that one were never
+ * consulted, so they cannot have steered the resolution: their appearance can
+ * only matter once the selected package stops resolving, and that package is an
+ * input already. A search root below a directory whose metadata churns, such as
+ * a home directory or the shared temporary directory, therefore cannot cost a
+ * descriptor its cache proof while its package resolves nearer.
+ *
+ * The rule is the resolution input recorder's
+ * (`RESOLUTION_INPUT_RECORDER_PATH`), which every evaluator that records
+ * resolution inputs takes it from: the ttsx descriptor evaluator, the isolated
+ * CommonJS evaluator, a utility plugin's config loader, and the loader's own
+ * candidate expansion and plugin discovery.
+ *
+ * Candidate bases require successful native realpath. The selected absolute
+ * path or file URL uses realpath when available, but preserves normalized
+ * lexical spelling if that query fails. Selection is not an existence or
+ * frozen-identity certificate for the completed resolver's selected file.
+ *
+ * @param base The candidate base: a package directory, or a path the specifier
+ *   names without its extension.
+ * @param resolvedFile The file the resolution selected, a path or a file URL,
+ *   or `undefined` when it failed.
+ * @param extensions The extensions the evaluator's resolution probes.
+ * @evidence contracts/common.md#principled-implementation The shared recorder compares the completed resolver's selected path against canonical candidate file/directory spellings; selected-path canonicalization can fall back to native lexical spelling, and candidate canonicalization failure refuses that candidate.
+ * @evidence contracts/common.md#clear-and-simple-design This typed adapter delegates one selection rule to the shared recorder instead of maintaining separate resolver guesses in each evaluator.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The adapter invokes the recorder's exported query without replacing foreign methods or reconstructing a package resolver from guessed target paths.
+ * @evidence contracts/common.md#meaningful-documentation Native JSDoc explains stopping semantics, canonical candidate admission, selected lexical fallback and parameter vocabularies in distinct paragraphs under the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation The shared rule normalizes native paths/file URLs and canonicalizes candidates; ambiguous folded containment requires native nonzero device/inode agreement. Selected-path realpath failure preserves lexical spelling. Callers supply extension policy without guessing it from OS names or POSIX separators.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Delegated candidate arrays, canonical strings and synchronous metadata are query-local; this adapter retains no selected-path history or acquired handle.
+ * @evidence contracts/performance.md#efficient-algorithms Delegation normalizes the selected path/URL, materializes all extension/substitution/manifest/index candidates, then scans until selection. Native realpath/stat, path-text comparisons and possible folded-containment ancestor reconstruction depend on candidate count and native path/topology; one adapter call is not constant-cost.
+ * @evidence contracts/performance.md#reuse-equivalent-work The recorder reuses each candidate canonicalization for equality/containment within the query. Its module is loaded once, but mutable filesystem selection is observed per call rather than cached as a cross-request answer.
+ */
+export function moduleResolutionBaseSelects(
+  base: string,
+  resolvedFile: string | undefined,
+  extensions: readonly string[],
+): boolean {
+  return RECORDER.moduleResolutionBaseSelects(base, resolvedFile, extensions);
+}
+
+/** The recorder, loaded once as a module of its own. */
+const RECORDER = require(RESOLUTION_INPUT_RECORDER_PATH) as {
+  moduleResolutionBaseSelects(
+    base: string,
+    resolvedFile: string | undefined,
+    extensions: readonly string[],
+  ): boolean;
+};

package/src/plugin/internal/load/observeImportSearchRoots.ts

@@ -0,0 +1,42 @@
+import { RESOLUTION_INPUT_RECORDER_PATH } from "./RESOLUTION_INPUT_RECORDER_PATH";
+
+/**
+ * Fingerprint the search roots a `#` import of `parent` can resolve a bare
+ * package through, before the resolution runs.
+ *
+ * A `#` specifier is looked up in the importer's own package `imports`, which
+ * may map it to a bare package that Node then looks up through the ordinary
+ * `node_modules` search from the importer. Which package that is can be named
+ * only once the resolution selected it, so the candidates of the nearer roots
+ * are observed afterwards; each root's own metadata, taken here, is what shows
+ * a nearer package that appeared in between. Pass the result to
+ * `visitImportMappedCandidates`.
+ *
+ * The rule is the resolution input recorder's
+ * (`RESOLUTION_INPUT_RECORDER_PATH`).
+ *
+ * @param parent The importer, a path or a file URL.
+ * @returns Each search root's metadata witness or unavailable `undefined`, by
+ *   native path. Returns `undefined` when the importer is not an absolute path
+ *   or convertible file URL; an absolute spelling need not exist.
+ * @evidence contracts/common.md#principled-implementation Taking search-root metadata before imports resolution can expose a nearer package that appears before the selected target is known; the later candidate visitor consumes this witness.
+ * @evidence contracts/common.md#clear-and-simple-design The adapter returns the shared recorder's pre-resolution witness without duplicating Node's imports mapping or candidate expansion.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts This adapter invokes the recorder's exported metadata query without replacing foreign methods or reproducing imports resolution.
+ * @evidence contracts/common.md#meaningful-documentation Native JSDoc explains why witnesses precede selection and how the visitor uses them, plus the non-file result; paragraph/tag separation follows the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation The recorder accepts native paths or file URLs and observes actual search-root metadata, supporting OS-neutral identity without POSIX-only URL/path conversion in this adapter.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The witness Map transfers to its caller, which owns the resolution-window lifetime; this adapter keeps no history, cache or handle. Delegated synchronous metadata queries retain no open descriptor.
+ * @evidence contracts/performance.md#efficient-algorithms Native path/URL normalization and Node search-root construction precede one metadataSignature query per root. Missing branches can walk to existing ancestors, and links incur target stat; complete path/signature text and root/ancestor counts drive query and Map storage costs.
+ * @evidence contracts/performance.md#reuse-equivalent-work The returned witness Map is shared with the matching completion visitor rather than replacing its pre-resolution observations with later metadata. Another resolution window obtains fresh witnesses, not a cross-request cached answer.
+ */
+export function observeImportSearchRoots(
+  parent: string | undefined,
+): ReadonlyMap<string, string | undefined> | undefined {
+  return RECORDER.observeImportSearchRoots(parent);
+}
+
+/** The recorder, loaded once as a module of its own. */
+const RECORDER = require(RESOLUTION_INPUT_RECORDER_PATH) as {
+  observeImportSearchRoots(
+    parent: string | undefined,
+  ): ReadonlyMap<string, string | undefined> | undefined;
+};

package/src/plugin/internal/load/pluginLabel.ts

@@ -0,0 +1,28 @@
+import type { ITtscPlugin } from "../../../structures/ITtscPlugin";
+import type { ITtscProjectPluginConfig } from "../../../structures/ITtscProjectPluginConfig";
+
+/**
+ * Choose the descriptor label used by loader diagnostics.
+ *
+ * @evidence contracts/common.md#principled-implementation Nonempty descriptor name wins, then transform specifier and finally the indexed fallback; this identity labels diagnostics without selecting native ownership.
+ * @evidence contracts/common.md#clear-and-simple-design One value selector is shared by native admission and downstream loader records.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Plugin names remain diagnostic labels and never confer built-in compiler behavior.
+ * @evidence contracts/common.md#meaningful-documentation The headline states the stable fallback identity used by callers.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The selected string or formatted fallback transfers immediately to the caller; no label history, handle or retained population is owned here.
+ * @evidence contracts/performance.md#efficient-algorithms Name and specifier type/length checks avoid scanning their contents; an absent selection formats the scalar index. Property reads follow ordinary descriptor semantics and do not bound user-defined accessor work.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Label selection defines no shared producer or cross-request descriptor-answer identity; callers own their mutable descriptor and config.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Name/specifier/index values are diagnostic data; this selector does not interpret native paths or acquire filesystem/process capabilities.
+ */
+export function pluginLabel(
+  plugin: ITtscPlugin,
+  config: ITtscProjectPluginConfig,
+  index: number,
+): string {
+  if (typeof plugin.name === "string" && plugin.name.length !== 0) {
+    return plugin.name;
+  }
+  if (typeof config.transform === "string" && config.transform.length !== 0) {
+    return config.transform;
+  }
+  return `#${index}`;
+}

package/src/plugin/internal/load/realpathHostInput.ts

@@ -0,0 +1,22 @@
+import fs from "node:fs";
+
+/**
+ * Physical path selected by a host input, or null while it is unresolved.
+ *
+ * @evidence contracts/common.md#principled-implementation Native realpath reports the target the filesystem currently selects; any unresolved query returns null so cache comparison cannot assume the lexical spelling is its physical target.
+ * @evidence contracts/common.md#clear-and-simple-design One nullable observation gives all host-input snapshot consumers the same failure policy.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Canonicalization failure does not reuse an old answer, rewrite filesystem globals or guess a platform target.
+ * @evidence contracts/common.md#meaningful-documentation Native JSDoc states physical-target and unresolved semantics, with separate acknowledgment prose following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation fs.realpathSync.native handles the OS's own path/link semantics; the implementation avoids POSIX separator processing and blanket case folding.
+ * @evidence contracts/performance.md#efficient-algorithms One native realpath query avoids content reads or a separate user-space ancestor walk; native path/link resolution work and returned target bytes depend on supplied path/topology rather than a constant-time query count.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A fresh target observation is required for cache validity; this function retains no realpath cache.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The synchronous query returns a caller-owned string or null and retains no handle or population.
+ */
+export function realpathHostInput(file: string): string | null {
+  try {
+    return fs.realpathSync.native(file);
+  } catch {
+    return null;
+  }
+}

package/src/plugin/internal/load/realpathHostInputPaths.ts

@@ -0,0 +1,27 @@
+import path from "node:path";
+
+import { realpathHostInput } from "./realpathHostInput";
+
+/**
+ * The physical target of each host input, keyed by its resolved path; `null`
+ * where it does not resolve. Recorded beside the content hashes because
+ * retargeting a symlinked input changes what it names without changing any
+ * bytes a hash has seen yet.
+ *
+ * @evidence contracts/common.md#principled-implementation Each resolved lexical key retains the current physical target or unresolved null, preserving symlink retargeting as distinct from unchanged content.
+ * @evidence contracts/common.md#clear-and-simple-design The collection mapper delegates one-path observation and leaves content hashing and proof acceptance separate.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Failed canonicalization remains null instead of borrowing a recorded target or assuming the lexical path is physical identity.
+ * @evidence contracts/common.md#meaningful-documentation Native JSDoc explains unresolved values and why realpaths accompany hashes, with prose/tag separation following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Native path.resolve and realpath observation support OS-neutral symlink/junction identity without blanket lowercasing or slash-only parsing.
+ * @evidence contracts/performance.md#efficient-algorithms Each input is natively normalized for its lexical key and receives one delegated current realpath query. Path/target text and native query work accompany input count; mapped pairs and the result coexist transiently, and duplicate resolved keys overwrite earlier observations rather than avoiding their queries.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Current physical targets must be observed anew to detect retargeting; this mapper owns no canonicalization cache.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources It returns caller-owned observations and retains no cross-call population or resource.
+ */
+export function realpathHostInputPaths(
+  files: readonly string[],
+): Record<string, string | null> {
+  return Object.fromEntries(
+    files.map((file) => [path.resolve(file), realpathHostInput(file)]),
+  );
+}

package/src/plugin/internal/load/rejectJsTransformFunctions.ts

@@ -0,0 +1,23 @@
+/**
+ * Reject unsupported JavaScript transforms on a descriptor object.
+ *
+ * @evidence contracts/common.md#principled-implementation Membership checks preserve the original rejection even for inherited or undefined transform properties; no JavaScript implementation enters the Go pipeline.
+ * @evidence contracts/common.md#clear-and-simple-design One validation call owns exactly the two prohibited descriptor keys and its named-specifier diagnostic.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts This is the actual loader guard, not a test-side reconstruction or native compilation substitute.
+ * @evidence contracts/common.md#meaningful-documentation The headline and key-presence explanation state the rejection responsibility without describing internal machinery.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources This descriptor predicate retains no cache, handle or historical result; a thrown diagnostic transfers to the caller.
+ * @evidence contracts/performance.md#efficient-algorithms At most two key-membership probes avoid enumerating unrelated descriptor fields. Native JavaScript membership follows prototype or proxy semantics, and failure formats the supplied specifier text; no bound on user-defined proxy work is established.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work No shared producer or cross-request descriptor-answer identity is owned by this immediate membership guard.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Descriptor membership and error text do not interpret native paths, discover capabilities or launch processes; the specifier is diagnostic data.
+ */
+export function rejectJsTransformFunctions(
+  specifier: string,
+  candidate: object,
+): void {
+  if ("transformSource" in candidate || "transformOutput" in candidate) {
+    throw new Error(
+      `ttsc: plugin "${specifier}" declares unsupported JS transform functions; ` +
+        "declare a native backend instead",
+    );
+  }
+}

package/src/plugin/internal/load/requirePluginSource.ts

@@ -0,0 +1,34 @@
+import fs from "node:fs";
+
+/**
+ * Require the selected source to exist and retain descriptor-path guidance.
+ *
+ * @evidence contracts/common.md#principled-implementation Actual filesystem existence determines admission; the unchanged diagnostic explains the supported factory-context alternatives when a descriptor path is absent.
+ * @evidence contracts/common.md#clear-and-simple-design One path probe owns this preflight decision; Go module/package classification remains the following loader operation.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Uses the real selected source path and filesystem rather than filenames or a fabricated loader result.
+ * @evidence contracts/common.md#meaningful-documentation The owning headline and retained diagnostic explain how callers correct a missing path.
+ *
+ * @evidence contracts/portability.md#os-neutral-implementation Accepts the caller-selected native path directly at fs.existsSync; diagnostic path spelling is retained and no slash assumptions or shell operations are introduced.
+ * @evidence contracts/performance.md#efficient-algorithms One native existence probe avoids source-tree traversal; absent-path diagnostics copy source and label text plus fixed guidance, so cost/storage include native path and supplied label lengths.
+ * @evidence contracts/performance.md#reuse-equivalent-work The operation reobserves caller-owned filesystem state per request because a previous absence or presence does not establish continued validity.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The synchronous existence query opens no source stream and this guard retains no cache, handle or historical presence answer; a thrown diagnostic transfers to its caller.
+ */
+export function requirePluginSource(source: string, label: string): void {
+  if (!fs.existsSync(source)) {
+    // A descriptor factory runs without CommonJS globals when ttsc loads it
+    // through ttsx or as ESM — `__dirname`/`__filename`/`require` are undefined,
+    // so a `source` derived from them mis-resolves (often against cwd) and lands
+    // here. Name that failure mode explicitly instead of leaving a bare
+    // not-found path: the breakage is otherwise silent.
+    throw new Error(
+      `ttsc: plugin "${label}" source does not exist: ${source}\n` +
+        `  Plugin descriptors run without CommonJS globals: __dirname, __filename, ` +
+        `and require are undefined when ttsc loads a descriptor through ttsx or as ESM. ` +
+        `If this path was derived from one of them, use context.dirname / ` +
+        `context.filename (the descriptor's own directory and file, populated in ` +
+        `every load mode), or resolve it from context.projectRoot, e.g. ` +
+        `createRequire(path.join(context.projectRoot, "package.json"))` +
+        `.resolve("<your-package>/package.json").`,
+    );
+  }
+}

package/src/plugin/internal/load/resolveNativeSource.ts

@@ -0,0 +1,42 @@
+import { SidecarEnvironment } from "../../../compiler/internal/sharedHost/SidecarEnvironment";
+import type { ITtscPlugin } from "../../../structures/ITtscPlugin";
+import type { ITtscProjectPluginConfig } from "../../../structures/ITtscProjectPluginConfig";
+import { NativeSourcePackages } from "../source/NativeSourcePackages";
+import { resolvePluginGoModule } from "../source/resolvePluginGoModule";
+import { pluginLabel } from "./pluginLabel";
+import { requirePluginSource } from "./requirePluginSource";
+
+/**
+ * Resolve the Go module and Go-owned proposed native kind of a source.
+ *
+ * Nested transform proposals preserve admitted source layout under the generic
+ * host's root manifests, with the tool pinned at the original module. Root and
+ * check sources retain their own manifests. The loader must confirm executable
+ * proposals in their full owning module and linked proposals inside each chosen
+ * actual host; this adapter cannot choose that host. Go errors and empty
+ * production-file selections are terminal.
+ *
+ * @evidence contracts/common.md#principled-implementation Real source admission and module discovery precede actual prospective-context Go metadata; only an error-free production package proposes executable or linked ownership, while final actual-context admission belongs to the loader/build.
+ * @evidence contracts/common.md#clear-and-simple-design Source/module admission and selected package observation have separate owners; callers may supply this load's batched observation.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No lexical scanner, filename exception or partial constraint parser substitutes for the selected Go tool.
+ * @evidence contracts/common.md#meaningful-documentation Native prose describes Go-owned package selection and erroneous-name rejection.
+ * @evidence contracts/portability.md#os-neutral-implementation Native module/path and effective-environment owners preserve platform identity; Go interprets target selection.
+ * @evidence contracts/performance.md#efficient-algorithms Module discovery is bounded; a missing supplied observation delegates contextual copy/workspace setup and one metadata command, without dependency compilation.
+ * @evidence contracts/performance.md#reuse-equivalent-work Loader-supplied observations batch equivalent packages within one load; direct calls reobserve current inputs and retain no cross-load cache.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Delegated metadata scratch has retirement-aware cleanup; returned module/kind strings transfer to the caller and no source handle is retained here.
+ */
+export function resolveNativeSource(
+  source: string,
+  plugin: ITtscPlugin,
+  config: ITtscProjectPluginConfig,
+  index: number,
+  options?: { env?: NodeJS.ProcessEnv; observation?: NativeSourcePackages.Package },
+): { kind: "executable" | "linked"; moduleRoot: string } {
+  const label = pluginLabel(plugin, config, index);
+  requirePluginSource(source, label);
+  const { moduleRoot } = resolvePluginGoModule(source, label);
+  const observation = options?.observation ?? NativeSourcePackages.propose([
+    { source, label, ownModule: plugin.stage === "check" },
+  ], SidecarEnvironment.merge(options?.env ?? process.env))[0]!.observation;
+  return { kind: NativeSourcePackages.kind(observation, label), moduleRoot };
+}

package/src/plugin/internal/load/validatePluginContributors.ts

@@ -0,0 +1,102 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import type { ITtscPlugin } from "../../../structures/ITtscPlugin";
+import { PluginPackageResolution } from "./PluginPackageResolution";
+
+/**
+ * Validate contributor records before native host compilation.
+ *
+ * The source preflight requires an immediate regular filename ending in .go but
+ * not _test.go. It does not parse package syntax, build constraints or platform
+ * suffixes; actual Go compilation owns buildability.
+ *
+ * @evidence contracts/common.md#principled-implementation Ordered record checks establish unique accepted names, absolute observed source directories and a regular non-test .go filename before best-effort physical normalization. These checks do not certify Go package buildability or freeze filesystem identity.
+ * @evidence contracts/common.md#clear-and-simple-design One traversal owns contributor admission; a private directory predicate isolates regular non-test filename discovery.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The actual loader now calls this unchanged guard; unit callers do not replace contributor compilation or transport assertions.
+ * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes filename preflight from actual buildability; returned source strings use best-effort native realpath and can retain original spelling on failure.
+ *
+ * @evidence contracts/portability.md#os-neutral-implementation Native path.isAbsolute, fs.stat, readdir and resolveRealPath preserve platform path and physical-source distinctions rather than using POSIX string heuristics.
+ * @evidence contracts/performance.md#efficient-algorithms Each contributor is checked with indexed seen-name membership and one direct directory listing, without recursive payload scans. Name regex/hash and path/entry text, native existence/stat/realpath operations and complete immediate-entry materialization contribute cost; record count alone does not bound that work.
+ * @evidence contracts/performance.md#reuse-equivalent-work Within one request the seen-name set avoids repeated name searches; filesystem admission is reobserved because callers may mutate contributor source between requests.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Name sets and directory listings are invocation-local; returned ordered records transfer to the caller. Their bytes grow with accepted records and names/paths, while a listing materializes all immediate entries; no population ceiling or historical cache is owned here and synchronous filesystem APIs retain no open handle.
+ */
+export function validatePluginContributors(
+  plugin: ITtscPlugin,
+): readonly { name: string; source: string }[] | undefined {
+  const contributors = plugin.contributors;
+  if (contributors === undefined) return undefined;
+  if (!Array.isArray(contributors)) {
+    throw new Error(
+      `ttsc: plugin "${plugin.name}" "contributors" must be an array of { name, source } entries`,
+    );
+  }
+  if (contributors.length === 0) return undefined;
+  const seen = new Set<string>();
+  const out: { name: string; source: string }[] = [];
+  for (const [index, entry] of contributors.entries()) {
+    if (typeof entry !== "object" || entry === null) {
+      throw new Error(
+        `ttsc: plugin "${plugin.name}" contributors[${index}] must be an object`,
+      );
+    }
+    const { name, source } = entry as { name?: unknown; source?: unknown };
+    if (typeof name !== "string" || !CONTRIBUTOR_NAME_PATTERN.test(name)) {
+      throw new Error(
+        `ttsc: plugin "${plugin.name}" contributors[${index}].name must match /^[a-z][a-z0-9_]*$/; ` +
+          `got ${JSON.stringify(name)}`,
+      );
+    }
+    if (seen.has(name)) {
+      throw new Error(
+        `ttsc: plugin "${plugin.name}" contributors[${index}] duplicate name ${JSON.stringify(name)}`,
+      );
+    }
+    seen.add(name);
+    if (typeof source !== "string" || source.length === 0) {
+      throw new Error(
+        `ttsc: plugin "${plugin.name}" contributors[${index}].source must be a non-empty string`,
+      );
+    }
+    if (!path.isAbsolute(source)) {
+      throw new Error(
+        `ttsc: plugin "${plugin.name}" contributors[${index}].source must be an absolute path; ` +
+          `got ${JSON.stringify(source)}`,
+      );
+    }
+    if (!fs.existsSync(source) || !fs.statSync(source).isDirectory()) {
+      throw new Error(
+        `ttsc: plugin "${plugin.name}" contributors[${index}].source must be an existing directory: ${source}`,
+      );
+    }
+    // Reject a directory lacking a regular non-test Go filename before
+    // native host compilation can attribute a failure to scratch paths.
+    // Filename admission does not certify package syntax or build constraints.
+    if (!hasBuildableGoSource(source)) {
+      throw new Error(
+        `ttsc: plugin "${plugin.name}" contributors[${index}].source must contain at least one non-test ".go" file: ${source}`,
+      );
+    }
+    out.push({ name, source: PluginPackageResolution.resolveRealPath(source) });
+  }
+  return out;
+}
+
+const CONTRIBUTOR_NAME_PATTERN = /^[a-z][a-z0-9_]*$/;
+
+function hasBuildableGoSource(dir: string): boolean {
+  // This immediate filename preflight is narrower than actual Go admission.
+  // Ignored filename prefixes, build constraints and syntax remain compiler-owned.
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return false;
+  }
+  return entries.some(
+    (entry) =>
+      entry.isFile() &&
+      entry.name.endsWith(".go") &&
+      !entry.name.endsWith("_test.go"),
+  );
+}

package/src/plugin/internal/load/validatePluginSource.ts

@@ -0,0 +1,19 @@
+import type { ITtscPlugin } from "../../../structures/ITtscPlugin";
+
+/**
+ * Require a nonempty string source on a plugin descriptor.
+ *
+ * @evidence contracts/common.md#principled-implementation The actual loader accepts only nonempty string source identity; absent, empty and nonstring values retain the same authored diagnostic.
+ * @evidence contracts/common.md#clear-and-simple-design One predicate distinguishes source presence before path resolution and native admission.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The production loader calls this source-field guard before native path admission; no expected descriptor value or test-side implementation replaces that operation.
+ * @evidence contracts/common.md#meaningful-documentation The headline identifies the accepted descriptor field and the rejected boundary.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources validatePluginSource acquires no handle, buffer or cache and retains nothing after it returns.
+ * @evidence contracts/performance.md#efficient-algorithms Source admission checks property type and string length without scanning source contents or resolving paths. Property reads retain ordinary descriptor object semantics; this guard does not bound user-defined accessor work.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work No expensive shared producer, reusable-answer identity or cross-request state is coordinated by this source-field guard.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation validatePluginSource computes from its arguments only; it opens no file, builds no path and calls no platform or process API.
+ */
+export function validatePluginSource(plugin: ITtscPlugin): void {
+  if (typeof plugin.source !== "string" || plugin.source.length === 0) {
+    throw new Error(`ttsc: plugin must declare source`);
+  }
+}

package/src/plugin/internal/load/visitImportMappedCandidates.ts

@@ -0,0 +1,63 @@
+import { RESOLUTION_INPUT_RECORDER_PATH } from "./RESOLUTION_INPUT_RECORDER_PATH";
+
+/**
+ * Visit the candidates of the package a `#` import resolved into, in every
+ * search root from the importer up to the one that selected it.
+ *
+ * A package's `imports` may map a `#` specifier to a bare package, which Node
+ * looks up through the ordinary `node_modules` search from the importer. A
+ * nearer copy of that package, a nested install or a moved workspace package,
+ * would be selected instead, so the candidates the lookup found missing in the
+ * nearer roots are inputs of whatever the importer evaluated. The package is
+ * named by the resolved module itself, by the directory after its last
+ * `node_modules`, or by the linked entry of a search root it lies in, so Node's
+ * `imports` algorithm is not copied. A target inside the importer's own
+ * package, or one no search root selects, visits nothing. Expansion also visits
+ * possible manifest target spellings; this conservative input population can
+ * exceed the spellings the completed Node resolver used.
+ *
+ * The rule is the resolution input recorder's
+ * (`RESOLUTION_INPUT_RECORDER_PATH`).
+ *
+ * @param parent The importer, a path or a file URL.
+ * @param resolved The module the resolution selected, a path or a file URL.
+ * @param extensions The extensions the evaluator's resolution probes.
+ * @param witnesses What `observeImportSearchRoots` took before the resolution,
+ *   or `undefined` when the caller observes nothing itself.
+ * @param visit Receives each candidate, and whether its search root moved since
+ *   `witnesses`, which leaves the candidate without proof.
+ * @evidence contracts/common.md#principled-implementation The selected target identifies the bare package a hash-import reached; nearer roots' candidates remain inputs and changed pre-resolution root witnesses prevent claiming stable proof.
+ * @evidence contracts/common.md#clear-and-simple-design A shared visitor emits candidates through the caller callback instead of duplicating imports resolution or retaining a second candidate population.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Actual selected targets and supplied probe extensions drive the recorder's exported visitor; this adapter neither modifies Node nor guesses one known package's missing paths.
+ * @evidence contracts/common.md#meaningful-documentation Native JSDoc explains selected-root bounds, linked packages, witness timing and the moved flag in separated prose and parameter entries under the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Native path/file-URL vocabulary and linked physical selection are handled by the shared recorder; this adapter forwards them without slash-only parsing or blanket case conversion.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Witnesses are borrowed; delegated root/candidate arrays, manifest values and base deduplication are query-local, while emitted records belong to the callback. This adapter retains no watcher, handle or cross-query population.
+ * @evidence contracts/performance.md#efficient-algorithms Delegation includes importer-manifest ancestor search, lexical/physical selected-path lookup, root/name candidate scans and possible linked/scoped directory listings with native identity queries. Candidate expansion recursively reads/parses manifest target values with a normalized-base Set; path/extension/manifest bytes, root/entry counts and callback work drive cost, not merely the final selected-root prefix.
+ * @evidence contracts/performance.md#reuse-equivalent-work One delegated base Set prevents duplicate expansion across manifest targets, and supplied witnesses retain the earlier root observation for movement checks. No mutable filesystem lookup answer is reused across resolution windows.
+ */
+export function visitImportMappedCandidates(
+  parent: string | undefined,
+  resolved: string | undefined,
+  extensions: readonly string[],
+  witnesses: ReadonlyMap<string, string | undefined> | undefined,
+  visit: (file: string, moved: boolean) => void,
+): void {
+  RECORDER.visitImportMappedCandidates(
+    parent,
+    resolved,
+    extensions,
+    witnesses,
+    visit,
+  );
+}
+
+/** The recorder, loaded once as a module of its own. */
+const RECORDER = require(RESOLUTION_INPUT_RECORDER_PATH) as {
+  visitImportMappedCandidates(
+    parent: string | undefined,
+    resolved: string | undefined,
+    extensions: readonly string[],
+    witnesses: ReadonlyMap<string, string | undefined> | undefined,
+    visit: (file: string, moved: boolean) => void,
+  ): void;
+};

package/src/plugin/internal/pluginDescriptorFailureReason.ts

@@ -0,0 +1,35 @@
+import fs from "node:fs";
+
+/**
+ * Read the failure envelope the descriptor shim writes to its result file when
+ * it stops on an error it can name.
+ *
+ * This is the other half of classifying how the evaluation ended, which is why
+ * it lives beside {@link pluginDescriptorProcessFailure} rather than at the call
+ * site: the status says that it failed, and this says why.
+ *
+ * Only a well-formed envelope is honoured. A real descriptor never carries this
+ * key, and every other shape — an absent file, a shim that died before writing,
+ * a half-written result, a descriptor written before a later non-zero exit —
+ * leaves the process status to speak for itself.
+ *
+ * @evidence contracts/common.md#principled-implementation Parsing the named error-envelope field yields trimmed human context only for a string; unreadable or invalid output contributes no invented reason to the already-known process failure.
+ * @evidence contracts/common.md#clear-and-simple-design One file adapter supplies failure context while the process classifier independently owns launch/signal/status interpretation.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The reserved envelope key is a shim protocol field, not a known-error-text special case or retry that masks descriptor failure.
+ * @evidence contracts/common.md#meaningful-documentation Native JSDoc explains accepted envelope and rejected partial/missing shapes, with separate purpose and failure paragraphs under the documentation skill.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The file text/parsed object are invocation-local and become reclaimable when references are discarded; returned reason text transfers to the caller without retained helper history or an open descriptor.
+ * @evidence contracts/performance.md#efficient-algorithms A synchronous UTF-8 file read and JSON.parse process output bytes/parsed structure before trimming a string field. Text/tree/trim work and temporary storage are uncapped by this adapter; absence of an explicit loop does not make parsing constant-cost.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This adapter reads the current evaluation result file; it defines no cross-evaluation identity or coordinator for sharing historical result text.
+ * @evidence contracts/portability.md#os-neutral-implementation The loader output path is passed to fs.readFileSync exactly as given, and any read or parse failure yields an empty reason, so no separator, case or platform assumption is made.
+ */
+export function pluginDescriptorFailureReason(outputPath: string): string {
+  try {
+    const parsed: unknown = JSON.parse(fs.readFileSync(outputPath, "utf8"));
+    if (typeof parsed !== "object" || parsed === null) return "";
+    const message = (parsed as { __ttscLoaderError?: unknown })
+      .__ttscLoaderError;
+    return typeof message === "string" ? message.trim() : "";
+  } catch {
+    return "";
+  }
+}

package/src/plugin/internal/pluginDescriptorProcessFailure.ts

@@ -0,0 +1,48 @@
+/**
+ * Classify the ways the isolated TypeScript descriptor evaluator can stop.
+ *
+ * The ttsx loader routes any child stdout/stderr directly to the parent's
+ * stderr; a failed process need not have printed a diagnostic. This classifier
+ * formats the reported error, signal or nonzero status without proving a
+ * signal's origin or collecting the child's stream bytes.
+ *
+ * It sets no deadline or output ceiling. Request/error text and the returned
+ * Error still occupy memory; descriptor output-file parsing and process
+ * lifetime remain with the loader.
+ *
+ * @evidence contracts/common.md#principled-implementation Launch error, signal and nonzero status are classified in causal order from the child-process result; only a zero-status run without either earlier failure has no process error.
+ * @evidence contracts/common.md#clear-and-simple-design The classifier returns an error without owning spawning, streamed diagnostics or descriptor decoding, keeping those responsibilities with the loader.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No descriptor-name exception, fixed runtime deadline or output threshold replaces the actual process result.
+ * @evidence contracts/common.md#meaningful-documentation Native JSDoc explains the already-streamed child output and remaining process-level information; separate paragraphs and a blank line before tags follow the documentation skill.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The classifier acquires no child or stream; a returned Error transfers to the caller and no helper-owned history is retained.
+ * @evidence contracts/performance.md#efficient-algorithms A fixed precedence chain formats at most one Error. Request and reported-message text affect allocation/formatting; text length is uncapped and no child-output population is collected here.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work One supplied result is classified without coordinating completed or in-flight evaluations.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Formats the process result's error, signal and exit status into a message; it reads no file and builds no path.
+ */
+export function pluginDescriptorProcessFailure(
+  result: DescriptorProcessResult,
+  request: string,
+): Error | undefined {
+  if (result.error) {
+    return new Error(
+      `ttsc: failed to launch ttsx for plugin descriptor "${request}": ${result.error.message}`,
+    );
+  }
+  if (result.signal) {
+    return new Error(
+      `ttsc: plugin descriptor "${request}" evaluation through ttsx was killed by signal ${result.signal}.`,
+    );
+  }
+  if (result.status !== 0) {
+    return new Error(
+      `ttsc: plugin descriptor "${request}" evaluation through ttsx failed with exit code ${String(result.status)}`,
+    );
+  }
+  return undefined;
+}
+
+interface DescriptorProcessResult {
+  error?: Error;
+  signal: NodeJS.Signals | null;
+  status: number | null;
+}