space-data-module-sdk 0.8.4 → 0.8.5

package/src/manifest/typeRefs.js

@@ -27,39 +27,160 @@ function normalizeAlignedMetadataScalar(value) {
   return value;
 }
 
+function inspectPayloadSchemaHash(value) {
+  if (value === undefined || value === null) {
+    return { valid: true, present: false, bytes: [] };
+  }
+  if (typeof value === "string") {
+    const hex = value.startsWith("0x") ? value.slice(2) : value;
+    if (hex.length === 0) {
+      return { valid: true, present: false, bytes: [] };
+    }
+    if (hex.length % 2 !== 0 || !/^[0-9a-fA-F]+$/.test(hex)) {
+      return { valid: false, present: true, bytes: [] };
+    }
+    const bytes = [];
+    for (let index = 0; index < hex.length; index += 2) {
+      bytes.push(Number.parseInt(hex.slice(index, index + 2), 16));
+    }
+    return { valid: true, present: true, bytes };
+  }
+  if (!Array.isArray(value) && !(value instanceof Uint8Array)) {
+    return { valid: false, present: true, bytes: [] };
+  }
+  const bytes = Array.from(value);
+  if (bytes.length === 0) {
+    return { valid: true, present: false, bytes: [] };
+  }
+  if (
+    bytes.some(
+      (entry) =>
+        !Number.isInteger(entry) || entry < 0 || entry > 0xff,
+    )
+  ) {
+    return { valid: false, present: true, bytes: [] };
+  }
+  return { valid: true, present: true, bytes };
+}
+
+export function normalizePayloadSchemaHash(value) {
+  const inspected = inspectPayloadSchemaHash(value);
+  return inspected.valid && inspected.present ? inspected.bytes : undefined;
+}
+
+export function isPayloadSchemaHashValid(value) {
+  return inspectPayloadSchemaHash(value).valid;
+}
+
 export function clonePayloadTypeRef(value = null) {
   if (!value || typeof value !== "object") {
     return { acceptsAnyFlatbuffer: true, fileIdentifier: null };
   }
   return {
     schemaName: normalizeNullableString(
-      value.schemaName ?? value.schema_name,
+      value.schemaName ?? value.schema_name ?? value.SCHEMA_NAME,
     ),
     fileIdentifier: normalizeNullableString(
-      value.fileIdentifier ?? value.file_identifier,
+      value.fileIdentifier ?? value.file_identifier ?? value.FILE_IDENTIFIER,
+    ),
+    schemaVersion: normalizeNullableString(
+      value.schemaVersion ?? value.schema_version ?? value.SCHEMA_VERSION,
+    ),
+    schemaHash: cloneSchemaHash(
+      value.schemaHash ?? value.schema_hash ?? value.SCHEMA_HASH,
     ),
-    schemaHash: cloneSchemaHash(value.schemaHash ?? value.schema_hash),
     acceptsAnyFlatbuffer: Boolean(
-      value.acceptsAnyFlatbuffer ?? value.accepts_any_flatbuffer ?? false,
+      value.acceptsAnyFlatbuffer ??
+        value.accepts_any_flatbuffer ??
+        value.ACCEPTS_ANY_FLATBUFFER ??
+        false,
     ),
     wireFormat: normalizePayloadWireFormatName(
-      value.wireFormat ?? value.wire_format,
+      value.wireFormat ?? value.wire_format ?? value.WIRE_FORMAT,
     ),
     rootTypeName: normalizeNullableString(
-      value.rootTypeName ?? value.root_type_name,
+      value.rootTypeName ??
+        value.root_type_name ??
+        value.rootType ??
+        value.ROOT_TYPE,
     ),
     fixedStringLength: normalizeAlignedMetadataScalar(
-      value.fixedStringLength ?? value.fixed_string_length,
+      value.fixedStringLength ??
+        value.fixed_string_length ??
+        value.FIXED_STRING_LENGTH,
     ),
     byteLength: normalizeAlignedMetadataScalar(
-      value.byteLength ?? value.byte_length,
+      value.byteLength ?? value.byte_length ?? value.BYTE_LENGTH,
     ),
     requiredAlignment: normalizeAlignedMetadataScalar(
-      value.requiredAlignment ?? value.required_alignment,
+      value.requiredAlignment ??
+        value.required_alignment ??
+        value.REQUIRED_ALIGNMENT,
     ),
   };
 }
 
+function schemaHashesEqual(left, right) {
+  const inspectedLeft = inspectPayloadSchemaHash(left);
+  const inspectedRight = inspectPayloadSchemaHash(right);
+  if (!inspectedLeft.valid || !inspectedRight.valid) {
+    return false;
+  }
+  if (!inspectedLeft.present || !inspectedRight.present) {
+    return inspectedLeft.present === inspectedRight.present;
+  }
+  if (inspectedLeft.bytes.length !== inspectedRight.bytes.length) {
+    return false;
+  }
+  return inspectedLeft.bytes.every(
+    (entry, index) => entry === inspectedRight.bytes[index],
+  );
+}
+
+/**
+ * Return true only when two concrete payload type refs carry one complete,
+ * identical SDS logical identity. Schema version and hash are optional, but
+ * when either peer declares one, both peers must declare the same value.
+ */
+export function payloadSchemaIdentitiesEqual(leftTypeRef = {}, rightTypeRef = {}) {
+  const left = clonePayloadTypeRef(leftTypeRef);
+  const right = clonePayloadTypeRef(rightTypeRef);
+  const requiredIdentityFields = [
+    "schemaName",
+    "fileIdentifier",
+    "rootTypeName",
+  ];
+  for (const field of requiredIdentityFields) {
+    if (!left[field] || !right[field] || left[field] !== right[field]) {
+      return false;
+    }
+  }
+  if (
+    (left.schemaVersion || right.schemaVersion) &&
+    left.schemaVersion !== right.schemaVersion
+  ) {
+    return false;
+  }
+  return schemaHashesEqual(left.schemaHash, right.schemaHash);
+}
+
+export function alignedPayloadLayoutsCompatible(leftTypeRef = {}, rightTypeRef = {}) {
+  const left = clonePayloadTypeRef(leftTypeRef);
+  const right = clonePayloadTypeRef(rightTypeRef);
+  if (
+    getPayloadTypeWireFormat(left) !== "aligned-binary" ||
+    getPayloadTypeWireFormat(right) !== "aligned-binary" ||
+    !payloadSchemaIdentitiesEqual(left, right)
+  ) {
+    return false;
+  }
+  return (
+    left.fixedStringLength === right.fixedStringLength &&
+    left.byteLength === right.byteLength &&
+    left.requiredAlignment === right.requiredAlignment
+  );
+}
+
 export function normalizePayloadWireFormatName(value) {
   if (value === undefined || value === null || value === "") {
     return null;
@@ -85,22 +206,23 @@ export function getPayloadTypeWireFormat(typeRef = {}) {
 }
 
 function schemaHashMatches(expected, actual) {
-  if (!Array.isArray(expected) && !(expected instanceof Uint8Array)) {
-    return true;
+  const inspectedExpected = inspectPayloadSchemaHash(expected);
+  if (!inspectedExpected.valid) {
+    return false;
   }
-  const expectedArray = Array.from(expected);
-  if (expectedArray.length === 0) {
+  if (!inspectedExpected.present) {
     return true;
   }
-  const actualArray =
-    Array.isArray(actual) || actual instanceof Uint8Array
-      ? Array.from(actual)
-      : null;
-  if (!actualArray || actualArray.length !== expectedArray.length) {
+  const inspectedActual = inspectPayloadSchemaHash(actual);
+  if (
+    !inspectedActual.valid ||
+    !inspectedActual.present ||
+    inspectedActual.bytes.length !== inspectedExpected.bytes.length
+  ) {
     return false;
   }
-  for (let index = 0; index < expectedArray.length; index += 1) {
-    if (expectedArray[index] !== actualArray[index]) {
+  for (let index = 0; index < inspectedExpected.bytes.length; index += 1) {
+    if (inspectedExpected.bytes[index] !== inspectedActual.bytes[index]) {
       return false;
     }
   }
@@ -117,8 +239,18 @@ export function payloadTypeRefsMatch(expectedTypeRef = {}, actualTypeRef = {}) {
   const expectedWireFormat = getPayloadTypeWireFormat(expected);
   const actualWireFormat = getPayloadTypeWireFormat(actual);
 
+  // A wildcard is blind to FRAMING as well as identity — the JS host and the
+  // in-wasm glue must answer this question identically or the same frame is
+  // admitted in one runtime and refused in the other. Mirror of
+  // WildcardAcceptsWireFormat in src/compiler/invokeGlue.js.
   if (expected.acceptsAnyFlatbuffer === true) {
-    return actualWireFormat === "flatbuffer";
+    if (actualWireFormat === "flatbuffer") {
+      return true;
+    }
+    return (
+      actualWireFormat === "aligned-binary" &&
+      Number(actual.requiredAlignment ?? 0) > 0
+    );
   }
   if (expectedWireFormat !== actualWireFormat) {
     return false;
@@ -132,13 +264,19 @@ export function payloadTypeRefsMatch(expectedTypeRef = {}, actualTypeRef = {}) {
   ) {
     return false;
   }
+  if (
+    expected.schemaVersion &&
+    expected.schemaVersion !== actual.schemaVersion
+  ) {
+    return false;
+  }
   if (!schemaHashMatches(expected.schemaHash, actual.schemaHash)) {
     return false;
   }
+  if (!optionalScalarMatches(expected.rootTypeName, actual.rootTypeName)) {
+    return false;
+  }
   if (expectedWireFormat === "aligned-binary") {
-    if (!optionalScalarMatches(expected.rootTypeName, actual.rootTypeName)) {
-      return false;
-    }
     if (!optionalScalarMatches(expected.fixedStringLength, actual.fixedStringLength)) {
       return false;
     }

package/src/runtime/compiledRuntimeAbi.js

@@ -0,0 +1,47 @@
+export const COMPILED_RUNTIME_HOST_IMPORT_MODULE = "space_data_module_host";
+export const COMPILED_RUNTIME_HOST_DISPATCH = "dispatch_current_invocation";
+
+export const COMPILED_RUNTIME_EXPORTS = Object.freeze({
+  mallocSymbol: "malloc",
+  freeSymbol: "free",
+  descriptorSymbol: "space_data_module_runtime_get_descriptor",
+  nodeDescriptorCountSymbol:
+    "space_data_module_runtime_get_node_descriptor_count",
+  edgeDescriptorCountSymbol:
+    "space_data_module_runtime_get_edge_descriptor_count",
+  triggerDescriptorCountSymbol:
+    "space_data_module_runtime_get_trigger_descriptor_count",
+  dependencyDescriptorCountSymbol:
+    "space_data_module_runtime_get_dependency_descriptor_count",
+  resetStateSymbol: "space_data_module_runtime_reset_state",
+  enqueueTriggerSymbol: "space_data_module_runtime_enqueue_trigger_frames",
+  enqueueTriggerFrameSymbol: "space_data_module_runtime_enqueue_trigger_frame",
+  enqueueEdgeSymbol: "space_data_module_runtime_enqueue_edge_frames",
+  enqueueEdgeFrameSymbol: "space_data_module_runtime_enqueue_edge_frame",
+  readyNodeSymbol: "space_data_module_runtime_get_ready_node_index",
+  beginInvocationSymbol:
+    "space_data_module_runtime_begin_node_invocation",
+  completeInvocationSymbol:
+    "space_data_module_runtime_complete_node_invocation",
+  ingressFrameDescriptorsSymbol:
+    "space_data_module_runtime_get_ingress_frame_descriptors",
+  ingressFrameDescriptorCountSymbol:
+    "space_data_module_runtime_get_ingress_frame_descriptor_count",
+  currentInvocationDescriptorSymbol:
+    "space_data_module_runtime_get_current_invocation_descriptor",
+  prepareInvocationDescriptorSymbol:
+    "space_data_module_runtime_prepare_node_invocation_descriptor",
+  applyInvocationResultSymbol:
+    "space_data_module_runtime_apply_node_invocation_result",
+  nodeDispatchDescriptorsSymbol:
+    "space_data_module_runtime_get_node_dispatch_descriptors",
+  nodeDispatchDescriptorCountSymbol:
+    "space_data_module_runtime_get_node_dispatch_descriptor_count",
+  dependencyDescriptorsSymbol:
+    "space_data_module_runtime_get_dependency_descriptors",
+  dependencyCountSymbol: "space_data_module_runtime_get_dependency_count",
+  nodeRuntimeStateSymbol: "space_data_module_runtime_get_node_states",
+  ingressRuntimeStateSymbol: "space_data_module_runtime_get_ingress_states",
+  dispatchCurrentInvocationSymbol:
+    "space_data_module_runtime_dispatch_current_invocation_direct",
+});

package/src/runtime/compiledRuntimeAbi.json

@@ -0,0 +1,33 @@
+{
+  "hostImportModule": "space_data_module_host",
+  "hostDispatchImport": "dispatch_current_invocation",
+  "exports": {
+    "mallocSymbol": "malloc",
+    "freeSymbol": "free",
+    "descriptorSymbol": "space_data_module_runtime_get_descriptor",
+    "nodeDescriptorCountSymbol": "space_data_module_runtime_get_node_descriptor_count",
+    "edgeDescriptorCountSymbol": "space_data_module_runtime_get_edge_descriptor_count",
+    "triggerDescriptorCountSymbol": "space_data_module_runtime_get_trigger_descriptor_count",
+    "dependencyDescriptorCountSymbol": "space_data_module_runtime_get_dependency_descriptor_count",
+    "resetStateSymbol": "space_data_module_runtime_reset_state",
+    "enqueueTriggerSymbol": "space_data_module_runtime_enqueue_trigger_frames",
+    "enqueueTriggerFrameSymbol": "space_data_module_runtime_enqueue_trigger_frame",
+    "enqueueEdgeSymbol": "space_data_module_runtime_enqueue_edge_frames",
+    "enqueueEdgeFrameSymbol": "space_data_module_runtime_enqueue_edge_frame",
+    "readyNodeSymbol": "space_data_module_runtime_get_ready_node_index",
+    "beginInvocationSymbol": "space_data_module_runtime_begin_node_invocation",
+    "completeInvocationSymbol": "space_data_module_runtime_complete_node_invocation",
+    "ingressFrameDescriptorsSymbol": "space_data_module_runtime_get_ingress_frame_descriptors",
+    "ingressFrameDescriptorCountSymbol": "space_data_module_runtime_get_ingress_frame_descriptor_count",
+    "currentInvocationDescriptorSymbol": "space_data_module_runtime_get_current_invocation_descriptor",
+    "prepareInvocationDescriptorSymbol": "space_data_module_runtime_prepare_node_invocation_descriptor",
+    "applyInvocationResultSymbol": "space_data_module_runtime_apply_node_invocation_result",
+    "nodeDispatchDescriptorsSymbol": "space_data_module_runtime_get_node_dispatch_descriptors",
+    "nodeDispatchDescriptorCountSymbol": "space_data_module_runtime_get_node_dispatch_descriptor_count",
+    "dependencyDescriptorsSymbol": "space_data_module_runtime_get_dependency_descriptors",
+    "dependencyCountSymbol": "space_data_module_runtime_get_dependency_count",
+    "nodeRuntimeStateSymbol": "space_data_module_runtime_get_node_states",
+    "ingressRuntimeStateSymbol": "space_data_module_runtime_get_ingress_states",
+    "dispatchCurrentInvocationSymbol": "space_data_module_runtime_dispatch_current_invocation_direct"
+  }
+}

package/src/runtime/index.d.ts

@@ -13,3 +13,35 @@ export {
 export function isArrayBufferLike(value: unknown): boolean;
 export function hasByteAddressableBuffer(value: unknown): boolean;
 export function toUint8Array(value: unknown): Uint8Array | null;
+
+export const COMPILED_RUNTIME_HOST_IMPORT_MODULE: "space_data_module_host";
+export const COMPILED_RUNTIME_HOST_DISPATCH: "dispatch_current_invocation";
+export const COMPILED_RUNTIME_EXPORTS: Readonly<{
+  mallocSymbol: "malloc";
+  freeSymbol: "free";
+  descriptorSymbol: "space_data_module_runtime_get_descriptor";
+  nodeDescriptorCountSymbol: "space_data_module_runtime_get_node_descriptor_count";
+  edgeDescriptorCountSymbol: "space_data_module_runtime_get_edge_descriptor_count";
+  triggerDescriptorCountSymbol: "space_data_module_runtime_get_trigger_descriptor_count";
+  dependencyDescriptorCountSymbol: "space_data_module_runtime_get_dependency_descriptor_count";
+  resetStateSymbol: "space_data_module_runtime_reset_state";
+  enqueueTriggerSymbol: "space_data_module_runtime_enqueue_trigger_frames";
+  enqueueTriggerFrameSymbol: "space_data_module_runtime_enqueue_trigger_frame";
+  enqueueEdgeSymbol: "space_data_module_runtime_enqueue_edge_frames";
+  enqueueEdgeFrameSymbol: "space_data_module_runtime_enqueue_edge_frame";
+  readyNodeSymbol: "space_data_module_runtime_get_ready_node_index";
+  beginInvocationSymbol: "space_data_module_runtime_begin_node_invocation";
+  completeInvocationSymbol: "space_data_module_runtime_complete_node_invocation";
+  ingressFrameDescriptorsSymbol: "space_data_module_runtime_get_ingress_frame_descriptors";
+  ingressFrameDescriptorCountSymbol: "space_data_module_runtime_get_ingress_frame_descriptor_count";
+  currentInvocationDescriptorSymbol: "space_data_module_runtime_get_current_invocation_descriptor";
+  prepareInvocationDescriptorSymbol: "space_data_module_runtime_prepare_node_invocation_descriptor";
+  applyInvocationResultSymbol: "space_data_module_runtime_apply_node_invocation_result";
+  nodeDispatchDescriptorsSymbol: "space_data_module_runtime_get_node_dispatch_descriptors";
+  nodeDispatchDescriptorCountSymbol: "space_data_module_runtime_get_node_dispatch_descriptor_count";
+  dependencyDescriptorsSymbol: "space_data_module_runtime_get_dependency_descriptors";
+  dependencyCountSymbol: "space_data_module_runtime_get_dependency_count";
+  nodeRuntimeStateSymbol: "space_data_module_runtime_get_node_states";
+  ingressRuntimeStateSymbol: "space_data_module_runtime_get_ingress_states";
+  dispatchCurrentInvocationSymbol: "space_data_module_runtime_dispatch_current_invocation_direct";
+}>;

package/src/runtime/index.js

@@ -1,2 +1,3 @@
 export * from "./bufferLike.js";
 export * from "./constants.js";
+export * from "./compiledRuntimeAbi.js";

package/src/runtime-host/index.js

@@ -111,3 +111,6 @@ export {
   createModuleRegistry,
   createRuntimeRegionStore,
 };
+// Flow-tier validating method registry (vendored sdn-flow semantics; distinct
+// from createModuleRegistry's module-lifecycle registry).
+export { MethodRegistry } from "./methodRegistry.js";

package/src/runtime-host/methodRegistry.js

@@ -0,0 +1,55 @@
+/**
+ * Manifest-aware flow-tier method registry (ported from
+ * orbpro-integration/sdk/src/runtime/MethodRegistry.js).
+ *
+ * This wraps the VENDORED sdn-flow MethodRegistry (src/flow/vendor/sdn-flow —
+ * behavior-identical to the sdn-flow pin at 4dd28e2; validation semantics like
+ * duplicate-plugin rejection, missing-handler errors, required-port presence,
+ * min/max stream bounds, acceptedTypeSets matching, and outputStreamCap
+ * enforcement are preserved verbatim) and adds manifest coercion: callers may
+ * register with a PluginManifestT, PMAN flatbuffer bytes, or a plain object.
+ *
+ * Distinct from createModuleRegistry (module lifecycle install/load/unload):
+ * this is the flow-graph invoke registry the JS FlowRuntime interpreter and
+ * the SdnCompatAdapter dispatch through.
+ */
+import { MethodRegistry as VendoredSdnFlowMethodRegistry } from "../flow/vendor/sdn-flow/index.js";
+import { normalizeManifestForSdnFlow } from "../flow/normalize.js";
+
+export class MethodRegistry {
+  #registry = new VendoredSdnFlowMethodRegistry();
+
+  registerPlugin({ manifest, handlers = {}, plugin = null }) {
+    return this.#registry.registerPlugin({
+      manifest: normalizeManifestForSdnFlow(manifest),
+      handlers,
+      plugin,
+    });
+  }
+
+  getPlugin(pluginId) {
+    return this.#registry.getPlugin(pluginId);
+  }
+
+  unregisterPlugin(pluginId) {
+    return this.#registry.unregisterPlugin(pluginId);
+  }
+
+  getMethod(pluginId, methodId) {
+    return this.#registry.getMethod(pluginId, methodId);
+  }
+
+  listPlugins() {
+    return this.#registry.listPlugins();
+  }
+
+  async invoke(options) {
+    return this.#registry.invoke(options);
+  }
+
+  clear() {
+    this.#registry.clear();
+  }
+}
+
+export default MethodRegistry;