@ttsc/wasm 0.30.4 → 0.31.0

package/lib/src/structures/ITtscApi.d.ts

@@ -10,34 +10,103 @@ import type { ITtscVersion } from "./ITtscVersion";
  *
  * Obtain an instance via `bootTtsc`, which waits for the wasm to signal
  * readiness and returns the typed handle together with its `IMemFSHost`.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   Signatures mirror host.Expose's direct metadata/list methods and asynchronous
+ *   project/snapshot methods, sharing request DTOs and the native result envelope.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   Named verbs distinguish project work from retained-program queries; requests
+ *   share small DTOs and async results share one envelope. Direct metadata/list
+ *   values stay synchronous because their native handlers do not load a project.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   Queries address retained programs through opaque handles rather than
+ *   substituting JavaScript source heuristics for compiler semantics.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   JSDoc separates acquisition, decoding, coordinates and snapshot ownership,
+ *   following the documentation skill's paragraph and context guidance.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources ITtscApi only groups the wasm API verbs and acquires no handle, task or retained state.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms ITtscApi only groups the wasm API verbs and chooses no algorithm.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work ITtscApi only groups the wasm API verbs and coordinates no computation.
  */
 export interface ITtscApi {
-    /** Build metadata reported by the wasm. Useful for diagnostics. */
+    /**
+     * Build metadata reported synchronously by the wasm.
+     *
+     * @evidence contracts/common.md#principled-implementation The direct return mirrors jsVersion's synchronous projection.
+     * @evidence contracts/common.md#clear-and-simple-design One direct metadata value requires no project request or asynchronous transport envelope.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Binary metadata supplies identity rather than a guessed browser or release constant.
+     * @evidence contracts/common.md#meaningful-documentation JSDoc states direct-return behavior under the documentation skill's context rule.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources version is a signature only; the lifetime of what it touches belongs to the Go host.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms version is a signature only; its algorithm and cost belong to the Go host.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work version is a signature only; sharing of repeated work belongs to the Go host.
+     */
     version(): ITtscVersion;
     /**
      * Compile a project: typecheck + emit. `result` is JSON;
      * `parseResult<ITtscCompileResult>` deserializes it.
+     *
+     * @evidence contracts/common.md#principled-implementation The Promise envelope follows native Build and the shared project request.
+     * @evidence contracts/common.md#clear-and-simple-design The named emit verb reuses project options and the result envelope without mixing no-emit switches into its request.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The loaded program supplies output, without a consumer-specific emitter path.
+     * @evidence contracts/common.md#meaningful-documentation JSDoc states purpose and decoding under the documentation skill's context rule.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources build is a signature only; the lifetime of what it touches belongs to the Go host.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms build is a signature only; its algorithm and cost belong to the Go host.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work build is a signature only; sharing of repeated work belongs to the Go host.
      */
     build(opts: ITtscBuildOpts): Promise<ITtscResult>;
     /**
      * Typecheck without emit. `result` is JSON; `parseResult<ITtscCompileResult>`
      * deserializes it.
+     *
+     * @evidence contracts/common.md#principled-implementation Native Check owns no-emit loading and the shared compile payload.
+     * @evidence contracts/common.md#clear-and-simple-design A separate no-emit verb makes intent explicit while sharing project and diagnostic representations.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts No-emit is a loader option rather than pretending an emitted build was a check.
+     * @evidence contracts/common.md#meaningful-documentation JSDoc explains no-emit and decoding under the documentation skill's clarity rule.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources check is a signature only; the lifetime of what it touches belongs to the Go host.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms check is a signature only; its algorithm and cost belong to the Go host.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work check is a signature only; sharing of repeated work belongs to the Go host.
      */
     check(opts: ITtscBuildOpts): Promise<ITtscResult>;
     /**
-     * Return every source file the program saw, keyed by project-relative path.
-     * Used by playgrounds that want to render the TypeScript view after a source
-     * rewriter (e.g. paths) has run. `result` is JSON; use
+     * Return source text keyed by project-relative path inside cwd and absolute
+     * path outside it. Used by playgrounds that want to render the TypeScript
+     * view after a source rewriter (e.g. paths) has run. `result` is JSON; use
      * `parseResult<ITtscTransformResult>` to deserialize.
+     *
+     * @evidence contracts/common.md#principled-implementation Native Transform projects post-plugin text through the shared project request.
+     * @evidence contracts/common.md#clear-and-simple-design The source projection is its own verb and DTO, keeping emitted output distinct from transformed TypeScript.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Source comes from the transformed program rather than inference from emitted JavaScript.
+     * @evidence contracts/common.md#meaningful-documentation JSDoc explains source stage, paths and decoding under the documentation skill's context rule.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources transform is a signature only; the lifetime of what it touches belongs to the Go host.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms transform is a signature only; its algorithm and cost belong to the Go host.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work transform is a signature only; sharing of repeated work belongs to the Go host.
      */
     transform(opts: ITtscBuildOpts): Promise<ITtscResult>;
     /**
      * Dispatch a registered plugin's subcommand. Returns the captured stdout /
      * stderr (the same streams the native sidecar binary would write to) together
      * with the exit code.
+     *
+     * @evidence contracts/common.md#principled-implementation Named dispatch adapts scalar options to a registered Go Plugin's command arguments.
+     * @evidence contracts/common.md#clear-and-simple-design One dispatcher forwards plugin-owned arguments without adding a host endpoint for each plugin command.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Invocation-owned streams replace global-output mutation; command semantics stay with the plugin.
+     * @evidence contracts/common.md#meaningful-documentation JSDoc explains dispatch and output ownership under the documentation skill's ownership rule.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources plugin is a signature only; the lifetime of what it touches belongs to the Go host.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms plugin is a signature only; its algorithm and cost belong to the Go host.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work plugin is a signature only; sharing of repeated work belongs to the Go host.
      */
     plugin(opts: ITtscPluginOpts): Promise<ITtscResult>;
-    /** Names of the plugins this wasm was built with. */
+    /**
+     * Names of registered plugins, returned synchronously.
+     *
+     * @evidence contracts/common.md#principled-implementation The direct array mirrors the native registry's name projection.
+     * @evidence contracts/common.md#clear-and-simple-design A direct name list exposes registration discovery without leaking Plugin instances or invoking commands.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Entries describe linked registrations rather than a fixed list of npm packages.
+     * @evidence contracts/common.md#meaningful-documentation JSDoc states registry provenance and direct return under the documentation skill's context rule.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources plugins is a signature only; the lifetime of what it touches belongs to the Go host.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms plugins is a signature only; its algorithm and cost belong to the Go host.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work plugins is a signature only; sharing of repeated work belongs to the Go host.
+     */
     plugins(): string[];
     /**
      * Load a project once and retain the TypeScript-Go Program in memory for
@@ -46,26 +115,78 @@ export interface ITtscApi {
      * Callers MUST call `releaseSnapshot` for every handle they receive to free
      * the program's checker pool lease and let Go GC reclaim the AST. Use
      * `parseResult<ITtscSnapshotResult>` to read the handle.
+     *
+     * @evidence contracts/common.md#principled-implementation An opaque handle references a retained native program for repeated queries.
+     * @evidence contracts/common.md#clear-and-simple-design Acquisition is distinct from querying and release, so the caller can identify its explicit retained-program lifetime.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Queries share the actual program rather than rebuilding approximations for each request.
+     * @evidence contracts/common.md#meaningful-documentation Separate JSDoc paragraphs explain acquisition, decoding and release under the documentation skill.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources snapshot is a signature only; the lifetime of what it touches belongs to the Go host.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms snapshot is a signature only; its algorithm and cost belong to the Go host.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work snapshot is a signature only; sharing of repeated work belongs to the Go host.
      */
     snapshot(opts: ITtscBuildOpts): Promise<ITtscResult>;
     /**
      * Drop a snapshot held by the wasm. Safe to call with an already-released
-     * handle — the response's `released` flag will be `false`.
+     * handle. The response's `released` flag will be `false`.
+     *
+     * @evidence contracts/common.md#principled-implementation Explicit release follows the registry's idempotent delete-and-close operation.
+     * @evidence contracts/common.md#clear-and-simple-design One handle-based release operation owns cleanup instead of coupling it to an unrelated query result.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The owning registry controls release rather than a guessed JavaScript GC event.
+     * @evidence contracts/common.md#meaningful-documentation JSDoc explains already-released behavior under the documentation skill's absence guidance.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources releaseSnapshot is a signature only; the lifetime of what it touches belongs to the Go host.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms releaseSnapshot is a signature only; its algorithm and cost belong to the Go host.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work releaseSnapshot is a signature only; sharing of repeated work belongs to the Go host.
      */
     releaseSnapshot(opts: ITtscSnapshotHandle): Promise<ITtscResult>;
-    /** List the currently retained snapshot handles. Debug aid. */
+    /**
+     * List currently retained snapshot handles in unspecified order.
+     *
+     * @evidence contracts/common.md#principled-implementation The Promise envelope projects the live native registry without exposing programs.
+     * @evidence contracts/common.md#clear-and-simple-design The listing exposes only current handles and uses the same async envelope as other registry operations.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Registry ownership supplies the list rather than a caller-side history.
+     * @evidence contracts/common.md#meaningful-documentation JSDoc states lifetime and order under the documentation skill's context rule.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources snapshots is a signature only; the lifetime of what it touches belongs to the Go host.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms snapshots is a signature only; its algorithm and cost belong to the Go host.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work snapshots is a signature only; sharing of repeated work belongs to the Go host.
+     */
     snapshots(): Promise<ITtscResult>;
-    /** List source file paths held by the snapshot's program. */
+    /**
+     * List non-declaration source paths held by the snapshot's program.
+     *
+     * @evidence contracts/common.md#principled-implementation A shared handle selects the retained program whose SourceFiles supplies the projection.
+     * @evidence contracts/common.md#clear-and-simple-design File identities are queried separately from their text and semantic details to keep this projection focused.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Compiler membership determines files rather than a filesystem glob approximation.
+     * @evidence contracts/common.md#meaningful-documentation JSDoc names snapshot provenance and declaration exclusion under the documentation skill's context rule.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources getSourceFiles is a signature only; the lifetime of what it touches belongs to the Go host.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms getSourceFiles is a signature only; its algorithm and cost belong to the Go host.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work getSourceFiles is a signature only; sharing of repeated work belongs to the Go host.
+     */
     getSourceFiles(opts: ITtscSnapshotHandle): Promise<ITtscResult>;
     /**
      * Read the current text the snapshot's program is holding for a file. After
      * transform-stage plugins ran inside this snapshot, the text reflects their
      * rewrites.
+     *
+     * @evidence contracts/common.md#principled-implementation A handle/file query reads the native program's current source text.
+     * @evidence contracts/common.md#clear-and-simple-design The shared file query selects one source; its text-only payload avoids duplicating snapshot or AST state.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Readback does not substitute an editor buffer that may differ from the retained program.
+     * @evidence contracts/common.md#meaningful-documentation JSDoc names retained and transformed text under the documentation skill's provenance guidance.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources getSourceFileText is a signature only; the lifetime of what it touches belongs to the Go host.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms getSourceFileText is a signature only; its algorithm and cost belong to the Go host.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work getSourceFileText is a signature only; sharing of repeated work belongs to the Go host.
      */
     getSourceFileText(opts: ITtscFileQuery): Promise<ITtscResult>;
     /**
      * Diagnostics from the snapshot's program. Pass `file` to filter to a single
-     * project-relative path.
+     * project-relative or absolute path.
+     *
+     * @evidence contracts/common.md#principled-implementation Program diagnostics supply the result, narrowed by an optional file selector.
+     * @evidence contracts/common.md#clear-and-simple-design One optional file filter refines the same diagnostic operation without another per-file endpoint.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Messages come from compiler diagnostics rather than a parallel source-pattern checker.
+     * @evidence contracts/common.md#meaningful-documentation JSDoc explains filter identity under the documentation skill's context rule.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources getDiagnostics is a signature only; the lifetime of what it touches belongs to the Go host.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms getDiagnostics is a signature only; its algorithm and cost belong to the Go host.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work getDiagnostics is a signature only; sharing of repeated work belongs to the Go host.
      */
     getDiagnostics(opts: ITtscSnapshotHandle & {
         file?: string;
@@ -73,17 +194,41 @@ export interface ITtscApi {
     /**
      * Return the syntax token touching `position` (byte offset), including
      * punctuation. Returns `{node: null}` for whitespace and comments.
+     *
+     * @evidence contracts/common.md#principled-implementation Native astnav owns token lookup in the retained program using byte coordinates.
+     * @evidence contracts/common.md#clear-and-simple-design The shared position request drives a syntax-only result, leaving checker-specific queries separate.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Compiler AST semantics replace guessed JavaScript lexical scans.
+     * @evidence contracts/common.md#meaningful-documentation JSDoc states units and null meaning under the documentation skill's coordinate/absence guidance.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources getNodeAtPosition is a signature only; the lifetime of what it touches belongs to the Go host.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms getNodeAtPosition is a signature only; its algorithm and cost belong to the Go host.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work getNodeAtPosition is a signature only; sharing of repeated work belongs to the Go host.
      */
     getNodeAtPosition(opts: ITtscPositionQuery): Promise<ITtscResult>;
     /**
      * Resolve the token at `position` and return the enclosing TypeScript-Go
      * semantic node's printed type string + flags. Returns `{type: null}` when
      * the position has no token or no type-bearing token.
+     *
+     * @evidence contracts/common.md#principled-implementation The retained checker owns semantic lookup and printing after token navigation.
+     * @evidence contracts/common.md#clear-and-simple-design Type presentation has its own nullable payload while using the same position selector as syntax and symbol queries.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Types come from compiler semantics rather than source spelling or a fabricated any result.
+     * @evidence contracts/common.md#meaningful-documentation JSDoc distinguishes token and semantic lookup under the documentation skill's context rule.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources getTypeAtPosition is a signature only; the lifetime of what it touches belongs to the Go host.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms getTypeAtPosition is a signature only; its algorithm and cost belong to the Go host.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work getTypeAtPosition is a signature only; sharing of repeated work belongs to the Go host.
      */
     getTypeAtPosition(opts: ITtscPositionQuery): Promise<ITtscResult>;
     /**
      * Resolve the symbol the token at `position` refers to, including up to 16
      * declaration sites. Returns `{symbol: null}` when no symbol is bound.
+     *
+     * @evidence contracts/common.md#principled-implementation The retained checker resolves symbols and projects bounded declaration metadata.
+     * @evidence contracts/common.md#clear-and-simple-design One symbol payload combines identity with a small declaration projection without adding follow-up declaration handles.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Declaration sites come from the symbol rather than searching text for equal names.
+     * @evidence contracts/common.md#meaningful-documentation JSDoc explains the cap and null result under the documentation skill's context rule.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources getSymbolAtPosition is a signature only; the lifetime of what it touches belongs to the Go host.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms getSymbolAtPosition is a signature only; its algorithm and cost belong to the Go host.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work getSymbolAtPosition is a signature only; sharing of repeated work belongs to the Go host.
      */
     getSymbolAtPosition(opts: ITtscPositionQuery): Promise<ITtscResult>;
 }

package/lib/src/structures/ITtscBuildOpts.d.ts

@@ -1,4 +1,21 @@
-/** Options shared by `build`, `check`, and `transform`. */
+/**
+ * Options shared by `build`, `check`, and `transform`.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   Required cwd and optional tsconfig mirror the native project endpoints;
+ *   omission delegates the default to the host that loads the project.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   The shared request contains project root and config selection only; the
+ *   chosen API verb owns whether that project is emitted, checked or projected.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   Project identity comes from the caller, rather than a consumer-specific root.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Member JSDoc distinguishes virtual absolute cwd from relative config paths
+ *   and names the default, following the documentation skill's clear prose.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources ITtscBuildOpts is a data interface and acquires no handle, task or retained state.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms ITtscBuildOpts is a data interface and chooses no algorithm or processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work ITtscBuildOpts is a data interface and coordinates no shared or repeated computation.
+ */
 export interface ITtscBuildOpts {
     /** Absolute virtual path the project lives at inside the MemFS. */
     cwd: string;

package/lib/src/structures/ITtscCompileResult.d.ts

@@ -2,10 +2,28 @@ import type { ITtscDiagnostic } from "./ITtscDiagnostic";
 /**
  * Structured payload inside `ITtscResult.result` for `build` and `check`.
  *
- * `output` maps emit-destination paths (relative to `cwd`) to file contents. It
- * is empty when `check` is called without emit.
+ * `output` maps emit-destination paths to file contents. Paths inside `cwd` are
+ * relative; outside destinations remain absolute. `check` returns an empty
+ * map.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   A path-keyed string record matches the native JSON output map; optional
+ *   diagnostics reflect its omitempty encoding rather than requiring a sentinel.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   Diagnostics and emitted files have separate fields, reusing one diagnostic
+ *   type while keeping the transport envelope outside this compile payload.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   Compiler-produced paths and contents remain data, without fixture-shaped keys.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   JSDoc identifies the enclosing envelope, path base and no-emit meaning;
+ *   separate paragraphs follow the documentation skill's purpose and context rule.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources ITtscCompileResult is a data interface and acquires no handle, task or retained state.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms ITtscCompileResult is a data interface and chooses no algorithm or processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work ITtscCompileResult is a data interface and coordinates no shared or repeated computation.
  */
 export interface ITtscCompileResult {
+    /** Present when the native result includes diagnostic messages. */
     diagnostics?: ITtscDiagnostic[];
+    /** Emitted file contents keyed by their destination paths. */
     output: Record<string, string>;
 }

package/lib/src/structures/ITtscDiagnostic.d.ts

@@ -1,14 +1,38 @@
 /**
  * A single TypeScript compiler diagnostic emitted during `build`, `check`, or
- * `transform`. `line` and `character` are 0-based.
+ * `transform`. `line` and `character` are 1-based, matching the native driver.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   Nullable file identity and optional locations mirror CompileDiagnostic's
+ *   native JSON projection; the severity union matches its two public categories.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   Identity, byte span, display location and message remain distinct fields;
+ *   optional coordinates express absent context without an extra location model.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   Diagnostic codes and locations come from the compiler rather than a guessed
+ *   editor coordinate or a fixture-specific message classification.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Native JSDoc explains byte ranges, 1-based display locations and missing
+ *   source context, following the documentation skill's units and absence rules.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources ITtscDiagnostic is a data interface and acquires no handle, task or retained state.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms ITtscDiagnostic is a data interface and chooses no algorithm or processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work ITtscDiagnostic is a data interface and coordinates no shared or repeated computation.
  */
 export interface ITtscDiagnostic {
+    /** Absolute slash-separated source path; null for project-wide diagnostics. */
     file: string | null;
+    /** Error affects the exit code; warning does not. */
     category: "error" | "warning";
+    /** Native compiler or plugin diagnostic identifier. */
     code: number;
+    /** Inclusive UTF-8 byte offset when source location is available. */
     start?: number;
+    /** Span length in UTF-8 bytes when source location is available. */
     length?: number;
+    /** 1-based source line; omitted when no display location is available. */
     line?: number;
+    /** 1-based UTF-8 byte column; omitted when no display location is available. */
     character?: number;
+    /** Complete diagnostic message for presentation to the caller. */
     messageText: string;
 }

package/lib/src/structures/ITtscFileQuery.d.ts

@@ -1,5 +1,23 @@
 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/lib/src/structures/ITtscFountainDiagnosticsResult.d.ts

@@ -1,5 +1,24 @@
 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/lib/src/structures/ITtscNodeAtPositionResult.d.ts

@@ -1,5 +1,22 @@
 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/lib/src/structures/ITtscNodeInfo.d.ts

@@ -1,10 +1,31 @@
-/** 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;

package/lib/src/structures/ITtscPluginOpts.d.ts

@@ -1,4 +1,22 @@
-/** 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;
@@ -6,8 +24,11 @@ export interface ITtscPluginOpts {
     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/lib/src/structures/ITtscPositionQuery.d.ts

@@ -2,13 +2,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/lib/src/structures/ITtscReleaseSnapshotResult.d.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/lib/src/structures/ITtscResult.d.ts

@@ -1,14 +1,40 @@
-/** 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/lib/src/structures/ITtscSnapshotHandle.d.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;