ttsc 0.30.4 → 0.31.0

package/src/plugin/resolveCapabilityPlugins.ts

@@ -1,49 +1,32 @@
 import fs from "node:fs";
 import path from "node:path";
 
-import { createNativeProjectContextJson } from "../compiler/internal/project/createNativeProjectContextArgs";
+import { createNativeProjectContextJson } from "../compiler/internal/project/createNativeProjectContextJson";
 import { resolveBinary } from "../compiler/internal/resolveBinary";
-import {
-  readCapabilityResolution,
-  writeCapabilityResolution,
-} from "./internal/capabilityResolutionCache";
-import { loadProjectPlugins } from "./internal/loadProjectPlugins";
-
-/**
- * One plugin that declared the requested capability.
- *
- * `manifest` is the `--plugins-json` payload its sidecar needs to find its own
- * configured entry. Without it the sidecar loads an empty rule configuration
- * and answers as though the project declared nothing — an empty answer that
- * looks exactly like a project which genuinely publishes none.
- */
-export interface ITtscCapabilityPlugin {
-  binary: string;
-  manifest: string;
-  /**
-   * The `--project-context-json` payload, or `undefined` when the plugin's
-   * descriptor does not declare it wants one.
-   *
-   * A sidecar is handed a project root, not asked to derive one. Without this a
-   * rule that resolves its own inputs — the documents an evidence claim reads,
-   * a Prisma schema, an OpenAPI file — has no base to resolve them against, and
-   * answers with an empty set rather than an error, because "this project
-   * declares nothing" is a legitimate answer it cannot distinguish from "I was
-   * not told where the project is".
-   */
-  projectContext?: string;
-}
+import { SidecarEnvironment } from "../compiler/internal/sharedHost/SidecarEnvironment";
+import { E2ETrace } from "../internal/E2ETrace";
+import { javascriptRuntimeCapabilities } from "../internal/javascriptRuntimeCapabilities";
+import type {
+  ITtscCapabilityPlugin,
+  ITtscCapabilityPluginResolution,
+} from "./ITtscCapabilityPlugin";
+import { CapabilityPluginResult } from "./internal/CapabilityPluginResult";
+import { CapabilityResolutionFormat } from "./internal/CapabilityResolutionFormat";
+import type { ITtscCapabilityResolutionEntry } from "./internal/ITtscCapabilityResolutionEntry";
+import { loadProjectPlugins } from "./internal/load/loadProjectPlugins";
+import { readCapabilityResolution } from "./internal/readCapabilityResolution";
+import { writeCapabilityResolution } from "./internal/writeCapabilityResolution";
 
 /**
  * The built sidecars of a project's configured plugins that declare one
  * capability.
  *
- * This is the seam a consumer outside the compiler needs to ask a plugin a
- * question the plugin declared it can answer. `ttscserver` already does this
- * for `capabilities.lsp`, but it does it from inside the launcher; a separate
- * tool — `@ttsc/graph`, an editor integration, a script — had no way to reach
- * the same answer without reimplementing plugin discovery, descriptor
- * evaluation, and the Go source build cache.
+ * This is the seam a consumer outside the compiler uses to ask a plugin a
+ * question the plugin declared it can answer. `ttscserver` asks for
+ * `capabilities.lsp` from inside the launcher; a separate tool — `@ttsc/graph`,
+ * an editor integration, a script — reaches the same answer here without
+ * reimplementing plugin discovery, descriptor evaluation, and the Go source
+ * build cache.
  *
  * It is contributor-agnostic by construction: the caller names a capability,
  * not a package. A project that configures no plugin, or none declaring that
@@ -51,28 +34,96 @@ export interface ITtscCapabilityPlugin {
  * the common case.
  *
  * Building a plugin is not free the first time. The Go source build is cached
- * by content, so a warm project pays a lookup; a cold one pays the build the
- * next `ttsc` invocation would have paid anyway.
+ * by content. A warm query still observes runtime authority, recorded host
+ * inputs, source/build state and binary presence; it can avoid descriptor
+ * evaluation and rebuilding without reducing all work to one lookup.
  *
  * @param options.capability - Capability flag the plugin descriptor must
  *   declare.
  * @param options.cwd - Project root. Defaults to the current directory.
  * @param options.tsconfig - Project tsconfig path, relative to `cwd`.
  * @returns One entry per declaring plugin, in configured plugin order.
+ * @evidence contracts/common.md#principled-implementation The compatibility API returns declaring sidecars from the shared capability-resolution owner; callers needing reusable empty-result proof use the richer resolution API.
+ * @evidence contracts/common.md#clear-and-simple-design One wrapper preserves the established array result without duplicating discovery, evaluation or build policy.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Empty degraded results remain the legacy contract, but are not advertised as evidence of absence; capability selection does not route by package name.
+ * @evidence contracts/common.md#meaningful-documentation Native JSDoc explains full discovery/build ownership, configured order and capability meaning, with separated paragraphs/tags following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Native invocation paths and sidecar identity remain with the owning resolver; this wrapper introduces no path parsing or shell invocation.
+ * @evidence contracts/performance.md#efficient-algorithms The wrapper delegates the full runtime/cache/discovery/build work to the owning resolver, then copies selected entry references in O(selected plugins). Its additional copy cost does not bound the delegated native/hash/serialization work.
+ * @evidence contracts/performance.md#reuse-equivalent-work The owning resolver applies the persistent answer's recorded authority and input premises; this wrapper adds no independent cache and discards the richer validity query, so the returned array alone does not certify later freshness.
+ *
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The wrapper returns caller-owned data and acquires no persistent process or retained result population.
  */
 export function resolveCapabilityPlugins(options: {
   capability: string;
   cwd?: string;
   tsconfig?: string;
 }): ITtscCapabilityPlugin[] {
+  return [...resolveCapabilityPluginResolution(options).plugins];
+}
+
+/**
+ * Resolve a capability with an owning freshness query, including empty answers.
+ *
+ * A missing native tool and errors inside the plugin-load/answer-publication
+ * try block yield an unavailable result whose freshness is always false.
+ * Initial path, authority/cache lookup and tool resolution precede that catch;
+ * their exceptions are not converted there. A successful lookup is reusable
+ * only while the recorded discovery and evaluation premises remain current. The
+ * query never re-evaluates a descriptor or builds a plugin.
+ *
+ * Unrecorded descriptor reads, module-based config inheritance, indirect
+ * runtime authority and failed persistence can leave a successful lookup
+ * without reusable proof. Its query then returns false; successful discovery is
+ * distinct from permission to reuse. The private opt-in trace reports computed
+ * eligibility and publication branches; it adds no authority probe and is not
+ * itself a freshness proof.
+ *
+ * @evidence contracts/common.md#principled-implementation Successful selection preserves the complete configured manifest and opt-in context; missing tools and caught load/publication failures produce degraded results. Dependent reuse requires the recorded input/build projections and authority checks, subject to producer declarations and sequential observation limits.
+ * @evidence contracts/common.md#clear-and-simple-design One owner combines discovery and cache acceptance, exposing only selected plugins, outcome and an opaque validity query to downstream consumers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Unproved or unavailable empty answers are never reusable success; consumers do not reconstruct a partial resolver or bypass descriptor-read declarations.
+ * @evidence contracts/common.md#meaningful-documentation Native JSDoc explains empty-answer proof, unavailable outcomes and the non-evaluating query; the result type documents consumer responsibility and closure lifetime following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Native resolve and shared filesystem observers preserve actual lexical/physical identities; executable and full JSON argv payloads cross the sidecar boundary without shell composition.
+ * @evidence contracts/performance.md#efficient-algorithms A valid persisted answer avoids descriptor startup and Go builds, but runtime probes, repeated executable/environment key construction, full entry JSON/host hashing, source metadata/build-environment checks and binary queries still contribute native/path/file/text costs. Freshness repeats authority and cache acceptance, then compares complete serialized entries; misses delegate full discovery/build work and selection scans all configured plugins before mapping the selected ones.
+ * @evidence contracts/performance.md#reuse-equivalent-work Persistent identity includes project/product version/environment/runtime authority and recorded input/source states. Callback equality compares the accepted serialized generation after current checks; it relies on producer declarations and non-atomic observation premises, not detection of every possible external read.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources A reusable result's closure retains serialized proof, captured selector/path strings and authority values while selected entries carry manifest/context text; consumers own release and no independent population/byte ceiling is imposed. Discovery/proof observers own transient processes/files and their cleanup attempts, with no live evaluator intentionally retained in the result. Default disk pruning is subject to its own protection/interval/failure policy and explicit roots remain caller-owned.
+ */
+export function resolveCapabilityPluginResolution(options: {
+  /** Capability name that selected sidecars must explicitly declare true. */
+  capability: string;
+
+  /** Invocation directory for native project/config resolution. */
+  cwd?: string;
+
+  /** Explicit config relative to cwd, or the resolver's default discovery. */
+  tsconfig?: string;
+}): ITtscCapabilityPluginResolution {
   const cwd = path.resolve(options.cwd ?? process.cwd());
-  const tsconfig = options.tsconfig ?? "tsconfig.json";
-  const cached = readCapabilityResolution({ cwd, tsconfig, version });
-  if (cached !== null) return select(cached, options.capability);
+  // Discovery and an explicit local tsconfig can select different files from
+  // the same cwd. NUL cannot occur in a filename, so this discovery key cannot
+  // collide with an explicitly supplied path.
+  const tsconfig = options.tsconfig ?? `${String.fromCharCode(0)}discovered`;
+  const runtimeProved = capabilityRuntimeAuthorityComplete(cwd);
+  const authority = runtimeProved
+    ? CapabilityResolutionFormat.resolutionFile({ cwd, tsconfig })
+    : null;
+  const cached = runtimeProved
+    ? readCapabilityResolution({ cwd, tsconfig, version })
+    : null;
+  E2ETrace.capabilityResolution("lookup", {
+    cwd,
+    tsconfig,
+    capability: options.capability,
+    runtimeProved,
+    authority,
+    cacheHit: cached !== null,
+  });
+  if (cached !== null)
+    return resolved(cached, options.capability, cwd, tsconfig, authority);
 
   const binary = resolveBinary();
-  if (binary === null || binary === undefined) return [];
-  try {
+  if (binary === null || binary === undefined)
+    return CapabilityPluginResult.unavailable();
+  return CapabilityPluginResult.fromTask(() => {
     const loaded = loadProjectPlugins({
       binary,
       cwd: options.cwd,
@@ -95,9 +146,19 @@ export function resolveCapabilityPlugins(options: {
         (plugin.capabilities as Record<string, unknown> | undefined)
           ?.projectContextArgs === true,
     );
+    // The files the answer was computed from, with the proof the load took of
+    // each while the descriptors evaluated. A plugin's
+    // `configFile` that no descriptor read is forwarded to the native plugin
+    // and deferred to its transform's own proof: the answer never read it.
+    const deferred = new Set(loaded.deferredHostInputs);
     const answer = {
-      hostInputs: loaded.hostInputs,
+      hostInputHashes: loaded.hostInputHashes,
+      hostInputRealpaths: loaded.hostInputRealpaths,
+      hostInputs: loaded.hostInputs.filter((input) => !deferred.has(input)),
       manifest,
+      // What the binaries below were keyed on, which a later read proves before
+      // it hands out a path.
+      pluginSources: loaded.pluginSources,
       plugins: loaded.nativePlugins.map((plugin) => ({
         binary: plugin.binary,
         capabilities: Object.fromEntries(
@@ -105,48 +166,152 @@ export function resolveCapabilityPlugins(options: {
             (plugin.capabilities as Record<string, unknown> | undefined) ?? {},
           ).map(([name, declared]) => [name, declared === true] as const),
         ),
-        source: plugin.source,
       })),
       projectContext: wantsContext
         ? createNativeProjectContextJson(loaded.project)
         : null,
     };
-    writeCapabilityResolution({ cwd, tsconfig, version }, answer);
-    return select(answer, options.capability);
+    // A descriptor that did not declare what it read computed an answer no
+    // recorded input can prove to a later call.
+    let authorityUnchanged: boolean | undefined;
+    const recorded =
+      runtimeProved &&
+      authority !== null &&
+      (authorityUnchanged =
+        CapabilityResolutionFormat.resolutionFile({ cwd, tsconfig }) ===
+        authority) &&
+      loaded.descriptorReadsDeclared &&
+      loaded.discoveryInputsComplete
+        ? writeCapabilityResolution(
+            { cwd, tsconfig, version, expectedAuthority: authority },
+            answer,
+          )
+        : null;
+    E2ETrace.capabilityResolution("answer", {
+      cwd,
+      tsconfig,
+      capability: options.capability,
+      runtimeProved,
+      authority,
+      authorityUnchanged,
+      descriptorReadsDeclared: loaded.descriptorReadsDeclared,
+      discoveryInputsComplete: loaded.discoveryInputsComplete,
+      observationsComplete: loaded.observationsComplete,
+      retainedHostInputs: answer.hostInputs.length,
+      deferredHostInputs: loaded.deferredHostInputs.length,
+      writeAttempted:
+        runtimeProved &&
+        authority !== null &&
+        authorityUnchanged === true &&
+        loaded.descriptorReadsDeclared &&
+        loaded.discoveryInputsComplete,
+      recorded: recorded !== null,
+    });
+    return recorded === null
+      ? {
+          isCurrent: () => false,
+          plugins: CapabilityPluginResult.select(answer, options.capability),
+          status: "resolved",
+        }
+      : resolved(recorded, options.capability, cwd, tsconfig, authority);
+  });
+}
+
+/**
+ * Whether the keyed executable is the actual sole descriptor runtime.
+ *
+ * A direct hook-capable Node executable selects itself for both direct and ttsx
+ * evaluation. Bun, wrappers and startup preloads introduce additional
+ * authorities that this cache format does not observe, so they are not reused.
+ * Native environment-name lookup preserves Windows aliases on direct and worker
+ * calls; POSIX names remain case-sensitive. Private tracing reports this
+ * operation's existing decision and preserves short-circuited comparisons as
+ * unobserved, without repeating native queries.
+ */
+function capabilityRuntimeAuthorityComplete(cwd: string): boolean {
+  if (SidecarEnvironment.read(process.env, "NODE_OPTIONS")?.trim()) {
+    E2ETrace.capabilityResolution("runtime-authority", {
+      cwd,
+      proved: false,
+      reason: "node-options",
+    });
+    return false;
+  }
+  const runtime =
+    SidecarEnvironment.read(process.env, "TTSC_NODE_BINARY") ??
+    process.execPath;
+  if (!path.isAbsolute(runtime)) {
+    E2ETrace.capabilityResolution("runtime-authority", {
+      cwd,
+      runtime,
+      proved: false,
+      reason: "relative-runtime",
+    });
+    return false;
+  }
+  try {
+    const capabilities = javascriptRuntimeCapabilities(
+      runtime,
+      process.env,
+      cwd,
+    );
+    let executableMatches: boolean | undefined;
+    const proved =
+      !capabilities.bun &&
+      capabilities.registerHooks &&
+      capabilities.executable !== undefined &&
+      (executableMatches =
+        fs.realpathSync.native(capabilities.executable) ===
+        fs.realpathSync.native(runtime));
+    E2ETrace.capabilityResolution("runtime-authority", {
+      cwd,
+      runtime,
+      bun: capabilities.bun,
+      registerHooks: capabilities.registerHooks,
+      executable: capabilities.executable,
+      executableMatches,
+      proved,
+    });
+    return proved;
   } catch {
-    // A project whose plugin configuration does not load is a project the user
-    // already sees an error for, from the command that compiles it. Failing here
-    // would turn "your lint config has a typo" into "the graph is broken", and
-    // the caller's own degraded answer is the honest one.
-    return [];
+    E2ETrace.capabilityResolution("runtime-authority", {
+      cwd,
+      runtime,
+      proved: false,
+      reason: "authority-exception",
+    });
+    return false;
   }
 }
 
-/** The declaring plugins, from a resolution however it was obtained. */
-function select(
-  resolution: {
-    manifest: string;
-    projectContext: string | null;
-    plugins: readonly {
-      binary: string;
-      capabilities: Record<string, boolean>;
-    }[];
-  },
+/** A complete accepted cache generation and its owning validity query. */
+function resolved(
+  entry: ITtscCapabilityResolutionEntry,
   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 }
-        : {}),
-    }));
+  cwd: string,
+  tsconfig: string,
+  authority: string | null,
+): ITtscCapabilityPluginResolution {
+  const proof = JSON.stringify(entry);
+  return {
+    isCurrent: () => {
+      try {
+        if (
+          authority === null ||
+          !capabilityRuntimeAuthorityComplete(cwd) ||
+          CapabilityResolutionFormat.resolutionFile({ cwd, tsconfig }) !==
+            authority
+        )
+          return false;
+        const current = readCapabilityResolution({ cwd, tsconfig, version });
+        return current !== null && JSON.stringify(current) === proof;
+      } catch {
+        return false;
+      }
+    },
+    plugins: CapabilityPluginResult.select(entry, capability),
+    status: "resolved",
+  };
 }
 
 /**

package/src/register.ts

@@ -2,10 +2,9 @@ import fs from "node:fs";
 import path from "node:path";
 
 import { prepareExecution } from "./launcher/internal/prepareExecution";
-import {
-  type RuntimeManifest,
-  installRuntimeHooks,
-} from "./launcher/internal/runtimeHooks";
+import { type RuntimeManifest } from "./launcher/internal/runtime/RuntimeManifest";
+import { installRuntimeHooks } from "./launcher/internal/runtime/installRuntimeHooks";
+import { runtimeRunKey } from "./launcher/internal/runtime/runtimeRunKey";
 
 const cleanupDirectories = new Set<string>();
 let runtimeSequence = 0;
@@ -13,25 +12,39 @@ let runtimeSequence = 0;
 /**
  * Prepare one TypeScript root with the same checked compiler pipeline as ttsx,
  * then expose its transient emit to the already-installed runtime hooks.
+ *
+ * The process-run key and sequence distinguish prepared roots. Installed hooks
+ * own same-root reuse; this adapter only transfers the existing emit manifest.
+ * Each prepared directory is retained until host exit, so long sessions can
+ * accumulate roots without an earlier eviction boundary.
  */
 function prepareEntry(filename: string): RuntimeManifest {
   const execution = prepareExecution(filename, {
-    runtimeCacheKey: `register-${process.pid}-${++runtimeSequence}`,
+    runtimeCacheKey: `register-${runtimeRunKey()}-${++runtimeSequence}`,
   });
   cleanupDirectories.add(execution.cleanupDir);
   return {
     depCacheDir: path.join(execution.cleanupDir, "deps"),
     emitDir: execution.emitDir,
-    emittedFiles: execution.emittedFiles,
+    emittedSources: execution.emittedSources,
+    emittedSourceProofFailures: execution.emittedSourceProofFailures,
     entryFile: execution.entryFile,
     entrySource: execution.entrySource,
+    outputs: execution.outputs,
     moduleOptions: execution.moduleOptions,
+    orphanCacheDir: execution.orphanCacheDir,
     projectRoot: execution.projectRoot,
     rootDir: execution.rootDir,
   };
 }
 
-/** Remove every register-owned transient emit when the JavaScript host exits. */
+/**
+ * Remove every register-owned transient emit when the JavaScript host exits.
+ * Cleanup is best-effort and does not override the host's exit status.
+ *
+ * Each recorded transient tree is visited once. Failed deletions may leave disk
+ * output, and abrupt process termination can bypass this callback.
+ */
 function cleanupRuntimeOutputs(): void {
   for (const directory of cleanupDirectories) {
     try {

package/src/structures/ITtscCompilerContext.ts

@@ -3,16 +3,26 @@ import type { ITtscProjectPluginConfig } from "./ITtscProjectPluginConfig";
 /**
  * Constructor context for {@link TtscCompiler}.
  *
- * Represents the project environment owned by a programmatic ttsc compiler
- * instance. The context is fixed when the class is constructed: compile,
- * prepare, and clean operations all use the same working directory, project
- * config, native toolchain, environment, cache root, and plugin list.
+ * Supplies the selection policy owned by a programmatic ttsc compiler instance.
+ * Construction copies the supplied options and environment overrides and
+ * captures plugin JSON conversion. Operations cannot replace those inputs.
  *
- * Keeping this context immutable prevents one `TtscCompiler` object from
- * silently compiling different projects across calls. Create another compiler
- * instance when any of these fields must change.
+ * Defaults remain invocation inputs: an omitted working directory uses the
+ * current process directory, inherited environment values come from the current
+ * process environment, and project/toolchain discovery reads current files.
+ * Relative path options are resolved when used. Supply explicit anchors and
+ * overrides when calls must keep those selections; construct another instance
+ * to change the supplied options.
  *
  * @author Jeongho Nam - https://github.com/samchon
+ * @evidence contracts/common.md#principled-implementation Optional construction inputs preserve explicit override versus discovery/default behavior; project root, config origin and invocation cwd remain distinct because wrappers and plugin resolution can use different anchors.
+ * @evidence contracts/common.md#clear-and-simple-design The context groups one compiler instance's environment and selection policy; operations use this context instead of accepting competing per-call plugin overrides.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Binary, environment and plugin overrides are supported embedding inputs, not fabricated compiler results or foreign-method replacements.
+ * @evidence contracts/common.md#meaningful-documentation Native JSDoc states override precedence, default cache ownership, plugin selection states and child-environment effects; documented members and prose/tag separation follow the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Path fields are native filesystem inputs with individually documented cwd/project/config bases; the representation does not require POSIX separators or collapse Windows paths, lexical selection and physical identity into one value. Process environment is supplied as Node's environment map, not shell assignment syntax.
+ * @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.
  */
 export interface ITtscCompilerContext {
   /**
@@ -22,6 +32,9 @@ export interface ITtscCompilerContext {
    * resolve project source files, resolve plugin packages, and resolve relative
    * cache paths.
    *
+   * An omitted value uses `process.cwd()` when the operation resolves its
+   * context; construction does not capture that default.
+   *
    * @default process.cwd()
    */
   cwd?: string;
@@ -77,13 +90,18 @@ export interface ITtscCompilerContext {
 
   /**
    * Additional environment variables for child compiler and plugin-descriptor
-   * processes.
+   * processes, and for the worker thread of
+   * {@link TtscCompiler.transformAsync}.
    *
-   * Values are merged over `process.env` before ttsc starts TypeScript-Go,
+   * The supplied overrides are copied at construction. Values are merged over
+   * the invocation's current `process.env` before ttsc starts TypeScript-Go,
    * native plugin binaries, isolated descriptor evaluators (including the
    * `ttsx` fallback), or the native compiler host used by
-   * {@link TtscCompiler.compile}. Descriptor output is diagnostic text and is
-   * forwarded to stderr so it cannot corrupt compiler/API protocol stdout.
+   * {@link TtscCompiler.compile}. `transformAsync` runs its whole transform on a
+   * worker thread under the same merge, so its in-process work, such as the
+   * temporary directories it creates, follows it too. Descriptor output is
+   * diagnostic text and is forwarded to stderr so it cannot corrupt
+   * compiler/API protocol stdout.
    */
   env?: NodeJS.ProcessEnv;
 

package/src/structures/ITtscCompilerDiagnostic.ts

@@ -8,6 +8,14 @@
  * terminal output.
  *
  * @author Jeongho Nam - https://github.com/samchon
+ * @evidence contracts/common.md#principled-implementation Nullable file identity distinguishes global findings from located findings; numeric or plugin string codes and optional coordinates preserve producer information without inventing locations.
+ * @evidence contracts/common.md#clear-and-simple-design A flat diagnostic record exposes severity, identity, location and text without coupling JavaScript consumers to the native compiler's internal message-chain objects.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Category names are the supported diagnostic vocabulary; plugin identifiers remain data rather than host-side special cases for known plugins.
+ * @evidence contracts/common.md#meaningful-documentation Native JSDoc states null-file semantics, producer coordinate units, optional spans and flattened text; member spacing and distinct descriptive/tag paragraphs 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.
+ * @evidence contracts/portability.md#os-neutral-implementation File names retain the producer's native path spelling, with null for global findings; offsets and native columns use UTF-8 bytes while rendered foreign columns retain their producer's unit, so consumers must not interpret them as UTF-16 protocol positions.
  */
 export interface ITtscCompilerDiagnostic {
   /**
@@ -38,7 +46,7 @@ export interface ITtscCompilerDiagnostic {
   /**
    * The starting position of the issue in the source file, if available.
    *
-   * TypeScript-Go reports this as a zero-based character offset. It is omitted
+   * Native TypeScript-Go reports a zero-based UTF-8 byte offset. It is omitted
    * for global diagnostics or messages that do not expose a source offset.
    */
   start?: number;
@@ -46,8 +54,9 @@ export interface ITtscCompilerDiagnostic {
   /**
    * The length of the problematic section in the source file, if available.
    *
-   * Omitted when TypeScript-Go or a native plugin reports only a point
-   * location, or when the diagnostic is not tied to a source file.
+   * Native TypeScript-Go reports a UTF-8 byte length. Omitted when it or a
+   * native plugin reports only a point location, or when the diagnostic is not
+   * tied to a source file.
    */
   length?: number;
 
@@ -60,11 +69,10 @@ export interface ITtscCompilerDiagnostic {
   line?: number;
 
   /**
-   * 1-based character (column) position where the diagnostic starts, if
-   * available.
+   * 1-based column where the diagnostic starts, if available.
    *
-   * This follows TypeScript's display convention rather than TypeScript-Go's
-   * zero-based internal column index.
+   * Native TypeScript-Go reports a UTF-8 byte column. Diagnostics parsed from
+   * another producer's rendered text retain that producer's column unit.
    */
   character?: number;
 
@@ -86,6 +94,15 @@ export namespace ITtscCompilerDiagnostic {
    * - `"error"`: issues that prevent successful compilation.
    * - `"suggestion"`: recommendations for code improvement.
    * - `"message"`: informational notes without warning or error severity.
+   *
+   * @evidence contracts/common.md#principled-implementation Four literal severities preserve the TypeScript diagnostic categories used by host decoding, with no ordinal encoding assumption.
+   * @evidence contracts/common.md#clear-and-simple-design The named union provides one shared severity vocabulary for all diagnostic consumers.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts These literals represent protocol categories and do not classify by a diagnostic's text or a fixture code.
+   * @evidence contracts/common.md#meaningful-documentation Native JSDoc explains the intended severity of each literal in separate list entries and separates the acknowledgments, following 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 type Category = "warning" | "error" | "suggestion" | "message";
 }