@ttsc/wasm 0.30.3 → 0.31.0

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

@@ -7,33 +7,335 @@ import type { IFileStats } from "./IFileStats";
  * implementation fulfils this interface. Only the operations that
  * typescript-go's compiler exercises are required; the rest are no-ops or
  * return `EPERM`/`EINVAL`.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   Node-style callback signatures and open flags adapt Go's js/wasm filesystem
+ *   bridge. The declared capability is virtual files/directories, not full POSIX.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   Node-shaped verbs are the Go runtime's existing extension boundary. The
+ *   interface separates seekable files, captured streams and unsupported links
+ *   without introducing another protocol between the runtime and its host.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   Unsupported links remain explicit errors; permission/ownership/time setters
+ *   are documented no-ops rather than hidden claims of native filesystem support.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Native JSDoc names bridge scope, callback conventions and capability limits,
+ *   following the documentation skill's context and failure guidance.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources IWasmExecFS only groups the virtual-filesystem members and acquires no handle, task or retained state.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms IWasmExecFS only groups the virtual-filesystem members and chooses no algorithm.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work IWasmExecFS only groups the virtual-filesystem members and coordinates no computation.
  */
 export interface IWasmExecFS {
+    /** Virtual open-flag values consumed by the Go bridge. */
     constants: Record<string, number>;
+    /**
+     * Write all supplied bytes at a file cursor or to captured fd 1/2.
+     *
+     * @evidence contracts/common.md#principled-implementation Synchronous writes mirror the bridge's byte-buffer operation.
+     * @evidence contracts/common.md#clear-and-simple-design The synchronous whole-buffer write is distinct from callback byte-slice writes because wasm_exec uses both call shapes.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Unknown descriptors throw rather than diverting writes to a diagnostic stream.
+     * @evidence contracts/common.md#meaningful-documentation JSDoc states descriptor and stream roles under the documentation skill's context guidance.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources writeSync is a signature only; the lifetime of what it touches belongs to createMemFS.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms writeSync is a signature only; its algorithm and cost belong to createMemFS.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work writeSync is a signature only; sharing of repeated work belongs to createMemFS.
+     */
     writeSync(fd: number, buf: Uint8Array): number;
+    /**
+     * Write a byte slice; null position uses the cursor, while append uses EOF.
+     *
+     * @evidence contracts/common.md#principled-implementation The Node callback operation separates buffer offsets from seek position.
+     * @evidence contracts/common.md#clear-and-simple-design Byte slice, descriptor position and completion stay explicit instead of overloading one offset parameter.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Access mode and stream identity own dispatch, without guessing a destination from payload bytes.
+     * @evidence contracts/common.md#meaningful-documentation JSDoc states position and append meaning under the documentation skill's units guidance.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources write is a signature only; the lifetime of what it touches belongs to createMemFS.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms write is a signature only; its algorithm and cost belong to createMemFS.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work write is a signature only; sharing of repeated work belongs to createMemFS.
+     */
     write(fd: number, buf: Uint8Array, offset: number, length: number, position: number | null, callback: (err: NodeJS.ErrnoException | null, n: number) => void): void;
+    /**
+     * Open a virtual path with bridge flags; low-level creation requires its
+     * parent.
+     *
+     * @evidence contracts/common.md#principled-implementation Node-shaped flags select file access and the returned descriptor owns its cursor.
+     * @evidence contracts/common.md#clear-and-simple-design One open boundary captures access flags and descriptor identity; recursive seeding remains outside this low-level operation.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Parent creation stays in writeFile/mkdirp instead of silently changing low-level open semantics.
+     * @evidence contracts/common.md#meaningful-documentation JSDoc explains parent and descriptor ownership under the documentation skill's context guidance.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources open is a signature only; the lifetime of what it touches belongs to createMemFS.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms open is a signature only; its algorithm and cost belong to createMemFS.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work open is a signature only; sharing of repeated work belongs to createMemFS.
+     */
     open(path: string, flags: number, mode: number, callback: (err: NodeJS.ErrnoException | null, fd: number) => void): void;
+    /**
+     * Release an open descriptor; closing a pipe write end signals EOF to
+     * readers.
+     *
+     * @evidence contracts/common.md#principled-implementation Explicit close follows descriptor ownership and the virtual pipe's endpoint lifecycle.
+     * @evidence contracts/common.md#clear-and-simple-design Descriptor release is one operation; file nodes and the two pipe endpoint roles keep their separate lifetimes.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Unknown descriptors remain errors rather than guessed already-closed successes.
+     * @evidence contracts/common.md#meaningful-documentation JSDoc explains release and EOF effects under the documentation skill's ownership guidance.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources close is a signature only; the lifetime of what it touches belongs to createMemFS.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms close is a signature only; its algorithm and cost belong to createMemFS.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work close is a signature only; sharing of repeated work belongs to createMemFS.
+     */
     close(fd: number, callback: (err: NodeJS.ErrnoException | null) => void): void;
+    /**
+     * Read a byte slice; null position advances the file cursor by bytes read.
+     *
+     * @evidence contracts/common.md#principled-implementation Node callback arguments distinguish destination-buffer offsets from file position.
+     * @evidence contracts/common.md#clear-and-simple-design Explicit slice and seek parameters preserve the bridge contract without exposing internal cursor or queue objects.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Descriptor access mode owns reads; EOF does not rewind a cursor past the current file length.
+     * @evidence contracts/common.md#meaningful-documentation JSDoc states byte units and cursor movement under the documentation skill's units guidance.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources read is a signature only; the lifetime of what it touches belongs to createMemFS.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms read is a signature only; its algorithm and cost belong to createMemFS.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work read is a signature only; sharing of repeated work belongs to createMemFS.
+     */
     read(fd: number, buffer: Uint8Array, offset: number, length: number, position: number | null, callback: (err: NodeJS.ErrnoException | null, n: number) => void): void;
+    /**
+     * Return sorted immediate child names of a virtual directory.
+     *
+     * @evidence contracts/common.md#principled-implementation A Node-style names array exposes directory membership independently from stat data.
+     * @evidence contracts/common.md#clear-and-simple-design Listing returns immediate names only, leaving metadata and recursion to their existing separate operations.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Entries come from the owned tree rather than expected source-file names.
+     * @evidence contracts/common.md#meaningful-documentation JSDoc states depth and order under the documentation skill's context guidance.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources readdir is a signature only; the lifetime of what it touches belongs to createMemFS.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms readdir is a signature only; its algorithm and cost belong to createMemFS.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work readdir is a signature only; sharing of repeated work belongs to createMemFS.
+     */
     readdir(path: string, callback: (err: NodeJS.ErrnoException | null, entries: string[]) => void): void;
+    /**
+     * Create one directory with an existing parent; virtual permissions are
+     * fixed.
+     *
+     * @evidence contracts/common.md#principled-implementation Single-directory creation remains distinct from the host's recursive seeding API.
+     * @evidence contracts/common.md#clear-and-simple-design One-directory creation keeps bridge semantics visible rather than silently creating missing ancestor chains.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Existing nodes and missing parents remain errors instead of being rewritten to fit a requested path.
+     * @evidence contracts/common.md#meaningful-documentation JSDoc explains creation depth and permission capability under the documentation skill's context guidance.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources mkdir is a signature only; the lifetime of what it touches belongs to createMemFS.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms mkdir is a signature only; its algorithm and cost belong to createMemFS.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work mkdir is a signature only; sharing of repeated work belongs to createMemFS.
+     */
     mkdir(path: string, perm: number, callback: (err: NodeJS.ErrnoException | null) => void): void;
+    /**
+     * Sample virtual file/directory metadata. Inspect err first; stats is absent
+     * on error and valid only after a successful callback.
+     *
+     * @evidence contracts/common.md#principled-implementation Node-shaped metadata adapts the Go bridge's stat consumer.
+     * @evidence contracts/common.md#clear-and-simple-design Path lookup projects one stats snapshot through the bridge's err-first callback, without another metadata cache contract.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Missing paths produce errors rather than synthetic existing-file metadata.
+     * @evidence contracts/common.md#meaningful-documentation JSDoc states virtual provenance and error absence under the documentation skill's context guidance.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources stat is a signature only; the lifetime of what it touches belongs to createMemFS.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms stat is a signature only; its algorithm and cost belong to createMemFS.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work stat is a signature only; sharing of repeated work belongs to createMemFS.
+     */
     stat(path: string, callback: (err: NodeJS.ErrnoException | null, stats: IFileStats) => void): void;
+    /**
+     * Sample path metadata; equivalent to stat because MemFS has no symlinks.
+     *
+     * @evidence contracts/common.md#principled-implementation Delegating to stat reuses the same metadata projection within the declared virtual capability.
+     * @evidence contracts/common.md#clear-and-simple-design The required bridge alias delegates to stat because no supported node can be a symlink.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The no-symlink capability is explicit rather than pretending to resolve arbitrary link targets.
+     * @evidence contracts/common.md#meaningful-documentation JSDoc explains equivalence and its reason under the documentation skill's rationale guidance.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources lstat is a signature only; the lifetime of what it touches belongs to createMemFS.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms lstat is a signature only; its algorithm and cost belong to createMemFS.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work lstat is a signature only; sharing of repeated work belongs to createMemFS.
+     */
     lstat(path: string, callback: (err: NodeJS.ErrnoException | null, stats: IFileStats) => void): void;
+    /**
+     * Sample the inode retained by a descriptor, or synthetic pipe-end metadata.
+     * Inspect err before using stats, which is absent on error.
+     *
+     * @evidence contracts/common.md#principled-implementation Open-node identity supplies stats even after the path is removed or replaced.
+     * @evidence contracts/common.md#clear-and-simple-design Descriptor stats resolve retained identity directly rather than adding a path-to-descriptor translation layer.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Descriptor metadata does not silently re-resolve a path to a different inode.
+     * @evidence contracts/common.md#meaningful-documentation JSDoc states retained-node and pipe roles under the documentation skill's ownership guidance.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources fstat is a signature only; the lifetime of what it touches belongs to createMemFS.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms fstat is a signature only; its algorithm and cost belong to createMemFS.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work fstat is a signature only; sharing of repeated work belongs to createMemFS.
+     */
     fstat(fd: number, callback: (err: NodeJS.ErrnoException | null, stats: IFileStats) => void): void;
+    /**
+     * Acknowledge an in-memory flush; MemFS provides no durable backing store.
+     *
+     * @evidence contracts/common.md#principled-implementation The callback-shaped operation adapts the bridge to an entirely memory-backed store.
+     * @evidence contracts/common.md#clear-and-simple-design The required flush callback is explicit while persistence remains outside this memory-only filesystem's capabilities.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Success does not claim disk durability or mutate foreign storage APIs.
+     * @evidence contracts/common.md#meaningful-documentation JSDoc states the durability limit under the documentation skill's capability guidance.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources fsync is a signature only; the lifetime of what it touches belongs to createMemFS.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms fsync is a signature only; its algorithm and cost belong to createMemFS.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work fsync is a signature only; sharing of repeated work belongs to createMemFS.
+     */
     fsync(fd: number, callback: (err: NodeJS.ErrnoException | null) => void): void;
+    /**
+     * Remove a file path; open descriptors retain its node until closed.
+     *
+     * @evidence contracts/common.md#principled-implementation Path removal and open-node lifetime follow separate ownership identities.
+     * @evidence contracts/common.md#clear-and-simple-design File unlink owns path removal; directory removal and descriptor close retain their separate named responsibilities.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Directories are rejected rather than orphaning descendants through file removal.
+     * @evidence contracts/common.md#meaningful-documentation JSDoc explains path versus descriptor lifetime under the documentation skill's ownership guidance.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources unlink is a signature only; the lifetime of what it touches belongs to createMemFS.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms unlink is a signature only; its algorithm and cost belong to createMemFS.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work unlink is a signature only; sharing of repeated work belongs to createMemFS.
+     */
     unlink(path: string, callback: (err: NodeJS.ErrnoException | null) => void): void;
+    /**
+     * Move a file or directory subtree after validating destination
+     * compatibility.
+     *
+     * @evidence contracts/common.md#principled-implementation Tree mutation preserves node identity and moves descendant paths as one operation.
+     * @evidence contracts/common.md#clear-and-simple-design A single subtree move owns validation and rebasing instead of composing public delete and recreate operations.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts A rejected destination does not trigger partial moves or type coercion to force success.
+     * @evidence contracts/common.md#meaningful-documentation JSDoc states subtree scope and validation ownership under the documentation skill's failure guidance.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources rename is a signature only; the lifetime of what it touches belongs to createMemFS.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms rename is a signature only; its algorithm and cost belong to createMemFS.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work rename is a signature only; sharing of repeated work belongs to createMemFS.
+     */
     rename(from: string, to: string, callback: (err: NodeJS.ErrnoException | null) => void): void;
+    /**
+     * Remove an empty virtual directory; root remains owned by the host.
+     *
+     * @evidence contracts/common.md#principled-implementation Directory removal validates kind and emptiness separately from file unlink.
+     * @evidence contracts/common.md#clear-and-simple-design Empty-directory removal has a focused boundary and leaves recursive deletion outside the bridge contract.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Nonempty directories are not recursively erased to satisfy a single rmdir request.
+     * @evidence contracts/common.md#meaningful-documentation JSDoc explains empty-only and root boundaries under the documentation skill's context guidance.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources rmdir is a signature only; the lifetime of what it touches belongs to createMemFS.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms rmdir is a signature only; its algorithm and cost belong to createMemFS.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work rmdir is a signature only; sharing of repeated work belongs to createMemFS.
+     */
     rmdir(path: string, callback: (err: NodeJS.ErrnoException | null) => void): void;
+    /**
+     * Compatibility no-op: virtual file permissions cannot be changed.
+     *
+     * @evidence contracts/common.md#principled-implementation The bridge signature is retained within the documented fixed-permission capability.
+     * @evidence contracts/common.md#clear-and-simple-design The required path-permission verb documents its no-op capability without creating unused permission state.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The no-op is explicit rather than claimed as native permission enforcement.
+     * @evidence contracts/common.md#meaningful-documentation JSDoc identifies the absent capability under the documentation skill's context guidance.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources chmod is a signature only; the lifetime of what it touches belongs to createMemFS.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms chmod is a signature only; its algorithm and cost belong to createMemFS.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work chmod is a signature only; sharing of repeated work belongs to createMemFS.
+     */
     chmod(path: string, mode: number, callback: (err: NodeJS.ErrnoException | null) => void): void;
+    /**
+     * Descriptor form of the fixed-permission compatibility no-op.
+     *
+     * @evidence contracts/common.md#principled-implementation The descriptor signature preserves the Go bridge's permission API shape.
+     * @evidence contracts/common.md#clear-and-simple-design The required descriptor variant preserves bridge call shape without a separate mutable permission model.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Descriptor acceptance does not claim an actual permission change.
+     * @evidence contracts/common.md#meaningful-documentation JSDoc states the same capability limit under the documentation skill's clarity guidance.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources fchmod is a signature only; the lifetime of what it touches belongs to createMemFS.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms fchmod is a signature only; its algorithm and cost belong to createMemFS.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work fchmod is a signature only; sharing of repeated work belongs to createMemFS.
+     */
     fchmod(fd: number, mode: number, callback: (err: NodeJS.ErrnoException | null) => void): void;
+    /**
+     * Compatibility no-op: MemFS ownership metadata is synthetic.
+     *
+     * @evidence contracts/common.md#principled-implementation The Node signature adapts a store without native users or groups.
+     * @evidence contracts/common.md#clear-and-simple-design The required path-ownership verb is explicit, with no user/group database this virtual store does not support.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Synthetic ownership is documented rather than inferred from the browser host.
+     * @evidence contracts/common.md#meaningful-documentation JSDoc explains ownership capability under the documentation skill's context guidance.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources chown is a signature only; the lifetime of what it touches belongs to createMemFS.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms chown is a signature only; its algorithm and cost belong to createMemFS.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work chown is a signature only; sharing of repeated work belongs to createMemFS.
+     */
     chown(path: string, uid: number, gid: number, callback: (err: NodeJS.ErrnoException | null) => void): void;
+    /**
+     * Descriptor form of the synthetic-ownership compatibility no-op.
+     *
+     * @evidence contracts/common.md#principled-implementation The descriptor API preserves the Go bridge's ownership operation shape.
+     * @evidence contracts/common.md#clear-and-simple-design The descriptor ownership variant shares the same absent capability instead of introducing descriptor-specific ownership state.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Success does not claim user/group mutation on an open virtual file.
+     * @evidence contracts/common.md#meaningful-documentation JSDoc names the descriptor scope and limit under the documentation skill's clarity guidance.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources fchown is a signature only; the lifetime of what it touches belongs to createMemFS.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms fchown is a signature only; its algorithm and cost belong to createMemFS.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work fchown is a signature only; sharing of repeated work belongs to createMemFS.
+     */
     fchown(fd: number, uid: number, gid: number, callback: (err: NodeJS.ErrnoException | null) => void): void;
+    /**
+     * Path ownership compatibility no-op; MemFS has no symbolic links.
+     *
+     * @evidence contracts/common.md#principled-implementation The bridge shape exists despite the store's fixed ownership and absent link capability.
+     * @evidence contracts/common.md#clear-and-simple-design The required link-ownership alias makes its limits explicit without adding unsupported symlink machinery.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The no-link limit is explicit rather than simulating a link-specific ownership model.
+     * @evidence contracts/common.md#meaningful-documentation JSDoc states both capability boundaries under the documentation skill's context guidance.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources lchown is a signature only; the lifetime of what it touches belongs to createMemFS.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms lchown is a signature only; its algorithm and cost belong to createMemFS.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work lchown is a signature only; sharing of repeated work belongs to createMemFS.
+     */
     lchown(path: string, uid: number, gid: number, callback: (err: NodeJS.ErrnoException | null) => void): void;
+    /**
+     * Compatibility no-op: timestamps change with mutations, not caller setters.
+     *
+     * @evidence contracts/common.md#principled-implementation The bridge signature adapts MemFS's mutation-owned timestamp projection.
+     * @evidence contracts/common.md#clear-and-simple-design Caller timestamp setting remains an explicit no-op; byte/tree mutations retain ownership of projected timestamps.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Caller timestamps are not falsely reported as installed metadata.
+     * @evidence contracts/common.md#meaningful-documentation JSDoc explains the timestamp owner under the documentation skill's rationale guidance.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources utimes is a signature only; the lifetime of what it touches belongs to createMemFS.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms utimes is a signature only; its algorithm and cost belong to createMemFS.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work utimes is a signature only; sharing of repeated work belongs to createMemFS.
+     */
     utimes(path: string, atime: number, mtime: number, callback: (err: NodeJS.ErrnoException | null) => void): void;
+    /**
+     * Reject hard-link creation with EPERM; aliases are not a MemFS capability.
+     *
+     * @evidence contracts/common.md#principled-implementation An explicit callback error marks an unsupported bridge operation.
+     * @evidence contracts/common.md#clear-and-simple-design One rejection boundary keeps unsupported inode aliasing out of the node tree and descriptor model.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts A copied file is not presented as a shared-inode hard link.
+     * @evidence contracts/common.md#meaningful-documentation JSDoc names the absent capability and error under the documentation skill's failure guidance.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources link is a signature only; the lifetime of what it touches belongs to createMemFS.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms link is a signature only; its algorithm and cost belong to createMemFS.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work link is a signature only; sharing of repeated work belongs to createMemFS.
+     */
     link(path: string, link: string, callback: (err: NodeJS.ErrnoException | null) => void): void;
+    /**
+     * Reject symbolic-link creation with EPERM.
+     *
+     * @evidence contracts/common.md#principled-implementation The bridge reports its absent symbolic-link capability explicitly.
+     * @evidence contracts/common.md#clear-and-simple-design An explicit unsupported operation avoids a second path-resolution model with no supported symlink nodes.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Link creation is not approximated by storing target text as an ordinary file.
+     * @evidence contracts/common.md#meaningful-documentation JSDoc names the rejection under the documentation skill's failure guidance.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources symlink is a signature only; the lifetime of what it touches belongs to createMemFS.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms symlink is a signature only; its algorithm and cost belong to createMemFS.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work symlink is a signature only; sharing of repeated work belongs to createMemFS.
+     */
     symlink(path: string, link: string, callback: (err: NodeJS.ErrnoException | null) => void): void;
+    /**
+     * Reject link-target lookup with EINVAL because MemFS has no symbolic links.
+     *
+     * @evidence contracts/common.md#principled-implementation Explicit unsupported lookup matches the virtual store's declared node kinds.
+     * @evidence contracts/common.md#clear-and-simple-design Link-target lookup remains a focused rejection instead of overloading ordinary file text as link state.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts No guessed path is returned as a fabricated link target.
+     * @evidence contracts/common.md#meaningful-documentation JSDoc states the reason and error under the documentation skill's rationale guidance.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources readlink is a signature only; the lifetime of what it touches belongs to createMemFS.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms readlink is a signature only; its algorithm and cost belong to createMemFS.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work readlink is a signature only; sharing of repeated work belongs to createMemFS.
+     */
     readlink(path: string, callback: (err: NodeJS.ErrnoException | null, link: string) => void): void;
+    /**
+     * Resize a file to a nonnegative integer byte length, zero-filling
+     * extensions. A length the engine cannot allocate reports `EFBIG` and changes
+     * nothing.
+     *
+     * @evidence contracts/common.md#principled-implementation Path-based resize operates on the stored node and preserves open-descriptor identity.
+     * @evidence contracts/common.md#clear-and-simple-design The path variant resolves a node then uses shared resize semantics rather than composing reads and writes.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Invalid lengths and directories remain errors rather than coerced file mutations.
+     * @evidence contracts/common.md#meaningful-documentation JSDoc explains units, validation and extension under the documentation skill's context guidance.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources truncate is a signature only; the lifetime of what it touches belongs to createMemFS.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms truncate is a signature only; its algorithm and cost belong to createMemFS.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work truncate is a signature only; sharing of repeated work belongs to createMemFS.
+     */
     truncate(path: string, length: number, callback: (err: NodeJS.ErrnoException | null) => void): void;
+    /**
+     * Resize a writable open file without changing its descriptor cursor. A
+     * length the engine cannot allocate reports `EFBIG` and changes nothing.
+     *
+     * @evidence contracts/common.md#principled-implementation Descriptor resize uses retained inode identity and its access grant.
+     * @evidence contracts/common.md#clear-and-simple-design Descriptor validation is separate from the shared byte resize; cursor ownership remains with read/write operations.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Pipe ends and captured streams are not coerced into truncatable files.
+     * @evidence contracts/common.md#meaningful-documentation JSDoc states permission and cursor behavior under the documentation skill's ownership guidance.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources ftruncate is a signature only; the lifetime of what it touches belongs to createMemFS.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms ftruncate is a signature only; its algorithm and cost belong to createMemFS.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work ftruncate is a signature only; sharing of repeated work belongs to createMemFS.
+     */
     ftruncate(fd: number, length: number, callback: (err: NodeJS.ErrnoException | null) => void): void;
     /**
      * JavaScript-only pipe emulation. Returns two fds: a read end and a write
@@ -50,6 +352,14 @@ export interface IWasmExecFS {
      * and fd 2 land in `stdout.buffer` and `stderr.buffer` through `writeSync`,
      * and a plugin's output is collected by the Go-side `host.InvokePlugin` into
      * invocation-owned in-process buffers.
+     *
+     * @evidence contracts/common.md#principled-implementation Two virtual descriptors expose JavaScript queue endpoints without claiming a Go syscall extension.
+     * @evidence contracts/common.md#clear-and-simple-design Two endpoint identities share one queue state; the JavaScript-only capability is kept distinct from native Go pipes.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The unreachable Go os.Pipe capability is explicit rather than hidden behind a monkey-patched syscall claim.
+     * @evidence contracts/common.md#meaningful-documentation Separate paragraphs explain endpoint shape, Go limits and actual output capture under the documentation skill.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources pipe2 is a signature only; the lifetime of what it touches belongs to createMemFS.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms pipe2 is a signature only; its algorithm and cost belong to createMemFS.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work pipe2 is a signature only; sharing of repeated work belongs to createMemFS.
      */
     pipe2(flags: number, callback: (err: NodeJS.ErrnoException | null, fds: [number, number]) => void): void;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttsc/wasm",
-  "version": "0.30.3",
+  "version": "0.31.0",
   "description": "Build in-browser ttsc playgrounds. Compose ttsc + typescript-go with your own plugins via the Go host helper.",
   "main": "lib/src/index.js",
   "types": "lib/src/index.d.ts",
@@ -37,6 +37,7 @@
   },
   "homepage": "https://ttsc.dev",
   "devDependencies": {
+    "@wrtnlabs/evidence": "^0.3.1",
     "@types/node": "^25.3.0",
     "rimraf": "^6.1.2",
     "typescript": "^7.0.2"
@@ -44,6 +45,7 @@
   "scripts": {
     "build": "node build/build-wasm.cjs && rimraf lib && tsc -p .",
     "build:wasm": "node build/build-wasm.cjs",
-    "build:ts": "rimraf lib && tsc -p ."
+    "build:ts": "rimraf lib && tsc -p .",
+    "evidence": "evidence"
   }
 }

package/shim-vendor/shim/ast/enums_gen.go

@@ -2,8 +2,8 @@
 //
 // Completes every exposed enum family: re-exports each member not already
 // re-exported elsewhere in the shim package, so a plugin that can name the
-// enum type can name all of its values. Prevents the #230 class (a sibling
-// const silently missing). Regenerate after a typescript-go bump with
+// enum type can name all of its values. Prevents a partially re-exported
+// family (a sibling const silently missing). Regenerate after a typescript-go bump with
 // `pnpm --filter ttsc shim:audit -fix`.
 
 package ast
@@ -61,10 +61,12 @@ const (
   NodeFlagsHasImplicitReturn                     = innerast.NodeFlagsHasImplicitReturn
   NodeFlagsHasJSDoc                              = innerast.NodeFlagsHasJSDoc
   NodeFlagsIdentifierHasExtendedUnicodeEscape    = innerast.NodeFlagsIdentifierHasExtendedUnicodeEscape
+  NodeFlagsIdentifierIsInJSDocNamespace          = innerast.NodeFlagsIdentifierIsInJSDocNamespace
   NodeFlagsInWithStatement                       = innerast.NodeFlagsInWithStatement
   NodeFlagsJSDoc                                 = innerast.NodeFlagsJSDoc
   NodeFlagsJavaScriptFile                        = innerast.NodeFlagsJavaScriptFile
   NodeFlagsJsonFile                              = innerast.NodeFlagsJsonFile
+  NodeFlagsNestedNamespace                       = innerast.NodeFlagsNestedNamespace
   NodeFlagsPermanentlySetIncrementalFlags        = innerast.NodeFlagsPermanentlySetIncrementalFlags
   NodeFlagsPossiblyContainsDeprecatedTag         = innerast.NodeFlagsPossiblyContainsDeprecatedTag
   NodeFlagsPossiblyContainsDynamicImport         = innerast.NodeFlagsPossiblyContainsDynamicImport

package/shim-vendor/shim/ast/go.mod

@@ -2,13 +2,13 @@ module github.com/microsoft/typescript-go/shim/ast
 
 go 1.26
 
-require github.com/microsoft/typescript-go v0.0.0-20260429010842-56ab4af42157
+require github.com/microsoft/typescript-go v0.0.0-20260610182825-7fc57c005063
 
 require (
-	github.com/go-json-experiment/json v0.0.0-20260214004413-d219187c3433 // indirect
+	github.com/go-json-experiment/json v0.0.0-20260601182631-00ed12fed2a6 // indirect
 	github.com/klauspost/cpuid/v2 v2.2.10 // indirect
 	github.com/zeebo/xxh3 v1.1.0 // indirect
-	golang.org/x/sync v0.20.0 // indirect
-	golang.org/x/sys v0.43.0 // indirect
-	golang.org/x/text v0.36.0 // indirect
+	golang.org/x/sync v0.21.0 // indirect
+	golang.org/x/sys v0.46.0 // indirect
+	golang.org/x/text v0.38.0 // indirect
 )

package/shim-vendor/shim/ast/go.sum

@@ -1,20 +1,20 @@
-github.com/go-json-experiment/json v0.0.0-20260214004413-d219187c3433 h1:vymEbVwYFP/L05h5TKQxvkXoKxNvTpjxYKdF1Nlwuao=
-github.com/go-json-experiment/json v0.0.0-20260214004413-d219187c3433/go.mod h1:tphK2c80bpPhMOI4v6bIc2xWywPfbqi1Z06+RcrMkDg=
+github.com/go-json-experiment/json v0.0.0-20260601182631-00ed12fed2a6 h1:nxP4pPoyqOAgX8lYDFCfl3DyKeXErCvSvhcyzwGV9CE=
+github.com/go-json-experiment/json v0.0.0-20260601182631-00ed12fed2a6/go.mod h1:tphK2c80bpPhMOI4v6bIc2xWywPfbqi1Z06+RcrMkDg=
 github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
 github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
 github.com/klauspost/cpuid/v2 v2.2.10 h1:tBs3QSyvjDyFTq3uoc/9xFpCuOsJQFNPiAhYdw2skhE=
 github.com/klauspost/cpuid/v2 v2.2.10/go.mod h1:hqwkgyIinND0mEev00jJYCxPNVRVXFQeu1XKlok6oO0=
-github.com/microsoft/typescript-go v0.0.0-20260429010842-56ab4af42157 h1:llOMPhKDiQ+UEJiAaQuuWaJOTg5V7tNNTEf9JPWoYSY=
-github.com/microsoft/typescript-go v0.0.0-20260429010842-56ab4af42157/go.mod h1:m8YA0PMC7ti0GW0RI05D6fEcjQeu98XVS+FWF+VDW2k=
+github.com/microsoft/typescript-go v0.0.0-20260610182825-7fc57c005063 h1:UUVrjTrD+7nkVvkJTjxwA5+SaZ5n1uyAffm2zX2gn+o=
+github.com/microsoft/typescript-go v0.0.0-20260610182825-7fc57c005063/go.mod h1:s3yhRRZ7nzSZaiKicku520Tj9Mvewr9y2UtrvpwOmDE=
 github.com/zeebo/assert v1.3.0 h1:g7C04CbJuIDKNPFHmsk4hwZDO5O+kntRxzaUoNXj+IQ=
 github.com/zeebo/assert v1.3.0/go.mod h1:Pq9JiuJQpG8JLJdtkwrJESF0Foym2/D9XMU5ciN/wJ0=
 github.com/zeebo/xxh3 v1.1.0 h1:s7DLGDK45Dyfg7++yxI0khrfwq9661w9EN78eP/UZVs=
 github.com/zeebo/xxh3 v1.1.0/go.mod h1:IisAie1LELR4xhVinxWS5+zf1lA4p0MW4T+w+W07F5s=
-golang.org/x/sync v0.20.0 h1:e0PTpb7pjO8GAtTs2dQ6jYa5BWYlMuX047Dco/pItO4=
-golang.org/x/sync v0.20.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
-golang.org/x/sys v0.43.0 h1:Rlag2XtaFTxp19wS8MXlJwTvoh8ArU6ezoyFsMyCTNI=
-golang.org/x/sys v0.43.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
-golang.org/x/text v0.36.0 h1:JfKh3XmcRPqZPKevfXVpI1wXPTqbkE5f7JA92a55Yxg=
-golang.org/x/text v0.36.0/go.mod h1:NIdBknypM8iqVmPiuco0Dh6P5Jcdk8lJL0CUebqK164=
+golang.org/x/sync v0.21.0 h1:HLII4xRRTtCRkxYp4HNFF0Js/Og6q2i++KXbg0gHCwM=
+golang.org/x/sync v0.21.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
+golang.org/x/sys v0.46.0 h1:noSf2Fq6F8DBgS+LysIkx7rIExoNHJsxOAtPp4rthXw=
+golang.org/x/sys v0.46.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
+golang.org/x/text v0.38.0 h1:sXmwo9DwP3OK9EZ7PqAdaooSGozfl/3a6/xJcbzPRhE=
+golang.org/x/text v0.38.0/go.mod h1:YXZt3QhHUKYT53r2lLKFIVi6Ao1jdzrTR/KQ09qyxF4=
 gotest.tools/v3 v3.5.2 h1:7koQfIKdy+I8UTetycgUqXWSDwpgv193Ka+qRsmBY8Q=
 gotest.tools/v3 v3.5.2/go.mod h1:LtdLGcnqToBH83WByAAi/wiwSFCArdFIUV/xxN4pcjA=