space-data-module-sdk 0.8.10 → 0.8.12

package/src/testing/parityGate.js

@@ -58,9 +58,12 @@ import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
 
 import { toLoadableWasmBytes } from "../bundle/artifactBytes.js";
+import { locateEmbeddedPlgManifest } from "../compliance/index.js";
+import { runtimeTargetSatisfies } from "../host/runtimeTargetGate.js";
 import {
   classifyArtifactImports,
   describeClassification,
+  readWasmExportNames,
   resolveHostSurface,
 } from "./hostContract.js";
 import { normalizeWasmEdgeOutcome } from "./wasmedgeOutput.js";
@@ -109,8 +112,56 @@ export const ContractVerdict = Object.freeze({
   ShimGap: "shim-gap",
   /** The lane could not run at all. */
   Unavailable: "lane-unavailable",
+  /**
+   * The artifact DECLARES that it does not run on this lane's runtime target.
+   * Not a pass, not a divergence, not a trap: a scope statement the artifact
+   * itself makes, recorded as evidence. Composed flows derive their
+   * runtimeTargets from their parts, so a WasmEdge-only flow is legitimate —
+   * and without this class its (correct, loud) refusal by the browser harness
+   * scored as a P1 cross-runtime divergence, which would have made the gate
+   * fail exactly the artifacts this SDK just taught the compiler to emit.
+   */
+  OutOfDeclaredScope: "out-of-declared-scope",
+});
+
+/** Which runtime target each parity lane stands for. */
+export const LANE_RUNTIME_TARGET = Object.freeze({
+  browser: "browser",
+  "wasmedge-native": "wasmedge",
+  "wasmedge-docker": "wasmedge",
 });
 
+/**
+ * The artifact's own declared runtimeTargets, read from its embedded `$PLG`.
+ * An artifact that declares none is unconstrained — every lane is in scope,
+ * which is the historical behaviour and stays the default.
+ */
+export function declaredRuntimeTargets(loadableBytes) {
+  try {
+    const located = locateEmbeddedPlgManifest(loadableBytes);
+    const declared = located?.decoded?.runtimeTargets;
+    return Array.isArray(declared)
+      ? declared.map((t) => String(t ?? "").trim().toLowerCase()).filter(Boolean)
+      : [];
+  } catch {
+    return [];
+  }
+}
+
+export function declaredCapabilities(loadableBytes) {
+  try {
+    const located = locateEmbeddedPlgManifest(loadableBytes);
+    return located?.decoded?.capabilities ?? [];
+  } catch {
+    return [];
+  }
+}
+
+export function laneIsInDeclaredScope(laneName, targets, capabilities) {
+  const leg = LANE_RUNTIME_TARGET[laneName];
+  return leg ? runtimeTargetSatisfies(targets, leg, capabilities) : true;
+}
+
 // --- Manifest ------------------------------------------------------------------
 
 /**
@@ -180,6 +231,16 @@ export async function loadGateManifest(manifestPath = DEFAULT_GATE_MANIFEST) {
           ? path.resolve(path.dirname(resolved), String(spec.fixture))
           : null,
         required: spec.required !== false,
+        // The GATE'S claim about which lanes this artifact owes evidence on.
+        // Authority for that belongs to the manifest, not to the artifact's
+        // own `$PLG`: an artifact must not be able to reduce what it is
+        // examined on by editing its own declaration. Omitted means "every
+        // active lane its declaration admits".
+        expectedLanes: Object.freeze(
+          Array.isArray(spec.expectedLanes)
+            ? spec.expectedLanes.map((lane) => String(lane))
+            : [],
+        ),
         note: spec.note ? String(spec.note) : null,
         negativeControl: spec.negativeControl === true,
       }),
@@ -204,6 +265,11 @@ export function makeExternalArtifact(spec) {
     profile: String(spec.profile ?? "library"),
     fixture: spec.fixture ? path.resolve(String(spec.fixture)) : null,
     required: spec.required !== false,
+    expectedLanes: Object.freeze(
+      Array.isArray(spec.expectedLanes)
+        ? spec.expectedLanes.map((lane) => String(lane))
+        : [],
+    ),
     note: spec.note ? String(spec.note) : "injected by caller (external artifact)",
     negativeControl: spec.negativeControl === true,
   });
@@ -250,6 +316,21 @@ export function classifyWasmEdgeProbe({
   if (/(loading failed|validation failed|magic header|malformed|invalid section)/i.test(text)) {
     return { outcome: "compile-error", missingImport: null, detail: head() };
   }
+  // The CLI rejected the INVOCATION, before loading anything: reactor mode
+  // needs an entry name. This says nothing about the artifact, so it must not
+  // be reported against the artifact — stageArtifact() now names `_initialize`
+  // for reactor artifacts, and this branch exists so a regression there is
+  // legible instead of masquerading as a cross-runtime divergence.
+  if (/function name is required when reactor mode is enabled/i.test(text)) {
+    return {
+      outcome: "probe-failure",
+      missingImport: null,
+      detail:
+        "WasmEdge refused the invocation: reactor mode requires an entry " +
+        "function name. This is a PROBE defect, not an artifact defect — the " +
+        "lane must pass the artifact's reactor entry (see resolveReactorEntry).",
+    };
+  }
   // Linked, then the CLI could not find a start entry: a reactor artifact.
   // Only reachable after successful instantiation.
   if (/(wasm function not found|function not found|_start|_initialize)/i.test(text)) {
@@ -359,15 +440,11 @@ async function probeWithNativeWasmEdge(context, staged) {
     context.pin,
     `native binary ${detected.binary}`,
   );
-  const outcome = await spawnCapture(
-    detected.binary,
-    ["--enable-threads", staged.basename],
-    {
-      cwd: staged.dir,
-      env: { PATH: process.env.PATH ?? "" },
-      timeoutMs: context.timeoutMs,
-    },
-  );
+  const outcome = await spawnCapture(detected.binary, wasmEdgeProbeArgs(staged), {
+    cwd: staged.dir,
+    env: { PATH: process.env.PATH ?? "" },
+    timeoutMs: context.timeoutMs,
+  });
   const normalized = normalizeWasmEdgeOutcome(outcome);
   return classifyWasmEdgeProbe({
     code: outcome.code,
@@ -391,7 +468,7 @@ async function probeWithDockerWasmEdge(context, staged) {
     "/parity",
   ];
   if (context.dockerPlatform) args.push("--platform", String(context.dockerPlatform));
-  args.push(context.pin.dockerImage, "--enable-threads", staged.basename);
+  args.push(context.pin.dockerImage, ...wasmEdgeProbeArgs(staged));
   const outcome = await spawnCapture(context.dockerBinary ?? "docker", args, {
     cwd: staged.dir,
     env: process.env,
@@ -678,7 +755,49 @@ export function deriveContractVerdict({
  * under the bare WasmEdge CLI is NOT a divergence, and the report says so in
  * those words rather than pretending the lanes matched.
  */
+/**
+ * The P1 cross-runtime divergences among the lanes that ACTUALLY RAN.
+ *
+ * Extracted and exported so a test can drive the real comparison instead of
+ * re-implementing it: a test that hand-rolls this loop passes whether or not
+ * the shipped one is correct, which is precisely how the defect below survived
+ * its own regression test.
+ *
+ * Pass the COMPARED lanes — the ones not `out-of-declared-scope`. This used to
+ * pivot on `lanes[0]`, which is the BROWSER lane, and for a WasmEdge-only
+ * artifact that entry is `out-of-declared-scope`, which agrees with everything.
+ * Pivoting on it silently stopped comparing wasmedge-native against
+ * wasmedge-docker: the gate reported such an artifact adequately gated on two
+ * lanes while comparing nothing at all, defeating the very rule
+ * `certified-on-a-single-lane` states. Scoping a lane out must remove that LANE
+ * from the comparison, never the comparison itself.
+ *
+ * @param {Array<{lane: string, contractVerdict: string, reason?: string|null}>} comparedLanes
+ * @returns {string[]} one message per divergence
+ */
+export function laneDivergences(comparedLanes) {
+  const messages = [];
+  for (let index = 1; index < (comparedLanes?.length ?? 0); index += 1) {
+    const pivot = comparedLanes[0];
+    const other = comparedLanes[index];
+    if (lanesAgree(pivot.contractVerdict, other.contractVerdict)) continue;
+    messages.push(
+      `P1 cross-runtime divergence: ${pivot.lane}=${pivot.contractVerdict} vs ` +
+        `${other.lane}=${other.contractVerdict} (${other.reason ?? "-"})`,
+    );
+  }
+  return messages;
+}
+
 export function lanesAgree(a, b) {
+  // A lane the artifact declared itself out of cannot disagree with anything:
+  // there is no behaviour to compare, only a scope statement.
+  if (
+    a === ContractVerdict.OutOfDeclaredScope ||
+    b === ContractVerdict.OutOfDeclaredScope
+  ) {
+    return true;
+  }
   const equivalence = (verdict) =>
     verdict === ContractVerdict.RunnerCannotSupplyCapability
       ? ContractVerdict.Satisfied
@@ -688,11 +807,52 @@ export function lanesAgree(a, b) {
 
 // --- Orchestrator ---------------------------------------------------------------
 
+/**
+ * A REACTOR artifact has no `_start`; its initialisation entry is `_initialize`
+ * (clang `-mexec-model=reactor`). The WasmEdge CLI refuses to run one without
+ * being told which function to call — "A function name is required when reactor
+ * mode is enabled." on stderr, exit 1, and NO runtime diagnostic — which the
+ * probe classifier could only honestly report as `probe-failure`. The effect
+ * was that a CORRECTLY built library module (the shape the module contract
+ * mandates for the RF family) was reported as a P1 cross-runtime divergence
+ * while the browser lane passed: the gate failed the artifact for the gate's
+ * own inability to invoke it.
+ *
+ * Naming the entry is also STRICTLY STRONGER evidence than the old bare
+ * invocation: a clean exit 0 means the runtime linked the imports, instantiated
+ * the module, and RAN its initialiser — observed, not inferred from an error
+ * string.
+ */
+export function resolveReactorEntry(loadableBytes) {
+  let exportNames;
+  try {
+    exportNames = readWasmExportNames(loadableBytes);
+  } catch {
+    return null;
+  }
+  if (exportNames.includes("_start")) return null;
+  return exportNames.includes("_initialize") ? "_initialize" : null;
+}
+
 async function stageArtifact(artifact) {
   const dir = await mkdtemp(path.join(os.tmpdir(), `sdm-gate-${artifact.id}-`));
   const basename = "artifact.wasm";
   await writeFile(path.join(dir, basename), artifact.loadableBytes);
-  return { dir, basename };
+  return {
+    dir,
+    basename,
+    reactorEntry: resolveReactorEntry(artifact.loadableBytes),
+  };
+}
+
+/**
+ * The invocation tail shared by both WasmEdge lanes, so the native and Docker
+ * lanes can never drift into probing the same artifact two different ways.
+ */
+export function wasmEdgeProbeArgs(staged) {
+  return staged.reactorEntry
+    ? ["--enable-threads", "--reactor", staged.basename, staged.reactorEntry]
+    : ["--enable-threads", staged.basename];
 }
 
 /**
@@ -733,6 +893,10 @@ export async function runParityGate(options = {}) {
   // --- resolve + load artifacts
   const artifacts = [];
   const failures = [];
+  // A caller may state the lanes an artifact owes from OUTSIDE the manifest
+  // file (`--artifact-lanes`), which is the only way to bind a cross-repo
+  // injected artifact whose declaration this repo does not own.
+  const expectedLanesById = options.expectedLanesById ?? {};
   for (const spec of declared) {
     try {
       const rawBytes = new Uint8Array(await readFile(spec.artifactPath));
@@ -744,6 +908,11 @@ export async function runParityGate(options = {}) {
         artifactSha256: sha256Hex(rawBytes),
         moduleSha256: sha256Hex(loadableBytes),
         structural: classifyArtifactImports(loadableBytes, spec.surface),
+        declaredRuntimeTargets: declaredRuntimeTargets(loadableBytes),
+        declaredCapabilities: declaredCapabilities(loadableBytes),
+        ...(expectedLanesById[spec.id]
+          ? { expectedLanes: expectedLanesById[spec.id] }
+          : {}),
       });
     } catch (error) {
       if (spec.required) {
@@ -824,10 +993,25 @@ export async function runParityGate(options = {}) {
   // --- Tier A: real instantiation probes
   const laneProbes = new Map(); // lane -> Map(artifactId -> probe)
 
-  if (activeLanes.includes("browser") && artifacts.length > 0) {
+  // SCOPE BEFORE PROBING. An artifact that declares it does not run on a lane
+  // has nothing to learn from being launched there; probing anyway costs a
+  // Chrome start or a WasmEdge spawn per artifact for evidence the verdict
+  // then discards, and leaves the (expected) trap in the log as noise the
+  // report says was out of scope.
+  const inScopeArtifacts = (lane) =>
+    artifacts.filter((artifact) =>
+      laneIsInDeclaredScope(
+        lane,
+        artifact.declaredRuntimeTargets,
+        artifact.declaredCapabilities,
+      ),
+    );
+
+  const browserArtifacts = inScopeArtifacts("browser");
+  if (activeLanes.includes("browser") && browserArtifacts.length > 0) {
     const probes = new Map();
     try {
-      const results = await runBrowserProbeLane(context, artifacts);
+      const results = await runBrowserProbeLane(context, browserArtifacts);
       for (const result of results) {
         probes.set(result.id, {
           outcome: result.outcome,
@@ -837,7 +1021,9 @@ export async function runParityGate(options = {}) {
           crossOriginIsolated: result.crossOriginIsolated === true,
         });
       }
-      const missing = artifacts.filter((artifact) => !probes.has(artifact.id));
+      const missing = browserArtifacts.filter(
+        (artifact) => !probes.has(artifact.id),
+      );
       for (const artifact of missing) {
         probes.set(artifact.id, {
           outcome: "lane-unavailable",
@@ -846,7 +1032,7 @@ export async function runParityGate(options = {}) {
         });
       }
     } catch (error) {
-      for (const artifact of artifacts) {
+      for (const artifact of browserArtifacts) {
         probes.set(artifact.id, {
           outcome: "lane-unavailable",
           detail: error?.message ?? String(error),
@@ -864,7 +1050,7 @@ export async function runParityGate(options = {}) {
 
   for (const lane of wasmedgeLanes) {
     const probes = new Map();
-    for (const artifact of artifacts) {
+    for (const artifact of inScopeArtifacts(lane)) {
       const staged = await stageArtifact(artifact);
       try {
         const probe =
@@ -889,26 +1075,105 @@ export async function runParityGate(options = {}) {
   const artifactReports = [];
   for (const artifact of artifacts) {
     const lanes = [];
-    for (const lane of laneProbes.keys()) {
-      const probe = laneProbes.get(lane).get(artifact.id) ?? {
+    // Iterate the ACTIVE lanes, not the probed ones: a lane with no in-scope
+    // artifact is never launched, and its scoping still has to appear in the
+    // report. A skipped lane is evidence; a missing row is silence.
+    for (const lane of activeLanes) {
+      const probe = laneProbes.get(lane)?.get(artifact.id) ?? {
         outcome: "lane-unavailable",
         detail: "no probe recorded",
         missingImport: null,
       };
-      const derived = deriveContractVerdict({
-        laneSuppliesCapabilities: lane === "browser",
-        probe,
-        structural: artifact.structural,
-      });
+      const inScope = laneIsInDeclaredScope(
+        lane,
+        artifact.declaredRuntimeTargets,
+        artifact.declaredCapabilities,
+      );
+      const derived = inScope
+        ? deriveContractVerdict({
+            laneSuppliesCapabilities: lane === "browser",
+            probe,
+            structural: artifact.structural,
+          })
+        : {
+            verdict: ContractVerdict.OutOfDeclaredScope,
+            reason:
+              `the artifact declares runtimeTargets ` +
+              `[${artifact.declaredRuntimeTargets.join(", ")}], which does not include ` +
+              `"${LANE_RUNTIME_TARGET[lane]}" — this lane is out of its declared scope, ` +
+              "so its refusal here is the contract working, not a divergence",
+          };
       lanes.push({
         lane,
-        evidence: LANE_EVIDENCE[lane] ?? "unlabelled lane",
-        outcome: probe.outcome,
-        missingImport: probe.missingImport ?? null,
-        detail: probe.detail ?? null,
+        evidence: inScope
+          ? (LANE_EVIDENCE[lane] ?? "unlabelled lane")
+          : "artifact's own embedded runtimeTargets declaration",
+        outcome: inScope ? probe.outcome : "out-of-declared-scope",
+        missingImport: inScope ? (probe.missingImport ?? null) : null,
+        detail: inScope ? (probe.detail ?? null) : derived.reason,
         contractVerdict: derived.verdict,
         reason: derived.reason,
-        crossOriginIsolated: probe.crossOriginIsolated,
+        crossOriginIsolated: inScope ? (probe.crossOriginIsolated ?? null) : null,
+        declaredRuntimeTargets: artifact.declaredRuntimeTargets,
+      });
+    }
+
+    // THE ARTIFACT DOES NOT PICK ITS EXAMINERS.
+    //
+    // Scoping a lane out is a legitimate statement about where an artifact
+    // runs; it is not a way to be certified without being run. An artifact in
+    // the gate's own certified set that scopes ITSELF out of every lane — or
+    // out of all but one, leaving nothing to compare — has not been gated at
+    // all, and `lanesAgree` returning true pairwise must never stand in for
+    // "two lanes were compared". One manifest string would otherwise disarm
+    // the negative control.
+    const comparedLanes = lanes.filter(
+      (entry) => entry.contractVerdict !== ContractVerdict.OutOfDeclaredScope,
+    );
+    const comparedLaneNames = comparedLanes.map((entry) => entry.lane);
+    if (comparedLanes.length === 0) {
+      failures.push({
+        artifact: artifact.id,
+        kind: "artifact-out-of-every-lane",
+        message:
+          `declares runtimeTargets [${artifact.declaredRuntimeTargets.join(", ")}], ` +
+          `which admits none of the active lanes [${activeLanes.join(", ")}] — ` +
+          "it cannot be certified by a gate that never ran it",
+      });
+    } else if (activeLanes.length > 1 && comparedLanes.length < 2) {
+      // NO ARTIFACT IS CERTIFIED ON THE EVIDENCE OF A SINGLE LANE. The rule is
+      // about evidence, not about the artifact's shape: one lane is one
+      // execution, and one execution is not parity. A WasmEdge-only artifact
+      // still clears this — native host vs pinned container at one pin is a
+      // real comparison, and those pins bump together by law. A browser-only
+      // artifact does not, until the second browser lane (sequential vs
+      // worker-pool, owed by browser-worker-topology) exists to compare it to.
+      failures.push({
+        artifact: artifact.id,
+        kind: "certified-on-a-single-lane",
+        message:
+          `only lane "${comparedLanes[0].lane}" of [${activeLanes.join(", ")}] compared it ` +
+          `(it declares runtimeTargets [${artifact.declaredRuntimeTargets.join(", ")}]) — ` +
+          "one execution is not parity, so no artifact is certified on the evidence of a " +
+          "single lane",
+      });
+    }
+    // The manifest's claim outranks the artifact's declaration: an artifact
+    // may not shrink the set of lanes it is examined on by editing its own
+    // `$PLG`.
+    const owed = (artifact.expectedLanes ?? []).filter((lane) =>
+      activeLanes.includes(lane),
+    );
+    const unmet = owed.filter((lane) => !comparedLaneNames.includes(lane));
+    if (unmet.length > 0) {
+      failures.push({
+        artifact: artifact.id,
+        kind: "expected-lane-not-compared",
+        message:
+          `the gate manifest requires lanes [${owed.join(", ")}] for this artifact, but ` +
+          `[${unmet.join(", ")}] produced no comparison — its own declaration ` +
+          `[${artifact.declaredRuntimeTargets.join(", ")}] cannot narrow what the gate ` +
+          "claims to certify",
       });
     }
 
@@ -937,14 +1202,8 @@ export async function runParityGate(options = {}) {
       }
     }
 
-    for (let index = 1; index < lanes.length; index += 1) {
-      if (!lanesAgree(lanes[0].contractVerdict, lanes[index].contractVerdict)) {
-        failures.push({
-          artifact: artifact.id,
-          kind: "lane-divergence",
-          message: `P1 cross-runtime divergence: ${lanes[0].lane}=${lanes[0].contractVerdict} vs ${lanes[index].lane}=${lanes[index].contractVerdict} (${lanes[index].reason ?? "-"})`,
-        });
-      }
+    for (const message of laneDivergences(comparedLanes)) {
+      failures.push({ artifact: artifact.id, kind: "lane-divergence", message });
     }
 
     artifactReports.push({
@@ -955,6 +1214,7 @@ export async function runParityGate(options = {}) {
       artifactSha256: artifact.artifactSha256,
       moduleSha256: artifact.moduleSha256,
       byteLength: artifact.loadableBytes.length,
+      declaredRuntimeTargets: artifact.declaredRuntimeTargets,
       structural: {
         verdict: artifact.structural.verdict,
         summary: describeClassification(artifact.structural),
@@ -972,7 +1232,50 @@ export async function runParityGate(options = {}) {
   const behavioral = [];
   for (const artifact of artifacts) {
     if (!artifact.fixture) continue;
-    const harnessLanes = ["browser", ...(wasmedgeLanes.includes("wasmedge-native") ? ["wasmedge"] : []), "docker-wasmedge"];
+    // Behavioral lanes are scoped by the artifact's OWN declaration too: a
+    // WasmEdge-only artifact has no browser behaviour to compare, and running
+    // it there would score the harness's (correct) refusal as a divergence.
+    // The scoping is RECORDED — a skipped lane is evidence, never silence.
+    const harnessLanes = [
+      "browser",
+      ...(wasmedgeLanes.includes("wasmedge-native") ? ["wasmedge"] : []),
+      "docker-wasmedge",
+    ].filter((laneName) =>
+      laneIsInDeclaredScope(
+        laneName === "wasmedge"
+          ? "wasmedge-native"
+          : laneName === "docker-wasmedge"
+            ? "wasmedge-docker"
+            : laneName,
+        artifact.declaredRuntimeTargets,
+        artifact.declaredCapabilities,
+      ),
+    );
+    const outOfScopeLanes = ["browser", "wasmedge", "docker-wasmedge"].filter(
+      (laneName) => !harnessLanes.includes(laneName),
+    );
+    if (harnessLanes.length < 2) {
+      // An artifact that declared a FIXTURE asked to be compared. If its own
+      // declaration leaves nothing to compare it against, that is a defect in
+      // the certified set, not a free pass.
+      const message =
+        `behavioral parity needs two comparable lanes; this artifact declares ` +
+        `runtimeTargets [${artifact.declaredRuntimeTargets.join(", ")}] and only ` +
+        `${harnessLanes.length} lane(s) remain in scope`;
+      behavioral.push({
+        artifact: artifact.id,
+        ok: false,
+        outOfDeclaredScope: outOfScopeLanes,
+        declaredRuntimeTargets: artifact.declaredRuntimeTargets,
+        note: message,
+      });
+      failures.push({
+        artifact: artifact.id,
+        kind: "behavioral-not-comparable",
+        message,
+      });
+      continue;
+    }
     try {
       const report = await runParityHarness({
         wasmPath: artifact.artifactPath,
@@ -984,7 +1287,17 @@ export async function runParityGate(options = {}) {
         timeoutMs: context.timeoutMs,
         log,
       });
-      behavioral.push({ artifact: artifact.id, ok: report.ok, report });
+      behavioral.push({
+        artifact: artifact.id,
+        ok: report.ok,
+        report,
+        ...(outOfScopeLanes.length > 0
+          ? {
+              outOfDeclaredScope: outOfScopeLanes,
+              declaredRuntimeTargets: artifact.declaredRuntimeTargets,
+            }
+          : {}),
+      });
       if (!report.ok) {
         for (const failure of report.failures) {
           failures.push({