@ttsc/wasm 0.30.3 → 0.31.0

package/src/MemFSError.ts

@@ -3,14 +3,37 @@
  *
  * 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 class MemFSError extends Error {
+  /** POSIX symbolic error, consumed by the Go bridge. */
   public code: string;
+
+  /** Negative Linux-style errno for the virtual filesystem ABI. */
   public errno: number;
+
+  /** Normalized virtual path, when the failing operation identifies one. */
   public path?: string;
+
+  /** Filesystem operation that produced the error. */
   public syscall?: string;
+
   constructor(code: string, syscall: string, path?: string) {
     super(`${code}: ${syscall} ${path ?? ""}`.trim());
     this.code = code;
@@ -37,8 +60,12 @@ function errnoForCode(code: string): number {
       return -21;
     case "EINVAL":
       return -22;
+    case "EFBIG":
+      return -27;
     case "ESPIPE":
       return -29;
+    case "EPIPE":
+      return -32;
     case "ENOTEMPTY":
       return -39;
     default:

package/src/bootTtsc.ts

@@ -16,16 +16,16 @@ import type { ITtscApi } from "./structures/ITtscApi";
 declare const importScripts: (...urls: string[]) => void;
 
 /**
- * Per-(apiName, wasmUrl) single-flight cache for boots. Keying on apiName alone
- * would let a second call with the same apiName but a different wasmUrl
- * silently return the cached IBootResult of the first wasm — the caller would
- * think they booted a fresh binary while the cached one stayed in place. The
- * composite key lets HMR / cache-busting query strings get a fresh boot while
- * still single-flighting genuine concurrent duplicate calls.
+ * One boot attempt shared by every caller that names the same API and binary.
+ * `controller` cancels the shared attempt, `host` is the filesystem its runtime
+ * binds, and `wasmExecUrl` is the runtime script it loaded; a joining caller
+ * must not name a different host or script.
  */
 interface BootInFlight {
   controller: AbortController;
   promise: Promise<IBootResult>;
+  host: IBootResult["host"];
+  wasmExecUrl: string;
 }
 
 interface BootCancellationReason {
@@ -33,6 +33,14 @@ interface BootCancellationReason {
   reason?: unknown;
 }
 
+/**
+ * Per-(apiName, wasmUrl) single-flight cache for boots. Keying on apiName alone
+ * would let a second call with the same apiName but a different wasmUrl
+ * silently return the cached IBootResult of the first wasm. The caller would
+ * think they booted a fresh binary while the cached one stayed in place. The
+ * composite key lets HMR / cache-busting query strings get a fresh boot while
+ * still single-flighting genuine concurrent duplicate calls.
+ */
 const bootsInFlight = new Map<string, BootInFlight>();
 
 /**
@@ -46,25 +54,23 @@ const terminalBootFailuresByApiName = new Map<
 >();
 
 /**
- * Per-apiName serialization chain. Two concurrent boots with the same apiName
- * but different wasmUrls each install their own `globalThis[apiName
- *
- * - "Ready"]`resolver — they would race and the second would overwrite the first,
- *   stranding the first boot's await. The chain serializes them so one boot's
- *   Go-side`Ready.Invoke()` always lands on the resolver that boot installed.
+ * Serialize boots sharing an API name because each installs the same
+ * `globalThis[apiName + "Ready"]` resolver. Serialization prevents a later
+ * attempt from overwriting the resolver before the earlier attempt settles.
  */
 const bootChainByApiName = new Map<string, Promise<unknown>>();
 
 function bootKey(apiName: string, wasmUrl: string): string {
-  return `${apiName}|${resolveWasmUrl(wasmUrl)}`;
+  return JSON.stringify([apiName, resolveWasmUrl(wasmUrl)]);
 }
 
 /**
- * Resolve `wasmUrl` against the current document base before keying so that
+ * Resolve `wasmUrl` against the current location before keying so that
  * `./playground.wasm`, `/compiler/playground.wasm`, and the fully qualified
  * absolute href all collapse to the same cache entry instead of spawning
- * duplicate boots. Falls back to the raw string when no base is available
- * (Node-side tests, non-DOM workers).
+ * duplicate boots. In environments without a location, such as Node-side tests,
+ * relative URLs use the synthetic `http://local/` base. If parsing fails, the
+ * input retains its original spelling.
  */
 function resolveWasmUrl(wasmUrl: string): string {
   try {
@@ -88,25 +94,94 @@ function resolveWasmUrl(wasmUrl: string): string {
  * 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 function bootTtsc(options: IBootTtscOptions): Promise<IBootResult> {
   const apiName = options.apiName ?? "ttsc";
-  const key = bootKey(apiName, options.wasmUrl);
+  let wasmUrl: string;
+  let wasmExecUrl: string;
+  try {
+    wasmUrl = resolveWasmUrl(options.wasmUrl);
+    wasmExecUrl = resolveWasmUrl(
+      options.wasmExecUrl ?? defaultWasmExecUrl(wasmUrl),
+    );
+  } catch (error) {
+    return Promise.reject(error);
+  }
+  const key = bootKey(apiName, wasmUrl);
   const terminalFailure = terminalBootFailuresByApiName.get(apiName);
   if (terminalFailure) return Promise.reject(terminalFailure);
   const inflight = bootsInFlight.get(key);
   if (inflight) {
+    if (
+      (options.host !== undefined && options.host !== inflight.host) ||
+      wasmExecUrl !== inflight.wasmExecUrl
+    ) {
+      return Promise.reject(
+        new Error(
+          `bootTtsc: ${apiName} is already bound to a different host or wasm_exec.js URL; use the original boot options or replace the Worker.`,
+        ),
+      );
+    }
     attachBootCancellation(inflight, options.signal);
     return inflight.promise;
   }
   const controller = new AbortController();
+  const host = options.host ?? createMemFS();
+  const bootOptions = { ...options, host, wasmUrl, wasmExecUrl };
   const prior = bootChainByApiName.get(apiName) ?? Promise.resolve();
   const queuedCancellation = createBootCancellationPromise(
     controller.signal,
@@ -125,7 +200,7 @@ export function bootTtsc(options: IBootTtscOptions): Promise<IBootResult> {
         "waiting for an earlier boot",
       );
       queuedCancellation.dispose();
-      return bootTtscOnce(options, apiName, controller.signal);
+      return bootTtscOnce(bootOptions, apiName, controller.signal);
     });
   let entry!: BootInFlight;
   const promise = Promise.race([queued, queuedCancellation.promise])
@@ -134,7 +209,7 @@ export function bootTtsc(options: IBootTtscOptions): Promise<IBootResult> {
       throw err;
     })
     .finally(queuedCancellation.dispose);
-  entry = { controller, promise };
+  entry = { controller, promise, host, wasmExecUrl };
   bootsInFlight.set(key, entry);
   attachBootCancellation(entry, options.signal);
   // Track the chain head for this apiName so the next boot waits on it.
@@ -195,6 +270,11 @@ async function bootTtscOnce(
   };
 
   try {
+    if (globalAny.fs !== host.fs) {
+      throw new Error(
+        "bootTtsc: globalThis.fs belongs to a different host; supply its original MemFS host or boot in a fresh Worker.",
+      );
+    }
     throwIfBootCanceled(signal, apiName, phase);
     // wasm_exec.js installs `globalThis.Go`. It also reads globalThis.fs at
     // module-eval time, so this import must follow the assignment above.
@@ -416,15 +496,11 @@ function bootCancellationError(
 }
 
 /**
- * Derive the `wasm_exec.js` URL from the wasm URL by replacing the filename.
- *
- * If `wasmUrl` has no directory component, returns `"wasm_exec.js"` (same
- * directory as the caller's base URL).
+ * Resolve the sibling runtime script using URL path semantics, dropping the
+ * binary's query and fragment so slashes in either cannot become directories.
  */
 function defaultWasmExecUrl(wasmUrl: string): string {
-  const slash = wasmUrl.lastIndexOf("/");
-  if (slash < 0) return "wasm_exec.js";
-  return wasmUrl.slice(0, slash + 1) + "wasm_exec.js";
+  return new URL("wasm_exec.js", resolveWasmUrl(wasmUrl)).href;
 }
 
 /**