PlatformCapabilities

Defined in: packages/runtime/src/platform/types.ts:133

Platform primitives the kernel cannot implement itself.

Role

Consumed — the kernel, pkg evaluator, and httpFS call into these via factory-injected closures. Implement one per host (Node / browser / test) by using createNodeCapabilities, createBrowserCapabilities, or createTestCapabilities.

Remarks

Processes never see PlatformCapabilities directly. The bag is passed once to the runtime at construction time and flows through closures into the subsystems that need it — loadAsset for WASM/asset resolution, importEsm for package evaluation (pkg bin), fetch for httpFS, compileWasm for WASI/Emscripten bin factories. This keeps the kernel host-agnostic.

Invariant

All methods are async and MUST NOT throw synchronously — any failure is a rejected promise. The kernel does not wrap calls in try/catch.

Invariant

Implementations MUST be pure with respect to the kernel — no hidden global state that survives across runtime instances; a test that creates two runtimes with different capability stubs must see them isolated.

Caveat

Capability failures surface as bin-level errors (e.g. a failed pkg install rejects because importEsm rejected). There is no global capability-error handler.

Example

import type { PlatformCapabilities } from '@fishnet/runtime'

// Minimal in-memory stub, e.g. for a deterministic test harness.
const caps: PlatformCapabilities = {
  async loadAsset()   { throw new Error('no assets') },
  async importEsm()   { throw new Error('no esm') },
  async fetch()       { throw new Error('no fetch') },
  async compileWasm(binary) {
    return (globalThis as { WebAssembly: { compile(b: Uint8Array): Promise<WebAssembly.Module> } })
      .WebAssembly.compile(binary)
  },
}

See

• createNodeCapabilities
• createBrowserCapabilities
• createTestCapabilities
• Runtime

Methods

compileWasm()

compileWasm(binary): Promise<WasmModule>

Defined in: packages/runtime/src/platform/types.ts:205

Compile WASM bytes into a WebAssembly.Module.

Parameters

binary

Uint8Array

Raw WASM bytes. Ownership is transferred-in — the implementation may read but MUST NOT retain after return.

Returns

Promise<WasmModule>

A structurally-branded WasmModule. The real type is WebAssembly.Module; the brand exists only so this .ts file does not require the WebAssembly ambient lib.

Invariant

Resolves to a fresh module every call — no deduping at the capability layer; createWasmBin / createWasiBin cache modules by source URL one level up.

Invariant

Rejects with a WebAssembly.CompileError on malformed bytes.

---

fetch()

fetch(url, init?): Promise<FetchResponse>

Defined in: packages/runtime/src/platform/types.ts:189

HTTP fetch — a minimal structural subset of WHATWG fetch.

Parameters

url

string

Absolute URL. No relative-URL base resolution.

init?

FetchInit

Optional request init. See FetchInit.

Returns

Promise<FetchResponse>

A FetchResponse. Network errors reject; HTTP-level errors (404, 500) resolve with ok: false.

Invariant

Conforms to the structural FetchResponse contract — specifically, text() / arrayBuffer() / json() may each only be called once on a response (single-shot bodies).

Invariant

Cross-origin / CORS concerns are the host’s problem — this capability does not add preflight, redirect, or cookie handling beyond what the platform’s fetch does.

---

importEsm()

importEsm(source): Promise<unknown>

Defined in: packages/runtime/src/platform/types.ts:172

Evaluate ESM source text and return the resulting module namespace.

Parameters

source

string

Self-contained ESM source text. Treated as one module; import specifiers MUST be either absolute URLs or already-bundled (no bare specifier resolution happens here).

Returns

Promise<unknown>

The module namespace object. Callers unwrap .default when the contract expects a default export.

Invariant

Must neutralize or substitute import.meta.url — the canonical implementations (Node data-URI, browser blob-URL) both rewrite it so Emscripten glue that calls createRequire(import.meta.url) receives a usable base path rather than the data/blob URL itself.

Invariant

Each call produces a fresh module — no memoization at the capability layer; the pkg evaluator handles caching.

Caveat

In browsers, this typically requires a CSP that permits blob: script sources; in Node it requires --experimental-vm-modules off (default) since it uses dynamic import(dataUri).

---

loadAsset()

loadAsset(url, relativeTo?): Promise<Uint8Array<ArrayBufferLike>>

Defined in: packages/runtime/src/platform/types.ts:150

Fetch a binary asset (WASM blob, glue file) from a URL or filesystem path.

Parameters

url

string

Absolute URL (file://, https://), an absolute filesystem path, or a relative path resolved against relativeTo.

relativeTo?

string

Optional base URL / path. On Node this is typically an import.meta.url; on browsers, a document/base URL.

Returns

Promise<Uint8Array<ArrayBufferLike>>

The raw bytes. The returned Uint8Array is caller-owned — the implementation MUST NOT retain or mutate the buffer after return.

Invariant

Resolves to a fresh Uint8Array on every call (callers may mutate in place) — no shared-buffer aliasing across calls.

Invariant

Rejects with a platform-specific error when the asset is missing or unreadable. Do not return an empty Uint8Array to signal not-found.