space-data-module-sdk 0.8.6 → 0.8.7

package/src/host/providerAccessTileStoreAdapter.js

@@ -0,0 +1,366 @@
+/**
+ * WasmEdge satisfaction — a host-side tile store behind the same port.
+ *
+ * THE RULING. Under WasmEdge, native or in Docker, there is no engine. The
+ * server-side satisfaction of this port is a host-side TILE STORE, not a
+ * refusal and not an engine port. It serves the identical operations from
+ * sources the host can reach, and it does so using ONLY capabilities that
+ * already exist — `filesystem` for a local tileset directory, `http` for a
+ * remote tile service. It introduces no new generic hook, so it needs no owner
+ * sign-off and no new connector.
+ *
+ * The refusal case still exists and is still first-class: a host with no tile
+ * store configured registers no adapter, `provider.list` succeeds with an
+ * empty array, and `acquire` answers SDM_PROVIDER_E_NO_PROVIDER — the same
+ * code a browser gives for an unknown provider id, reachable and therefore
+ * testable in every lane.
+ *
+ * Node-side wiring of a specific curated source is CONFIGURATION of this
+ * adapter, never a change to the ABI.
+ */
+
+import {
+  PROVIDER_NO_DATA_F64,
+  ProviderAccessError,
+  ProviderCost,
+  ProviderEncoding,
+  ProviderError,
+  ProviderFlags,
+  normalizeRequestPositions,
+  resolveRequestLevel,
+} from "./providerAccessAbi.js";
+
+const TWO_PI = 6.283185307179586;
+const PI_OVER_TWO = 1.5707963267948966;
+
+/**
+ * A tile store is anything that can answer "give me the decoded elements of
+ * tile (level,x,y)". The transport is the caller's business — a preopened
+ * directory read through the `filesystem` capability, an HTTP tile service
+ * through the `http` capability, or an in-memory map.
+ *
+ *   readTile(level, x, y) -> { elements: TypedArray, width, height } | null
+ *
+ * Returning null means "not available" and becomes E_NOT_AVAILABLE. Throwing
+ * with `.code` set selects a specific ABI code; anything else becomes E_HOST
+ * with the detail on `provider.lastError`.
+ */
+export function createTileStoreTerrainProvider(options = {}) {
+  const store = options.store;
+  if (!store || typeof store.readTile !== "function") {
+    throw new TypeError(
+      "createTileStoreTerrainProvider requires a store with readTile(level, x, y).",
+    );
+  }
+  const id = options.id ?? "terrain.tilestore";
+  const tileWidth = options.tileWidth ?? 65;
+  const tileHeight = options.tileHeight ?? 65;
+  const maxLevel = options.maxLevel ?? 14;
+  const defaultLevel = options.defaultLevel ?? 9;
+  // A store that decodes on read costs REDECODE; one that memoizes decoded
+  // tiles costs RESIDENT. The store declares it; the adapter never guesses.
+  const costClass = options.costClass ?? ProviderCost.RESIDENT;
+
+  // Shared with every other adapter, so a spacing request resolves to the SAME
+  // level in the browser and on the host. Two adapters doing their own level
+  // arithmetic would sample different ground and lose byte parity for a reason
+  // no diff would show.
+  function resolveLevel(request) {
+    return resolveRequestLevel(request, {
+      tileWidth,
+      maxLevel,
+      minLevel: options.minLevel ?? 0,
+      defaultLevel,
+      mostDetailedLevel: options.mostDetailedLevel ?? maxLevel,
+    });
+  }
+
+  function loadTile(level, x, y) {
+    const tile = store.readTile(level, x, y);
+    return thenish(tile, (resolved) => {
+      if (!resolved) {
+        throw new ProviderAccessError(
+          ProviderError.NOT_AVAILABLE,
+          `Tile ${level}/${x}/${y} is not present in the store.`,
+          { providerId: id },
+        );
+      }
+      return resolved;
+    });
+  }
+
+  function sampleTile(tile, i, j) {
+    const width = tile.width ?? tileWidth;
+    return tile.elements[j * width + i];
+  }
+
+  return {
+    id,
+    kind: "terrain",
+    name: options.name ?? "Host tile store terrain",
+    ready: true,
+    minLevel: options.minLevel ?? 0,
+    maxLevel,
+    tileWidth,
+    tileHeight,
+    encoding: ProviderEncoding.HEIGHT_F32,
+    costClass,
+    credit: options.credit ?? "",
+    attributes: { surface: "tile-store" },
+
+    availability(params) {
+      if (typeof store.hasTile === "function") {
+        return store.hasTile(params.level, params.x, params.y);
+      }
+      return params.level <= maxLevel;
+    },
+
+    prefetch(params) {
+      // A tile store has no camera. It can genuinely prefetch, and says so.
+      if (typeof store.prefetch === "function") return store.prefetch(params);
+      return { requested: 0, pending: 0 };
+    },
+
+    awaitReady() {
+      return { ready: true, pending: 0 };
+    },
+
+    acquireTile(request) {
+      const { level, strategyCode } = resolveLevel(request);
+      const x = request.x | 0;
+      const y = request.y | 0;
+      return thenish(loadTile(level, x, y), (tile) => {
+        const elements =
+          tile.elements instanceof Float32Array
+            ? tile.elements
+            : Float32Array.from(tile.elements);
+        let min = Infinity;
+        let max = -Infinity;
+        for (const value of elements) {
+          if (value < min) min = value;
+          if (value > max) max = value;
+        }
+        return {
+          planes: [elements],
+          descriptor: {
+            encoding: ProviderEncoding.HEIGHT_F32,
+            width: tile.width ?? tileWidth,
+            height: tile.height ?? tileHeight,
+            level,
+            tileX: x,
+            tileY: y,
+            minValue: Number.isFinite(min) ? min : 0,
+            maxValue: Number.isFinite(max) ? max : 0,
+            costClass,
+            ...tileRectangle(level, x, y),
+          },
+        };
+      });
+    },
+
+    async acquireProfile(request) {
+      const { level, strategyCode } = resolveLevel(request);
+      const positions = interpolate(request);
+      const heights = new Float64Array(positions.length);
+      const cache = new Map();
+      let min = Infinity;
+      let max = -Infinity;
+      let partial = false;
+
+      for (let index = 0; index < positions.length; index += 1) {
+        const [lon, lat] = positions[index];
+        const sample = toTileSample(lon, lat, level, tileWidth, tileHeight);
+        const key = `${sample.tileX}/${sample.tileY}`;
+        if (!cache.has(key)) {
+          try {
+            cache.set(key, await loadTile(level, sample.tileX, sample.tileY));
+          } catch (error) {
+            if (error?.code !== ProviderError.NOT_AVAILABLE) throw error;
+            cache.set(key, null);
+          }
+        }
+        const tile = cache.get(key);
+        if (!tile) {
+          heights[index] = PROVIDER_NO_DATA_F64;
+          partial = true;
+          continue;
+        }
+        const value = sampleTile(tile, sample.i, sample.j);
+        heights[index] = value;
+        if (value < min) min = value;
+        if (value > max) max = value;
+      }
+
+      const first = positions[0];
+      const last = positions[positions.length - 1];
+      return {
+        planes: [heights],
+        descriptor: {
+          encoding: ProviderEncoding.HEIGHT_F64,
+          width: positions.length,
+          height: 1,
+          level,
+          minValue: Number.isFinite(min) ? min : 0,
+          maxValue: Number.isFinite(max) ? max : 0,
+          flags: partial ? ProviderFlags.PARTIAL : 0,
+          west: Math.min(first[0], last[0]),
+          east: Math.max(first[0], last[0]),
+          south: Math.min(first[1], last[1]),
+          north: Math.max(first[1], last[1]),
+          costClass,
+          strategy: strategyCode,
+        },
+      };
+    },
+
+    async acquireRegion(request) {
+      const { level, strategyCode } = resolveLevel(request);
+      const [west, south, east, north] = request.rectangle ?? [0, 0, 0, 0];
+      const width = Math.max(1, request.width | 0);
+      const height = Math.max(1, request.height | 0);
+      const values = new Float32Array(width * height);
+      const cache = new Map();
+      let min = Infinity;
+      let max = -Infinity;
+      let partial = false;
+
+      for (let row = 0; row < height; row += 1) {
+        const lat = north + ((south - north) * row) / height;
+        for (let column = 0; column < width; column += 1) {
+          const lon = west + ((east - west) * column) / width;
+          const sample = toTileSample(lon, lat, level, tileWidth, tileHeight);
+          const key = `${sample.tileX}/${sample.tileY}`;
+          if (!cache.has(key)) {
+            try {
+              cache.set(key, await loadTile(level, sample.tileX, sample.tileY));
+            } catch (error) {
+              if (error?.code !== ProviderError.NOT_AVAILABLE) throw error;
+              cache.set(key, null);
+            }
+          }
+          const tile = cache.get(key);
+          if (!tile) {
+            values[row * width + column] = -3.4028234663852886e38;
+            partial = true;
+            continue;
+          }
+          const value = sampleTile(tile, sample.i, sample.j);
+          values[row * width + column] = value;
+          if (value < min) min = value;
+          if (value > max) max = value;
+        }
+      }
+
+      return {
+        planes: [values],
+        descriptor: {
+          encoding: ProviderEncoding.HEIGHT_F32,
+          width,
+          height,
+          level,
+          minValue: Number.isFinite(min) ? min : 0,
+          maxValue: Number.isFinite(max) ? max : 0,
+          flags: partial ? ProviderFlags.PARTIAL : 0,
+          west,
+          south,
+          east,
+          north,
+          costClass,
+          strategy: strategyCode,
+        },
+      };
+    },
+  };
+}
+
+/**
+ * Tile store backed by the SDK host's `filesystem` capability.
+ *
+ * Uses only an existing generic hook. `decode(bytes, level, x, y)` is supplied
+ * by the caller because a tile format is not the ABI's business.
+ */
+export function createFilesystemTileStore(options = {}) {
+  const host = options.host;
+  const root = String(options.root ?? "").replace(/\/+$/, "");
+  const decode = options.decode;
+  const template = options.template ?? "{level}/{x}/{y}.bin";
+  if (!host?.filesystem) {
+    throw new TypeError(
+      "createFilesystemTileStore requires a host with the filesystem capability.",
+    );
+  }
+  if (typeof decode !== "function") {
+    throw new TypeError(
+      "createFilesystemTileStore requires decode(bytes, level, x, y).",
+    );
+  }
+
+  function pathFor(level, x, y) {
+    return `${root}/${template
+      .replace("{level}", String(level))
+      .replace("{x}", String(x))
+      .replace("{y}", String(y))}`;
+  }
+
+  return {
+    async readTile(level, x, y) {
+      try {
+        const bytes = await host.filesystem.readFile(pathFor(level, x, y));
+        if (!bytes) return null;
+        return decode(bytes, level, x, y);
+      } catch (error) {
+        if (
+          error?.code === "ENOENT" ||
+          /not found|no such file/i.test(error?.message ?? "")
+        ) {
+          return null;
+        }
+        throw error;
+      }
+    },
+  };
+}
+
+function thenish(value, onValue) {
+  return value !== null && typeof value?.then === "function"
+    ? value.then(onValue)
+    : onValue(value);
+}
+
+function tileRectangle(level, x, y) {
+  const tiles = 1 << level;
+  const width = TWO_PI / (tiles * 2);
+  const height = Math.PI / tiles;
+  const west = -Math.PI + x * width;
+  const north = PI_OVER_TWO - y * height;
+  return { west, south: north - height, east: west + width, north };
+}
+
+function toTileSample(lon, lat, level, tileWidth, tileHeight) {
+  const tiles = 1 << level;
+  const gx = ((lon + Math.PI) / TWO_PI) * tiles * 2;
+  const gy = ((PI_OVER_TWO - lat) / Math.PI) * tiles;
+  const tileX = Math.min(Math.max(Math.floor(gx), 0), tiles * 2 - 1);
+  const tileY = Math.min(Math.max(Math.floor(gy), 0), tiles - 1);
+  return {
+    tileX,
+    tileY,
+    i: Math.min(Math.max(Math.floor((gx - tileX) * tileWidth), 0), tileWidth - 1),
+    j: Math.min(Math.max(Math.floor((gy - tileY) * tileHeight), 0), tileHeight - 1),
+  };
+}
+
+function interpolate(request) {
+  const explicit = normalizeRequestPositions(request);
+  if (explicit) return explicit;
+  const [lon0, lat0] = request.start ?? [0, 0];
+  const [lon1, lat1] = request.end ?? [0, 0];
+  const samples = Math.max(2, request.samples | 0 || 2);
+  const positions = new Array(samples);
+  const last = samples - 1;
+  for (let index = 0; index < samples; index += 1) {
+    const t = index / last;
+    positions[index] = [lon0 + (lon1 - lon0) * t, lat0 + (lat1 - lat0) * t];
+  }
+  return positions;
+}

package/src/host/terrainSourceSeam.js

@@ -0,0 +1,205 @@
+/**
+ * Terrain source seam — the one interface a terrain consumer binds to.
+ *
+ * This exists so that the in-flight RF terrain solver does not ship a private
+ * terrain path. It is deliberately tiny and deliberately dual-shaped:
+ *
+ *   readHeights(positions, out)  the real entry — contiguous metres, one
+ *                                Float64Array, no per-sample JS object, no-data
+ *                                as the ABI sentinel rather than `undefined`
+ *
+ *   sampleCompat(provider, ps)   signature-compatible with the sampler the
+ *                                solver's injectable statics already hold, so
+ *                                the seam can be assigned on day one with no
+ *                                call-site change
+ *
+ * The cutover is therefore two recorded steps, not a rewrite: assign the seam
+ * now through the existing statics; move call sites to `readHeights` and make
+ * the source an explicit parameter when the engine port lands.
+ */
+
+import {
+  PROVIDER_NO_DATA_F64,
+  ProviderCost,
+  ProviderFlags,
+  decodeTileDescriptor,
+  isProviderNoData,
+  providerStrategyName,
+} from "./providerAccessAbi.js";
+
+const PROVIDER_FLAG_PARTIAL = ProviderFlags.PARTIAL;
+const PROVIDER_FLAG_INTERPOLATED = ProviderFlags.INTERPOLATED;
+
+export const TERRAIN_SOURCE_NO_DATA = PROVIDER_NO_DATA_F64;
+
+const REQUIRED_METHODS = Object.freeze([
+  "readHeights",
+  "readProfile",
+  "sampleCompat",
+]);
+const REQUIRED_FIELDS = Object.freeze(["id", "costClass"]);
+
+/**
+ * Prove at wiring time that whatever a consumer was handed is the real seam.
+ * A consumer that calls this cannot silently fall back to a private path,
+ * because a private path will not conform.
+ */
+export function assertTerrainSourceConformance(source, label = "terrain source") {
+  const problems = [];
+  if (!source || typeof source !== "object") {
+    throw new TypeError(`${label} must be an object implementing the terrain source seam.`);
+  }
+  for (const field of REQUIRED_FIELDS) {
+    if (source[field] === undefined || source[field] === null) {
+      problems.push(`missing field "${field}"`);
+    }
+  }
+  for (const method of REQUIRED_METHODS) {
+    if (typeof source[method] !== "function") {
+      problems.push(`missing method "${method}()"`);
+    }
+  }
+  if (problems.length > 0) {
+    throw new TypeError(
+      `${label} does not conform to the terrain source seam: ${problems.join(", ")}. ` +
+        "See docs/provider-access-abi.md#consumer-seam--terrain-source.",
+    );
+  }
+  return source;
+}
+
+/**
+ * Wrap a provider access port as a terrain source.
+ *
+ * `maxCost` is passed through unchanged: a consumer that wants only resident
+ * bytes leaves it at the default and gets a refusal instead of a silent
+ * re-decode; a consumer that knowingly accepts the engine's re-decoding
+ * sampler raises it and says so in its own source.
+ */
+export function createTerrainSourceFromPort(port, options = {}) {
+  if (!port || typeof port.invoke !== "function") {
+    throw new TypeError("createTerrainSourceFromPort requires a provider access port.");
+  }
+  const providerId = options.providerId ?? null;
+  const maxCost = Number.isInteger(options.maxCost)
+    ? options.maxCost
+    : ProviderCost.DEQUANTIZE;
+  const level = options.level ?? "mostDetailed";
+
+  async function acquireProfile(positions, callOptions = {}) {
+    const request = {
+      op: "profile",
+      positions: positions.map((position) => toRadianPair(position)),
+      maxCost: callOptions.maxCost ?? maxCost,
+    };
+    // Spacing wins over level when supplied: a consumer knows the stride it
+    // intends to march at, not a provider's level scheme.
+    const spacing = callOptions.spacing ?? options.spacing;
+    if (spacing !== undefined && spacing !== null) {
+      request.spacing = spacing;
+    } else {
+      request.level = callOptions.level ?? level;
+    }
+    if (providerId) request.providerId = providerId;
+    else request.kind = "terrain";
+
+    const { handle, descriptor } = await port.invoke("provider.acquire", request);
+    try {
+      const decoded = decodeTileDescriptor(descriptor);
+      const { bytes } = await port.invoke("provider.readRaw", {
+        handle,
+        plane: 0,
+        srcOffset: 0,
+        length: positions.length * 8,
+      });
+      return { bytes, decoded };
+    } finally {
+      await port.invoke("provider.release", { handle });
+    }
+  }
+
+  function strategyOf(callOptions = {}) {
+    const spacing = callOptions.spacing ?? options.spacing;
+    if (spacing !== undefined && spacing !== null) return "grid-matched-level";
+    return (callOptions.level ?? level) === "mostDetailed"
+      ? "most-detailed"
+      : "fixed-level";
+  }
+
+  function toHeights(bytes) {
+    return new Float64Array(
+      bytes.buffer,
+      bytes.byteOffset,
+      Math.floor(bytes.byteLength / 8),
+    );
+  }
+
+  return {
+    id: providerId ?? "terrain.port",
+    costClass: maxCost,
+
+    /** Bulk: contiguous metres. `out` is filled and returned when supplied. */
+    async readHeights(positions, out, callOptions = {}) {
+      const { bytes } = await acquireProfile(positions, callOptions);
+      const heights = toHeights(bytes);
+      if (!out) return heights.slice();
+      out.set(heights.subarray(0, out.length));
+      return out;
+    },
+
+    /**
+     * Heights PLUS provenance.
+     *
+     * A consumer that cannot see which level answered cannot tell a solve that
+     * resolved the ridges from one that interpolated them away, so the level
+     * actually used and how it was chosen come back with the data rather than
+     * being inferred from the request.
+     */
+    async readProfile(positions, callOptions = {}) {
+      const { bytes, decoded } = await acquireProfile(positions, callOptions);
+      const heights = toHeights(bytes);
+      return {
+        heights: callOptions.out
+          ? (callOptions.out.set(heights.subarray(0, callOptions.out.length)),
+            callOptions.out)
+          : heights.slice(),
+        level: decoded.level,
+        // Provenance comes from the DESCRIPTOR the adapter filled, so it
+        // reports what actually happened rather than what was asked for. The
+        // request-shaped guess is only a fallback for an adapter that has not
+        // been taught to report yet.
+        strategy: decoded.strategy
+          ? providerStrategyName(decoded.strategy)
+          : strategyOf(callOptions),
+        costClass: decoded.costClass,
+        partial: Boolean(decoded.flags & PROVIDER_FLAG_PARTIAL),
+        interpolated: Boolean(decoded.flags & PROVIDER_FLAG_INTERPOLATED),
+      };
+    },
+
+    /**
+     * Legacy shape. Mutates `height` on the supplied cartographics, exactly as
+     * the engine sampler does — including leaving no-data samples `undefined`,
+     * because that is what the existing call sites expect. New code should use
+     * readHeights and the sentinel.
+     */
+    async sampleCompat(_provider, positions) {
+      const heights = await this.readHeights(positions);
+      for (let index = 0; index < positions.length; index += 1) {
+        const height = heights[index];
+        positions[index].height = isProviderNoData(height) ? undefined : height;
+      }
+      return positions;
+    },
+  };
+}
+
+function toRadianPair(position) {
+  if (Array.isArray(position)) return [Number(position[0]), Number(position[1])];
+  if (typeof position?.longitude === "number") {
+    return [position.longitude, position.latitude];
+  }
+  throw new TypeError(
+    "A terrain sample position must be [lonRadians, latRadians] or a Cartographic.",
+  );
+}

package/src/host/wasiThreadHost.js

@@ -37,6 +37,9 @@ const IS_NODE =
   !!process.release &&
   process.release.name === "node";
 
+// Split so no bundler can constant-fold it back into a literal `node:` import.
+const NODE_BUILTIN_PREFIX = "no" + "de:";
+
 const BROWSER_WORKER_URL = new URL(
   "./wasiThreadBrowserWorker.mjs",
   import.meta.url,
@@ -207,7 +210,15 @@ export async function createWasiThreadSpawn({
     // pthread_create time is fine here — there is no startup-vs-join deadlock.
     const workers = new Set();
     const osThreadIds = new Set();
-    const workerThreads = await import("node:worker_threads");
+    // The specifier is assembled at runtime on purpose. This branch is dead in
+    // a browser, but a LITERAL `import("node:worker_threads")` is still
+    // statically resolved by esbuild/vite/rollup under a browser target, and
+    // the whole bundle fails to build. Keeping it opaque is what lets one host
+    // shim serve both runtimes; the browser branch below is the SAB+Worker one.
+    const nodeWorkerThreadsSpecifier = NODE_BUILTIN_PREFIX + "worker_threads";
+    const workerThreads = await import(
+      /* @vite-ignore */ /* webpackIgnore: true */ nodeWorkerThreadsSpecifier
+    );
     const NodeWorker = workerThreads.Worker;
     const nodeWorkerUrl = new URL("./wasiThreadWorker.mjs", import.meta.url);
 

package/src/index.d.ts

@@ -1962,7 +1962,11 @@ export interface BrowserModuleHarness {
 }
 export function detectArtifactProfile(wasmModule: WebAssembly.Module): string;
 export function createBrowserModuleHarness(options?: {
-  wasmSource: Uint8Array | ArrayBuffer | string | WebAssembly.Module | unknown;
+  wasmSource: Uint8Array | ArrayBuffer | string | Response | WebAssembly.Module | unknown;
+  // `true` uses env/global-configured trust; an object sets it explicitly;
+  // `false` disables verification. Ignored for a precompiled WebAssembly.Module
+  // (unverifiable — pass bytes/URL/Response when verification is required).
+  verifySignature?: boolean | { trustedPublicKeys?: string[]; requireSignature?: boolean };
   host?: BrowserHost | RuntimeHost | Record<string, unknown>;
   hostOptions?: BrowserHostOptions;
   args?: string[];
@@ -1979,6 +1983,25 @@ export function createBrowserModuleHarness(options?: {
   allowRawInvoke?: boolean;
   initialMemoryBytes?: number;
   maximumMemoryBytes?: number;
+  // Upper bound on guest wasi-threads spawns; sizes the browser warm worker
+  // pool (defaults to hardware concurrency). No effect on a non-threaded guest.
+  maxThreads?: number;
+  // Request-isolated BroadcastChannel descriptor a nested pthread hostcall
+  // dispatches over; supplied by createWorkerModuleHarness for the in-worker
+  // harness instance, not something a top-level caller usually sets by hand.
+  threadHostcallChannel?: {
+    channelName: string;
+    token: string;
+    maxResponseBytes?: number;
+    timeoutMs?: number;
+  };
+  // Explicit successful cross-origin-isolation negotiation for wasi-threads
+  // guests; defaults to true. See docs/browser-wasmedge-isomorphic.md's
+  // cross-origin-isolation section for when this is required.
+  enableBrowserWasiThreads?: boolean;
+  // Capacity of the module-memory arena a direct-invoke request is written
+  // into (bytes). Defaults to 64 KiB.
+  directInvokeRequestArenaBytes?: number;
   logOutput?: boolean;
   hostcallDispatch?: (operation: string, params: unknown) => unknown;
 }): Promise<BrowserModuleHarness>;
@@ -1997,7 +2020,11 @@ export interface WorkerModuleHarness {
   destroy(): Promise<void>;
 }
 export function createWorkerModuleHarness(options: {
-  wasmSource: Uint8Array | ArrayBuffer;
+  // A precompiled WebAssembly.Module is preferred: it skips a redundant
+  // compile and is structured-cloned to the worker directly (no plaintext
+  // bytes cross the postMessage boundary at all). Uint8Array/ArrayBuffer is
+  // compiled once on the controlling thread before the worker is spawned.
+  wasmSource: WebAssembly.Module | Uint8Array | ArrayBuffer;
   host?: unknown;
   hostOptions?: BrowserHostOptions;
   dispatchHost?: (operation: string, params: unknown) => Promise<unknown>;