ttsc 0.30.3 → 0.31.0

package/lib/structures/ITtscPluginCapabilities.d.ts

@@ -12,8 +12,43 @@
  * Every field is optional and defaults to `false`. Plugin authors opt in by
  * setting only the capabilities their sidecar actually implements; ttsc keeps
  * the conservative default for everything else.
+ *
+ * @evidence contracts/common.md#principled-implementation Optional booleans represent independent descriptor opt-ins; an omitted capability means the host must not send a protocol the sidecar has not declared.
+ * @evidence contracts/common.md#clear-and-simple-design Each supported protocol has its own named field so callers can negotiate one behavior without inferring unrelated support.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Capability declarations replace plugin-name special cases; false defaults are the conservative protocol contract rather than test accommodations.
+ * @evidence contracts/common.md#meaningful-documentation Native JSDoc explains each protocol, its false default and relevant independence from other capabilities; documented members and descriptive prose are separated according to 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 These opt-ins describe a native sidecar's accepted argv and process protocols, including private absolute artifact paths and separate lexical/physical project identities; omission leaves the optional protocol unsupported on every platform rather than inferring it from an OS or plugin name.
  */
 export interface ITtscPluginCapabilities {
+    /**
+     * Whether a check-stage host accepts `--check-observations-json=<absolute
+     * private path>` and writes the host input observations from that same check
+     * Program to the private channel. This opt-in applies to the actual check
+     * verb, not effectful fix/format verbs exposed by a check-stage descriptor.
+     *
+     * The channel preserves input paths, content and physical-identity witnesses,
+     * and explicit observation incompleteness independently of text diagnostics
+     * and process status. Hosts report it for unsuccessful checks as well. A
+     * missing capability keeps the option out of strict hosts' argv; it does not
+     * imply that their input population was completely observed.
+     *
+     * @default false
+     */
+    checkObservations?: true;
+    /**
+     * Whether the host consumes `TTSC_TSGO_ARGS_CWD` with its forwarded compiler
+     * payload. Upstream response and CLI option parsing use that directory;
+     * Program, plugin and rule-input roots retain the selected `--cwd`.
+     *
+     * Only invocations requiring a distinct compiler argument base need this
+     * protocol. An omitted capability retains same-directory legacy behavior.
+     *
+     * @default false
+     */
+    compilerArgsCwd?: true;
     /**
      * Whether the sidecar accepts `--diagnostics` and `--extendedDiagnostics` on
      * its command line and may print plugin-owned timing detail to stdout.
@@ -35,6 +70,21 @@ export interface ITtscPluginCapabilities {
      * @default false
      */
     lsp?: boolean;
+    /**
+     * Whether the sidecar supports the compiler-owned emit provenance protocol.
+     *
+     * An opted-in host accepts `--emit-provenance-json=<absolute private path>`
+     * and reports the physical source identities of outputs it actually wrote.
+     * Runtime consumers use that ledger instead of inferring source ownership
+     * from an output filename or configuration prediction.
+     *
+     * When omitted, ttsc does not pass the option to a strict third-party host. A
+     * runtime operation requiring verified emit provenance must then report that
+     * the selected host does not support it.
+     *
+     * @default false
+     */
+    emitProvenance?: true;
     /**
      * Whether the sidecar accepts ttsc's `--project-context-json` identity
      * protocol. The payload keeps lexical selection paths, physical Program
@@ -76,13 +126,13 @@ export interface ITtscPluginCapabilities {
     residentCheck?: boolean;
     /**
      * Whether the sidecar accepts `--singleThreaded` and `--checkers` on its
-     * command line. The lint sidecar parses both flags via `parseSubcommandFlags`
-     * and threads them into `loadProgram` (parse phase) and `engine.SetSerial`
-     * (rule walk); other check-stage hosts may not.
+     * command line. The lint sidecar parses both flags in its shared subcommand
+     * flag parser and threads them into program loading (parse phase) and
+     * `engine.SetSerial` (rule walk); other check-stage hosts may not.
      *
      * When `false` (the default), ttsc strips both flags from the sidecar's arg
-     * list — the conservative behavior that ad3443a restored after `#113`
-     * over-forwarded them to typia/nestia hosts.
+     * list, because a host that does not declare the capability has an unknown
+     * flag set and would reject an undeclared flag.
      *
      * @default false
      */

package/lib/structures/ITtscPluginContributor.d.ts

@@ -4,25 +4,36 @@
  * The native builder copies `source` into `<scratch>/contrib/<name>/` and adds
  * a blank-import for `<host-module>/contrib/<name>` to the synthesized
  * `ttsc_contributions.go` placed alongside the host's main package.
+ *
+ * @evidence contracts/common.md#principled-implementation A contributor pairs its validated Go sub-package name with its source directory because the builder embeds packages into the owning host module rather than building separate modules.
+ * @evidence contracts/common.md#clear-and-simple-design The two fields expose only the import identity and source population the builder needs; host-module and scratch-layout policy stay with the builder.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The name grammar and no-go.mod rule express Go package composition requirements, without consumer-specific overrides or a prebuilt-binary escape path.
+ * @evidence contracts/common.md#meaningful-documentation Native JSDoc gives the generated import location, naming restriction, uniqueness and copied-source exclusions; member and tag separation follow the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Native absolute source paths remain distinct from Go import names, whose slash vocabulary and ASCII package-name restriction belong to Go semantics rather than a host filesystem assumption. The builder owns native joins and source copying.
+ * @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 ITtscPluginContributor {
     /**
      * Sub-package name.
      *
      * Forms the final import path together with the host plugin's Go module path;
-     * must match `/^[a-z][a-z0-9_]*$/` — a lowercase ASCII letter followed by
-     * lowercase letters, digits, or underscores — and be unique within one plugin
-     * build.
+     * must start with a lowercase ASCII letter, contain only lowercase letters,
+     * digits or underscores, and be unique within one plugin build.
      */
     name: string;
     /**
      * Absolute path to the contributor's Go source directory.
      *
-     * Every `.go` file under this directory is copied into the scratch build tree
-     * as a sub-package of the host plugin's module. A top-level `go.mod` is
-     * rejected because contributors are packages, not modules. Copied source
-     * prunes `node_modules`, `.git`, `.ttsc`, generated workspace files, and
-     * local artifact files.
+     * Regular source files and package data are copied into the scratch build
+     * tree as a sub-package of the host plugin's module. A top-level `go.mod` is
+     * rejected because contributors are packages, not modules.
+     *
+     * The snapshot omits links, the `node_modules`, `.git` and `.ttsc`
+     * directories, generated workspace files and named local artifacts. A regular
+     * `.git` file remains included. Package data using excluded names remains
+     * excluded even when a Go embed directive references it.
      */
     source: string;
 }

package/lib/structures/ITtscPluginFactoryContext.d.ts

@@ -7,9 +7,18 @@ import type { ITtscProjectPluginConfig } from "./ITtscProjectPluginConfig";
  * descriptor needs to inspect the original plugin config, the resolved tsconfig
  * path, the project root, or the descriptor's own location on disk.
  *
- * The factory runs in Node.js while ttsc is loading `compilerOptions.plugins`.
- * It should only create the descriptor. Heavy validation and TypeScript-Go work
- * belong in the Go source plugin selected by {@link ITtscPlugin.source}.
+ * The factory runs in an isolated supported JavaScript runtime while ttsc loads
+ * `compilerOptions.plugins`. It should only create the descriptor. Heavy
+ * validation and TypeScript-Go work belong in the selected Go source plugin.
+ *
+ * @evidence contracts/common.md#principled-implementation Separate invocation, project, configuration and descriptor locations preserve their different resolution bases; the generic plugin field keeps the factory's own config type without guessing its shape.
+ * @evidence contracts/common.md#clear-and-simple-design One factory input collects already-resolved context and the original configuration so descriptors need neither reparse CLI arguments nor infer their own load mode.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Explicit filename/dirname fields are the supported descriptor boundary for both module modes; they avoid substituting globals or consumer-specific path repairs.
+ * @evidence contracts/common.md#meaningful-documentation Native JSDoc explains each path's origin, generated-wrapper overrides and the descriptor factory's limited responsibility; member spacing, paragraphs and separation before tags follow the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Explicit native descriptor and project path anchors support OS-neutral path resolution without deriving them from URL text, POSIX separator splitting or CommonJS-only globals. Invocation cwd, project root and config origin keep their separate identities across generated wrappers.
+ * @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 ITtscPluginFactoryContext<T = ITtscProjectPluginConfig> {
     /**

package/lib/structures/ITtscProjectPluginConfig.d.ts

@@ -6,16 +6,33 @@
  * or plugin packages expose through `package.json`. ttsc deliberately keeps it
  * open-ended because plugin packages own their own config fields.
  *
- * Ttsc interprets only two properties:
+ * Two properties select whether and where ttsc loads the plugin:
  *
  * - `transform`: the JavaScript module specifier used to load the plugin
  *   descriptor or factory.
  * - `enabled`: an opt-out switch that keeps the config entry in the file while
  *   preventing ttsc from loading it.
  *
- * Every other property is preserved as plugin config. After ttsc loads and
- * builds the plugin, the original entry is serialized into the native plugin
- * manifest so Go code can read exactly the same plugin-specific options.
+ * A conventional string `configFile` also registers a potential native input.
+ * When no JavaScript loading stage consumed that path, its proof must come from
+ * the consuming plugin; existing JavaScript observations keep their own proof
+ * requirements. Relative values use the selected plugin config anchor, or the
+ * selected project config's directory. Registration alone does not read the
+ * file or certify its contents.
+ *
+ * Plugin-owned options are serialized into the native manifest. The
+ * programmatic compiler captures JSON conversion at construction, so custom
+ * `toJSON` behavior can define the serialized payload independently of the
+ * host's loading selectors.
+ *
+ * @evidence contracts/common.md#principled-implementation Transform/enabled describe host selection and conventional configFile identifies potential native input proof without replacing consumed JavaScript observations; an unknown-valued index signature permits plugin-owned JSON configuration without claiming the host validates its meaning.
+ * @evidence contracts/common.md#clear-and-simple-design One open entry shape holds loading selectors and plugin-owned options; constructor snapshotting separately owns captured JSON when programmatic conversion requires a distinct wire payload.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The open payload is a documented extension boundary; plugin-specific validation belongs to the factory or native implementation rather than host special cases.
+ * @evidence contracts/common.md#meaningful-documentation Native JSDoc states resolution bases, opt-out semantics, deferred config-file proof and JSON conversion versus plugin-owned validation; separate paragraphs, member spacing and a blank line before tags follow the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Transform accepts package specifiers and native paths with explicit declaration or consumer bases; conventional configFile uses the selected plugin-config anchor. Native resolution belongs to the loader, without requiring one separator spelling in this config type.
+ * @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 ITtscProjectPluginConfig {
     /**
@@ -28,9 +45,14 @@ export interface ITtscProjectPluginConfig {
     /**
      * Plugin module specifier, relative path, or absolute path to load.
      *
-     * Relative paths are resolved from the tsconfig/jsconfig file that declared
-     * the plugin entry. Package specifiers are resolved with Node's package
-     * resolution from that same directory.
+     * For tsconfig/jsconfig entries, relative paths resolve from the config file
+     * that declared the entry, while package specifiers resolve from the
+     * consuming project root. A caller-supplied replacement list uses that
+     * project root for both forms.
+     *
+     * For automatically discovered package markers, relative paths resolve from
+     * the publishing package. Package specifiers resolve from the consuming
+     * project's package directory.
      *
      * The loaded JavaScript module must export an {@link ITtscPlugin} descriptor
      * or descriptor factory. The Go implementation itself is declared by the
@@ -38,10 +60,13 @@ export interface ITtscProjectPluginConfig {
      */
     transform?: string;
     /**
-     * Plugin-specific config passed through unchanged to the native plugin.
+     * Plugin-specific configuration carried in the native manifest's JSON
+     * payload.
      *
-     * Ttsc does not validate these fields. Plugin packages should document their
-     * own config contract and validate it inside their factory or Go source.
+     * Plugin packages should document and validate their options in the factory
+     * or Go source. Ttsc requires serializable programmatic input and observes
+     * the conventional `configFile` input, but does not validate plugin-owned
+     * meaning.
      */
     [key: string]: unknown;
 }

package/lib/structures/TtscPluginStage.d.ts

@@ -8,5 +8,14 @@
  *   declaration output is generated. Check plugins may also implement `fix` and
  *   `format` commands, which `ttsc fix` / `ttsc format` invoke with emit
  *   disabled.
+ *
+ * @evidence contracts/common.md#principled-implementation The two literal stages preserve the host distinction between source transformation and pre-emit diagnostics; they do not imply access to emitted artifacts.
+ * @evidence contracts/common.md#clear-and-simple-design A literal union names the two supported pipeline positions without adding independent mode flags.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Both discriminants are protocol values, not plugin-name exceptions or fixture-specific stages.
+ * @evidence contracts/common.md#meaningful-documentation Native JSDoc describes timing, available text and fix/format behavior in separate prose and list entries; a blank comment line separates these facts from 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 TtscPluginStage = "transform" | "check";

package/lib/structures/internal/ITtscLoadedNativePlugin.d.ts

@@ -2,16 +2,30 @@ import type { ITtscPluginCapabilities } from "../ITtscPluginCapabilities";
 import type { ITtscPluginContributor } from "../ITtscPluginContributor";
 import type { ITtscProjectPluginConfig } from "../ITtscProjectPluginConfig";
 import type { TtscPluginStage } from "../TtscPluginStage";
-/** Native plugin source selected and built from one plugin descriptor. */
+/**
+ * Loaded native plugin entry and the executable selected for its dispatch. A
+ * linked transform entry can share a compiler host's executable rather than own
+ * a separately built process binary.
+ *
+ * @evidence contracts/common.md#principled-implementation Loaded state pairs the built executable with source, original configuration and stage; executable versus linked distinguishes process dispatch from composition into another host.
+ * @evidence contracts/common.md#clear-and-simple-design This host-owned record carries resolved descriptor facts needed by later execution without exposing descriptor evaluation or cache machinery to consumers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Effective host capabilities and reportsTypeScriptDiagnostics govern forwarding and guard behavior; a linked source does not independently certify its selected host, and names remain labels rather than special-case routing keys.
+ * @evidence contracts/common.md#meaningful-documentation Native member comments describe binary provenance, original config, linked ownership and capability meaning; blank member lines and prose/tag separation follow the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Binary and source are resolved native paths supplied by the loader/build owner; this representation neither hardcodes platform suffixes nor serializes process execution as shell text.
+ * @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 ITtscLoadedNativePlugin {
-    /** Executable produced by the lazy Go source build cache. */
+    /** Built executable or the compiler host selected for a linked transform. */
     binary: string;
     /**
-     * Capability flags declared by the descriptor (see
-     * `ITtscPluginCapabilities`).
+     * Effective dispatch capabilities (see `ITtscPluginCapabilities`). Source
+     * composition can inherit the aggregate host's declaration; the builtin
+     * linked utility host additionally supplies its owned emit-provenance flag.
      */
     capabilities?: ITtscPluginCapabilities;
-    /** Original tsconfig plugin entry passed unchanged to the native plugin. */
+    /** Selected plugin entry; native transport serializes its JSON payload. */
     config: ITtscProjectPluginConfig;
     /** Contributor Go sources statically linked into the binary, if any. */
     contributors?: readonly ITtscPluginContributor[];

package/lib/structures/internal/ITtscParsedProjectConfig.d.ts

@@ -1,7 +1,29 @@
 import type { ITtscProjectPluginConfig } from "../ITtscProjectPluginConfig";
 import type { ITtscProjectIdentity } from "./ITtscProjectIdentity";
-/** Resolved project config subset used inside the ttsc host. */
+/**
+ * Resolved project config subset used inside the ttsc host.
+ *
+ * @evidence contracts/common.md#principled-implementation Resolved compiler options retain unknown compiler-owned fields, while config ancestry and each plugin's declaring directory preserve distinct inheritance and resolution identities.
+ * @evidence contracts/common.md#clear-and-simple-design One resolved project record groups option values and their provenance; lexical/physical identity stays in its shared representation rather than being reconstructed from root alone.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Inherited plugin bases are actual provenance, not package-name path exceptions; unknown compiler options are preserved instead of guessed by the host.
+ * @evidence contracts/common.md#meaningful-documentation Native member comments identify ancestry, option normalization, plugin origins and project identity; documented-member and tag spacing follow the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Per-entry declaring directories and separate lexical/physical-path selections preserve distinct native resolution roles, including the identity resolver's realpath-failure fallback and independent project-root override. Resolved outDir is native absolute path data; parser/path utilities own normalization and filesystem proof.
+ * @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 ITtscParsedProjectConfig {
+    /**
+     * Lexical config-selection and inheritance-resolution inputs, including
+     * missing candidates.
+     */
+    configInputs?: readonly string[];
+    /**
+     * True when config selection uses fully observed file candidates; module
+     * inheritance is unproved. Omitted by older/manual records and treated
+     * false.
+     */
+    configInputsComplete?: boolean;
     /** Every resolved tsconfig/jsconfig in the inherited `extends` chain. */
     configPaths: readonly string[];
     /** Compiler options after extends inheritance has been applied. */
@@ -11,12 +33,16 @@ export interface ITtscParsedProjectConfig {
         /** Project plugin entries after inheritance resolution. */
         plugins: ITtscProjectPluginConfig[];
     } & Record<string, unknown>;
-    /** Lexical and physical identities retained for native plugin contexts. */
+    /** Lexical selections and attempted-realpath results for native contexts. */
     identity: Omit<ITtscProjectIdentity, "pluginConfigOrigin">;
     /** Absolute path to the resolved tsconfig/jsconfig. */
     path: string;
     /** Directory that declared each inherited plugin entry. */
     pluginBaseDirs: string[];
-    /** Directory containing the resolved tsconfig/jsconfig. */
+    /**
+     * Selected project root from identity resolution: the explicit override when
+     * supplied, otherwise the resolved config directory, after attempted
+     * realpath.
+     */
     root: string;
 }

package/lib/structures/internal/ITtscProjectIdentity.d.ts

@@ -1,16 +1,31 @@
-/** Separate lexical and physical identities for one selected project. */
+/**
+ * Separate lexical and physical identities for one selected project.
+ *
+ * The resolver attempts realpath for the physical fields. If that operation
+ * fails, it retains the selected absolute spelling; the field names alone do
+ * not certify filesystem identity.
+ *
+ * @evidence contracts/common.md#principled-implementation Invocation and logical spellings remain separate from the resolver's physical-path selections because symlink selection and compiler ownership can differ; realpath failure preserves the selected absolute spelling rather than certifying it, and explicit overrides remain distinguishable from defaults.
+ * @evidence contracts/common.md#clear-and-simple-design Named identity fields make each path's role available to plugin contexts without overloading one project root for selection, loading and caller overrides.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Lexical paths are not discarded and later recreated with platform guesses; caller-declared origins stay explicit rather than being inferred from generated wrapper locations.
+ * @evidence contracts/common.md#meaningful-documentation Native comments explain canonicalization and the origin of each identity; blank member lines and prose/tag separation follow the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Native lexical selections and physical-path results retain their separate roles, including the realpath-failure fallback; the type requires neither manual separator splitting nor blanket lowercasing, and physical equality remains a filesystem owner's responsibility.
+ * @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 ITtscProjectIdentity {
-    /** Caller working directory before filesystem canonicalization. */
+    /** Absolute invocation working directory, without realpath resolution. */
     invocationCwd: string;
-    /** Caller-selected config spelling before filesystem canonicalization. */
+    /** Selected absolute config spelling, before realpath resolution. */
     logicalConfigPath: string;
     /** Directory containing the caller-selected config spelling. */
     logicalProjectRoot: string;
-    /** Realpath-resolved config used to load the TypeScript Program. */
+    /** Config path after attempted realpath; selected spelling on failure. */
     physicalConfigPath: string;
-    /** Realpath-resolved root supplied to the TypeScript Program host. */
+    /** Selected root after attempted realpath; selected spelling on failure. */
     physicalProjectRoot: string;
-    /** Caller-declared project-root override, when present. */
+    /** Caller project-root override resolved from invocation cwd, when present. */
     explicitProjectRoot?: string;
     /** Caller-declared plugin-config discovery origin, when present. */
     pluginConfigOrigin?: string;

package/lib/structures/internal/ITtscProjectInputSnapshot.d.ts

@@ -1,4 +1,15 @@
-/** Normalized local filesystem dependencies published by project rules. */
+/**
+ * Normalized local filesystem dependencies published by project rules.
+ *
+ * @evidence contracts/common.md#principled-implementation Exact paths, glob populations and selection-reload inputs have distinct roles; declared spellings accompany physical identities so link retargeting remains observable instead of being lost during normalization.
+ * @evidence contracts/common.md#clear-and-simple-design One snapshot exposes normalized comparison inputs and optional pre-normalization watch inputs, keeping filesystem publication separate from watcher installation.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Missing exact paths remain meaningful candidates; consumers do not replace them with a fabricated present-file list or compensate for lost symlink spellings.
+ * @evidence contracts/common.md#meaningful-documentation Native comments explain missing paths, slash glob vocabulary, reload scope and why declared spellings are retained; paragraph, member and tag spacing follow the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Native exact paths and forward-slash glob patterns are distinct vocabularies. Normalization uses observed realpath prefixes and filesystem case policy, preserving unresolved spelling when evidence is unavailable. Retained pre-identity spellings let consumers consider link/junction replacement attention; the value itself certifies neither complete alias resolution nor installed watcher behavior.
+ * @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 ITtscProjectInputSnapshot {
     /** Exact absolute paths, retained even while missing. */
     files: readonly string[];
@@ -8,22 +19,26 @@ export interface ITtscProjectInputSnapshot {
     reloadFiles?: readonly string[];
     /** Directories whose immediate topology changes execution selection. */
     reloadDirectories?: readonly string[];
-    /** Physical project root that anchored relative declarations. */
+    /** Selected root identity, with unresolved spelling where proof is absent. */
     root: string;
     /**
      * The spellings the contributors published, before identity normalization.
      *
-     * Normalizing a declaration resolves it through every symlink on its way, so
-     * the retained snapshot names the file the link currently points at rather
-     * than the link. That is what every comparison needs and the wrong thing to
-     * watch: retargeting or replacing the link is exactly what decides which
-     * bytes the declaration names next, and it happens at the spelling that
-     * normalization discarded. Consumers that install watchers keep both.
+     * Successful realpath observations can replace a link spelling with its
+     * target; missing or unavailable suffixes retain unresolved spelling. The
+     * merger retains absolute lexical spellings when they differ from normalized
+     * identity lists, so watcher consumers can consider both target changes and
+     * replacement attention at a declared link. These lists do not install or
+     * certify watcher delivery by themselves.
      */
     declared?: {
+        /** Original exact-path spellings, including absent candidates. */
         files: readonly string[];
+        /** Original glob spellings before physical-identity normalization. */
         globs: readonly string[];
+        /** Original exact inputs that alter execution selection. */
         reloadFiles?: readonly string[];
+        /** Original directory inputs that alter execution selection. */
         reloadDirectories?: readonly string[];
     };
 }

package/lib/structures/internal/ITtscProjectLocatorOptions.d.ts

@@ -1,11 +1,25 @@
-/** Inputs for locating the tsconfig/jsconfig that owns an invocation. */
+/**
+ * Inputs for locating the tsconfig/jsconfig that owns an invocation.
+ *
+ * @evidence contracts/common.md#principled-implementation Optional explicit config, source file and cwd preserve the locator's alternative selection bases; an independent project-root override supports generated configs without changing their selected identity.
+ * @evidence contracts/common.md#clear-and-simple-design This input record states selection hints only, leaving discovery and physical identity derivation with the project locator.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Explicit overrides are supported caller inputs rather than special cases for temporary fixture paths or known consumers.
+ * @evidence contracts/common.md#meaningful-documentation Native member comments identify relative-path/discovery bases and wrapper-root semantics; member spacing and prose/tag separation follow the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Native cwd/file/config/root inputs are kept distinct with documented anchors so the locator can use OS-neutral path APIs; the type requires neither a POSIX root nor manual separator concatenation.
+ * @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 ITtscProjectLocatorOptions {
     /** Working directory for relative paths and upward config discovery. */
     cwd?: string;
-    /** Source file used as the starting point for nearest-config discovery. */
+    /**
+     * Source path resolved from `cwd`; discovery begins at its parent, or at the
+     * path itself when it names an existing directory.
+     */
     file?: string;
-    /** Project root override for generated tsconfig wrappers. */
+    /** Selected project root resolved from `cwd`, separate from config selection. */
     projectRoot?: string;
-    /** Explicit tsconfig/jsconfig path. */
+    /** Explicit config file or directory, absolute or resolved from `cwd`. */
     tsconfig?: string;
 }

package/lib/structures/internal/TtscBuildOptions.d.ts

@@ -1,31 +1,50 @@
 import type { TtscCommonOptions } from "./TtscCommonOptions";
-/** Internal options for a TypeScript-Go project build. */
+/**
+ * Internal options for a TypeScript-Go project build.
+ *
+ * @evidence contracts/common.md#principled-implementation Optional emit distinguishes requested emission, analysis and project-defined selection; forwarded compiler flags retain their documented precedence, while fix/format request host commands separately from emission selection.
+ * @evidence contracts/common.md#clear-and-simple-design Shared process/project options are inherited once, while this record adds only project-build controls rather than unrelated single-file path policy.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Overrides are declared host controls; the launcher owns command restrictions and mutation-command emission suppression, while API callers supply their own selection rather than relying on fixture-specific behavior.
+ * @evidence contracts/common.md#meaningful-documentation Native JSDoc spells out emit selection and forwarded-option precedence, source-rewrite command effects, launcher restrictions and verbosity ownership; paragraphs, member and tag spacing follow the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Config and output-directory overrides are native path values interpreted by the build owner from cwd, while inherited environment and passthrough argv remain structured; this type does not embed POSIX shell or separator assumptions.
+ * @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 TtscBuildOptions extends TtscCommonOptions {
-    /** Project config file to compile. Relative paths are resolved from `cwd`. */
+    /** Config file or containing directory, absolute or resolved from `cwd`. */
     tsconfig?: string;
     /**
      * Emit override for the current call.
      *
-     * - `true`: force file writes even when the project has `noEmit`.
-     * - `false`: force diagnostics/check-only behavior.
-     * - `undefined`: follow the resolved tsconfig exactly.
+     * - `true`: request emission despite the project's `noEmit` setting.
+     * - `false`: select the analysis/check lane.
+     * - `undefined`: use the project's `noEmit` selection.
+     *
+     * Forwarded compiler options follow these compiler defaults and can override
+     * them. Emission still depends on successful checks and producer behavior.
      */
     emit?: boolean;
     /**
-     * Invoke fix-capable check-stage plugins before the final no-emit check.
-     * Source files may be rewritten; JavaScript/declaration emit stays disabled.
+     * Request the fix command from configured check-stage hosts. A host may
+     * reject unsupported commands. Source files may be rewritten. The launcher
+     * also sets `emit: false`; API callers select emission separately.
      */
     fix?: boolean;
     /**
-     * Invoke format-capable check-stage plugins. Source files may be rewritten
-     * with formatter-class edits (whitespace, punctuation, ordering); diagnostics
-     * are not reported and JavaScript/declaration emit stays disabled. The
-     * launcher selects this through the `ttsc format` subcommand and rejects
-     * combination with watch mode, single-file mode, or an explicit `--emit`.
+     * Request the format command from configured check-stage hosts. Source files
+     * may be rewritten, and a host may reject unsupported commands. With `emit:
+     * false`, the dispatcher adds no later type-check or transform pass. The
+     * launcher sets that emit selection for `ttsc format` and rejects watch mode,
+     * single-file mode, or an explicit enabled `--emit`.
      */
     format?: boolean;
-    /** Per-call TypeScript-Go `outDir` override. */
+    /** Per-call output-directory request, absolute or resolved from `cwd`. */
     outDir?: string;
-    /** Suppress summary banners from ttsc/native sidecars. Defaults to `true`. */
+    /**
+     * Request native quiet/verbose presentation; `false` also adds ttsc's direct
+     * build summary. The launcher defaults to `true`; omitted SDK values leave
+     * native verbosity modifiers unset.
+     */
     quiet?: boolean;
 }

package/lib/structures/internal/TtscBuildResult.d.ts

@@ -1,14 +1,73 @@
 import type { ITtscCompilerDiagnostic } from "../ITtscCompilerDiagnostic";
-/** Internal result captured from TypeScript-Go or native plugin sidecars. */
+import type { ITtscCompilerTransformation } from "../ITtscCompilerTransformation";
+/**
+ * Internal result captured from TypeScript-Go or native plugin sidecars.
+ *
+ * @evidence contracts/common.md#principled-implementation Exit status, actual normal completion, diagnostics, streams, check-generation witnesses and optional emitted-source provenance remain separate. Absent provenance, an unknown output's empty source list and a complete empty output map differ; null input witnesses record absence while missing keys establish no reusable proof.
+ * @evidence contracts/common.md#clear-and-simple-design One result record carries process facts and separately requested emitted-file/provenance data without making display-text parsing responsible for source ownership.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Streams derive from actual host output, though failure normalization can move stdout into stderr and phase composition can concatenate them. Numeric status remains separate from normal-completion proof; neither diagnostic text nor normalization invents successful execution or source ownership.
+ * @evidence contracts/common.md#meaningful-documentation Native comments state status versus actual completion, emitted-list availability, generation ownership, null versus missing witnesses and unknown/ambiguous provenance states; member and tag separation follow the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Provenance distinguishes actual absolute native output spelling from physical source identity captured by the producer or stable external observations; neither path is case-folded or reconstructed from a URL, and each producer owns its resolution premise.
+ * @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 TtscBuildResult {
-    /** Structured diagnostics collected from compiler output. */
+    /** Compiler-time graph of the same check generation, when transported. */
+    graph?: ITtscCompilerTransformation.IReferenceGraph;
+    /** Structured compiler/plugin diagnostics, supplied or parsed from output. */
     diagnostics: ITtscCompilerDiagnostic[];
     /** Files written by the build when emitted-file listing was requested. */
     emittedFiles?: string[];
+    /**
+     * Emitter provenance for actual written JavaScript outputs. Keys are absolute
+     * native output spellings; values retain contributing physical source paths.
+     * Native producers capture those identities in the compile generation. The
+     * external compiler adapter instead requires matching pre/post source
+     * selection, effective options, physical identities and contents, including
+     * the selected executable. It cannot detect a concurrent change restored
+     * between observations.
+     *
+     * Multiple sources are ambiguous for single-file routing, and an empty list
+     * means the producer could not establish full ownership under its premise.
+     *
+     * Absent means unavailable or an older producer. A present empty map means a
+     * supported producer reported no eligible written JavaScript output.
+     * Consumers must not infer source ownership from emitted filenames in either
+     * unknown state. Provenance does not by itself establish overall build
+     * success.
+     */
+    emittedSources?: Record<string, readonly string[]>;
+    /**
+     * Actual proof-refusal reasons for reported output paths. Diagnostic context
+     * alone establishes no source ownership and does not replace compiler
+     * errors.
+     */
+    emittedSourceProofFailures?: Readonly<Record<string, string>>;
+    /** Native inputs declared or observed by the contributing check generations. */
+    hostInputs?: string[];
+    /**
+     * Generation-captured SHA-256 witnesses, keyed by declared native input. Null
+     * records observed absence; a missing key supplies no reusable proof.
+     */
+    hostInputHashes?: Record<string, string | null>;
+    /**
+     * Generation-captured physical paths, or null for observed absence. Missing
+     * keys preserve unavailable or conflicting proof without a later realpath.
+     */
+    hostInputRealpaths?: Record<string, string | null>;
+    /** A contributing producer explicitly reported incomplete observations. */
+    observationsComplete?: false;
+    /**
+     * Actual spawn completion fact before null-status coercion. True requires a
+     * present native exit status and no terminating signal; absence proves no
+     * completion premise for generation-owned metadata.
+     */
+    processCompletedNormally?: boolean;
     /** Process-style exit status. `0` means success. */
     status: number;
-    /** Captured stdout from TypeScript-Go or native plugin sidecars. */
+    /** Host stdout text after any failure normalization or phase composition. */
     stdout: string;
-    /** Captured stderr from TypeScript-Go or native plugin sidecars. */
+    /** Host stderr text after any failure normalization or phase composition. */
     stderr: string;
 }