space-data-module-sdk 0.8.13 → 0.8.15

package/src/conformance/selfTest.js

@@ -0,0 +1,275 @@
+/**
+ * `space-data-module conformance propagator --self-test` — must exit 0 BY
+ * failing (finding §5). A gate never observed to fail is indistinguishable
+ * from one that cannot fail, so the runner ships with a battery of mock
+ * propagators, each carrying ONE planted defect drawn from a real defect this
+ * program found in the wild, and requires the suite to catch every one of
+ * them — plus a conformant baseline it must NOT flag.
+ *
+ * The mocks implement the same driver interface the WASM ABI driver exposes,
+ * so the suite under test is byte-for-byte the suite that adjudicates real
+ * artifacts. No toolchain, no artifact, no network.
+ */
+
+import { ORBPRO_STATE_VECTOR, ReferenceFrame, StateFlags, ErrorCode, REQUIRED_ABI_EXPORTS } from "./abiDriver.js";
+import { computeVerdict, runPropagatorSuite } from "./propagatorSuite.js";
+import { BANDS_DEFAULT, buildSelfTestCorpus } from "./selfTestCorpus.js";
+import { propagateTwoBody } from "./twoBodyReference.js";
+
+const PAGE = 65536;
+
+/** Encode a state through the GENERATED layout, so byte-identity is honest. */
+function packStateVector(state) {
+  const bytes = new Uint8Array(ORBPRO_STATE_VECTOR.size);
+  const view = new DataView(bytes.buffer);
+  const { offsets } = ORBPRO_STATE_VECTOR;
+  view.setFloat64(offsets.epoch, state.epoch, true);
+  for (const axis of [0, 1, 2]) {
+    view.setFloat64(offsets.position + axis * 8, state.position[axis], true);
+    view.setFloat64(offsets.velocity + axis * 8, state.velocity[axis], true);
+  }
+  view.setUint8(offsets.reference_frame, state.referenceFrame);
+  bytes[offsets.reference_frame + 1] = state.reserved?.[0] ?? 0;
+  bytes[offsets.reference_frame + 2] = state.reserved?.[1] ?? 0;
+  bytes[offsets.reference_frame + 3] = state.reserved?.[2] ?? 0;
+  view.setUint32(offsets.flags, state.flags, true);
+  return bytes;
+}
+
+function decodePacked(bytes) {
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const { offsets } = ORBPRO_STATE_VECTOR;
+  return {
+    epoch: view.getFloat64(offsets.epoch, true),
+    position: [0, 1, 2].map((axis) => view.getFloat64(offsets.position + axis * 8, true)),
+    velocity: [0, 1, 2].map((axis) => view.getFloat64(offsets.velocity + axis * 8, true)),
+    referenceFrame: view.getUint8(offsets.reference_frame),
+    reserved: [1, 2, 3].map((i) => view.getUint8(offsets.reference_frame + i)),
+    flags: view.getUint32(offsets.flags, true),
+  };
+}
+
+/**
+ * A mock propagator with a simulated linear memory (never shrinks, grows in
+ * whole pages — WebAssembly semantics, so the leak test measures the same
+ * thing it measures on a real artifact).
+ */
+class MockPropagatorDriver {
+  constructor(defect = null) {
+    this.defect = defect;
+    this.records = null;
+    // One page: tight enough that a per-cycle leak of a few KiB reaches a
+    // page boundary inside the self-test's measurement window.
+    this.capacityBytes = PAGE;
+    this.arenaBytes = 0;
+    this.bumpBytes = 0;
+    this.callSerial = 0;
+  }
+
+  exportNames() {
+    if (this.defect === "missing-exports") {
+      return REQUIRED_ABI_EXPORTS.filter((name) => name !== "plugin_destroy");
+    }
+    return [...REQUIRED_ABI_EXPORTS];
+  }
+
+  memoryBytes() {
+    return this.capacityBytes;
+  }
+
+  #reserve(byteLength) {
+    this.arenaBytes += byteLength;
+    const needed = this.arenaBytes + this.bumpBytes;
+    while (needed > this.capacityBytes) {
+      this.capacityBytes += PAGE;
+    }
+  }
+
+  alloc(byteLength) {
+    this.bumpBytes += byteLength;
+    const needed = this.arenaBytes + this.bumpBytes;
+    while (needed > this.capacityBytes) {
+      this.capacityBytes += PAGE;
+    }
+    return 8; // aligned, non-zero; the mock has no real address space
+  }
+
+  free() {
+    // bump allocator: freed on destroy, like the reference module's arena
+  }
+
+  #validate(record) {
+    if (!(record.eccentricity < 1) || !(record.meanMotionRevPerDay > 0)) {
+      return false;
+    }
+    return true;
+  }
+
+  initFromOmm(records) {
+    if (this.defect !== "confident-nonsense") {
+      for (const record of records) {
+        if (!this.#validate(record)) return ErrorCode.UNPHYSICAL;
+      }
+    }
+    this.records = [...records];
+    this.#reserve(records.length * 88);
+    return this.records.length;
+  }
+
+  ingestOne(record) {
+    if (this.defect !== "confident-nonsense" && !this.#validate(record)) {
+      return ErrorCode.UNPHYSICAL;
+    }
+    if (!this.records) this.records = [];
+    this.records.push(record);
+    this.#reserve(88);
+    if (this.defect === "count-fallback") {
+      // The defect the create-returns-handle primitive exists to kill: the
+      // module "returns success" instead of the handle it assigned.
+      return 0;
+    }
+    return this.records.length - 1;
+  }
+
+  #state(julianDate, record) {
+    const propagated = propagateTwoBody(record, julianDate);
+    let { position, velocity } = propagated;
+    if (this.defect === "units-km") {
+      position = position.map((value) => value / 1000);
+      velocity = velocity.map((value) => value / 1000);
+    }
+    if (this.defect === "nondeterministic") {
+      this.callSerial += 1;
+      position = position.map((value) => value + this.callSerial * 1e-9);
+    }
+    return {
+      epoch: julianDate,
+      position,
+      velocity,
+      referenceFrame:
+        this.defect === "frame-lies" ? ReferenceFrame.TEME : ReferenceFrame.ECEF,
+      reserved: [0, 0, 0],
+      flags: StateFlags.VALID,
+    };
+  }
+
+  propagate(julianDate, entityIndex) {
+    if (!this.records || this.records.length === 0) {
+      return { status: ErrorCode.NOT_INITIALIZED, state: null, bytes: new Uint8Array(64) };
+    }
+    if (!(entityIndex >= 0 && entityIndex < this.records.length)) {
+      return { status: ErrorCode.BAD_ENTITY_INDEX, state: null, bytes: new Uint8Array(64) };
+    }
+    const bytes = packStateVector(this.#state(julianDate, this.records[entityIndex]));
+    return { status: ErrorCode.OK, state: decodePacked(bytes), bytes };
+  }
+
+  propagateBatch(julianDate, count) {
+    if (!this.records || this.records.length === 0) {
+      return { status: ErrorCode.NOT_INITIALIZED, states: [] };
+    }
+    if (!(count >= 0 && count <= this.records.length)) {
+      return { status: ErrorCode.BAD_ENTITY_INDEX, states: [] };
+    }
+    const states = [];
+    for (let index = 0; index < count; index += 1) {
+      const state = this.#state(julianDate, this.records[index]);
+      if (this.defect === "batch-divergence") {
+        state.position = [state.position[0] + 1e-3, state.position[1], state.position[2]];
+      }
+      states.push(decodePacked(packStateVector(state)));
+    }
+    return { status: ErrorCode.OK, states };
+  }
+
+  entityCount() {
+    return this.records ? this.records.length : 0;
+  }
+
+  destroy() {
+    this.records = null;
+    this.bumpBytes = 0;
+    if (this.defect !== "leaky-destroy") {
+      this.arenaBytes = 0;
+    }
+    // capacityBytes deliberately never shrinks: wasm linear memory semantics.
+  }
+}
+
+/**
+ * Every planted defect names the check that must catch it. Each is a real
+ * defect class this program found live (finding §4): the 1000x units error,
+ * the {} destroy, the silent acceptance of unphysical elements, the count-1
+ * identity race, an undeclared frame, a batch path that is not the same
+ * physics, nondeterminism.
+ */
+export const PLANTED_DEFECTS = Object.freeze([
+  { defect: "units-km", mustFail: "tierB/anchors" },
+  { defect: "leaky-destroy", mustFail: "tier4/lifecycle-leak" },
+  { defect: "confident-nonsense", mustFail: "tierC/typed-refusals" },
+  { defect: "count-fallback", mustFail: "tierC/create-returns-handle" },
+  { defect: "frame-lies", mustFail: "tierC/frame-flags-reserved-declared" },
+  { defect: "batch-divergence", mustFail: "tierC/batch-single-agreement" },
+  { defect: "nondeterministic", mustFail: "tierC/determinism-byte-identity" },
+  { defect: "missing-exports", mustFail: "tier0/instantiation-and-exports" },
+]);
+
+/**
+ * Run the self-test. Returns {ok, results}: ok only when the baseline mock is
+ * clean AND every planted defect is caught by the check that owns it.
+ */
+export async function runPropagatorSelfTest(options = {}) {
+  const corpus = buildSelfTestCorpus();
+  // Small leak windows: the mocks' allocator is deterministic, so the steady
+  // state is reached immediately; what matters is that the LEAKY mock grows.
+  const leak = options.leak ?? { warmupCycles: 6, measureCycles: 40, entities: 128 };
+  const results = [];
+
+  const baselineChecks = await runPropagatorSuite(
+    async () => new MockPropagatorDriver(null),
+    { corpus, leak },
+  );
+  const baselineVerdict = computeVerdict(baselineChecks);
+  const baselineOk = baselineVerdict !== "FAIL";
+  results.push({
+    scenario: "baseline-conformant-mock",
+    expected: "no failures",
+    verdict: baselineVerdict,
+    ok: baselineOk,
+    failed: baselineChecks.filter((check) => check.status === "fail").map((c) => c.id),
+  });
+
+  for (const { defect, mustFail } of PLANTED_DEFECTS) {
+    const checks = await runPropagatorSuite(
+      async () => new MockPropagatorDriver(defect),
+      { corpus, leak },
+    );
+    const verdict = computeVerdict(checks);
+    const failedIds = checks.filter((check) => check.status === "fail").map((c) => c.id);
+    const caught = verdict === "FAIL" && failedIds.includes(mustFail);
+    results.push({
+      scenario: `planted:${defect}`,
+      expected: `FAIL at ${mustFail}`,
+      verdict,
+      ok: caught,
+      failed: failedIds,
+    });
+  }
+
+  return { ok: results.every((entry) => entry.ok), results, bands: BANDS_DEFAULT };
+}
+
+export function formatSelfTestReport(outcome) {
+  const lines = [];
+  lines.push(
+    `conformance self-test — ${outcome.ok ? "OK (the gate has been seen to fail)" : "BROKEN"}`,
+  );
+  for (const entry of outcome.results) {
+    const marker = entry.ok ? "ok  " : "MISS";
+    lines.push(
+      `  [${marker}] ${entry.scenario}: expected ${entry.expected}, verdict ${entry.verdict}` +
+        (entry.failed.length > 0 ? ` (failed: ${entry.failed.join(", ")})` : ""),
+    );
+  }
+  return lines.join("\n");
+}

package/src/conformance/selfTestCorpus.js

@@ -0,0 +1,68 @@
+/**
+ * The self-test's corpus: generated at runtime from the independent two-body
+ * closed form, in exactly the vectors.json format the real kits use
+ * (space-data-network-modules propagator/keplerian-reference/vectors/ is the
+ * committed exemplar). Generating rather than committing keeps the self-test
+ * free of a data file that could drift from the generator — the corpus IS the
+ * generator here, which is admissible only because the self-test's job is to
+ * prove the SUITE can fail, not to conformance-test a real module.
+ */
+
+import { ReferenceFrame, StateFlags } from "./abiDriver.js";
+import { GENERIC_ELEMENTS } from "./propagatorSuite.js";
+import { MU, propagateTwoBody } from "./twoBodyReference.js";
+
+/** The exemplar corpus's tolerance bands, per quantity. */
+export const BANDS_DEFAULT = Object.freeze({
+  position: Object.freeze({ abs: 1e-6, rel: 1e-9 }),
+  velocity: Object.freeze({ abs: 1e-9, rel: 1e-9 }),
+  time: Object.freeze({ abs: 1e-9, rel: 0 }),
+});
+
+export function buildSelfTestCorpus() {
+  const offsetsMinutes = [0, 45, 720];
+  const cases = [];
+  for (const elements of GENERIC_ELEMENTS) {
+    for (const minutes of offsetsMinutes) {
+      const julianDate = elements.epochJd + minutes / 1440;
+      const { position, velocity } = propagateTwoBody(elements, julianDate);
+      cases.push({
+        id: `self-test-${elements.noradCatId}@+${minutes}min`,
+        tier: "B",
+        operation: "plugin_propagate",
+        params: { elements, julianDate },
+        expect: {
+          "position.0": position[0],
+          "position.1": position[1],
+          "position.2": position[2],
+          "velocity.0": velocity[0],
+          "velocity.1": velocity[1],
+          "velocity.2": velocity[2],
+          epoch: julianDate,
+          reference_frame: ReferenceFrame.ECEF,
+          flags: StateFlags.VALID,
+        },
+        band: BANDS_DEFAULT,
+      });
+    }
+  }
+
+  return {
+    schemaVersion: 1,
+    conformance: {
+      model: "two-body point-mass, no drag, no J2, no third bodies",
+      mu: MU,
+      units: "SI throughout: metres, metres/second, Julian days, degrees on input",
+      outputFrame: `ECEF (${ReferenceFrame.ECEF})`,
+    },
+    tolerancePolicy: "fail <=> |observed - expected| > abs + rel * |expected|",
+    invariants: [
+      { id: "vis-viva-closure", tier: "C", applies: "every propagated state" },
+      { id: "period-closure", tier: "C", applies: "every element set" },
+      { id: "determinism", tier: "C", applies: "every case" },
+      { id: "frame-and-flags-declared", tier: "C", applies: "every propagated state" },
+      { id: "refusal-is-typed", tier: "C", applies: "every documented failure" },
+    ],
+    cases,
+  };
+}

package/src/conformance/twoBodyReference.js

@@ -0,0 +1,132 @@
+/**
+ * Independent two-body closed form, for the conformance runner's SELF-TEST.
+ *
+ * This is adjudication scaffolding, not product physics: the finding's Tier B
+ * definition REQUIRES anchors computed independently of any module under test
+ * (graph/findings/official-harness-shapes.md §5), and the self-test needs a
+ * conformant baseline to prove that every planted defect is caught. Written
+ * from the textbook relations; it mirrors — by construction, not by copy-check
+ * — the reference corpus generator in space-data-network-modules
+ * propagator/keplerian-reference/vectors/index.mjs. Where the two agree, they
+ * agree because two-body motion has one answer.
+ */
+
+/// WGS-72 gravitational parameter, m^3/s^2 — the model OMM mean elements are
+/// fitted under.
+export const MU = 398600.8e9;
+
+/// Earth rotation rate, rad/s (IAU 1982).
+export const EARTH_ROTATION_RATE = 7.292115146706979e-5;
+
+export const SECONDS_PER_DAY = 86400.0;
+export const J2000_JD = 2451545.0;
+
+/** `fail <=> |observed - expected| > abs + rel * |expected|` */
+export function withinBand(observed, expected, band) {
+  return Math.abs(observed - expected) <= band.abs + band.rel * Math.abs(expected);
+}
+
+/** Solve Kepler's equation independently of any module under test. */
+export function solveKepler(meanAnomaly, eccentricity) {
+  let M = meanAnomaly % (2 * Math.PI);
+  if (M < 0) M += 2 * Math.PI;
+  let E = eccentricity < 0.8 ? M : Math.PI;
+  for (let i = 0; i < 200; i += 1) {
+    const f = E - eccentricity * Math.sin(E) - M;
+    const fp = 1 - eccentricity * Math.cos(E);
+    const d = f / fp;
+    E -= d;
+    if (Math.abs(d) < 1e-15) return E;
+  }
+  throw new Error("reference Kepler solve did not converge");
+}
+
+/** Greenwich Mean Sidereal Time, radians (IAU 1982). */
+export function gmstRadians(julianDate) {
+  const tut1 = (julianDate - J2000_JD) / 36525.0;
+  const seconds =
+    67310.54841 +
+    (876600.0 * 3600.0 + 8640184.812866) * tut1 +
+    0.093104 * tut1 * tut1 -
+    6.2e-6 * tut1 * tut1 * tut1;
+  let gmst = (seconds * ((2 * Math.PI) / SECONDS_PER_DAY)) % (2 * Math.PI);
+  if (gmst < 0) gmst += 2 * Math.PI;
+  return gmst;
+}
+
+/**
+ * Closed-form two-body propagation from mean elements to an ECEF state, in
+ * METERS (the ABI's normative unit — the km/meters contradiction was W0.1).
+ */
+export function propagateTwoBody(elements, julianDate) {
+  const {
+    epochJd,
+    meanMotionRevPerDay,
+    eccentricity,
+    inclinationDeg,
+    raOfAscNodeDeg,
+    argOfPericenterDeg,
+    meanAnomalyDeg,
+  } = elements;
+
+  const deg = Math.PI / 180;
+  const n = (meanMotionRevPerDay * 2 * Math.PI) / SECONDS_PER_DAY;
+  const a = Math.cbrt(MU / (n * n));
+  const dt = (julianDate - epochJd) * SECONDS_PER_DAY;
+  const M = meanAnomalyDeg * deg + n * dt;
+  const E = solveKepler(M, eccentricity);
+
+  const cosE = Math.cos(E);
+  const sinE = Math.sin(E);
+  const beta = Math.sqrt(1 - eccentricity * eccentricity);
+  const xPqw = a * (cosE - eccentricity);
+  const yPqw = a * beta * sinE;
+  const eDot = n / (1 - eccentricity * cosE);
+  const vxPqw = -a * sinE * eDot;
+  const vyPqw = a * beta * cosE * eDot;
+
+  const O = raOfAscNodeDeg * deg;
+  const i = inclinationDeg * deg;
+  const w = argOfPericenterDeg * deg;
+  const cO = Math.cos(O);
+  const sO = Math.sin(O);
+  const ci = Math.cos(i);
+  const si = Math.sin(i);
+  const cw = Math.cos(w);
+  const sw = Math.sin(w);
+
+  const r11 = cO * cw - sO * sw * ci;
+  const r12 = -cO * sw - sO * cw * ci;
+  const r21 = sO * cw + cO * sw * ci;
+  const r22 = -sO * sw + cO * cw * ci;
+  const r31 = sw * si;
+  const r32 = cw * si;
+
+  const xI = r11 * xPqw + r12 * yPqw;
+  const yI = r21 * xPqw + r22 * yPqw;
+  const zI = r31 * xPqw + r32 * yPqw;
+  const vxI = r11 * vxPqw + r12 * vyPqw;
+  const vyI = r21 * vxPqw + r22 * vyPqw;
+  const vzI = r31 * vxPqw + r32 * vyPqw;
+
+  const theta = gmstRadians(julianDate);
+  const ct = Math.cos(theta);
+  const st = Math.sin(theta);
+
+  const x = ct * xI + st * yI;
+  const y = -st * xI + ct * yI;
+  const z = zI;
+  const vxRot = ct * vxI + st * vyI;
+  const vyRot = -st * vxI + ct * vyI;
+
+  return {
+    position: [x, y, z],
+    velocity: [
+      vxRot + EARTH_ROTATION_RATE * y,
+      vyRot - EARTH_ROTATION_RATE * x,
+      vzI,
+    ],
+    semiMajorAxis: a,
+    meanMotion: n,
+  };
+}

package/src/testing/isomorphicHarness.js

@@ -0,0 +1,233 @@
+/**
+ * The isomorphic module-test harness — ONE dist/isomorphic/module.wasm driven
+ * through the browser harness (SAB + Workers) and native WasmEdge with one
+ * API, so a module's behavior tests are written once and run per lane.
+ *
+ * MOVED INTO THE SDK by W1.4 of the official-harness-shapes program (it began
+ * life as space-data-network-modules/tests/lib/isomorphicHarness.mjs, which
+ * now re-exports this file). Living here makes it part of the SDK's testing
+ * contract: module repos stop copying it, and the conformance runner and the
+ * module suites drive artifacts through the same loader.
+ *
+ * Node-only (child_process, fs): import via `space-data-module-sdk/testing/isomorphic`.
+ */
+
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import { fileURLToPath } from "node:url";
+
+import { createBrowserModuleHarness } from "../host/browserModuleHarness.js";
+import { loadModule } from "../host/isomorphicLoader.js";
+
+export const STANDALONE_RUNTIME_KINDS = Object.freeze(["browser", "wasmedge"]);
+
+function resolveWasmPath(wasmPath) {
+  if (wasmPath instanceof URL) {
+    return fileURLToPath(wasmPath);
+  }
+  return String(wasmPath);
+}
+
+export function isMissingWasmEdgeError(error) {
+  return /spawn wasmedge ENOENT|command not found|Failed to launch/i.test(
+    String(error),
+  );
+}
+
+export function isWasmEdgeAvailable() {
+  const result = spawnSync("wasmedge", ["--version"], { stdio: "ignore" });
+  return result.status === 0;
+}
+
+export async function createStandaloneHarness(runtimeKind, wasmPath, options = {}) {
+  const resolvedWasmPath = resolveWasmPath(wasmPath);
+  if (runtimeKind === "browser") {
+    return createBrowserModuleHarness({
+      wasmSource: fs.readFileSync(resolvedWasmPath),
+      surface: options.surface ?? "command",
+      host: options.host,
+      hostOptions: options.hostOptions,
+      args: options.args,
+      env: options.env,
+      logOutput: options.logOutput,
+      performance: options.performance,
+      wasmMemory: options.wasmMemory,
+      memory: options.memory,
+      sharedMemory: options.sharedMemory,
+      allowRawInvoke: options.allowRawInvoke,
+      initialMemoryBytes: options.initialMemoryBytes,
+      maximumMemoryBytes: options.maximumMemoryBytes,
+    });
+  }
+
+  if (runtimeKind === "wasmedge") {
+    return loadModule({
+      wasmSource: resolvedWasmPath,
+      runtimeKind: "wasmedge",
+      enableThreads: options.enableThreads ?? false,
+      wasmEdgeBinary: options.wasmEdgeBinary,
+      wasmEdgeRunnerBinary: options.wasmEdgeRunnerBinary,
+      args: options.args,
+      env: options.env,
+      cwd: options.cwd,
+    });
+  }
+
+  throw new Error(`Unsupported runtime kind: ${runtimeKind}`);
+}
+
+export async function createStandaloneHarnessOrSkip(
+  runtimeKind,
+  wasmPath,
+  t,
+  options = {},
+) {
+  if (runtimeKind === "wasmedge" && !isWasmEdgeAvailable()) {
+    t.skip("Install wasmedge to verify the server-path harness.");
+    return null;
+  }
+
+  try {
+    return await createStandaloneHarness(runtimeKind, wasmPath, options);
+  } catch (error) {
+    if (runtimeKind === "wasmedge" && isMissingWasmEdgeError(error)) {
+      t.skip("Install wasmedge to verify the server-path harness.");
+      return null;
+    }
+    throw error;
+  }
+}
+
+export function assertSuccessfulResponse(
+  response,
+  { outputPortId = "response" } = {},
+) {
+  assert.equal(response.statusCode, 0);
+  assert.ok(response.errorCode === "" || response.errorCode === null);
+  const frame = response.outputs.find((entry) => entry.portId === outputPortId);
+  assert.ok(frame, `missing ${outputPortId} output frame`);
+  return frame.payload;
+}
+
+function toPayloadBytes(payload) {
+  if (payload instanceof Uint8Array) {
+    return payload;
+  }
+  if (ArrayBuffer.isView(payload)) {
+    return new Uint8Array(payload.buffer, payload.byteOffset, payload.byteLength);
+  }
+  if (payload instanceof ArrayBuffer) {
+    return new Uint8Array(payload);
+  }
+  throw new TypeError("Binary module requests require Uint8Array-compatible payload bytes.");
+}
+
+function isBrowserDirectHarness(harness) {
+  return harness?.runtime?.kind === "browser" && harness?.runtime?.surface === "direct";
+}
+
+export async function invokeBinaryRequest(
+  harness,
+  payload,
+  {
+    methodId = "invoke",
+    inputPortId = "request",
+    inputTypeRef = null,
+    alignment = 8,
+  } = {},
+) {
+  const payloadBytes = toPayloadBytes(payload);
+
+  if (!isBrowserDirectHarness(harness)) {
+    const response = await harness.invoke({
+      methodId,
+      inputs: [
+        {
+          portId: inputPortId,
+          typeRef: inputTypeRef,
+          payload: payloadBytes,
+        },
+      ],
+    });
+    return response;
+  }
+
+  if (
+    typeof SharedArrayBuffer !== "function" ||
+    !(harness.memory?.buffer instanceof SharedArrayBuffer)
+  ) {
+    throw new Error(
+      "Browser direct binary requests require SharedArrayBuffer-backed module memory.",
+    );
+  }
+  const alloc = harness.instance?.exports?.plugin_alloc;
+  const free = harness.instance?.exports?.plugin_free;
+  if (typeof alloc !== "function" || typeof free !== "function") {
+    throw new Error(
+      "Browser direct binary requests require plugin_alloc and plugin_free exports.",
+    );
+  }
+
+  const payloadSize = payloadBytes.byteLength;
+  const payloadPtr = payloadSize > 0 ? alloc(payloadSize) : 0;
+  if (payloadSize > 0 && !payloadPtr) {
+    throw new Error("plugin_alloc returned null for binary request payload.");
+  }
+  if (payloadSize > 0 && payloadPtr % alignment !== 0) {
+    if (payloadPtr > 0) {
+      free(payloadPtr, payloadSize);
+    }
+    throw new Error(
+      `plugin_alloc returned a payload pointer (${payloadPtr}) that is not ${alignment}-byte aligned.`,
+    );
+  }
+
+  try {
+    if (payloadSize > 0) {
+      new Uint8Array(harness.memory.buffer, payloadPtr, payloadSize).set(payloadBytes);
+    }
+    const response = await harness.invoke({
+      methodId,
+      externalArena: new Uint8Array(harness.memory.buffer),
+      inputs: [
+        {
+          portId: inputPortId,
+          typeRef: inputTypeRef,
+          offset: payloadPtr,
+          size: payloadSize,
+          alignment,
+        },
+      ],
+    });
+    return response;
+  } finally {
+    if (payloadSize > 0) {
+      free(payloadPtr, payloadSize);
+    }
+  }
+}
+
+export async function invokeJsonRequest(
+  harness,
+  request,
+  {
+    methodId = "invoke",
+    inputPortId = "request",
+    outputPortId = "response",
+    inputTypeRef = null,
+  } = {},
+) {
+  const response = await harness.invoke({
+    methodId,
+    inputs: [
+      {
+        portId: inputPortId,
+        typeRef: inputTypeRef,
+        payload: Buffer.from(JSON.stringify(request), "utf8"),
+      },
+    ],
+  });
+  const payload = assertSuccessfulResponse(response, { outputPortId });
+  return JSON.parse(new TextDecoder().decode(payload));
+}