space-data-module-sdk 0.8.9 → 0.8.11

package/bin/space-data-module.js

@@ -38,6 +38,8 @@ async function main(argv) {
       return runFlow(rest);
     case "parity":
       return runParity(rest);
+    case "parity-gate":
+      return runParityGateCommand(rest);
     case "protect":
       return runProtect(rest);
     case "sign":
@@ -142,6 +144,38 @@ function parseArgs(argv) {
       case "--allow-single-lane":
         options.allowSingleLane = true;
         break;
+      case "--gate-manifest":
+        options.gateManifestPath = path.resolve(
+          requireValue(argv, ++index, value),
+        );
+        break;
+      case "--artifact": {
+        // --artifact <id>=<path>[:<surface>] — inject an artifact owned by
+        // another repo (e.g. a decrypted closed rf-* module) WITHOUT this repo
+        // depending on that checkout.
+        const spec = requireValue(argv, ++index, value);
+        const eq = spec.indexOf("=");
+        if (eq < 1) {
+          throw new Error(`--artifact expects <id>=<path>[:<surface>], got "${spec}"`);
+        }
+        const id = spec.slice(0, eq);
+        const rest = spec.slice(eq + 1);
+        const colon = rest.lastIndexOf(":");
+        const hasSurface = colon > 0 && !rest.slice(colon + 1).includes("/");
+        options.extraArtifacts = options.extraArtifacts ?? [];
+        options.extraArtifacts.push({
+          id,
+          path: path.resolve(hasSurface ? rest.slice(0, colon) : rest),
+          surface: hasSurface ? rest.slice(colon + 1) : "module",
+        });
+        break;
+      }
+      case "--require-native-wasmedge":
+        options.requireNativeWasmEdge = true;
+        break;
+      case "--expect-fail":
+        options.expectFailure = true;
+        break;
       default:
         throw new Error(`Unknown argument: ${value}`);
     }
@@ -166,6 +200,9 @@ function printUsage() {
   space-data-module parity --wasm ./dist/isomorphic/module.wasm --fixture ./fixtures/parity/basic.json
   space-data-module parity --wasm ./dist/isomorphic/module.wasm --fixture ./f.json --lanes browser,wasmedge,docker-wasmedge [--json]
   space-data-module parity ... --self-test-divergence docker-wasmedge   (fire drill: prove the diff fails loudly)
+  space-data-module parity-gate                                          (THE isomorphism acceptance gate: certified artifact set x real lanes)
+  space-data-module parity-gate --artifact rf-fspl=./dist/isomorphic/module.wasm:module --json
+  space-data-module parity-gate --gate-manifest ./parity/negative-control.json --expect-fail   (prove the gate can fail)
   space-data-module flow check ./flows/my.flow.json --deps ./modules-root
   space-data-module flow compile ./flows/my.flow.json --deps ./modules-root [--out ./flows/my/dist]
   space-data-module protect --manifest ./manifest.json --wasm ./dist/module.wasm --json
@@ -322,6 +359,61 @@ async function runParity(argv) {
   return report.ok ? 0 : 2;
 }
 
+// space-data-module parity-gate [--gate-manifest ./parity/gate.json]
+//   [--artifact <id>=<path>[:<surface>]] [--lanes ...] [--json]
+//   [--require-native-wasmedge] [--expect-fail] [--timeout-sec N]
+//
+// THE acceptance gate for tri-runtime isomorphism: every artifact in the
+// certified set is really instantiated under the pinned WasmEdge AND in a real
+// headless Chrome behind COOP/COEP, its import set is classified against the
+// declared host contract, and command-profile artifacts are additionally
+// byte-diffed across lanes and thread counts.
+//
+// Exit 0 only when every artifact satisfies the contract in every lane and no
+// behavioral divergence is found. `--expect-fail` inverts the verdict: it is
+// how the negative control (a known-bad artifact) proves the gate can fail.
+async function runParityGateCommand(argv) {
+  const options = parseArgs(argv);
+  const { runParityGate, formatGateReport, gateReceiptDigest } = await import(
+    "../src/testing/parityGate.js"
+  );
+  const report = await runParityGate({
+    manifestPath: options.gateManifestPath,
+    extraArtifacts: options.extraArtifacts,
+    lanes: options.lanes,
+    timeoutMs: options.timeoutMs,
+    chromeBinary: options.chromeBinary,
+    wasmedgeBinary: options.wasmedgeBinary,
+    dockerPlatform: options.dockerPlatform,
+    requireNativeWasmEdge: options.requireNativeWasmEdge === true,
+    log: (line) => console.error(line),
+  });
+  if (options.json) {
+    console.log(
+      JSON.stringify({ ...report, receiptDigest: gateReceiptDigest(report) }, null, 2),
+    );
+  } else {
+    const text = formatGateReport(report);
+    if (report.ok) console.log(text);
+    else console.error(text);
+  }
+
+  if (options.expectFailure) {
+    if (report.ok) {
+      console.error(
+        "NEGATIVE CONTROL BROKEN: --expect-fail was set and the gate PASSED. " +
+          "A gate that cannot fail on a known-bad artifact is not a gate.",
+      );
+      return 3;
+    }
+    console.error(
+      `negative control OK: gate failed as required (${report.failures.length} failure(s), kinds: ${[...new Set(report.failures.map((f) => f.kind))].join(", ")}).`,
+    );
+    return 0;
+  }
+  return report.ok ? 0 : 2;
+}
+
 async function runCheck(argv) {
   const options = parseArgs(argv);
   if (options.manifestPath) {

package/docs/flatsql-host-contract.md

@@ -0,0 +1,95 @@
+# The FlatSQL host contract (why the floor moved to ^1.4.4)
+
+## The defect the bump repairs
+
+The SDK floored `flatsql` at `^0.4.2`. `^0.4.2` admits nothing in 1.x, so the
+floor sat a full major behind, and — the part that matters — the 0.4.x
+`wasm/flatsql-wasi.wasm` is an **emscripten-glue artifact**. Measured on the
+shipped bytes:
+
+| version | imports | shape |
+| --- | --- | --- |
+| 0.4.2 | **69** | 59 on `env`: ~40 `invoke_*` EH trampolines, `__cxa_*`, `__resumeException`, `llvm_eh_typeid_for`, 10 `__syscall_*`, `emscripten_notify_memory_growth` |
+| 1.4.4 | **13** | 7 `flatsql_io_*` + 6 WASI preview1 |
+
+Under the pinned WasmEdge 0.16.4:
+
+```
+0.4.2 -> instantiation failed: unknown import … "env" "invoke_vi"
+1.4.4 -> links; blocked only on the DECLARED capability env.flatsql_io_open
+```
+
+Modules are EH-free and `emcc`-shaped artifacts are a browser-only trap, so
+`^0.4.2` pinned a **non-isomorphic engine**. That is an auto-reject under the
+module contract, and the tri-runtime parity gate now says so out loud:
+`flatsql-standalone :: FORBIDDEN import class [emscripten-eh,
+emscripten-runtime, emscripten-syscall] — 59 import(s)`.
+
+## What the bump costs
+
+Nothing at the JS call sites. The SDK uses `FlatSQLDatabase.fromSchema`,
+`.query`, `.insert`, and `DirectAccessor.registerAccessor`/`.registerBuilder`
+(`src/runtime-host/flatsqlRuntimeStore.js`); all are present in 1.4.4, and the
+C ABI went 57 → 96 exports with **zero removed**.
+
+One real behavioral change surfaced, and it is a *fix*, not a break:
+
+> **0.4.2 silently ignored `ORDER BY`.** `listRows()` is
+> `SELECT … ORDER BY schemaFileId, rowId`, and on 0.4.2 it returned INSERTION
+> order. 1.4.4 honours the clause. `test/runtime-host-stream-ingest.test.js`
+> had encoded the broken behaviour (OMM-then-ENTM); it now asserts the sorted
+> contract and checks payloads by handle instead of by position, so it cannot
+> re-encode an engine bug as SDK semantics.
+
+## The host contract 1.4.x makes unconditional
+
+1.4.x imports these seven functions on module `env` **unconditionally**. A host
+that does not supply them cannot instantiate the artifact, so host wiring and
+the artifact bump land together or not at all:
+
+```
+i32 flatsql_io_open(ptr path, i32 pathLen, i32 flags)
+i32 flatsql_io_read(i32 h, ptr dst, i32 len, f64 offset)
+i32 flatsql_io_write(i32 h, ptr src, i32 len, f64 offset)
+i32 flatsql_io_truncate(i32 h, f64 size)
+i32 flatsql_io_sync(i32 h)
+f64 flatsql_io_size(i32 h)
+i32 flatsql_io_close(i32 h)
+```
+
+**Offsets are `f64`, never `i64`.** emscripten legalizes i64 across the JS
+boundary for the browser target and not for `STANDALONE_WASM`; using i64 would
+give one import two different signatures in the two lanes, which is the exact
+shape of a cross-runtime divergence.
+
+The SDK publishes this contract so consumers wire it identically in both lanes
+rather than each inventing it:
+
+```js
+import {
+  FLATSQL_IO_IMPORTS,       // the seven "env.flatsql_io_*" keys
+  FLATSQL_IO_SIGNATURES,    // params/result valtypes, f64 offsets
+  HOST_SURFACES,            // HOST_SURFACES["flatsql-engine"]
+} from "space-data-module-sdk/testing";
+```
+
+## What the SDK does NOT do
+
+module-sdk does not link the VFS into its own artifacts, and that is by design:
+an SDK module exports **zero** `flatsql_io_*` imports. A module keeps the
+generic hook set, which rides inside the one sanctioned
+`space_data_module_host` bridge; a private import would be a NEW HOST
+CAPABILITY, and that is an owner decision, never a dependency bump. The SDK
+consumes flatsql through its **JS API** only
+(`src/runtime-host/flatsqlRuntimeStore.js`); flow artifacts receive the live
+engine from the caller as `engineLink` (`src/flow/flowRuntimeHost.js`), so the
+host that instantiates the engine is the host that supplies the seven imports.
+
+## Evidence
+
+`space-data-module parity-gate` — the `flatsql-standalone` artifact resolves
+through this repo's own dependency, so the gate always classifies the engine a
+consumer would actually load. At 1.4.4 it reports `in-surface (WASI + declared
+capabilities: 7)`, `satisfied` in the real-browser lane and
+`runner-cannot-supply-declared-capability` under the bare WasmEdge CLI, naming
+`env.flatsql_io_open` as the single blocker.

package/docs/tri-runtime-parity-gate.md

@@ -0,0 +1,146 @@
+# The Tri-Runtime Parity GATE
+
+`docs/tri-runtime-parity.md` describes the parity **harness**: one
+`module.wasm`, one fixture, byte-identical stdout across browser / native
+WasmEdge / Docker WasmEdge. This document describes the **gate** — the thing
+the dev-graph gauntlet actually runs, and the thing an isomorphism claim is
+accepted against.
+
+## Why a gate and not just the harness
+
+The harness is necessary and not sufficient:
+
+- it can only speak about artifacts that already instantiate in every lane, so
+  the most important failure — *an artifact that is not isomorphic at all* —
+  is invisible to it;
+- it takes ONE artifact, so it says nothing about the artifact **set** a
+  release ships;
+- and until this gate landed, the gauntlet slot that was supposed to enforce
+  it was a hardcoded `echo TODO …; exit 1` marked `required: false`. It failed
+  on every run for every task, so every receipt read PASS-WITH-GAPS and the
+  red became background noise. That is the worst state a gate can be in:
+  present enough to look like coverage, incapable of ever providing it.
+
+```
+space-data-module parity-gate                       # the certified set
+space-data-module parity-gate --json                # machine receipt
+space-data-module parity-gate --gate-manifest ./parity/negative-control.json --expect-fail
+```
+
+## What it checks
+
+### Tier A — host-contract conformance (REAL instantiation, per lane)
+
+Every artifact in the certified set is really instantiated:
+
+| lane | what it actually is | what it proves |
+| --- | --- | --- |
+| `browser` | real headless Chrome behind COOP/COEP (cross-origin isolated, SAB-capable). Never jsdom. | The artifact instantiates against **exactly** the declared host surface — WASI preview1 stubs plus the declared capability imports, with signatures read from the binary. Anything else it demands is a `LinkError` naming the offender. |
+| `wasmedge-native` | a native WasmEdge binary, version-checked against `src/testing/wasmedgePin.json`. | The artifact links on the real production runtime. |
+| `wasmedge-docker` | the pinned WasmEdge container (image tag **derived** from the same pin). | Same, in the container the fleet ships. |
+
+Alongside the runtime probes, every artifact's import section is classified
+structurally against its declared surface, because *why* an instantiation
+failed is the entire content of the finding:
+
+- **forbidden import class** — `invoke_*` / `__cxa_*` / `__resumeException` /
+  `llvm_eh_typeid_for` (emscripten EH), `__syscall_*` (emscripten JS-library
+  syscalls), `emscripten_*` (emscripten runtime hooks), or a single-letter
+  import module (the minified emcc browser build). These are `emcc`-shaped
+  artifacts: browser-only by construction, EH-carrying, not instantiable on a
+  plain WasmEdge host. **Auto-reject.**
+- **outside the declared surface** — a private import is a NEW HOST
+  CAPABILITY, which is an owner decision, never a PR.
+- **in-surface** — WASI plus, at most, the declared capability imports.
+
+### Tier B — behavioral parity
+
+Artifacts with `profile: "command"` and a fixture additionally go through
+`runParityHarness()`: identical stdin bytes, identical explicit guest env,
+byte-identical stdout and identical trap classes across every lane × thread
+count (1/2/4/8).
+
+## Declared host surfaces
+
+| surface | contents |
+| --- | --- |
+| `module` | WASI preview1 + wasi-threads (`wasi.thread-spawn`, `env.memory`) + the ONE sanctioned hostcall bridge `space_data_module_host.{call,response_len,read_response,clear_response,last_status_code,dispatch_current_invocation}` (plus the legacy `sdn_flow_host.dispatch_current_invocation`). The generic hook set (`http`/`tcp`/`wallet_sign`/`keyslot.sign`/clock/fs) rides *inside* that bridge, which is why a module needs no per-capability imports. |
+| `module-standalone` | WASI preview1 + wasi-threads only. |
+| `flatsql-engine` | WASI preview1 + exactly the seven `flatsql_io_*` VFS imports. Offsets are **f64, never i64** — emscripten legalizes i64 across the JS boundary for the browser target and not for `STANDALONE_WASM`, which would give one import two different signatures in the two lanes. |
+
+## Verdicts
+
+| verdict | meaning |
+| --- | --- |
+| `satisfied` | instantiated on the declared surface. |
+| `runner-cannot-supply-declared-capability` | did **not** instantiate, and the only blocker is a DECLARED capability the lane runner cannot register. The bare WasmEdge CLI has no mechanism for host functions, so an engine artifact reports this while the browser lane reports `satisfied`. **This is recorded verbatim, never counted as a silent pass**, and the two are treated as agreeing. Upgrade path: graph task `module-sdk-parity-lane-embedded-wasmedge` (run the guest through the node's real WasmEdge *embedding*, which also unlocks threaded guests — `--enable-threads` enables only the threads proposal, not the wasi-threads host module). |
+| `violated` | forbidden class, out-of-surface import, or a link error the contract does not explain. **FAIL.** |
+| `shim-gap` | a lane that *does* supply the declared surface still failed to link a declared capability — an SDK host-shim defect. **FAIL.** |
+| `lane-unavailable` | the lane could not run. **FAIL**, and kept lexically distinct from divergence: a harness that cannot run and a runtime that disagrees must never look alike in a receipt. |
+
+Rules, all hard: forbidden class ⇒ FAIL even when every lane agrees (lanes
+agreeing that an artifact is broken everywhere is not parity); lane
+disagreement ⇒ FAIL as a P1 cross-runtime divergence; behavioral divergence ⇒
+FAIL.
+
+## The certified set — and fresh-worktree isolation
+
+`parity/gate.json` lists the artifacts this SDK certifies. **Every entry
+resolves inside this repo** — a repo-relative path or a node-resolved
+dependency. That is deliberate: the previous tri-lane test defaulted its
+artifact path to a sibling checkout that does not exist on a normal machine,
+so the acceptance instrument was silently un-runnable and nobody who did not
+set an env var by hand had ever seen it work (graph:
+`parity-harness-cannot-run-locally`). The gate must run in ANY fresh worktree.
+
+Artifacts owned by other repos are **injected by the caller**:
+
+```
+space-data-module parity-gate \
+  --artifact rf-fspl=./packages/rf-fspl/dist/isomorphic/module.wasm:module
+```
+
+so the owning repo's gauntlet profile supplies its own artifacts and this repo
+never depends on that checkout.
+
+## The WasmEdge pin
+
+`src/testing/wasmedgePin.json` remains the single source. Native and container
+runtimes are both version-checked against it; drift is a loud failure, not a
+warning. When no native WasmEdge exists on the box, the report carries an
+explicit `pinVerification.native = absent` gap — the host/container pin PAIR
+could not be cross-verified, which is *recorded*, not passed. Hosts that
+provision the binary run with `--require-native-wasmedge`, which turns the gap
+into a failure.
+
+## The one runtime difference the SDK absorbs (and where)
+
+**Measured on WasmEdge 0.16.4, native and containerized: the CLI writes its own
+diagnostics — `[2026-08-08 00:45:38.689] [error] …` — to STDOUT, not stderr.**
+`src/testing/wasmedgeOutput.js` is the shim that absorbs this, and it is a
+*host shim*, which is the only place a runtime difference is ever allowed to
+live. It does two things and nothing else: it lifts the runtime's log lines out
+of the captured stdout so the harness byte-compares the GUEST's bytes, and it
+hands those lines to the classifier so a failed instantiation is actually seen.
+
+Both halves were live defects before it existed:
+
+- the gate's WasmEdge probe read only stderr and **defaulted to
+  `instantiated`** when it recognized nothing — so an artifact that
+  demonstrably cannot link (`flatsql-wasi` at 1.4.4 under the bare CLI) read as
+  a clean pass. A false pass in an acceptance instrument is worse than no
+  instrument. The classifier now requires POSITIVE evidence of linking (clean
+  exit, guest output, or a post-link diagnostic such as a missing `_start` on a
+  reactor artifact) and otherwise returns `probe-failure`, which fails the gate.
+  Regression test: *"a silent nonzero exit is a probe-failure, NEVER an
+  inferred pass"*.
+- the parity harness compared those log lines as if they were guest output, so
+  any error-path fixture would have reported a phantom output divergence, and
+  its trap-class detection (which scanned stderr for trap markers) could never
+  fire on a WasmEdge trap.
+
+## Negative control
+
+`parity/negative-control.json` declares a known-bad artifact and is run with
+`--expect-fail`; a PASS there is itself an error (exit 3). Keep it. A gate
+nobody has watched fail is indistinguishable from a gate that cannot fail.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "space-data-module-sdk",
-  "version": "0.8.9",
+  "version": "0.8.11",
   "description": "Module SDK for building, validating, signing, and deploying WebAssembly modules on the Space Data Network.",
   "type": "module",
   "types": "./src/index.d.ts",
@@ -74,6 +74,7 @@
   "files": [
     "bin/",
     "docs/",
+    "parity/",
     "schemas/",
     "src/",
     "templates/"
@@ -84,6 +85,10 @@
     "test:runtime-matrix": "SPACE_DATA_MODULE_SDK_ENABLE_RUNTIME_MATRIX=1 node --test test/runtime-matrix.test.js",
     "test:parity": "node --test test/parity-harness.test.js",
     "test:parity-tri-lane": "SPACE_DATA_MODULE_SDK_ENABLE_TRI_RUNTIME_PARITY=1 node --test test/parity-tri-lane.test.js",
+    "test:parity-gate": "node --test test/parity-gate.test.js",
+    "test:parity-gate-lanes": "SPACE_DATA_MODULE_SDK_ENABLE_PARITY_GATE=1 node --test test/parity-gate-lanes.test.js",
+    "gate:parity": "node ./bin/space-data-module.js parity-gate",
+    "gate:parity-negative-control": "node ./bin/space-data-module.js parity-gate --gate-manifest ./parity/negative-control.json --expect-fail",
     "test:stream-ingest": "node --test test/runtime-host-stream-ingest.test.js",
     "test:module-stream": "node --test test/module-flatbuffer-stream-pump.test.js",
     "benchmark:stream-1gib": "SPACE_DATA_MODULE_SDK_ENABLE_1GB_STREAM_TEST=1 node --test test/runtime-host-stream-ingest.test.js",
@@ -98,7 +103,7 @@
   "dependencies": {
     "flatbuffers": "^25.9.23",
     "flatc-wasm": "^26.1.32",
-    "flatsql": "^0.4.2",
+    "flatsql": "^1.4.4",
     "hd-wallet-wasm": "2.0.28",
     "sdn-emception": "1.0.0",
     "spacedatastandards.org": "https://github.com/DigitalArsenal/spacedatastandards.org/archive/06deda5079204a46bd97a7ce6ac2868e991c6b8f.tar.gz"

package/parity/gate.json

@@ -0,0 +1,28 @@
+{
+  "//": "THE representative artifact set the module SDK certifies as isomorphic. Every entry resolves INSIDE this repo (a repo-relative path or a node-resolved dependency) so the gate runs in ANY fresh worktree with zero shared-checkout coupling — reaching into a sibling checkout is exactly what made the previous parity lane silently un-runnable (graph: parity-harness-cannot-run-locally). Artifacts owned by other repos (e.g. a decrypted closed rf-* module) are INJECTED by the caller with --artifact id=path:surface, so the owning repo's gauntlet profile supplies them without this repo ever depending on that checkout.",
+  "name": "module-sdk-tri-runtime",
+  "artifacts": [
+    {
+      "id": "sdk-command-module",
+      "path": "examples/single-file-bundle/vectors/base-module.wasm",
+      "surface": "module",
+      "profile": "command",
+      "fixture": "sdk-command.json",
+      "note": "An SDK-built module: clang wasm32-wasip1-threads, WASI-only imports, generic hooks over the PIV codec on stdin/stdout. Instantiates and RUNS in every lane, so it carries the behavioral (Tier B) parity too."
+    },
+    {
+      "id": "sdk-published-module",
+      "path": "examples/single-file-bundle/vectors/single-file-module.wasm",
+      "surface": "module",
+      "profile": "command",
+      "note": "The SAME module after publication: signature/manifest records appended as a trailing custom section. Proves the record-stripping path yields a loadable payload that instantiates identically in all lanes — a published artifact must never be a fourth runtime."
+    },
+    {
+      "id": "flatsql-standalone",
+      "packagePath": "flatsql/wasm/flatsql-wasi.wasm",
+      "surface": "flatsql-engine",
+      "profile": "library",
+      "note": "The FlatSQL engine as the SDK's own dependency pin resolves it. Contract: WASI preview1 + EXACTLY the seven declared flatsql_io_* VFS imports (offsets f64, never i64). An emscripten-glue build here is an auto-reject: it cannot instantiate on a plain WasmEdge host, which is precisely the ^0.4.2 floor defect (graph: module-sdk-flatsql-floor-not-isomorphic)."
+    }
+  ]
+}

package/parity/negative-control.json

@@ -0,0 +1,14 @@
+{
+  "//": "NEGATIVE CONTROL. This manifest deliberately declares an artifact known to violate the module contract, and the gate is run with --expect-fail. A gate that has never been observed to fail is indistinguishable from a gate that cannot fail — which is exactly the defect this whole task exists to repair (the previous slot was a hardcoded `exit 1` that could never go green, and before that a `required:false` red everyone learned to ignore). Run: `space-data-module parity-gate --gate-manifest ./parity/negative-control.json --expect-fail`.",
+  "name": "module-sdk-tri-runtime-NEGATIVE-CONTROL",
+  "artifacts": [
+    {
+      "id": "negative-control-flatsql-emscripten-glue",
+      "packagePath": "flatsql/wasm/flatsql.wasm",
+      "surface": "flatsql-engine",
+      "profile": "library",
+      "negativeControl": true,
+      "note": "The emscripten BROWSER build of the FlatSQL engine, declared against the isomorphic engine surface. It carries minified emscripten glue imports and cannot instantiate on a plain WasmEdge host. The gate MUST report a forbidden-import-class failure. If this ever passes, the classifier has been broken — not the artifact fixed."
+    }
+  ]
+}

package/parity/sdk-command.json

@@ -0,0 +1,22 @@
+{
+  "name": "sdk-command-parity",
+  "threadEnvVar": "SDM_PARITY_THREADS",
+  "threadCounts": [1, 2, 4, 8],
+  "cases": [
+    {
+      "id": "empty-stdin",
+      "stdinUtf8": "",
+      "//": "The command surface's no-input path. Every runtime must emit the SAME response frame bytes and take the SAME exit class — a deterministic error path is parity evidence exactly like a success path."
+    },
+    {
+      "id": "malformed-stdin",
+      "stdinUtf8": "not a PIV frame",
+      "//": "Malformed input: the trap/error CLASS must be identical across runtimes, not merely 'an error in each'."
+    },
+    {
+      "id": "truncated-piv-header",
+      "stdinHex": "24504956",
+      "//": "A valid PIV file identifier with nothing after it — the truncated-frame path, which is where lanes with different stdin buffering habits diverge if anything does."
+    }
+  ]
+}

package/src/standards/catalogCore.js

@@ -62,8 +62,35 @@ function collectFlatbufferTableFields(idl, tableName) {
     .filter(Boolean);
 }
 
+// A schema has TWO written forms in this ecosystem and they mean the same file:
+//
+//   "SCV.fbs"       — the catalog's canonical form, built as `<CODE>.fbs` from
+//                     the standards manifest (parseStandardsEntry below).
+//   "SCV/main.fbs"  — the PATH form, which is how the schema actually lives in
+//                     spacedatastandards.org (`schema/SCV/main.fbs`) and is
+//                     therefore what modules, tests and generated bindings across
+//                     the stack write.
+//
+// Matching them as raw strings made every manifest using the path form fail
+// resolution with `standards-type-identity-mismatch` — "mixes a known
+// schemaName ... with a different standards entry" — because the `$SCV` file
+// identifier DID resolve while the name did not. That is not a manifest defect
+// and not a schema defect; it is this matcher refusing a spelling the standards
+// repository itself uses. The rest of the toolchain already treats the two as
+// one schema (see the closed-modules builder's
+// `^([A-Z][A-Z0-9]{2})(?:\/main)?\.fbs$` header-injection regex), so the
+// catalog must too, or a correct module cannot be compiled.
+//
+// Deliberately narrow: ONLY the exact `<CODE>/main.fbs` shape collapses. Any
+// other path is left alone so two genuinely different schemas can never be
+// merged by a loose rule.
+const SCHEMA_PATH_FORM = /^([A-Za-z][A-Za-z0-9_]*)\/main\.fbs$/;
+
 function normalizeSchemaName(value) {
-  return value === undefined || value === null ? "" : String(value);
+  if (value === undefined || value === null) return "";
+  const text = String(value);
+  const pathForm = SCHEMA_PATH_FORM.exec(text);
+  return pathForm ? `${pathForm[1]}.fbs` : text;
 }
 
 function normalizeFileIdentifier(value) {