@ttsc/wasm 0.30.3 → 0.31.0

package/src/structures/IBootTtscOptions.ts

@@ -1,23 +1,49 @@
 import type { IMemFSHost } from "./IMemFSHost";
 
-/** Options for `bootTtsc`. All fields except `wasmUrl` have sensible defaults. */
+/**
+ * Options for `bootTtsc`. All fields except `wasmUrl` have defaults.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   URLs, AbortSignal and an injectable MemFS use browser integration primitives;
+ *   the explicit API name mirrors the Go host's global bridge identity.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   Binary and bridge identity are explicit, while optional cancellation and
+ *   host injection cover actual boot ownership without a generic loader layer.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   Runtime identity and host come from the caller or documented protocol defaults,
+ *   without selecting a different boot path for a named consumer.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Native JSDoc explains defaults, cancellation sharing and host identity. Separate
+ *   ownership paragraphs follow the documentation skill's context guidance.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources IBootTtscOptions is a data interface and acquires no handle, task or retained state.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms IBootTtscOptions is a data interface and chooses no algorithm or processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work IBootTtscOptions is a data interface and coordinates no shared or repeated computation.
+ */
 export interface IBootTtscOptions {
   /** URL of the .wasm to fetch. */
   wasmUrl: string;
+
   /** Cancel this boot attempt, including a shared in-flight attempt. */
   signal?: AbortSignal;
-  /** URL of wasm_exec.js. Defaults to the same directory as wasmUrl. */
+
+  /**
+   * URL of wasm_exec.js; defaults to a sibling URL without the binary's
+   * query/fragment.
+   */
   wasmExecUrl?: string;
+
   /**
    * GlobalThis property name the wasm binds. Must match the value the wasm was
    * built with (the `apiName` passed to `host.Expose`). Defaults to `"ttsc"`.
    */
   apiName?: string;
+
   /**
-   * Optional pre-existing MemFS host. When omitted, a fresh one is created and
-   * stored on the returned BootResult. Pass an existing host when you want to
-   * boot multiple wasms over the same filesystem (e.g. base ttsc + a typia
-   * wasm) so they share project sources.
+   * Optional pre-existing MemFS host. A new boot creates one when omitted;
+   * joining an existing boot reuses its host. A different explicit host or
+   * runtime-script URL is rejected. Pass an existing host when you want to
+   * retry before a runtime starts or reuse an existing boot's filesystem. This
+   * does not make one Worker safe to host multiple Go runtimes simultaneously.
    */
   host?: IMemFSHost;
 }

package/src/structures/IFileStats.ts

@@ -3,21 +3,86 @@
  *
  * Mirrors the subset of `fs.Stats` that `wasm_exec.js` reads. Fields not
  * relevant to Go's `os.FileInfo` (e.g. ownership) are zeroed.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   Node-shaped fields and kind predicates match the Go js/wasm bridge's stats
+ *   consumer; this is a virtual projection rather than a native inode model.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   One stats snapshot groups sampled kind, byte size and projected metadata;
+ *   predicates expose the two supported kinds without another node hierarchy.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   Synthetic device/ownership values express MemFS capabilities, without
+ *   presenting browser-host metadata as actual operating-system file identity.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Native JSDoc explains bridge scope, time and size units and synthetic fields,
+ *   following the documentation skill's concrete context guidance.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources IFileStats only groups the virtual-filesystem members and acquires no handle, task or retained state.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms IFileStats only groups the virtual-filesystem members and chooses no algorithm.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work IFileStats only groups the virtual-filesystem members and coordinates no computation.
  */
 export interface IFileStats {
+  /**
+   * Whether the sampled node is a virtual directory.
+   *
+   * @evidence contracts/common.md#principled-implementation makeStats captures node.kind once, so the predicate reports that sampled directory classification.
+   * @evidence contracts/common.md#clear-and-simple-design The kind query is separate from metadata fields and shares the captured classification with isFile.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It reports the sampled node kind, not a filename heuristic.
+   * @evidence contracts/common.md#meaningful-documentation JSDoc names snapshot provenance under the documentation skill's context rule.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources isDirectory is a signature only; the lifetime of what it touches belongs to createMemFS.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms isDirectory is a signature only; its algorithm and cost belong to createMemFS.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work isDirectory is a signature only; sharing of repeated work belongs to createMemFS.
+   */
   isDirectory(): boolean;
+
+  /**
+   * Whether the sampled node is a virtual regular file.
+   *
+   * @evidence contracts/common.md#principled-implementation MemFS has only file and directory nodes, making the inverse sampled-directory flag its regular-file classification.
+   * @evidence contracts/common.md#clear-and-simple-design The predicate exposes the other supported node kind through the same snapshot rather than recalculating a path.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The virtual node kind determines the result, without extension special cases.
+   * @evidence contracts/common.md#meaningful-documentation JSDoc distinguishes regular-file classification under the documentation skill's clarity rule.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources isFile is a signature only; the lifetime of what it touches belongs to createMemFS.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms isFile is a signature only; its algorithm and cost belong to createMemFS.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work isFile is a signature only; sharing of repeated work belongs to createMemFS.
+   */
   isFile(): boolean;
+
+  /** File byte length; zero for a directory. */
   size: number;
+
+  /** Virtual file-kind and permission bits, in Node stat format. */
   mode: number;
+
+  /** Modification time in milliseconds since the Unix epoch. */
   mtimeMs: number;
+
+  /** Access-time projection; MemFS uses its modification timestamp. */
   atimeMs: number;
+
+  /** Change-time projection; MemFS uses its modification timestamp. */
   ctimeMs: number;
+
+  /** Synthetic device identity; MemFS uses zero. */
   dev: number;
+
+  /** Synthetic inode identity; MemFS uses zero. */
   ino: number;
+
+  /** Synthetic link count; MemFS uses one. */
   nlink: number;
+
+  /** Synthetic owner id; MemFS uses zero. */
   uid: number;
+
+  /** Synthetic group id; MemFS uses zero. */
   gid: number;
+
+  /** Synthetic special-device identity; MemFS uses zero. */
   rdev: number;
+
+  /** Virtual preferred I/O block size in bytes. */
   blksize: number;
+
+  /** Allocated-size projection measured in 512-byte blocks. */
   blocks: number;
 }

package/src/structures/IMemFSHost.ts

@@ -4,15 +4,112 @@ import type { IWasmExecFS } from "./IWasmExecFS";
  * Handle returned by `createMemFS`. Provides the `fs` shim to install on
  * `globalThis` plus convenience methods for seeding the virtual filesystem
  * before booting the wasm.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   A bridge plus seeding/readback methods keeps virtual filesystem ownership
+ *   explicit, with byte and text access separate and missing reads nullable.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   Low-level bridge access, convenience seeding/readback and output captures
+ *   have distinct members, all sharing one host instead of separate stores.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   The same owned filesystem serves compiler input and caller readback;
+ *   output captures are distinct from ordinary files and from native host I/O.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Native JSDoc explains copying, directory creation, missing reads and stream
+ *   reset scope, following the documentation skill's ownership/context guidance.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources IMemFSHost only groups the virtual-filesystem members and acquires no handle, task or retained state.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms IMemFSHost only groups the virtual-filesystem members and chooses no algorithm.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work IMemFSHost only groups the virtual-filesystem members and coordinates no computation.
  */
 export interface IMemFSHost {
+  /** Bridge installed before evaluating wasm_exec.js. */
   fs: IWasmExecFS;
+
+  /**
+   * Store copied bytes or UTF-8 text, creating missing parent directories.
+   *
+   * @evidence contracts/common.md#principled-implementation A dedicated seeding API owns recursive directory creation rather than changing low-level open.
+   * @evidence contracts/common.md#clear-and-simple-design One convenience operation owns caller-data copying and parent creation; low-level open keeps its separate contract.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Caller data is copied into the real backing tree, not an alternate fixture store.
+   * @evidence contracts/common.md#meaningful-documentation JSDoc states encoding, copying and parent creation under the documentation skill's context guidance.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources writeFile is a signature only; the lifetime of what it touches belongs to createMemFS.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms writeFile is a signature only; its algorithm and cost belong to createMemFS.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work writeFile is a signature only; sharing of repeated work belongs to createMemFS.
+   */
   writeFile(path: string, data: string | Uint8Array): void;
+
+  /**
+   * Read an owned copy of file bytes; return null for an absent path or
+   * directory.
+   *
+   * @evidence contracts/common.md#principled-implementation Nullable copied bytes distinguish an absent file from an empty file.
+   * @evidence contracts/common.md#clear-and-simple-design Byte readback has one nullable result and leaves text conversion to the separate text operation.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Readback uses the compiler's backing tree rather than reconstructing expected output.
+   * @evidence contracts/common.md#meaningful-documentation JSDoc explains ownership and null meaning under the documentation skill's absence guidance.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources readFile is a signature only; the lifetime of what it touches belongs to createMemFS.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms readFile is a signature only; its algorithm and cost belong to createMemFS.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work readFile is a signature only; sharing of repeated work belongs to createMemFS.
+   */
   readFile(path: string): Uint8Array | null;
+
+  /**
+   * Decode file bytes as UTF-8; return null for an absent path or directory.
+   *
+   * Decoding follows `TextDecoder`: a leading byte-order mark is dropped and a
+   * malformed sequence becomes U+FFFD. `readFile` returns the exact bytes.
+   *
+   * @evidence contracts/common.md#principled-implementation Text decoding adapts the same byte store using TextDecoder's UTF-8 behavior.
+   * @evidence contracts/common.md#clear-and-simple-design A text view shares the stored file identity and hides decoding/cache details from callers.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The text view does not introduce a separately mutable source cache.
+   * @evidence contracts/common.md#meaningful-documentation JSDoc names encoding and null meaning under the documentation skill's units/context guidance.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources readFileText is a signature only; the lifetime of what it touches belongs to createMemFS.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms readFileText is a signature only; its algorithm and cost belong to createMemFS.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work readFileText is a signature only; sharing of repeated work belongs to createMemFS.
+   */
   readFileText(path: string): string | null;
+
+  /**
+   * Whether a normalized path names a stored file or directory.
+   *
+   * @evidence contracts/common.md#principled-implementation A presence query delegates to the same virtual path identity as read and write.
+   * @evidence contracts/common.md#clear-and-simple-design A separate presence predicate includes directories without expanding the file-read result shape.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Actual tree membership determines presence, without an extension-based guess.
+   * @evidence contracts/common.md#meaningful-documentation JSDoc distinguishes presence from file readability under the documentation skill's clarity guidance.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources exists is a signature only; the lifetime of what it touches belongs to createMemFS.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms exists is a signature only; its algorithm and cost belong to createMemFS.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work exists is a signature only; sharing of repeated work belongs to createMemFS.
+   */
   exists(path: string): boolean;
+
+  /**
+   * Create a directory chain; reject file ancestors before creating any prefix.
+   *
+   * @evidence contracts/common.md#principled-implementation Recursive seeding is explicit and validates the whole chain before mutation.
+   * @evidence contracts/common.md#clear-and-simple-design Parent creation is one named convenience operation instead of being hidden in every bridge path.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts A file is not reclassified as a directory to force a requested path to exist.
+   * @evidence contracts/common.md#meaningful-documentation JSDoc explains rejection effects under the documentation skill's failure guidance.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources mkdirp is a signature only; the lifetime of what it touches belongs to createMemFS.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms mkdirp is a signature only; its algorithm and cost belong to createMemFS.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work mkdirp is a signature only; sharing of repeated work belongs to createMemFS.
+   */
   mkdirp(path: string): void;
+
+  /** Captured UTF-8 output written to the reserved stdout descriptor. */
   stdout: { buffer: string };
+
+  /** Captured UTF-8 output written to the reserved stderr descriptor. */
   stderr: { buffer: string };
+
+  /**
+   * Clear stdout/stderr captures without changing files or open descriptors.
+   *
+   * @evidence contracts/common.md#principled-implementation Resetting only owned stream buffers makes capture lifetime explicit.
+   * @evidence contracts/common.md#clear-and-simple-design Stream reset has one explicit boundary and does not combine filesystem cleanup with capture management.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Reset does not erase compiler input or hide failed operations as a filesystem reset.
+   * @evidence contracts/common.md#meaningful-documentation JSDoc states the reset boundary under the documentation skill's ownership guidance.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources resetStdio is a signature only; the lifetime of what it touches belongs to createMemFS.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms resetStdio is a signature only; its algorithm and cost belong to createMemFS.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work resetStdio is a signature only; sharing of repeated work belongs to createMemFS.
+   */
   resetStdio(): void;
 }

package/src/structures/ITtscApi.ts

@@ -11,28 +11,79 @@ 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>;
 
@@ -40,10 +91,28 @@ export interface ITtscApi {
    * 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[];
 
   /**
@@ -53,31 +122,83 @@ 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 },
@@ -86,6 +207,14 @@ 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>;
 
@@ -93,12 +222,28 @@ export interface ITtscApi {
    * 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/src/structures/ITtscBuildOpts.ts

@@ -1,7 +1,25 @@
-/** 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;
+
   /** Tsconfig path, relative to `cwd`. Defaults to `tsconfig.json`. */
   tsconfig?: string;
 }

package/src/structures/ITtscCompileResult.ts

@@ -3,10 +3,29 @@ 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/src/structures/ITtscDiagnostic.ts

@@ -1,14 +1,45 @@
 /**
  * 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;
 }