@rybosome/tspice 0.0.3 → 0.0.8

package/backend-wasm/dist/runtime/create-backend.node.js

@@ -1,20 +1,157 @@
 import { assertEmscriptenModule } from "../lowlevel/exports.js";
 import { createCoordsVectorsApi } from "../domains/coords-vectors.js";
+import { createCellsWindowsApi } from "../domains/cells-windows.js";
 import { createEphemerisApi } from "../domains/ephemeris.js";
 import { createFramesApi } from "../domains/frames.js";
 import { createGeometryApi } from "../domains/geometry.js";
+import { createGeometryGfApi } from "../domains/geometry-gf.js";
 import { createIdsNamesApi } from "../domains/ids-names.js";
 import { createKernelsApi } from "../domains/kernels.js";
+import { createKernelPoolApi } from "../domains/kernel-pool.js";
 import { createTimeApi, getToolkitVersion } from "../domains/time.js";
+import { createFileIoApi } from "../domains/file-io.js";
+import { createErrorApi } from "../domains/error.js";
+import { createDskApi } from "../domains/dsk.js";
+import { createEkApi } from "../domains/ek.js";
 import { createWasmFs } from "./fs.js";
+import { createSpiceHandleRegistry } from "./spice-handles.js";
+import { createVirtualOutputRegistry } from "./virtual-outputs.js";
 export const WASM_JS_FILENAME = "tspice_backend_wasm.node.js";
 export const WASM_BINARY_FILENAME = "tspice_backend_wasm.wasm";
+// Cache wasm binaries by URL to avoid repeated (sometimes flaky) disk reads.
+//
+// This cache MUST be bounded: in long-lived processes that construct backends
+// dynamically (or accept user-provided URLs), an unbounded cache would retain
+// bytes indefinitely.
+const WASM_BINARY_CACHE_MAX_ENTRIES = 2;
+const wasmBinaryCache = new Map();
+function boundedCacheGet(key) {
+    const hit = wasmBinaryCache.get(key);
+    if (!hit)
+        return undefined;
+    // Refresh recency (Map preserves insertion order).
+    wasmBinaryCache.delete(key);
+    wasmBinaryCache.set(key, hit);
+    return hit;
+}
+function boundedCacheSet(key, value) {
+    // Refresh recency on overwrite (Map preserves insertion order).
+    wasmBinaryCache.delete(key);
+    wasmBinaryCache.set(key, value);
+    while (wasmBinaryCache.size > WASM_BINARY_CACHE_MAX_ENTRIES) {
+        const lruKey = wasmBinaryCache.keys().next().value;
+        if (!lruKey)
+            break;
+        wasmBinaryCache.delete(lruKey);
+    }
+}
+/**
+ * Convert a Uint8Array view into an exact-length ArrayBuffer (copying only when needed).
+ */
+export function toExactArrayBuffer(bytes) {
+    // Fast-path: if this view covers the whole underlying buffer, return it
+    // directly (no copy).
+    // NOTE: `Uint8Array#buffer` is typed as `ArrayBufferLike` (can be
+    // `SharedArrayBuffer`). We only want to return an actual `ArrayBuffer`.
+    if (bytes.buffer instanceof ArrayBuffer &&
+        bytes.byteOffset === 0 &&
+        bytes.byteLength === bytes.buffer.byteLength) {
+        return bytes.buffer;
+    }
+    // Node Buffers can be views into a larger ArrayBuffer (and can be offset).
+    // Passing `bytes.buffer` directly can include unrelated trailing bytes, and
+    // getting `ArrayBuffer#slice` bounds wrong can truncate the module.
+    //
+    // Copy into a fresh, exact-length ArrayBuffer starting at 0.
+    const uint8 = new Uint8Array(bytes.byteLength);
+    uint8.set(bytes);
+    return uint8.buffer;
+}
+/** Read the tspice backend WASM binary from disk (Node-only). */
+export async function readWasmBinaryForNode(wasmUrl) {
+    // Allow http(s) URLs to be fetched by Emscripten.
+    if (wasmUrl.startsWith("http://") || wasmUrl.startsWith("https://")) {
+        return undefined;
+    }
+    const WINDOWS_DRIVE_PATH_RE = /^[A-Za-z]:[\\/]/;
+    const URL_SCHEME_WITH_AUTHORITY_RE = /^[A-Za-z][A-Za-z\d+.-]*:\/\//;
+    const SINGLE_LETTER_SCHEME_RE = /^[A-Za-z]:/;
+    const [{ readFile }, { fileURLToPath }] = await Promise.all([
+        import("node:fs/promises"),
+        import("node:url"),
+    ]);
+    // In Node, treat values as filesystem paths unless they are unambiguously a
+    // URL (file://, or any other scheme://...) or a known non-fs scheme like
+    // data: or blob:.
+    const isWindowsDrivePath = WINDOWS_DRIVE_PATH_RE.test(wasmUrl);
+    const isFileUrl = wasmUrl.startsWith("file://");
+    if (!isWindowsDrivePath && !isFileUrl) {
+        if (wasmUrl.startsWith("node:")) {
+            const u = new URL(wasmUrl);
+            throw new Error(`Unsupported wasmUrl scheme '${u.protocol}'. Expected http(s) URL, file:// URL, or a filesystem path.`);
+        }
+        if (wasmUrl.startsWith("blob:") || wasmUrl.startsWith("data:")) {
+            const u = new URL(wasmUrl);
+            throw new Error(`Unsupported wasmUrl scheme '${u.protocol}'. Expected http(s) URL, file:// URL, or a filesystem path.`);
+        }
+        if (URL_SCHEME_WITH_AUTHORITY_RE.test(wasmUrl)) {
+            const u = new URL(wasmUrl);
+            if (u.protocol !== "http:" && u.protocol !== "https:" && u.protocol !== "file:") {
+                throw new Error(`Unsupported wasmUrl scheme '${u.protocol}'. Expected http(s) URL, file:// URL, or a filesystem path.`);
+            }
+        }
+        // Avoid treating `c:foo` as a Windows drive path; it's ambiguous and often a typo.
+        // But allow longer values like `foo:bar/...` to be treated as filesystem paths.
+        if (SINGLE_LETTER_SCHEME_RE.test(wasmUrl)) {
+            const u = new URL(wasmUrl);
+            throw new Error(`Unsupported wasmUrl scheme '${u.protocol}'. Expected http(s) URL, file:// URL, or a filesystem path.`);
+        }
+    }
+    const wasmPath = wasmUrl.startsWith("file://") ? fileURLToPath(wasmUrl) : wasmUrl;
+    const cached = boundedCacheGet(wasmPath);
+    if (cached) {
+        return cached;
+    }
+    const bytes = await readFile(wasmPath);
+    const buffer = toExactArrayBuffer(bytes);
+    boundedCacheSet(wasmPath, buffer);
+    return buffer;
+}
+/** Create a {@link SpiceBackend} implementation backed by WASM (Node runtime). */
 export async function createWasmBackend(options = {}) {
     // NOTE: Keep this as a literal string so bundlers (Vite) don't generate a
     // runtime glob map for *every* file in this directory (including *.d.ts.map),
     // which can lead to JSON being imported as an ESM module.
-    const defaultWasmUrl = new URL("../tspice_backend_wasm.wasm", import.meta.url);
-    const wasmUrl = options.wasmUrl?.toString() ?? defaultWasmUrl.href;
+    const wasmUrl = options.wasmUrl?.toString() ?? new URL("../tspice_backend_wasm.wasm", import.meta.url).href;
+    const WINDOWS_DRIVE_PATH_RE = /^[A-Za-z]:[\\/]/;
+    const URL_SCHEME_WITH_AUTHORITY_RE = /^[A-Za-z][A-Za-z\d+.-]*:\/\//;
+    const SINGLE_LETTER_SCHEME_RE = /^[A-Za-z]:/;
+    const isWindowsDrivePath = (value) => WINDOWS_DRIVE_PATH_RE.test(value);
+    const isAllowedNodeUrl = (value) => value.startsWith("http://") || value.startsWith("https://") || value.startsWith("file://");
+    const throwUnsupportedScheme = (u) => {
+        throw new Error(`Unsupported wasmUrl scheme '${u.protocol}'. Expected http(s) URL, file:// URL, or a filesystem path.`);
+    };
+    // In Node, treat values as filesystem paths unless they are unambiguously a
+    // URL (http(s)://, file://, or any other scheme://...) or a known non-fs
+    // scheme like data: or blob:.
+    if (!isWindowsDrivePath(wasmUrl) && !isAllowedNodeUrl(wasmUrl)) {
+        if (wasmUrl.startsWith("node:")) {
+            throwUnsupportedScheme(new URL(wasmUrl));
+        }
+        if (wasmUrl.startsWith("blob:") || wasmUrl.startsWith("data:")) {
+            throwUnsupportedScheme(new URL(wasmUrl));
+        }
+        if (URL_SCHEME_WITH_AUTHORITY_RE.test(wasmUrl)) {
+            const u = new URL(wasmUrl);
+            if (u.protocol !== "http:" && u.protocol !== "https:" && u.protocol !== "file:") {
+                throwUnsupportedScheme(u);
+            }
+        }
+        // Avoid treating `c:foo` as a Windows drive path; it's ambiguous and often a typo.
+        if (SINGLE_LETTER_SCHEME_RE.test(wasmUrl)) {
+            throwUnsupportedScheme(new URL(wasmUrl));
+        }
+    }
     let createEmscriptenModule;
     try {
         // NOTE: This must be a literal import path so bundlers like Vite don't
@@ -26,18 +163,138 @@ export async function createWasmBackend(options = {}) {
         throw new Error(`Failed to load tspice WASM glue (../${WASM_JS_FILENAME}): ${String(error)}`);
     }
     const wasmLocator = wasmUrl;
-    // Node's built-in `fetch` can't load `file://...` URLs, so in Node we feed the
-    // bytes directly to Emscripten via `wasmBinary`.
-    const wasmBinary = wasmUrl.startsWith("file://")
-        ? await (async () => {
-            const [{ readFile }, { fileURLToPath }] = await Promise.all([
+    // In Node, avoid Emscripten's fetch/instantiateStreaming path for:
+    // - `file://...` URLs (Node's built-in `fetch` can't load them)
+    // - plain filesystem paths when `fetch` exists
+    // Instead, feed the bytes directly to Emscripten via `wasmBinary`.
+    let wasmBinary;
+    if (wasmUrl.startsWith("file://")) {
+        wasmBinary = await (async () => {
+            const [{ readFileSync, statSync }, { writeFile, rename }, { fileURLToPath }] = await Promise.all([
+                import("node:fs"),
                 import("node:fs/promises"),
                 import("node:url"),
             ]);
+            const usingDefaultWasmUrl = options.wasmUrl == null;
             const wasmPath = fileURLToPath(wasmUrl);
-            return readFile(wasmPath);
-        })()
-        : undefined;
+            // `WebAssembly` is available in Node, but TypeScript only types it when the DOM
+            // lib is enabled. Define a minimal type so we can use `validate()` without pulling
+            // in browser-only lib typings.
+            const wasmApi = globalThis.WebAssembly;
+            const assertMagicHeader = (bytes, path, urlForMessage) => {
+                // Validate WASM magic header: 0x00 0x61 0x73 0x6d ("\0asm")
+                if (bytes.length < 4 ||
+                    bytes[0] !== 0x00 ||
+                    bytes[1] !== 0x61 ||
+                    bytes[2] !== 0x73 ||
+                    bytes[3] !== 0x6d) {
+                    const prefixBytes = bytes.slice(0, Math.min(8, bytes.length));
+                    const prefix = Array.from(prefixBytes)
+                        .map((b) => b.toString(16).padStart(2, "0"))
+                        .join(" ");
+                    throw new Error(`Invalid WASM magic header for ${path} (url=${urlForMessage}). ` +
+                        `Expected 00 61 73 6d ("\\0asm") but got ${prefix}${bytes.length > 8 ? " ..." : ""}.`);
+                }
+            };
+            const isValidWasm = (bytes) => {
+                // Fail fast on truncated/corrupt cache restores.
+                //
+                // If `validate()` is unavailable (or stubbed), assume valid and let
+                // instantiation fail with a real error.
+                if (!wasmApi?.validate) {
+                    return true;
+                }
+                return wasmApi.validate(bytes);
+            };
+            const readBytesWithSizeCheck = (path, urlForMessage) => {
+                const readWithSizeCheck = () => {
+                    const bytes = readFileSync(path);
+                    const statSize = statSync(path).size;
+                    return { bytes, statSize };
+                };
+                // On macOS + Node 22 we've occasionally observed truncated reads leading to
+                // `WebAssembly.instantiate(): section ... extends past end of the module`.
+                // Sync reads + a size sanity-check seems to avoid the issue.
+                let { bytes, statSize } = readWithSizeCheck();
+                if (bytes.length !== statSize) {
+                    const firstReadSize = bytes.length;
+                    const firstStatSize = statSize;
+                    ({ bytes, statSize } = readWithSizeCheck());
+                    if (bytes.length !== statSize) {
+                        throw new Error(`WASM binary read size mismatch for ${path} (url=${urlForMessage}): ` +
+                            `readFileSync().length=${bytes.length} (previous=${firstReadSize}) ` +
+                            `statSync().size=${statSize} (previous=${firstStatSize}). ` +
+                            `This may indicate a transient/inconsistent filesystem state.`);
+                    }
+                }
+                return bytes;
+            };
+            let lastValidationError;
+            async function readValidatedOrNull(path, urlForMessage) {
+                try {
+                    const bytes = readBytesWithSizeCheck(path, urlForMessage);
+                    assertMagicHeader(bytes, path, urlForMessage);
+                    if (!isValidWasm(bytes)) {
+                        throw new Error(`WebAssembly.validate() returned false for ${path} (url=${urlForMessage}).`);
+                    }
+                    return bytes;
+                }
+                catch (error) {
+                    lastValidationError = error;
+                    return null;
+                }
+            }
+            // If turbo restores `dist/**` from cache, downstream tasks can sometimes observe
+            // partially-written outputs. Validate the wasm bytes before loading.
+            const initial = await readValidatedOrNull(wasmPath, wasmUrl);
+            if (initial) {
+                return initial;
+            }
+            // Retry briefly in case another process is still writing/restoring the file.
+            for (const delayMs of [10, 25, 50, 100, 250]) {
+                await new Promise((resolve) => setTimeout(resolve, delayMs));
+                const retry = await readValidatedOrNull(wasmPath, wasmUrl);
+                if (retry) {
+                    return retry;
+                }
+            }
+            // If the dist wasm is still invalid, fall back to the checked-in Emscripten artifact
+            // when running from a workspace checkout.
+            if (usingDefaultWasmUrl) {
+                const fallbackUrl = new URL(`../../emscripten/${WASM_BINARY_FILENAME}`, import.meta.url);
+                const fallbackPath = fileURLToPath(fallbackUrl);
+                const fallback = await readValidatedOrNull(fallbackPath, fallbackUrl.href);
+                if (fallback) {
+                    if (options.repairInvalidDistWasm === true) {
+                        // Best-effort repair so subsequent loads see a valid file.
+                        try {
+                            const tmpPath = `${wasmPath}.tmp.${process.pid}.${Date.now()}`;
+                            await writeFile(tmpPath, fallback);
+                            await rename(tmpPath, wasmPath);
+                        }
+                        catch {
+                            // ignore
+                        }
+                    }
+                    return fallback;
+                }
+            }
+            const message = `Invalid/partial WASM binary at ${wasmPath}. ` +
+                `Try rerunning backend-wasm build (pnpm -C packages/backend-wasm build) ` +
+                `or ensure turbo cache outputs are fully restored before tests run.`;
+            throw lastValidationError != null
+                ? new Error(message, { cause: lastValidationError })
+                : new Error(message);
+        })();
+    }
+    else {
+        try {
+            wasmBinary = await readWasmBinaryForNode(wasmUrl);
+        }
+        catch (error) {
+            throw new Error(`Failed to read tspice WASM binary (wasmUrl=${wasmUrl}): ${String(error)}`);
+        }
+    }
     let module;
     try {
         module = (await createEmscriptenModule({
@@ -53,21 +310,33 @@ export async function createWasmBackend(options = {}) {
     catch (error) {
         throw new Error(`Failed to initialize tspice WASM module (wasmUrl=${wasmUrl}): ${String(error)}`);
     }
-    assertEmscriptenModule(module);
+    const skipAssertViaEnv = process.env.TSPICE_WASM_SKIP_EMSCRIPTEN_ASSERT === "1" ||
+        process.env.TSPICE_WASM_SKIP_EMSCRIPTEN_ASSERT === "true";
+    const validateEmscriptenModule = options.validateEmscriptenModule ?? !skipAssertViaEnv;
+    if (validateEmscriptenModule) {
+        assertEmscriptenModule(module);
+    }
     // The toolkit version is constant for the lifetime of a loaded module.
     const toolkitVersion = getToolkitVersion(module);
     const fsApi = createWasmFs(module);
+    const spiceHandles = createSpiceHandleRegistry();
+    const virtualOutputs = createVirtualOutputRegistry();
     const backend = {
         kind: "wasm",
         ...createTimeApi(module, toolkitVersion),
         ...createKernelsApi(module, fsApi),
+        ...createKernelPoolApi(module),
         ...createIdsNamesApi(module),
         ...createFramesApi(module),
-        ...createEphemerisApi(module),
+        ...createEphemerisApi(module, spiceHandles, virtualOutputs),
         ...createGeometryApi(module),
+        ...createGeometryGfApi(module),
         ...createCoordsVectorsApi(module),
-        // WASM-only
-        ...fsApi,
+        ...createFileIoApi(module, spiceHandles, virtualOutputs),
+        ...createErrorApi(module),
+        ...createCellsWindowsApi(module),
+        ...createEkApi(module, spiceHandles),
+        ...createDskApi(module, spiceHandles),
     };
     return backend;
 }

package/backend-wasm/dist/runtime/create-backend.web.d.ts

@@ -1,7 +1,10 @@
-import type { SpiceBackendWasm } from "#backend-contract";
+import type { SpiceBackend } from "#backend-contract";
 export type { CreateWasmBackendOptions } from "./create-backend-options.js";
 import type { CreateWasmBackendOptions } from "./create-backend-options.js";
 export declare const WASM_JS_FILENAME: "tspice_backend_wasm.web.js";
 export declare const WASM_BINARY_FILENAME: "tspice_backend_wasm.wasm";
-export declare function createWasmBackend(options?: CreateWasmBackendOptions): Promise<SpiceBackendWasm>;
+/** Create a {@link SpiceBackend} implementation backed by WASM (web/runtime loader). */
+export declare function createWasmBackend(options?: CreateWasmBackendOptions): Promise<SpiceBackend & {
+    kind: "wasm";
+}>;
 //# sourceMappingURL=create-backend.web.d.ts.map

package/backend-wasm/dist/runtime/create-backend.web.js

@@ -1,20 +1,44 @@
 import { assertEmscriptenModule } from "../lowlevel/exports.js";
 import { createCoordsVectorsApi } from "../domains/coords-vectors.js";
+import { createCellsWindowsApi } from "../domains/cells-windows.js";
 import { createEphemerisApi } from "../domains/ephemeris.js";
 import { createFramesApi } from "../domains/frames.js";
 import { createGeometryApi } from "../domains/geometry.js";
+import { createGeometryGfApi } from "../domains/geometry-gf.js";
 import { createIdsNamesApi } from "../domains/ids-names.js";
 import { createKernelsApi } from "../domains/kernels.js";
+import { createKernelPoolApi } from "../domains/kernel-pool.js";
 import { createTimeApi, getToolkitVersion } from "../domains/time.js";
+import { createFileIoApi } from "../domains/file-io.js";
+import { createErrorApi } from "../domains/error.js";
+import { createDskApi } from "../domains/dsk.js";
+import { createEkApi } from "../domains/ek.js";
 import { createWasmFs } from "./fs.js";
+import { createSpiceHandleRegistry } from "./spice-handles.js";
+import { createVirtualOutputRegistry } from "./virtual-outputs.js";
 export const WASM_JS_FILENAME = "tspice_backend_wasm.web.js";
 export const WASM_BINARY_FILENAME = "tspice_backend_wasm.wasm";
+/** Create a {@link SpiceBackend} implementation backed by WASM (web/runtime loader). */
 export async function createWasmBackend(options = {}) {
     // NOTE: Keep this as a literal string so bundlers (Vite) don't generate a
     // runtime glob map for *every* file in this directory (including *.d.ts.map),
     // which can lead to JSON being imported as an ESM module.
-    const defaultWasmUrl = new URL("../tspice_backend_wasm.wasm", import.meta.url);
-    const wasmUrl = options.wasmUrl?.toString() ?? defaultWasmUrl.href;
+    const wasmUrl = options.wasmUrl?.toString() ??
+        // NOTE: Inline blob workers set `options.wasmUrl` explicitly, since
+        // `import.meta.url` will be `blob:` for the worker entry module.
+        new URL("../tspice_backend_wasm.wasm", import.meta.url).href;
+    const URL_SCHEME_RE = /^[A-Za-z][A-Za-z\d+.-]*:/;
+    const WINDOWS_DRIVE_PATH_RE = /^[A-Za-z]:[\\/]/;
+    const hasUrlScheme = (value) => URL_SCHEME_RE.test(value) && !WINDOWS_DRIVE_PATH_RE.test(value);
+    if (hasUrlScheme(wasmUrl)) {
+        const u = new URL(wasmUrl);
+        // In web builds, `blob:` URLs are a real-world possibility (some bundlers and
+        // runtime loaders produce them). `data:` is also generally fetchable.
+        const allowedProtocols = new Set(["http:", "https:", "file:", "blob:", "data:"]);
+        if (!allowedProtocols.has(u.protocol)) {
+            throw new Error(`Unsupported wasmUrl scheme '${u.protocol}'. Expected http(s) URL, file:// URL, blob: URL, data: URL, or a filesystem path.`);
+        }
+    }
     let createEmscriptenModule;
     try {
         // NOTE: This must be a literal import path so bundlers like Vite don't
@@ -40,21 +64,31 @@ export async function createWasmBackend(options = {}) {
     catch (error) {
         throw new Error(`Failed to initialize tspice WASM module (wasmUrl=${wasmUrl}): ${String(error)}`);
     }
-    assertEmscriptenModule(module);
+    const validateEmscriptenModule = options.validateEmscriptenModule ?? true;
+    if (validateEmscriptenModule) {
+        assertEmscriptenModule(module);
+    }
     // The toolkit version is constant for the lifetime of a loaded module.
     const toolkitVersion = getToolkitVersion(module);
     const fsApi = createWasmFs(module);
+    const spiceHandles = createSpiceHandleRegistry();
+    const virtualOutputs = createVirtualOutputRegistry();
     const backend = {
         kind: "wasm",
         ...createTimeApi(module, toolkitVersion),
         ...createKernelsApi(module, fsApi),
+        ...createKernelPoolApi(module),
         ...createIdsNamesApi(module),
         ...createFramesApi(module),
-        ...createEphemerisApi(module),
+        ...createEphemerisApi(module, spiceHandles, virtualOutputs),
         ...createGeometryApi(module),
+        ...createGeometryGfApi(module),
         ...createCoordsVectorsApi(module),
-        // WASM-only
-        ...fsApi,
+        ...createFileIoApi(module, spiceHandles, virtualOutputs),
+        ...createErrorApi(module),
+        ...createCellsWindowsApi(module),
+        ...createEkApi(module, spiceHandles),
+        ...createDskApi(module, spiceHandles),
     };
     return backend;
 }

package/backend-wasm/dist/runtime/fs.d.ts

@@ -4,6 +4,12 @@ export type WasmFsApi = {
     writeFile(path: string, data: Uint8Array): void;
     loadKernel(path: string, data: Uint8Array): void;
 };
+/** Normalize and validate a virtual kernel path for the WASM FS (under `/kernels`). */
+export declare function resolveKernelPath(path: string): string;
+/** Create a minimal WASM-FS facade for writing files and loading kernels via `furnsh`. */
 export declare function createWasmFs(module: EmscriptenModule): WasmFsApi;
+/**
+ * Write a {@link KernelSource} into the WASM FS (if needed) and return the path to load.
+ */
 export declare function writeKernelSource(module: EmscriptenModule, fs: WasmFsApi, kernel: KernelSource): string;
 //# sourceMappingURL=fs.d.ts.map

package/backend-wasm/dist/runtime/fs.js

@@ -1,4 +1,26 @@
+import { normalizeVirtualKernelPath } from "#core";
 import { tspiceCall1Path } from "../codec/calls.js";
+/** Normalize and validate a virtual kernel path for the WASM FS (under `/kernels`). */
+export function resolveKernelPath(path) {
+    const raw = path.trim();
+    if (!raw) {
+        throw new Error("Kernel path must be non-empty");
+    }
+    // Fail fast for common non-virtual path forms. This improves debuggability for
+    // consumers who accidentally pass OS paths/URLs to the WASM backend.
+    //
+    // Note: `/kernels/...` is an allowed virtual path form.
+    if (/^[a-zA-Z]+:/.test(raw) || // urls, `file:`, Windows drive letters, etc.
+        raw.startsWith("//") ||
+        raw.startsWith("\\\\") ||
+        (raw.startsWith("/") && !raw.startsWith("/kernels/"))) {
+        throw new Error(`WASM kernel paths must be virtual ids (e.g. "naif0012.tls"), not OS paths/URLs: ${path}`);
+    }
+    // We treat kernel paths as *virtual* WASM-FS paths under `/kernels`.
+    // Normalize to a canonical absolute path.
+    return `/kernels/${normalizeVirtualKernelPath(raw)}`;
+}
+/** Create a minimal WASM-FS facade for writing files and loading kernels via `furnsh`. */
 export function createWasmFs(module) {
     function writeFile(path, data) {
         const dir = path.split("/").slice(0, -1).join("/") || "/";
@@ -14,17 +36,21 @@ export function createWasmFs(module) {
     return {
         writeFile,
         loadKernel: (path, data) => {
-            const resolvedPath = path.startsWith("/") ? path : `/kernels/${path}`;
+            const resolvedPath = resolveKernelPath(path);
             writeFile(resolvedPath, data);
             tspiceCall1Path(module, module._tspice_furnsh, resolvedPath);
         },
     };
 }
+/**
+ * Write a {@link KernelSource} into the WASM FS (if needed) and return the path to load.
+ */
 export function writeKernelSource(module, fs, kernel) {
     if (typeof kernel === "string") {
         return kernel;
     }
-    fs.writeFile(kernel.path, kernel.bytes);
-    return kernel.path;
+    const resolved = resolveKernelPath(kernel.path);
+    fs.writeFile(resolved, kernel.bytes);
+    return resolved;
 }
 //# sourceMappingURL=fs.js.map

package/backend-wasm/dist/runtime/spice-handles.d.ts

@@ -0,0 +1,3 @@
+export type { SpiceHandleEntry, SpiceHandleKind, SpiceHandleRegistry, } from "#backend-contract";
+export { createSpiceHandleRegistry } from "#backend-contract";
+//# sourceMappingURL=spice-handles.d.ts.map

package/backend-wasm/dist/runtime/spice-handles.js

@@ -0,0 +1,2 @@
+export { createSpiceHandleRegistry } from "#backend-contract";
+//# sourceMappingURL=spice-handles.js.map

package/backend-wasm/dist/runtime/virtual-outputs.d.ts

@@ -0,0 +1,16 @@
+export type VirtualOutputRegistry = {
+    /** Mark an output path as opened for write by a native handle. */
+    markOpen(resolvedPath: string): void;
+    /** Mark an output path as closed (writer handle closed). */
+    markClosed(resolvedPath: string): void;
+    /**
+     * Assert that a VirtualOutput is readable.
+     *
+     * This is used to ensure `readVirtualOutput()` does not become a generic
+     * filesystem read primitive.
+     */
+    assertReadable(resolvedPath: string, virtualPath: string): void;
+};
+/** Create an in-memory registry tracking open/closed virtual outputs for the WASM backend. */
+export declare function createVirtualOutputRegistry(): VirtualOutputRegistry;
+//# sourceMappingURL=virtual-outputs.d.ts.map

package/backend-wasm/dist/runtime/virtual-outputs.js

@@ -0,0 +1,35 @@
+/** Create an in-memory registry tracking open/closed virtual outputs for the WASM backend. */
+export function createVirtualOutputRegistry() {
+    const known = new Set();
+    const openRefCount = new Map();
+    return {
+        markOpen: (resolvedPath) => {
+            known.add(resolvedPath);
+            openRefCount.set(resolvedPath, (openRefCount.get(resolvedPath) ?? 0) + 1);
+        },
+        markClosed: (resolvedPath) => {
+            const next = (openRefCount.get(resolvedPath) ?? 0) - 1;
+            if (next <= 0) {
+                openRefCount.delete(resolvedPath);
+            }
+            else {
+                openRefCount.set(resolvedPath, next);
+            }
+            // Even if the counts get out of sync, preserve `known` so reads remain
+            // namespace-restricted to outputs created via writer APIs.
+            known.add(resolvedPath);
+        },
+        assertReadable: (resolvedPath, virtualPath) => {
+            if (!known.has(resolvedPath)) {
+                throw new Error(`readVirtualOutput(): VirtualOutput ${JSON.stringify(virtualPath)} is not a known virtual output for this backend instance. ` +
+                    "Only outputs created via writer APIs (e.g. spkopn(...VirtualOutput...)) can be read back.");
+            }
+            const open = openRefCount.get(resolvedPath) ?? 0;
+            if (open > 0) {
+                throw new Error(`readVirtualOutput(): VirtualOutput ${JSON.stringify(virtualPath)} is still open. ` +
+                    "Close the writer handle first (e.g. spkcls(handle)) before reading bytes.");
+            }
+        },
+    };
+}
+//# sourceMappingURL=virtual-outputs.js.map