ttsc 0.30.4 → 0.31.1

package/src/structures/ITtscPluginCapabilities.ts

@@ -12,8 +12,45 @@
  * 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.
@@ -37,6 +74,22 @@ export interface ITtscPluginCapabilities {
    */
   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
@@ -82,13 +135,13 @@ export interface ITtscPluginCapabilities {
 
   /**
    * 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/src/structures/ITtscPluginContributor.ts

@@ -4,26 +4,37 @@
  * 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/src/structures/ITtscPluginFactoryContext.ts

@@ -8,9 +8,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/src/structures/ITtscProjectPluginConfig.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 {
   /**
@@ -29,9 +46,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
@@ -40,10 +62,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/src/structures/TtscPluginStage.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/src/structures/internal/ITtscLoadedNativePlugin.ts

@@ -3,27 +3,49 @@ 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[];
+
   /** Whether this source owns a process or is linked into another host. */
   kind: "executable" | "linked";
+
   /** Optional human label used in diagnostics and native manifests. */
   name?: string;
+
   /** Whether a check-stage plugin already emits TypeScript diagnostics. */
   reportsTypeScriptDiagnostics?: boolean;
+
   /** Go source directory selected by the plugin descriptor. */
   source: string;
+
   /** Pipeline stage where the native source participates. */
   stage: TtscPluginStage;
 }

package/src/structures/internal/ITtscParsedProjectConfig.ts

@@ -1,23 +1,57 @@
 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. */
   compilerOptions: {
     /** Absolute output directory when configured. */
     outDir?: string;
+
     /** 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/src/structures/internal/ITtscProjectIdentity.ts

@@ -1,17 +1,38 @@
-/** 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/src/structures/internal/ITtscProjectInputSnapshot.ts

@@ -1,29 +1,52 @@
-/** 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[];
+
   /** Absolute glob patterns using forward-slash separators. */
   globs: readonly string[];
+
   /** Exact paths whose change invalidates plugin/execution selection. */
   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/src/structures/internal/ITtscProjectLocatorOptions.ts

@@ -1,11 +1,28 @@
-/** 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/src/structures/internal/TtscBuildOptions.ts

@@ -1,32 +1,56 @@
 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;
 }