@ttsc/wasm 0.30.3 → 0.31.0

package/src/structures/ITtscFileQuery.ts

@@ -1,6 +1,24 @@
 import type { ITtscSnapshotHandle } from "./ITtscSnapshotHandle";
 
-/** Request shape for `getSourceFileText`. */
+/**
+ * Request shape for `getSourceFileText`.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   Extending the shared handle keeps snapshot identity consistent while adding
+ *   the file selector accepted by resolveSnapshotFile in the native host.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   Extending the common handle adds only the file selector, so all file queries
+ *   share one snapshot identity definition and path interpretation boundary.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   The request names its snapshot and file explicitly; no project lookup is
+ *   replaced by a fixed consumer path.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   JSDoc names the endpoint and accepted path bases, while the inherited member
+ *   documents the opaque handle, following the documentation skill's context rule.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources ITtscFileQuery is a data interface and acquires no handle, task or retained state.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms ITtscFileQuery is a data interface and chooses no algorithm or processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work ITtscFileQuery is a data interface and coordinates no shared or repeated computation.
+ */
 export interface ITtscFileQuery extends ITtscSnapshotHandle {
   /** Project-relative or absolute path inside the snapshot's program. */
   path: string;

package/src/structures/ITtscFountainDiagnosticsResult.ts

@@ -1,6 +1,25 @@
 import type { ITtscDiagnostic } from "./ITtscDiagnostic";
 
-/** Payload inside `ITtscResult.result` for `getDiagnostics`. */
+/**
+ * Payload inside `ITtscResult.result` for `getDiagnostics`.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   The required array matches the native endpoint's initialized result slice,
+ *   unlike compile payloads where an absent diagnostics property is supported.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   A single initialized list represents the selection; messages reuse the
+ *   compile diagnostic DTO and the transport status remains in its envelope.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   Reusing the compiler diagnostic shape avoids a separate simplified schema
+ *   that discards information to satisfy a particular UI.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Native JSDoc identifies the envelope and explains empty-result meaning,
+ *   using the documentation skill's concrete context guidance.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources ITtscFountainDiagnosticsResult is a data interface and acquires no handle, task or retained state.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms ITtscFountainDiagnosticsResult is a data interface and chooses no algorithm or processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work ITtscFountainDiagnosticsResult is a data interface and coordinates no shared or repeated computation.
+ */
 export interface ITtscFountainDiagnosticsResult {
+  /** Messages selected by the query; an empty array means none were returned. */
   diagnostics: ITtscDiagnostic[];
 }

package/src/structures/ITtscNodeAtPositionResult.ts

@@ -1,6 +1,23 @@
 import type { ITtscNodeInfo } from "./ITtscNodeInfo";
 
-/** Payload inside `ITtscResult.result` for `getNodeAtPosition`. */
+/**
+ * Payload inside `ITtscResult.result` for `getNodeAtPosition`.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   A nullable node mirrors the native pointer's JSON encoding and distinguishes
+ *   a successful query with no token from an error envelope.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   One nullable node field expresses a token query result; node details and
+ *   transport errors stay in their existing separate representations.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   No fabricated node stands in for an absent token; absence remains explicit.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   JSDoc names the endpoint and null meaning, following the documentation
+ *   skill's requirement to explain optional or absent state.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources ITtscNodeAtPositionResult is a data interface and acquires no handle, task or retained state.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms ITtscNodeAtPositionResult is a data interface and chooses no algorithm or processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work ITtscNodeAtPositionResult is a data interface and coordinates no shared or repeated computation.
+ */
 export interface ITtscNodeAtPositionResult {
   /** `null` when no syntax token touches the position. */
   node: ITtscNodeInfo | null;

package/src/structures/ITtscNodeInfo.ts

@@ -1,13 +1,38 @@
-/** Syntax-token shape returned by `getNodeAtPosition`. */
+/**
+ * Syntax-token shape returned by `getNodeAtPosition`.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   Numeric kind and byte ranges preserve TypeScript-Go's AST representation;
+ *   a printable name and optional text make the JSON usable without that AST.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   Kind, range and spelling are a flat token projection, without exposing
+ *   parent links or mutable compiler nodes to the JavaScript consumer.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   Positions remain native byte offsets, without a guessed UTF-16 conversion
+ *   or an invented source span for a particular token.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Members explain range units, endpoint inclusion and optional text. Native
+ *   JSDoc follows the documentation skill's concrete usage-context guidance.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources ITtscNodeInfo is a data interface and acquires no handle, task or retained state.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms ITtscNodeInfo is a data interface and chooses no algorithm or processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work ITtscNodeInfo is a data interface and coordinates no shared or repeated computation.
+ */
 export interface ITtscNodeInfo {
   /** Numeric `ast.Kind` from TypeScript-Go. */
   kind: number;
+
   /** Human-readable name of `kind`. */
   kindName: string;
-  /** Byte offset where the node begins (inclusive). */
+
+  /**
+   * Byte offset of the token's first byte (inclusive), after leading whitespace
+   * and comments.
+   */
   pos: number;
+
   /** Byte offset where the node ends (exclusive). */
   end: number;
+
   /** Source text covered by the node, when available. */
   text?: string;
 }

package/src/structures/ITtscPluginOpts.ts

@@ -1,13 +1,38 @@
-/** Options for dispatching a named plugin subcommand via `api.plugin`. */
+/**
+ * Options for dispatching a named plugin subcommand via `api.plugin`.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   Required dispatch fields plus scalar options mirror buildPluginArgv's native
+ *   translation, allowing each registered plugin to own its argument schema.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   Named dispatch fields are separated from forwarded scalars; the index
+ *   signature permits plugin-owned arguments without hardwiring plugin schemas.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   Plugin defaults remain with the plugin; this transport does not hardcode
+ *   consumer-specific arguments or pretend to validate an unknown command.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Member JSDoc distinguishes dispatch identity from forwarded arguments and
+ *   boolean omission, following the documentation skill's usage-context guidance.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources ITtscPluginOpts is a data interface and acquires no handle, task or retained state.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms ITtscPluginOpts is a data interface and chooses no algorithm or processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work ITtscPluginOpts is a data interface and coordinates no shared or repeated computation.
+ */
 export interface ITtscPluginOpts {
   /** Plugin id registered with `host.Expose` (e.g. `@ttsc/banner`). */
   name: string;
+
   /** Subcommand the plugin's Run will receive (e.g. `build`). */
   command: string;
+
   /** Forwarded as `--cwd=<value>`. */
   cwd?: string;
-  /** Forwarded as `--tsconfig=<value>`. Defaults to `tsconfig.json`. */
+
+  /** Forwarded as `--tsconfig=<value>`; an absent value is left to the plugin. */
   tsconfig?: string;
-  /** Any extra key/value pairs map to `--key=value` argv entries. */
+
+  /**
+   * Scalars become `--key=value`; true becomes `--key`, false/undefined are
+   * omitted.
+   */
   [key: string]: string | boolean | number | undefined;
 }

package/src/structures/ITtscPositionQuery.ts

@@ -3,13 +3,30 @@ import type { ITtscFileQuery } from "./ITtscFileQuery";
 /**
  * Request shape for `getNodeAtPosition`, `getTypeAtPosition`,
  * `getSymbolAtPosition`.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   Extending the shared file query adds the native byte-offset selector without
+ *   duplicating snapshot/file identity. The native boundary validates finite
+ *   integer bounds before converting JavaScript numbers to Go byte offsets.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   The file query owns snapshot and path selection; this extension adds only
+ *   the byte coordinate shared by syntax, type and symbol endpoint handlers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   The native coordinate system is explicit rather than repaired by guessing
+ *   that a JavaScript character index equals an offset into UTF-8 source.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Member JSDoc gives the accepted interval and explains the caller's UTF-16
+ *   conversion responsibility, following the documentation skill's units rule.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources ITtscPositionQuery is a data interface and acquires no handle, task or retained state.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms ITtscPositionQuery is a data interface and chooses no algorithm or processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work ITtscPositionQuery is a data interface and coordinates no shared or repeated computation.
  */
 export interface ITtscPositionQuery extends ITtscFileQuery {
   /**
-   * Byte offset into the file's source text. It must satisfy `0 <= position <
-   * sourceText's UTF-8 byte length`; the offset immediately after the final
-   * byte is out of range. JS callers with a UTF-16 line/character pair must
-   * resolve it to a byte offset first.
+   * Integer byte offset into the file's source text. It must satisfy `0 <=
+   * position < sourceText's UTF-8 byte length`; the offset immediately after
+   * the final byte is out of range. JS callers with a UTF-16 line/character
+   * pair must resolve it to a byte offset first.
    */
   position: number;
 }

package/src/structures/ITtscReleaseSnapshotResult.ts

@@ -1,5 +1,25 @@
-/** Payload inside `ITtscResult.result` for `releaseSnapshot`. */
+/**
+ * Payload inside `ITtscResult.result` for `releaseSnapshot`.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   The boolean mirrors the native release outcome without making an unknown
+ *   handle into a transport failure; idempotent callers can inspect the result.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   One outcome field conveys registry removal; handle lookup and resource
+ *   cleanup belong to the native owner, outside this response value.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   The actual release outcome is represented instead of always reporting success.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   JSDoc separates the enclosing payload from absent-handle meaning, following
+ *   the documentation skill's guidance for failure and optional state.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources ITtscReleaseSnapshotResult is a data interface and acquires no handle, task or retained state.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms ITtscReleaseSnapshotResult is a data interface and chooses no algorithm or processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work ITtscReleaseSnapshotResult is a data interface and coordinates no shared or repeated computation.
+ */
 export interface ITtscReleaseSnapshotResult {
-  /** `false` when the handle was not present (already released). */
+  /**
+   * `false` when the handle was absent, whether never created or already
+   * released.
+   */
   released: boolean;
 }

package/src/structures/ITtscResult.ts

@@ -1,14 +1,43 @@
-/** Envelope returned by every `ITtscApi` method. */
+/**
+ * Envelope returned by asynchronous `ITtscApi` operations.
+ *
+ * `version` and `plugins` return their synchronous values directly.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   The uniform exit-code/stream/payload shape mirrors the native JavaScript
+ *   bridge, with structured JSON separate from plugin output streams.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   One envelope separates status, two output channels and structured payload
+ *   text, leaving endpoint-specific DTOs outside the transport representation.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   A nonzero code remains visible; empty payload text is not replaced with a
+ *   fabricated success object or interpreted as evidence that the call succeeded.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Separate JSDoc paragraphs distinguish asynchronous envelopes from direct
+ *   values; members explain channels, following the documentation skill's guidance.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources ITtscResult is a data interface and acquires no handle, task or retained state.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms ITtscResult is a data interface and chooses no algorithm or processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work ITtscResult is a data interface and coordinates no shared or repeated computation.
+ */
 export interface ITtscResult {
   /** Exit code. 0 = success, 2 = compiler/config/usage error, 3 = runtime error. */
   code: number;
-  /** Anything the wasm wrote to its stdout stream. */
+
+  /**
+   * Invocation-owned plugin stdout; project/query endpoints use an empty
+   * string.
+   */
   stdout: string;
-  /** Anything the wasm wrote to its stderr stream. */
+
+  /**
+   * Plugin stderr or a project/query failure message; distinct from host.stderr
+   * capture.
+   */
   stderr: string;
+
   /**
-   * For the base endpoints, the JSON-encoded compile/transform result. For the
-   * plugin endpoint, this is empty — the plugin's own output sits in
+   * For project and snapshot endpoints, the JSON-encoded structured result. For
+   * the plugin endpoint, this is empty. The plugin's own output sits in
    * stdout/stderr. Use `parseResult<T>` to deserialize.
    */
   result: string;

package/src/structures/ITtscSnapshotHandle.ts

@@ -1,4 +1,22 @@
-/** Common request shape for fountain verbs that act on an existing snapshot. */
+/**
+ * Common request shape for fountain verbs that act on an existing snapshot.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   The opaque string matches the native snapshot registry's public identity
+ *   and is shared by query types through interface extension.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   The shared request contains only registry identity; derived requests add
+ *   selectors without exposing the retained Program or duplicating its lifecycle.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   Callers pass the returned identity; they need not reconstruct an internal
+ *   sequence or depend on the current handle spelling.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   JSDoc identifies the shared request role and opaque producer, following the
+ *   documentation skill's requirement for nonobvious usage context.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources ITtscSnapshotHandle is a data interface and acquires no handle, task or retained state.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms ITtscSnapshotHandle is a data interface and chooses no algorithm or processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work ITtscSnapshotHandle is a data interface and coordinates no shared or repeated computation.
+ */
 export interface ITtscSnapshotHandle {
   /** Opaque handle returned by `snapshot`. */
   handle: string;

package/src/structures/ITtscSnapshotResult.ts

@@ -1,4 +1,25 @@
-/** Payload inside `ITtscResult.result` for `snapshot`. */
+/**
+ * Payload inside `ITtscResult.result` for `snapshot`.
+ *
+ * The caller owns the returned snapshot and must release it when queries
+ * finish.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   Returning an opaque handle keeps retained Go program objects behind the
+ *   native registry while allowing several queries to share one snapshot.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   A single opaque handle transfers query access to the caller; registry state
+ *   and Program cleanup remain with the host instead of entering the payload.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   The handle refers to a real registered program, without encoding a consumer
+ *   path or fabricated query result into the public identity.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Separate JSDoc paragraphs explain the envelope and release ownership, and
+ *   the member names its consumers, following the documentation skill's guidance.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources ITtscSnapshotResult is a data interface and acquires no handle, task or retained state.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms ITtscSnapshotResult is a data interface and chooses no algorithm or processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work ITtscSnapshotResult is a data interface and coordinates no shared or repeated computation.
+ */
 export interface ITtscSnapshotResult {
   /** Opaque handle; pass back to fountain verbs and to `releaseSnapshot`. */
   handle: string;

package/src/structures/ITtscSnapshotsResult.ts

@@ -1,4 +1,22 @@
-/** Payload inside `ITtscResult.result` for `snapshots`. */
+/**
+ * Payload inside `ITtscResult.result` for `snapshots`.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   A string array mirrors the registry listing without exposing program objects
+ *   or implying an ordering that the native map does not provide.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   A flat list exposes live registry identities without a second snapshot
+ *   descriptor layer or ownership information already supplied by its API.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   Entries are current registry identities rather than an expected debug list.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   JSDoc identifies the envelope, empty state and unspecified order using the
+ *   documentation skill's concrete context guidance.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources ITtscSnapshotsResult is a data interface and acquires no handle, task or retained state.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms ITtscSnapshotsResult is a data interface and chooses no algorithm or processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work ITtscSnapshotsResult is a data interface and coordinates no shared or repeated computation.
+ */
 export interface ITtscSnapshotsResult {
+  /** Live handles in unspecified order; empty when none are registered. */
   handles: string[];
 }

package/src/structures/ITtscSourceFileTextResult.ts

@@ -1,4 +1,22 @@
-/** Payload inside `ITtscResult.result` for `getSourceFileText`. */
+/**
+ * Payload inside `ITtscResult.result` for `getSourceFileText`.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   A required text field mirrors the native successful response; missing files
+ *   use the error envelope rather than overloading an empty source string.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   The selected file's text is the only payload field; request identity and
+ *   error status remain in the existing request and transport envelope.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   Text comes from the retained program, without substituting the caller's
+ *   editor buffer or a separately loaded approximation of the snapshot.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Native JSDoc names the endpoint and retained-program provenance, following
+ *   the documentation skill's rule to explain the facts needed by a consumer.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources ITtscSourceFileTextResult is a data interface and acquires no handle, task or retained state.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms ITtscSourceFileTextResult is a data interface and chooses no algorithm or processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work ITtscSourceFileTextResult is a data interface and coordinates no shared or repeated computation.
+ */
 export interface ITtscSourceFileTextResult {
   /** Current source text held by the snapshot's program. */
   text: string;

package/src/structures/ITtscSourceFilesResult.ts

@@ -1,5 +1,26 @@
-/** Payload inside `ITtscResult.result` for `getSourceFiles`. */
+/**
+ * Payload inside `ITtscResult.result` for `getSourceFiles`.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   A string array carries the native program's source-file keys without making
+ *   the JavaScript consumer depend on Go AST objects.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   The payload exposes only source identities; source text and semantic queries
+ *   remain separate operations instead of inflating every file-list response.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   The program supplies file identity; the response does not invent a fixed
+ *   entry file or hide files according to a consumer name.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   JSDoc identifies the endpoint, declaration-file exclusion and path convention,
+ *   following the documentation skill's usage-context guidance.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources ITtscSourceFilesResult is a data interface and acquires no handle, task or retained state.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms ITtscSourceFilesResult is a data interface and chooses no algorithm or processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work ITtscSourceFilesResult is a data interface and coordinates no shared or repeated computation.
+ */
 export interface ITtscSourceFilesResult {
-  /** Project-relative paths of non-declaration source files. */
+  /**
+   * Non-declaration source paths: project-relative inside cwd, absolute
+   * outside.
+   */
   files: string[];
 }

package/src/structures/ITtscSymbolAtPositionResult.ts

@@ -1,6 +1,23 @@
 import type { ITtscSymbolInfo } from "./ITtscSymbolInfo";
 
-/** Payload inside `ITtscResult.result` for `getSymbolAtPosition`. */
+/**
+ * Payload inside `ITtscResult.result` for `getSymbolAtPosition`.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   The nullable symbol follows native pointer JSON encoding, keeping successful
+ *   absence distinct from a failed query envelope.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   A nullable symbol field holds the lookup outcome; reusable symbol metadata
+ *   and transport failure are represented separately without another status flag.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   Absence is explicit rather than filled with a guessed identifier or symbol.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   JSDoc names the envelope and null meaning, following the documentation
+ *   skill's requirement to explain absence rather than repeat the field type.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources ITtscSymbolAtPositionResult is a data interface and acquires no handle, task or retained state.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms ITtscSymbolAtPositionResult is a data interface and chooses no algorithm or processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work ITtscSymbolAtPositionResult is a data interface and coordinates no shared or repeated computation.
+ */
 export interface ITtscSymbolAtPositionResult {
   /** `null` when no touching token has an associated symbol. */
   symbol: ITtscSymbolInfo | null;

package/src/structures/ITtscSymbolDeclaration.ts

@@ -1,7 +1,32 @@
-/** A single declaration site for a symbol. */
+/**
+ * A single declaration site for a symbol.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   Nullable file identity and byte ranges preserve the native AST declaration
+ *   projection, including declarations without an associated source file.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   Source identity and a byte interval are sufficient for a declaration site;
+ *   this value contains no redundant source text or compiler object references.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   A missing source file remains null; neither a placeholder filename nor a
+ *   guessed JavaScript character range is inserted into the declaration.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Member JSDoc explains path provenance and interval units, following the
+ *   documentation skill's guidance for absent state and coordinates.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources ITtscSymbolDeclaration is a data interface and acquires no handle, task or retained state.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms ITtscSymbolDeclaration is a data interface and chooses no algorithm or processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work ITtscSymbolDeclaration is a data interface and coordinates no shared or repeated computation.
+ */
 export interface ITtscSymbolDeclaration {
-  /** Project-relative or absolute path; `null` for synthetic declarations. */
+  /** Project-relative or absolute path; null when no source file is associated. */
   file: string | null;
+
+  /**
+   * Inclusive start offset of the declaration's first token in the source's
+   * UTF-8 bytes, after leading whitespace, comments and JSDoc.
+   */
   pos: number;
+
+  /** Exclusive end offset in the source's UTF-8 bytes. */
   end: number;
 }

package/src/structures/ITtscSymbolInfo.ts

@@ -1,15 +1,37 @@
 import type { ITtscSymbolDeclaration } from "./ITtscSymbolDeclaration";
 
-/** Symbol shape returned by `getSymbolAtPosition`. */
+/**
+ * Symbol shape returned by `getSymbolAtPosition`.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   Names, flags and declaration projections match the native checker result;
+ *   separate displayed text avoids confusing raw internal names with presentation.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   Identity and presentation are separate, while bounded declaration sites reuse
+ *   one site DTO and their total count explains a truncated projection directly.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   The declaration cap is the host's response-size policy, with the original
+ *   total retained rather than pretending the shortened list is complete.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   JSDoc explains internal naming, printing and capped versus total declarations,
+ *   following the documentation skill's concrete context guidance.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources ITtscSymbolInfo is a data interface and acquires no handle, task or retained state.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms ITtscSymbolInfo is a data interface and chooses no algorithm or processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work ITtscSymbolInfo is a data interface and coordinates no shared or repeated computation.
+ */
 export interface ITtscSymbolInfo {
   /** Raw symbol name, including TypeScript's internal prefix markers. */
   name: string;
+
   /** Printed symbol, equivalent to TypeScript's `SymbolToString(s)`. */
   text?: string;
+
   /** Numeric `SymbolFlags` bitmask from TypeScript-Go. */
   flags: number;
+
   /** Up to 16 declaration sites; see `declarationCount` for the unclamped total. */
   declarations?: ITtscSymbolDeclaration[];
+
   /** Total number of declarations, even when `declarations` was clamped. */
   declarationCount?: number;
 }

package/src/structures/ITtscTransformResult.ts

@@ -3,11 +3,30 @@ import type { ITtscDiagnostic } from "./ITtscDiagnostic";
 /**
  * Structured payload inside `ITtscResult.result` for `transform`.
  *
- * `typescript` maps source file paths (relative to `cwd`) to their
- * post-transform TypeScript text — useful for playgrounds that want to show the
- * rewritten source before it is emitted.
+ * `typescript` maps source paths to post-transform TypeScript text for a
+ * preview before emit. Paths inside `cwd` are relative; outside sources remain
+ * absolute.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   A path-keyed string record matches the native transform payload, keeping
+ *   transformed TypeScript distinct from build's emitted JavaScript map.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   A source-text map and the shared diagnostic DTO serve transform consumers;
+ *   emitted files belong to the compile result instead of a mixed payload.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   The payload exposes actual transformed source, without treating expected
+ *   emitted answers as a replacement for the transform result.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Separate paragraphs identify the envelope and source stage; members explain
+ *   optional diagnostics, following the documentation skill's clarity guidance.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources ITtscTransformResult is a data interface and acquires no handle, task or retained state.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms ITtscTransformResult is a data interface and chooses no algorithm or processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work ITtscTransformResult is a data interface and coordinates no shared or repeated computation.
  */
 export interface ITtscTransformResult {
+  /** Present when the native transform includes diagnostic messages. */
   diagnostics?: ITtscDiagnostic[];
+
+  /** Post-transform source text keyed by source-file paths. */
   typescript: Record<string, string>;
 }

package/src/structures/ITtscTypeAtPositionResult.ts

@@ -1,6 +1,23 @@
 import type { ITtscTypeInfo } from "./ITtscTypeInfo";
 
-/** Payload inside `ITtscResult.result` for `getTypeAtPosition`. */
+/**
+ * Payload inside `ITtscResult.result` for `getTypeAtPosition`.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   A nullable type mirrors the native optional semantic result, separately from
+ *   the error code carried by the enclosing request envelope.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   The nullable type field carries the semantic result without conflating it
+ *   with request failure or adding a parallel state discriminator.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   No universal any/error type is fabricated for positions without type semantics.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Native JSDoc identifies the endpoint and meaningful null state, following
+ *   the documentation skill's guidance for consumer-facing context.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources ITtscTypeAtPositionResult is a data interface and acquires no handle, task or retained state.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms ITtscTypeAtPositionResult is a data interface and chooses no algorithm or processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work ITtscTypeAtPositionResult is a data interface and coordinates no shared or repeated computation.
+ */
 export interface ITtscTypeAtPositionResult {
   /** `null` when no touching token has a type. */
   type: ITtscTypeInfo | null;

package/src/structures/ITtscTypeInfo.ts

@@ -1,7 +1,26 @@
-/** Type shape returned by `getTypeAtPosition`. */
+/**
+ * Type shape returned by `getTypeAtPosition`.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   Printed text and native flag bits project the checker result through JSON
+ *   without exposing Go checker objects or an incomplete parallel type model.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   Printed text and native flags provide presentation and classification in a
+ *   small value; structural compiler types remain owned by the native checker.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   TypeToString is the presentation authority; the consumer need not infer
+ *   a type from source spelling or a manually maintained flag lookup.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Member JSDoc names the native printing API and flag provenance, following
+ *   the documentation skill's concrete context guidance.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources ITtscTypeInfo is a data interface and acquires no handle, task or retained state.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms ITtscTypeInfo is a data interface and chooses no algorithm or processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work ITtscTypeInfo is a data interface and coordinates no shared or repeated computation.
+ */
 export interface ITtscTypeInfo {
   /** Printed type, equivalent to TypeScript's `TypeToString(t)`. */
   text: string;
+
   /** Numeric `TypeFlags` bitmask from TypeScript-Go. */
   flags: number;
 }