@ttsc/wasm 0.30.3 → 0.31.0

package/host/invoke.go

@@ -0,0 +1,133 @@
+package host
+
+import (
+  "context"
+  "io"
+  "sync"
+)
+
+// PluginInvocation owns all mutable state for one plugin call.
+//
+// A plugin that needs asynchronous work must register it with Go before Run
+// returns. InvokePlugin waits for every registered function. Registration
+// after Run returns is rejected, and writes made after the invocation closes
+// return io.ErrClosedPipe. This gives child goroutines an explicit ownership
+// boundary without sharing process-global output state.
+//
+// @evidence contracts/common.md#principled-implementation Context, io.Writer and synchronization primitives make request and child ownership explicit.
+// @evidence contracts/common.md#clear-and-simple-design Public command inputs and writers are distinct from private registration state; Go is the single boundary that couples task acceptance with the owner's completion wait.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Mutable buffers belong to each request, without global-stream swapping for concurrent calls.
+// @evidence contracts/common.md#meaningful-documentation Native paragraphs explain child registration and late-write rejection under the documentation skill.
+// @evidenceExclude contracts/performance.md#efficient-algorithms This owning request type groups task state and inputs; its Go and InvokePlugin operations choose the processing strategy.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work One effectful invocation is not a coordinator of equivalent request computations.
+// @evidence contracts/performance.md#bound-retention-and-release-resources InvokePlugin acquires this request's context, copied arguments and writers. Go registers child tasks until Run exits; the owner waits for them and closes streams on normal and panic exits. Task count and captured bytes are unbounded, and children must cooperate with cancellation because the host cannot force goroutine termination.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation PluginInvocation holds in-memory streams and a goroutine counter and carries no native path, process or platform capability.
+type PluginInvocation struct {
+  // Context derives from the caller and is canceled when invocation ownership ends.
+  Context context.Context
+
+  // Command is the selected plugin subcommand.
+  Command string
+
+  // Args is the invocation-owned copy of forwarded CLI arguments.
+  Args []string
+
+  // Stdout accepts writes until all registered work completes.
+  Stdout io.Writer
+
+  // Stderr has the same ownership boundary as Stdout.
+  Stderr io.Writer
+
+  childrenMu     sync.Mutex
+  children       sync.WaitGroup
+  acceptingChild bool
+}
+
+// Go registers and starts invocation-owned asynchronous work. It returns false
+// when Run has already returned and the ownership boundary is closed.
+//
+// The task receives the invocation context. It must honor cancellation itself;
+// registration does not supply a timeout or recover a panic in the child.
+//
+// @evidence contracts/common.md#principled-implementation A mutex couples acceptance and WaitGroup.Add, making child registration precede the owner's Wait.
+// @evidence contracts/common.md#clear-and-simple-design One registration method keeps the acceptance check and task-count transition together, with no separate caller-managed Add/Wait protocol.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Late work is rejected instead of relying on a race-prone Add after Wait begins.
+// @evidence contracts/common.md#meaningful-documentation Separate native paragraphs explain acceptance and task obligations under the documentation skill.
+// @evidence contracts/performance.md#efficient-algorithms Registration checks acceptance and increments the WaitGroup count under one mutex in O(1), then schedules one goroutine. Task work is supplied by the plugin and is not rescanned by registration.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work This operation registers an effectful child task; it does not determine equivalence of computations across requests.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Acceptance acquires one child count and goroutine; deferred Done releases the count when the task exits. Run's owner closes registration before waiting. Outstanding count is unbounded and completion depends on the task honoring its context and returning.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation PluginInvocation.Go starts an in-process goroutine and touches no native path or operating-system process.
+func (invocation *PluginInvocation) Go(task func(context.Context)) bool {
+  if task == nil {
+    return false
+  }
+  invocation.childrenMu.Lock()
+  if !invocation.acceptingChild {
+    invocation.childrenMu.Unlock()
+    return false
+  }
+  invocation.children.Add(1)
+  invocation.childrenMu.Unlock()
+  go func() {
+    defer invocation.children.Done()
+    task(invocation.Context)
+  }()
+  return true
+}
+
+// InvokePlugin executes one plugin call and captures its request-owned output.
+// Independent invocations may run concurrently without sharing buffers.
+//
+// The caller's arguments are copied before dispatch. Run must return and each
+// registered task must finish before the result can be captured; the context is
+// propagated through an invocation-owned child context, without a deadline or
+// forced goroutine stop. A panic from Run cancels that context, closes child
+// registration, waits for cooperative registered work and closes its streams
+// before propagating to the caller's panic handler.
+//
+// @evidence contracts/common.md#principled-implementation Each call copies arguments and owns synchronized writers; closing task acceptance under the same mutex as registration makes Wait safe after Run exits. Deferred finalization closes streams only after registered work finishes, including cooperative cancellation on a Run panic.
+// @evidence contracts/common.md#clear-and-simple-design One invocation owns context, child registration and output finalization. The private writer enforces the same closing boundary for both streams, without a global capture mechanism or separate plugin lifecycle framework.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Owned streams replace process-global output mutation. Deferred finalization covers normal and panic exits without swallowing a panic; child tasks remain responsible for honoring context because Go cannot forcibly stop them.
+// @evidence contracts/common.md#meaningful-documentation Native paragraphs explain isolation and completion obligations under the documentation skill's ownership guidance.
+// @evidence contracts/performance.md#efficient-algorithms Copying A argument references costs O(A); the two bytes.Buffer writers grow amortized with B captured bytes and final string capture costs O(B). Waiting tracks G registered tasks without scanning a task list. The selected plugin owns its command's algorithm.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work Each command owns effects and output; this executor does not coordinate equivalent request computations, and equal argument strings do not make calls shareable.
+// @evidence contracts/performance.md#bound-retention-and-release-resources The call owns context, argument copy, G child tasks and B captured bytes. Deferred finalization closes registration, waits for registered work, closes both writers and cancels the context on every return/panic path. G and B have no fixed bound, and a noncooperative task can keep finalization waiting; the returned strings transfer captured output to the caller.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation InvokePlugin runs an in-process Plugin against in-memory buffers and starts no operating-system process and reads no native path.
+func InvokePlugin(ctx context.Context, plugin Plugin, command string, args []string) (result APIResult) {
+  if ctx == nil {
+    ctx = context.Background()
+  }
+  ctx, cancel := context.WithCancel(ctx)
+  stdout := &invocationBuffer{}
+  stderr := &invocationBuffer{}
+  invocation := &PluginInvocation{
+    Context:        ctx,
+    Command:        command,
+    Args:           append([]string(nil), args...),
+    Stdout:         stdout,
+    Stderr:         stderr,
+    acceptingChild: true,
+  }
+  code := 0
+  returned := false
+  defer func() {
+    defer cancel()
+    if !returned {
+      cancel()
+    }
+    invocation.childrenMu.Lock()
+    invocation.acceptingChild = false
+    invocation.childrenMu.Unlock()
+    invocation.children.Wait()
+    stdout.close()
+    stderr.close()
+    result = APIResult{
+      Code:   code,
+      Stdout: stdout.String(),
+      Stderr: stderr.String(),
+    }
+  }()
+  code = plugin.Run(invocation)
+  returned = true
+  return
+}

package/host/plugin.go

@@ -2,7 +2,6 @@ package host
 
 import (
   "bytes"
-  "context"
   "io"
   "sync"
 )
@@ -13,88 +12,54 @@ import (
 // adapters and registers them with Config. Every run receives invocation-owned
 // streams; a plugin must write only to those streams, never os.Stdout or
 // os.Stderr.
+//
+// @evidence contracts/common.md#principled-implementation A small Go interface supplies named command dispatch through invocation-owned streams.
+// @evidence contracts/common.md#clear-and-simple-design Name identifies registration and Run owns command execution; invocation context and streams are supplied through one request rather than host-owned plugin-specific APIs.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The supported plugin boundary avoids mutating process-global stdout/stderr to capture a call.
+// @evidence contracts/common.md#meaningful-documentation Native paragraphs explain browser linkage and stream ownership under the documentation skill.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Plugin is an interface that acquires no handle, task or retained state.
+// @evidenceExclude contracts/performance.md#efficient-algorithms Plugin is an interface that chooses no algorithm or processing strategy.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work Plugin is an interface that coordinates no shared or repeated computation.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Plugin declares command dispatch for in-process adapters and carries no native path, process or platform decision.
 type Plugin interface {
   // Name is the npm-style plugin id passed to api.plugin.
+  //
+  // @evidence contracts/common.md#principled-implementation Explicit registration identity decouples dispatch from the concrete plugin type.
+  // @evidence contracts/common.md#clear-and-simple-design One name query supplies the registry key without exposing command state or concrete plugin implementation.
+  // @evidence contracts/common.md#prohibited-implementation-shortcuts The implementation declares its id rather than being recognized by a consumer-specific type check.
+  // @evidence contracts/common.md#meaningful-documentation The Go member comment names the API consumer under the documentation skill's context rule.
+  // @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Plugin.Name is an abstract method; the invocation and the concrete plugin own its resources.
+  // @evidenceExclude contracts/performance.md#efficient-algorithms Plugin.Name is an abstract method; the concrete plugin chooses its algorithm.
+  // @evidenceExclude contracts/performance.md#reuse-equivalent-work Plugin.Name is an abstract method; the concrete plugin owns any reuse of its work.
+  // @evidenceExclude contracts/portability.md#os-neutral-implementation Plugin.Name is an interface method with no native path, process or platform decision.
   Name() string
 
   // Run dispatches one subcommand and returns the native CLI exit code.
+  //
+  // @evidence contracts/common.md#principled-implementation A request object supplies context, arguments and owned writers through one Go extension boundary.
+  // @evidence contracts/common.md#clear-and-simple-design One invocation groups command inputs and owned effects; command-specific parsing stays with the implementation rather than the generic host.
+  // @evidence contracts/common.md#prohibited-implementation-shortcuts Commands run through the registered implementation rather than changing a foreign global launcher.
+  // @evidence contracts/common.md#meaningful-documentation The member comment states dispatch and exit-code roles under the documentation skill's clarity rule.
+  // @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Plugin.Run is an abstract method; the invocation and the concrete plugin own its resources.
+  // @evidenceExclude contracts/performance.md#efficient-algorithms Plugin.Run is an abstract method; the concrete plugin chooses its algorithm.
+  // @evidenceExclude contracts/performance.md#reuse-equivalent-work Plugin.Run is an abstract method; the concrete plugin owns any reuse of its work.
+  // @evidenceExclude contracts/portability.md#os-neutral-implementation Plugin.Run is an interface method with no native path, process or platform decision.
   Run(invocation *PluginInvocation) int
 }
 
-// PluginInvocation owns all mutable state for one plugin call.
-//
-// A plugin that needs asynchronous work must register it with Go before Run
-// returns. InvokePlugin waits for every registered function. Registration
-// after Run returns is rejected, and writes made after the invocation closes
-// return io.ErrClosedPipe. This gives child goroutines an explicit ownership
-// boundary without sharing process-global output state.
-type PluginInvocation struct {
-  Context context.Context
-  Command string
-  Args    []string
-  Stdout  io.Writer
-  Stderr  io.Writer
-
-  childrenMu     sync.Mutex
-  children       sync.WaitGroup
-  acceptingChild bool
-}
-
-// Go registers and starts invocation-owned asynchronous work. It returns false
-// when Run has already returned and the ownership boundary is closed.
-func (invocation *PluginInvocation) Go(task func(context.Context)) bool {
-  if task == nil {
-    return false
-  }
-  invocation.childrenMu.Lock()
-  if !invocation.acceptingChild {
-    invocation.childrenMu.Unlock()
-    return false
-  }
-  invocation.children.Add(1)
-  invocation.childrenMu.Unlock()
-  go func() {
-    defer invocation.children.Done()
-    task(invocation.Context)
-  }()
-  return true
-}
-
-// InvokePlugin executes one plugin call and captures its request-owned output.
-// Independent invocations may run concurrently without sharing buffers.
-func InvokePlugin(ctx context.Context, plugin Plugin, command string, args []string) APIResult {
-  if ctx == nil {
-    ctx = context.Background()
-  }
-  stdout := &invocationBuffer{}
-  stderr := &invocationBuffer{}
-  invocation := &PluginInvocation{
-    Context:        ctx,
-    Command:        command,
-    Args:           append([]string(nil), args...),
-    Stdout:         stdout,
-    Stderr:         stderr,
-    acceptingChild: true,
-  }
-  code := plugin.Run(invocation)
-
-  invocation.childrenMu.Lock()
-  invocation.acceptingChild = false
-  invocation.childrenMu.Unlock()
-  invocation.children.Wait()
-
-  stdout.close()
-  stderr.close()
-  return APIResult{
-    Code:   code,
-    Stdout: stdout.String(),
-    Stderr: stderr.String(),
-  }
-}
-
 // Config carries the optional registrations the host applies before binding
 // globalThis[name]. Pass Config{} for a vanilla ttsc + tsgo wasm.
+//
+// @evidence contracts/common.md#principled-implementation An explicit slice of the small Plugin interface keeps linkage and registration with the consumer host.
+// @evidence contracts/common.md#clear-and-simple-design One registration list is sufficient for the host factory; command options and mutable invocation state remain owned by the selected plugin call.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The host receives linked registrations rather than guessing installed packages from hardcoded ids.
+// @evidence contracts/common.md#meaningful-documentation The native comment explains empty configuration and registration timing under the documentation skill's context rule.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Config is a data type and acquires no handle, task or retained state.
+// @evidenceExclude contracts/performance.md#efficient-algorithms Config is a data type and chooses no algorithm or processing strategy.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work Config is a data type and coordinates no shared or repeated computation.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Config is a data type and performs no native filesystem, path or process operation.
 type Config struct {
+  // Plugins are registered once; empty names and nil entries are skipped.
   Plugins []Plugin
 }
 

package/host/result.go

@@ -0,0 +1,108 @@
+// JSON payload shapes shared by the wasm and native entrypoints.
+package host
+
+// APIResult is the stdout/stderr capture returned by InvokePlugin. The
+// js/wasm binding wraps it in the same JS result envelope that build/check/
+// transform use, adding `result` when an endpoint has a JSON payload. `code`
+// follows the native CLI exit-code contract (0 success, 2 compiler/config/
+// usage error, 3 runtime error).
+//
+// @evidence contracts/common.md#principled-implementation Explicit stream fields mirror invocation capture and the JavaScript envelope.
+// @evidence contracts/common.md#clear-and-simple-design One capture value separates exit status and the two streams, leaving project JSON to the JavaScript envelope.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The exit code remains data rather than being replaced by a success-only output shape.
+// @evidence contracts/common.md#meaningful-documentation Native comments explain channels and exit codes under the documentation skill's context guidance.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources APIResult is a data type and acquires no handle, task or retained state.
+// @evidenceExclude contracts/performance.md#efficient-algorithms APIResult is a data type and chooses no algorithm or processing strategy.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work APIResult is a data type and coordinates no shared or repeated computation.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation APIResult is a data type and performs no native filesystem, path or process operation.
+type APIResult struct {
+  // Code is the plugin's CLI exit status.
+  Code int `json:"code"`
+
+  // Stdout contains this invocation's standard output.
+  Stdout string `json:"stdout"`
+
+  // Stderr contains this invocation's diagnostic output.
+  Stderr string `json:"stderr"`
+}
+
+// CompileResult mirrors `ttsc api-compile`. Field names are TypeScript-style
+// so JS callers can use it directly without remapping.
+//
+// @evidence contracts/common.md#principled-implementation JSON field tags preserve the TypeScript-facing compiler payload and optional diagnostic list.
+// @evidence contracts/common.md#clear-and-simple-design Diagnostics reuse one wire DTO while output text is keyed by destination; the transport envelope stays outside this payload.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Emitted paths and contents remain compiler data rather than a consumer-shaped output schema.
+// @evidence contracts/common.md#meaningful-documentation Comments identify the wire shape, omission and output path base under the documentation skill's context rule.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources CompileResult is a data type and acquires no handle, task or retained state.
+// @evidenceExclude contracts/performance.md#efficient-algorithms CompileResult is a data type and chooses no algorithm or processing strategy.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work CompileResult is a data type and coordinates no shared or repeated computation.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation CompileResult is a data type and performs no native filesystem, path or process operation.
+type CompileResult struct {
+  // Diagnostics is omitted when the result has no messages.
+  Diagnostics []CompileDiagnostic `json:"diagnostics,omitempty"`
+
+  // Output maps emitted paths to JS / d.ts text. Paths inside cwd are relative;
+  // outside destinations stay absolute. Empty when no files were produced.
+  Output map[string]string `json:"output"`
+}
+
+// TransformResult is the no-emit companion. The `typescript` map keys files
+// the same way `output` does in compile mode.
+//
+// @evidence contracts/common.md#principled-implementation A distinct source-text map avoids conflating transformed TypeScript with emitted output.
+// @evidence contracts/common.md#clear-and-simple-design The source-text map and shared diagnostics form one transform payload, separate from compile output and invocation streams.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The payload represents actual program text instead of reconstructing it from JavaScript emit.
+// @evidence contracts/common.md#meaningful-documentation Native comments distinguish the source stage and optional messages under the documentation skill's clarity rule.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources TransformResult is a data type and acquires no handle, task or retained state.
+// @evidenceExclude contracts/performance.md#efficient-algorithms TransformResult is a data type and chooses no algorithm or processing strategy.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work TransformResult is a data type and coordinates no shared or repeated computation.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation TransformResult is a data type and performs no native filesystem, path or process operation.
+type TransformResult struct {
+  // Diagnostics is omitted when the result has no messages.
+  Diagnostics []CompileDiagnostic `json:"diagnostics,omitempty"`
+
+  // TypeScript holds post-plugin text under project-relative or outside absolute paths.
+  TypeScript map[string]string `json:"typescript"`
+}
+
+// CompileDiagnostic is the public TypeScript-side diagnostic DTO. Mirrors the
+// shape `ttsc api-compile` writes so the JS host can render it without
+// remapping fields.
+//
+// Start/Length are UTF-8 byte offsets and lengths. Line/Character are 1-based;
+// Character counts UTF-8 bytes from the line start, as the native driver does.
+// Zero display locations are omitted when no source context is available.
+//
+// @evidence contracts/common.md#principled-implementation Nullable file and optional location fields follow the driver's diagnostic projection through JSON.
+// @evidence contracts/common.md#clear-and-simple-design File identity, severity, byte span and display location remain distinct fields, with pointers for absent spans rather than an alternate diagnostic model.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Compiler coordinates are preserved rather than guessed from JavaScript text indices.
+// @evidence contracts/common.md#meaningful-documentation Separate comments explain coordinate units and absence under the documentation skill's paragraph guidance.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources CompileDiagnostic is a data type and acquires no handle, task or retained state.
+// @evidenceExclude contracts/performance.md#efficient-algorithms CompileDiagnostic is a data type and chooses no algorithm or processing strategy.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work CompileDiagnostic is a data type and coordinates no shared or repeated computation.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation CompileDiagnostic is a data type and performs no native filesystem, path or process operation.
+type CompileDiagnostic struct {
+  // File is an absolute slash path, or nil for a project-wide message.
+  File *string `json:"file"`
+
+  // Category is error or warning; errors affect the command exit code.
+  Category string `json:"category"`
+
+  // Code is the compiler or plugin diagnostic identifier.
+  Code int32 `json:"code"`
+
+  // Start is the optional inclusive UTF-8 byte offset.
+  Start *int `json:"start,omitempty"`
+
+  // Length is the optional span length in UTF-8 bytes.
+  Length *int `json:"length,omitempty"`
+
+  // Line is 1-based and omitted without a display location.
+  Line int `json:"line,omitempty"`
+
+  // Character is a 1-based UTF-8 byte column, omitted without a location.
+  Character int `json:"character,omitempty"`
+
+  // MessageText is the complete compiler or plugin message.
+  MessageText string `json:"messageText"`
+}

package/lib/src/BootTtscWorkerTerminationError.d.ts

@@ -5,11 +5,31 @@
  * same API name in the same Worker would install a new readiness bridge that
  * the stale runtime could invoke, so `bootTtsc` terminally rejects later boots
  * until the caller terminates the Worker.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   An Error subclass carries a stable machine-readable code, API identity and
+ *   original cause so the owner can replace the Worker rather than parse prose.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   One error identity groups the terminal discriminator, API slot and cause;
+ *   Worker replacement remains the caller's responsibility, outside this value.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   The error exposes the runtime's terminal ownership limit rather than hiding
+ *   it under retries that would reuse a stale global readiness bridge.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Separate JSDoc paragraphs explain the failure and why replacement is required;
+ *   members explain identity and cause, following the documentation skill.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources BootTtscWorkerTerminationError retains only its own fields and cause and is released with the rejection.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms BootTtscWorkerTerminationError builds one message string and chooses no processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work BootTtscWorkerTerminationError is an error value and coordinates no shared or repeated computation.
  */
 export declare class BootTtscWorkerTerminationError extends Error {
+    /** Stable discriminator for Worker-replacement handling. */
     static readonly CODE = "TTSC_WASM_WORKER_TERMINATION_REQUIRED";
+    /** Global API bridge whose Go runtime has already started. */
     readonly apiName: string;
+    /** Instance discriminator shared with the class constant. */
     readonly code = "TTSC_WASM_WORKER_TERMINATION_REQUIRED";
+    /** Original cancellation, startup or runtime failure. */
     readonly cause: unknown;
     constructor(apiName: string, cause: unknown);
 }

package/lib/src/BootTtscWorkerTerminationError.js

@@ -8,11 +8,31 @@ exports.BootTtscWorkerTerminationError = void 0;
  * same API name in the same Worker would install a new readiness bridge that
  * the stale runtime could invoke, so `bootTtsc` terminally rejects later boots
  * until the caller terminates the Worker.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   An Error subclass carries a stable machine-readable code, API identity and
+ *   original cause so the owner can replace the Worker rather than parse prose.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   One error identity groups the terminal discriminator, API slot and cause;
+ *   Worker replacement remains the caller's responsibility, outside this value.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   The error exposes the runtime's terminal ownership limit rather than hiding
+ *   it under retries that would reuse a stale global readiness bridge.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Separate JSDoc paragraphs explain the failure and why replacement is required;
+ *   members explain identity and cause, following the documentation skill.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources BootTtscWorkerTerminationError retains only its own fields and cause and is released with the rejection.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms BootTtscWorkerTerminationError builds one message string and chooses no processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work BootTtscWorkerTerminationError is an error value and coordinates no shared or repeated computation.
  */
 class BootTtscWorkerTerminationError extends Error {
+    /** Stable discriminator for Worker-replacement handling. */
     static CODE = "TTSC_WASM_WORKER_TERMINATION_REQUIRED";
+    /** Global API bridge whose Go runtime has already started. */
     apiName;
+    /** Instance discriminator shared with the class constant. */
     code = BootTtscWorkerTerminationError.CODE;
+    /** Original cancellation, startup or runtime failure. */
     cause;
     constructor(apiName, cause) {
         const causeMessage = cause instanceof Error ? cause.message : String(cause ?? "boot failed");

package/lib/src/BootTtscWorkerTerminationError.js.map

@@ -1 +1 @@
-{"version":3,"file":"BootTtscWorkerTerminationError.js","sourceRoot":"","sources":["../../src/BootTtscWorkerTerminationError.ts"],"names":[],"mappings":";;;AAAA;;;;;;;GAOG;AACH,oCAA4C,SAAQ,KAAK;IAChD,MAAM,CAAU,IAAI,GAAG,uCAAuC,CAAC;IAEtD,OAAO,CAAS;IAChB,IAAI,GAAG,8BAA8B,CAAC,IAAI,CAAC;IAClC,KAAK,CAAU;IAExC,YAAmB,OAAe,EAAE,KAAc;QAChD,MAAM,YAAY,GAChB,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,IAAI,aAAa,CAAC,CAAC;QAC1E,KAAK,CACH,IAAI,8BAA8B,CAAC,IAAI,KAAK,YAAY,kBAAkB,OAAO,iFAAiF,CACnK,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,gCAAgC,CAAC;QAC7C,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;CACF"}
+{"version":3,"file":"BootTtscWorkerTerminationError.js","sourceRoot":"","sources":["../../src/BootTtscWorkerTerminationError.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,oCAA4C,SAAQ,KAAK;IACvD,4DAA4D;IACrD,MAAM,CAAU,IAAI,GAAG,uCAAuC,CAAC;IAEtE,8DAA8D;IAC9C,OAAO,CAAS;IAEhC,6DAA6D;IAC7C,IAAI,GAAG,8BAA8B,CAAC,IAAI,CAAC;IAE3D,yDAAyD;IAChC,KAAK,CAAU;IAExC,YAAmB,OAAe,EAAE,KAAc;QAChD,MAAM,YAAY,GAChB,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,IAAI,aAAa,CAAC,CAAC;QAC1E,KAAK,CACH,IAAI,8BAA8B,CAAC,IAAI,KAAK,YAAY,kBAAkB,OAAO,iFAAiF,CACnK,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,gCAAgC,CAAC;QAC7C,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;CACF"}

package/lib/src/MemFSError.d.ts

@@ -3,13 +3,32 @@
  *
  * Matches the shape of `NodeJS.ErrnoException` so Go's `os` package interprets
  * it as a proper `os.PathError` with a numeric error code. Thrown by the MemFS
- * implementation when a callback would otherwise pass `null` for an impossible
- * filesystem operation (missing path, type mismatch, …).
+ * implementation for rejected virtual filesystem operations.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   Error fields follow NodeJS.ErrnoException and Go's js/wasm filesystem bridge;
+ *   numeric errno values describe that virtual ABI, not the browser host OS.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   The Error subclass groups the bridge's machine fields with its message;
+ *   one private mapping owns errno translation for every virtual operation.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   POSIX error identifiers are protocol constants; failed operations remain
+ *   errors instead of returning a fake successful callback value.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Native JSDoc explains the bridge and members' machine-readable roles,
+ *   following the documentation skill's concrete context guidance.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources MemFSError retains only its own fields and is released with the thrown error.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms MemFSError maps a code with one constant switch and chooses no processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work MemFSError is an error value and coordinates no shared or repeated computation.
  */
 export declare class MemFSError extends Error {
+    /** POSIX symbolic error, consumed by the Go bridge. */
     code: string;
+    /** Negative Linux-style errno for the virtual filesystem ABI. */
     errno: number;
+    /** Normalized virtual path, when the failing operation identifies one. */
     path?: string;
+    /** Filesystem operation that produced the error. */
     syscall?: string;
     constructor(code: string, syscall: string, path?: string);
 }

package/lib/src/MemFSError.js

@@ -6,13 +6,32 @@ exports.MemFSError = void 0;
  *
  * Matches the shape of `NodeJS.ErrnoException` so Go's `os` package interprets
  * it as a proper `os.PathError` with a numeric error code. Thrown by the MemFS
- * implementation when a callback would otherwise pass `null` for an impossible
- * filesystem operation (missing path, type mismatch, …).
+ * implementation for rejected virtual filesystem operations.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   Error fields follow NodeJS.ErrnoException and Go's js/wasm filesystem bridge;
+ *   numeric errno values describe that virtual ABI, not the browser host OS.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   The Error subclass groups the bridge's machine fields with its message;
+ *   one private mapping owns errno translation for every virtual operation.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   POSIX error identifiers are protocol constants; failed operations remain
+ *   errors instead of returning a fake successful callback value.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Native JSDoc explains the bridge and members' machine-readable roles,
+ *   following the documentation skill's concrete context guidance.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources MemFSError retains only its own fields and is released with the thrown error.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms MemFSError maps a code with one constant switch and chooses no processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work MemFSError is an error value and coordinates no shared or repeated computation.
  */
 class MemFSError extends Error {
+    /** POSIX symbolic error, consumed by the Go bridge. */
     code;
+    /** Negative Linux-style errno for the virtual filesystem ABI. */
     errno;
+    /** Normalized virtual path, when the failing operation identifies one. */
     path;
+    /** Filesystem operation that produced the error. */
     syscall;
     constructor(code, syscall, path) {
         super(`${code}: ${syscall} ${path ?? ""}`.trim());
@@ -40,8 +59,12 @@ function errnoForCode(code) {
             return -21;
         case "EINVAL":
             return -22;
+        case "EFBIG":
+            return -27;
         case "ESPIPE":
             return -29;
+        case "EPIPE":
+            return -32;
         case "ENOTEMPTY":
             return -39;
         default:

package/lib/src/MemFSError.js.map

@@ -1 +1 @@
-{"version":3,"file":"MemFSError.js","sourceRoot":"","sources":["../../src/MemFSError.ts"],"names":[],"mappings":";;;AAAA;;;;;;;GAOG;AACH,gBAAwB,SAAQ,KAAK;IAC5B,IAAI,CAAS;IACb,KAAK,CAAS;IACd,IAAI,CAAU;IACd,OAAO,CAAU;IACxB,YAAY,IAAY,EAAE,OAAe,EAAE,IAAa;QACtD,KAAK,CAAC,GAAG,IAAI,KAAK,OAAO,IAAI,IAAI,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC;QAClD,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,KAAK,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;QAChC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;CACF;;AAED,kFAAkF;AAClF,SAAS,YAAY,CAAC,IAAY;IAChC,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,QAAQ;YACX,OAAO,CAAC,CAAC,CAAC;QACZ,KAAK,OAAO;YACV,OAAO,CAAC,CAAC,CAAC;QACZ,KAAK,OAAO;YACV,OAAO,CAAC,EAAE,CAAC;QACb,KAAK,QAAQ;YACX,OAAO,CAAC,EAAE,CAAC;QACb,KAAK,SAAS;YACZ,OAAO,CAAC,EAAE,CAAC;QACb,KAAK,QAAQ;YACX,OAAO,CAAC,EAAE,CAAC;QACb,KAAK,QAAQ;YACX,OAAO,CAAC,EAAE,CAAC;QACb,KAAK,QAAQ;YACX,OAAO,CAAC,EAAE,CAAC;QACb,KAAK,WAAW;YACd,OAAO,CAAC,EAAE,CAAC;QACb;YACE,OAAO,CAAC,CAAC,CAAC;IACd,CAAC;AACH,CAAC"}
+{"version":3,"file":"MemFSError.js","sourceRoot":"","sources":["../../src/MemFSError.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,gBAAwB,SAAQ,KAAK;IACnC,uDAAuD;IAChD,IAAI,CAAS;IAEpB,iEAAiE;IAC1D,KAAK,CAAS;IAErB,0EAA0E;IACnE,IAAI,CAAU;IAErB,oDAAoD;IAC7C,OAAO,CAAU;IAExB,YAAY,IAAY,EAAE,OAAe,EAAE,IAAa;QACtD,KAAK,CAAC,GAAG,IAAI,KAAK,OAAO,IAAI,IAAI,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC;QAClD,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,KAAK,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;QAChC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;CACF;;AAED,kFAAkF;AAClF,SAAS,YAAY,CAAC,IAAY;IAChC,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,QAAQ;YACX,OAAO,CAAC,CAAC,CAAC;QACZ,KAAK,OAAO;YACV,OAAO,CAAC,CAAC,CAAC;QACZ,KAAK,OAAO;YACV,OAAO,CAAC,EAAE,CAAC;QACb,KAAK,QAAQ;YACX,OAAO,CAAC,EAAE,CAAC;QACb,KAAK,SAAS;YACZ,OAAO,CAAC,EAAE,CAAC;QACb,KAAK,QAAQ;YACX,OAAO,CAAC,EAAE,CAAC;QACb,KAAK,QAAQ;YACX,OAAO,CAAC,EAAE,CAAC;QACb,KAAK,OAAO;YACV,OAAO,CAAC,EAAE,CAAC;QACb,KAAK,QAAQ;YACX,OAAO,CAAC,EAAE,CAAC;QACb,KAAK,OAAO;YACV,OAAO,CAAC,EAAE,CAAC;QACb,KAAK,WAAW;YACd,OAAO,CAAC,EAAE,CAAC;QACb;YACE,OAAO,CAAC,CAAC,CAAC;IACd,CAAC;AACH,CAAC"}

package/lib/src/bootTtsc.d.ts

@@ -12,12 +12,59 @@ import type { IBootTtscOptions } from "./structures/IBootTtscOptions";
  * stop the old runtime; replace the Worker before retrying.
  *
  * **Single-Worker caveat.** Even with the chain, a second boot loaded into the
- * SAME Worker after a first boot completes will overlay its Go runtime on top
- * of the first — `importScripts(wasmExecUrl)` rebinds `globalThis.Go`, and the
+ * same Worker after a first boot completes will overlay its Go runtime on top
+ * of the first. `importScripts(wasmExecUrl)` rebinds `globalThis.Go`, and the
  * first wasm's keepalive goroutine keeps running through the new runtime's
  * js-bridge tables. The serialization is sufficient for the typical use case
  * (one boot per Worker over the page's lifetime) but DOES NOT make a Worker
  * safe to host two wasm instances at once. Create a fresh Worker per concurrent
  * wasm.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   The documented Go wasm_exec bridge is installed before streaming
+ *   instantiation, and Promise sharing coordinates calls that use its global
+ *   readiness slot. This follows the host.Expose integration rather than
+ *   inventing a second runtime protocol.
+ *
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   The entry owns one attempt's host and cancellation, the per-API chain owns
+ *   readiness-slot serialization, and bootTtscOnce owns setup and cleanup.
+ *   These separate identities are needed because duplicate calls may join,
+ *   distinct binary URLs may queue, and a started runtime cannot be retried.
+ *
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   The ttsc default API name and Ready/Failed slots are the host protocol,
+ *   not consumer or fixture matches. The attempt installs missing Go host
+ *   shims and removes only its own failed installation; it does not replace an
+ *   existing foreign filesystem. The documented one-runtime-per-Worker
+ *   limitation is retained rather than hidden beneath retries after go.run.
+ *
+ * @evidence contracts/common.md#meaningful-documentation
+ *   JSDoc explains why same-URL calls share a boot, why API-slot serialization
+ *   is needed and why post-start failure requires Worker replacement. Separate
+ *   paragraphs state purpose and the shared-runtime caveat under the
+ *   documentation skill; option and result interfaces document cancellation
+ *   and host ownership.
+ *
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Cache lookup uses normalized URL length U and expected constant-time Map
+ *   access; fetch/streaming compilation process the B binary bytes without a
+ *   second JavaScript binary buffer. C joined callers add O(C) abort listeners,
+ *   and cancellation uses events rather than a polling scan.
+ *
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   One API/normalized-URL pair shares fetch and instantiation only with the same
+ *   runtime-script URL and an identical supplied host. Omitted hosts reuse the
+ *   entry's actual host. Per-API Promise
+ *   chains serialize access to the global readiness slot; distinct URLs are
+ *   distinct boot identities. The URL must identify immutable binary content
+ *   for successful-result reuse to remain valid within the Worker lifetime.
+ *
+ * @evidence contracts/performance.md#bound-retention-and-release-resources
+ *   Each entry owns its controller, host and result; settlement removes joined
+ *   caller listeners and internal cancellation listeners. Successful boot keys,
+ *   API chain heads and terminal failures remain until Worker termination, with
+ *   no fixed key or retained-byte bound. Failed pre-start entries are removed;
+ *   started runtimes cannot be stopped here and require Worker replacement.
  */
 export declare function bootTtsc(options: IBootTtscOptions): Promise<IBootResult>;