@qubic.ts/contracts 0.1.0

package/src/codec/entry-input.ts

@@ -0,0 +1,959 @@
+import type {
+  ContractDefinition,
+  ContractEntry,
+  ContractEntryKind,
+  ContractIoTypeDefinition,
+  ContractsRegistry,
+} from "../registry/types.js";
+
+type ContractsInput = ContractsRegistry | readonly ContractDefinition[];
+
+export type EncodeContractEntryInputOptions = Readonly<{
+  registry: ContractsInput;
+  contractName: string;
+  entryName: string;
+  kind?: ContractEntryKind;
+  value: unknown;
+  allowSequentialLayout?: boolean;
+}>;
+
+export type DecodeContractEntryInputOptions = Readonly<{
+  registry: ContractsInput;
+  contractName: string;
+  entryName: string;
+  kind?: ContractEntryKind;
+  bytes: Uint8Array;
+  allowSequentialLayout?: boolean;
+}>;
+
+export type EncodedContractEntryInput = Readonly<{
+  contractName: string;
+  entryName: string;
+  kind: ContractEntryKind;
+  inputType: number;
+  inputTypeName: string;
+  bytes: Uint8Array;
+}>;
+
+export type DecodedContractEntryInput<T = unknown> = Readonly<{
+  contractName: string;
+  entryName: string;
+  kind: ContractEntryKind;
+  inputType: number;
+  inputTypeName: string;
+  value: T;
+}>;
+
+type CodecContext = Readonly<{
+  ioTypeByName: ReadonlyMap<string, ContractIoTypeDefinition>;
+  allowSequentialLayout: boolean;
+}>;
+
+const MAX_SAFE_U64 = 18_446_744_073_709_551_615n;
+const MAX_SAFE_U128 = (1n << 128n) - 1n;
+const MIN_SAFE_S64 = -(1n << 63n);
+const MAX_SAFE_S64 = (1n << 63n) - 1n;
+
+export function encodeContractEntryInputData(
+  options: EncodeContractEntryInputOptions,
+): EncodedContractEntryInput {
+  const contract = resolveContract(options.registry, options.contractName);
+  const entry = resolveEntry(contract, options.entryName, options.kind);
+  const inputTypeName = resolveEntryInputTypeName(entry);
+  const context = createCodecContext(contract, options.allowSequentialLayout ?? false);
+
+  const ioType = context.ioTypeByName.get(inputTypeName);
+  const encoded = ioType
+    ? encodeByTypeDefinition(ioType, options.value, context, [inputTypeName])
+    : encodeWithoutTypeDefinition(entry, inputTypeName, options.value);
+
+  return {
+    contractName: contract.name,
+    entryName: entry.name,
+    kind: entry.kind,
+    inputType: entry.inputType,
+    inputTypeName,
+    bytes: encoded,
+  };
+}
+
+export function decodeContractEntryInputData<T = unknown>(
+  options: DecodeContractEntryInputOptions,
+): DecodedContractEntryInput<T> {
+  const contract = resolveContract(options.registry, options.contractName);
+  const entry = resolveEntry(contract, options.entryName, options.kind);
+  const inputTypeName = resolveEntryInputTypeName(entry);
+  const context = createCodecContext(contract, options.allowSequentialLayout ?? false);
+  const ioType = context.ioTypeByName.get(inputTypeName);
+
+  if (!ioType) {
+    return {
+      contractName: contract.name,
+      entryName: entry.name,
+      kind: entry.kind,
+      inputType: entry.inputType,
+      inputTypeName,
+      value: options.bytes.slice() as T,
+    };
+  }
+
+  const decoded = decodeByTypeDefinition(ioType, options.bytes, context, [inputTypeName]);
+  if (decoded.byteLength !== options.bytes.length) {
+    throw new Error(
+      `Input bytes contain trailing data for ${contract.name}.${entry.name}: consumed ${decoded.byteLength} of ${options.bytes.length}`,
+    );
+  }
+
+  return {
+    contractName: contract.name,
+    entryName: entry.name,
+    kind: entry.kind,
+    inputType: entry.inputType,
+    inputTypeName,
+    value: decoded.value as T,
+  };
+}
+
+function resolveContract(registry: ContractsInput, contractName: string): ContractDefinition {
+  const contracts = isContractsRegistry(registry) ? registry.contracts : registry;
+  const contract = contracts.find((item) => item.name === contractName);
+  if (!contract) {
+    throw new Error(`Unknown contract: ${contractName}`);
+  }
+  return contract;
+}
+
+function isContractsRegistry(value: ContractsInput): value is ContractsRegistry {
+  return !Array.isArray(value);
+}
+
+function resolveEntry(
+  contract: ContractDefinition,
+  entryName: string,
+  kind?: ContractEntryKind,
+): ContractEntry {
+  const matches = contract.entries.filter(
+    (entry) => entry.name === entryName && (kind ? entry.kind === kind : true),
+  );
+  if (matches.length === 0) {
+    throw new Error(`Unknown contract entry: ${contract.name}.${entryName}`);
+  }
+  if (matches.length > 1) {
+    throw new Error(
+      `Ambiguous contract entry: ${contract.name}.${entryName}. Specify kind ("function" | "procedure").`,
+    );
+  }
+  return matches[0] as ContractEntry;
+}
+
+function resolveEntryInputTypeName(entry: ContractEntry): string {
+  return entry.inputTypeName ?? `${entry.name}_input`;
+}
+
+function createCodecContext(
+  contract: ContractDefinition,
+  allowSequentialLayout: boolean,
+): CodecContext {
+  const ioTypeByName = new Map((contract.ioTypes ?? []).map((typeDef) => [typeDef.name, typeDef]));
+  return {
+    ioTypeByName,
+    allowSequentialLayout,
+  };
+}
+
+function encodeWithoutTypeDefinition(
+  entry: ContractEntry,
+  inputTypeName: string,
+  value: unknown,
+): Uint8Array {
+  if (value instanceof Uint8Array) {
+    if (entry.inputSize !== undefined && value.length !== entry.inputSize) {
+      throw new Error(
+        `Input byte size mismatch for ${entry.name}: expected ${entry.inputSize}, received ${value.length}`,
+      );
+    }
+    return value.slice();
+  }
+
+  throw new Error(
+    `No io type definition found for ${inputTypeName}. Provide raw Uint8Array input bytes or regenerate with --io-extractor castxml.`,
+  );
+}
+
+function encodeByTypeDefinition(
+  typeDef: ContractIoTypeDefinition,
+  value: unknown,
+  context: CodecContext,
+  path: readonly string[],
+): Uint8Array {
+  if (typeDef.kind === "alias") {
+    const nestedTypeName = resolveIoTypeName(typeDef.target, context.ioTypeByName);
+    if (nestedTypeName) {
+      const nested = context.ioTypeByName.get(nestedTypeName) as ContractIoTypeDefinition;
+      const encoded = encodeByTypeDefinition(nested, value, context, [...path, nestedTypeName]);
+      if (typeDef.byteSize !== undefined && encoded.length !== typeDef.byteSize) {
+        throw new Error(
+          `Encoded alias byte size mismatch at ${path.join(".")}: expected ${typeDef.byteSize}, received ${encoded.length}`,
+        );
+      }
+      return encoded;
+    }
+
+    return encodeByTypeExpression(typeDef.target, value, context, path, typeDef.byteSize);
+  }
+
+  return encodeStruct(typeDef, value, context, path);
+}
+
+function encodeStruct(
+  typeDef: Extract<ContractIoTypeDefinition, { kind: "struct" }>,
+  value: unknown,
+  context: CodecContext,
+  path: readonly string[],
+): Uint8Array {
+  const objectValue = asRecord(value, path);
+
+  const hasOffsets = typeDef.fields.every((field) => field.byteOffset !== undefined);
+  if (hasOffsets) {
+    if (typeDef.byteSize === undefined) {
+      throw new Error(
+        `Missing byteSize metadata for ${path.join(".")}. Regenerate with --io-extractor castxml.`,
+      );
+    }
+
+    const out = new Uint8Array(typeDef.byteSize);
+    for (const field of typeDef.fields) {
+      const fieldValue = objectValue[field.name];
+      const fieldPath = [...path, field.name];
+      const fieldBytes = encodeByTypeExpression(field.type, fieldValue, context, fieldPath);
+      const fieldOffset = field.byteOffset as number;
+      if (fieldOffset + fieldBytes.length > out.length) {
+        throw new Error(`Encoded field exceeds struct size at ${fieldPath.join(".")}`);
+      }
+      out.set(fieldBytes, fieldOffset);
+    }
+    return out;
+  }
+
+  if (!context.allowSequentialLayout) {
+    throw new Error(
+      `Missing byteOffset metadata for ${path.join(".")}. Regenerate with --io-extractor castxml or set allowSequentialLayout=true.`,
+    );
+  }
+
+  const fieldBytes: Uint8Array[] = [];
+  for (const field of typeDef.fields) {
+    const fieldValue = objectValue[field.name];
+    fieldBytes.push(encodeByTypeExpression(field.type, fieldValue, context, [...path, field.name]));
+  }
+  return concatBytes(fieldBytes);
+}
+
+function encodeByTypeExpression(
+  typeExpression: string,
+  value: unknown,
+  context: CodecContext,
+  path: readonly string[],
+  expectedByteSize?: number,
+): Uint8Array {
+  const normalizedType = normalizeTypeExpression(typeExpression);
+
+  const resolvedTypeName = resolveIoTypeName(normalizedType, context.ioTypeByName);
+  if (resolvedTypeName) {
+    const typeDef = context.ioTypeByName.get(resolvedTypeName) as ContractIoTypeDefinition;
+    const encoded = encodeByTypeDefinition(typeDef, value, context, [...path, resolvedTypeName]);
+    if (expectedByteSize !== undefined && encoded.length !== expectedByteSize) {
+      throw new Error(
+        `Encoded value size mismatch at ${path.join(".")}: expected ${expectedByteSize}, received ${encoded.length}`,
+      );
+    }
+    return encoded;
+  }
+
+  const arraySpec = parseArrayType(normalizedType);
+  if (arraySpec) {
+    const arrayValue = asArray(value, path);
+    if (arrayValue.length !== arraySpec.length) {
+      throw new Error(
+        `Invalid array length at ${path.join(".")}: expected ${arraySpec.length}, received ${arrayValue.length}`,
+      );
+    }
+    const encodedItems = arrayValue.map((item, index) =>
+      encodeByTypeExpression(arraySpec.elementType, item, context, [...path, String(index)]),
+    );
+    const out = concatBytes(encodedItems);
+    if (expectedByteSize !== undefined && out.length !== expectedByteSize) {
+      throw new Error(
+        `Encoded value size mismatch at ${path.join(".")}: expected ${expectedByteSize}, received ${out.length}`,
+      );
+    }
+    return out;
+  }
+
+  const primitive = encodePrimitiveValue(normalizedType, value, path, expectedByteSize);
+  if (primitive) return primitive;
+
+  if (
+    value instanceof Uint8Array &&
+    expectedByteSize !== undefined &&
+    value.length === expectedByteSize
+  ) {
+    return value.slice();
+  }
+
+  throw new Error(`Unsupported type expression at ${path.join(".")}: ${typeExpression}`);
+}
+
+function decodeByTypeDefinition(
+  typeDef: ContractIoTypeDefinition,
+  bytes: Uint8Array,
+  context: CodecContext,
+  path: readonly string[],
+): Readonly<{ value: unknown; byteLength: number }> {
+  if (typeDef.kind === "alias") {
+    const nestedTypeName = resolveIoTypeName(typeDef.target, context.ioTypeByName);
+    if (nestedTypeName) {
+      const nested = context.ioTypeByName.get(nestedTypeName) as ContractIoTypeDefinition;
+      return decodeByTypeDefinition(nested, bytes, context, [...path, nestedTypeName]);
+    }
+
+    return decodeByTypeExpression(typeDef.target, bytes, context, path, typeDef.byteSize);
+  }
+
+  return decodeStruct(typeDef, bytes, context, path);
+}
+
+function decodeStruct(
+  typeDef: Extract<ContractIoTypeDefinition, { kind: "struct" }>,
+  bytes: Uint8Array,
+  context: CodecContext,
+  path: readonly string[],
+): Readonly<{ value: unknown; byteLength: number }> {
+  const hasOffsets = typeDef.fields.every((field) => field.byteOffset !== undefined);
+  const objectValue: Record<string, unknown> = {};
+
+  if (hasOffsets) {
+    if (typeDef.byteSize === undefined) {
+      throw new Error(
+        `Missing byteSize metadata for ${path.join(".")}. Regenerate with --io-extractor castxml.`,
+      );
+    }
+    if (bytes.length < typeDef.byteSize) {
+      throw new Error(
+        `Input bytes are shorter than expected for ${path.join(".")}: expected at least ${typeDef.byteSize}, received ${bytes.length}`,
+      );
+    }
+
+    for (const field of typeDef.fields) {
+      const fieldPath = [...path, field.name];
+      const fieldOffset = field.byteOffset as number;
+      const fieldSize = resolveTypeByteLength(field.type, context, new Set());
+      if (fieldSize === undefined) {
+        throw new Error(`Cannot resolve field size at ${fieldPath.join(".")} (${field.type})`);
+      }
+
+      const slice = bytes.subarray(fieldOffset, fieldOffset + fieldSize);
+      const decoded = decodeByTypeExpression(field.type, slice, context, fieldPath, fieldSize);
+      objectValue[field.name] = decoded.value;
+    }
+
+    return {
+      value: objectValue,
+      byteLength: typeDef.byteSize,
+    };
+  }
+
+  if (!context.allowSequentialLayout) {
+    throw new Error(
+      `Missing byteOffset metadata for ${path.join(".")}. Regenerate with --io-extractor castxml or set allowSequentialLayout=true.`,
+    );
+  }
+
+  let cursor = 0;
+  for (const field of typeDef.fields) {
+    const fieldSize = resolveTypeByteLength(field.type, context, new Set());
+    if (fieldSize === undefined) {
+      throw new Error(
+        `Cannot resolve field size at ${[...path, field.name].join(".")} (${field.type})`,
+      );
+    }
+    const slice = bytes.subarray(cursor, cursor + fieldSize);
+    const decoded = decodeByTypeExpression(
+      field.type,
+      slice,
+      context,
+      [...path, field.name],
+      fieldSize,
+    );
+    objectValue[field.name] = decoded.value;
+    cursor += fieldSize;
+  }
+
+  return {
+    value: objectValue,
+    byteLength: cursor,
+  };
+}
+
+function decodeByTypeExpression(
+  typeExpression: string,
+  bytes: Uint8Array,
+  context: CodecContext,
+  path: readonly string[],
+  expectedByteSize?: number,
+): Readonly<{ value: unknown; byteLength: number }> {
+  const normalizedType = normalizeTypeExpression(typeExpression);
+
+  const resolvedTypeName = resolveIoTypeName(normalizedType, context.ioTypeByName);
+  if (resolvedTypeName) {
+    const typeDef = context.ioTypeByName.get(resolvedTypeName) as ContractIoTypeDefinition;
+    const decoded = decodeByTypeDefinition(typeDef, bytes, context, [...path, resolvedTypeName]);
+    if (expectedByteSize !== undefined && decoded.byteLength !== expectedByteSize) {
+      throw new Error(
+        `Decoded byte size mismatch at ${path.join(".")}: expected ${expectedByteSize}, received ${decoded.byteLength}`,
+      );
+    }
+    return decoded;
+  }
+
+  const arraySpec = parseArrayType(normalizedType);
+  if (arraySpec) {
+    const values: unknown[] = [];
+    const elementSize = resolveTypeByteLength(arraySpec.elementType, context, new Set());
+    if (elementSize === undefined) {
+      throw new Error(
+        `Cannot resolve array element size at ${path.join(".")} (${arraySpec.elementType})`,
+      );
+    }
+
+    let cursor = 0;
+    for (let i = 0; i < arraySpec.length; i++) {
+      const slice = bytes.subarray(cursor, cursor + elementSize);
+      const decoded = decodeByTypeExpression(
+        arraySpec.elementType,
+        slice,
+        context,
+        [...path, String(i)],
+        elementSize,
+      );
+      values.push(decoded.value);
+      cursor += elementSize;
+    }
+
+    if (expectedByteSize !== undefined && cursor !== expectedByteSize) {
+      throw new Error(
+        `Decoded byte size mismatch at ${path.join(".")}: expected ${expectedByteSize}, received ${cursor}`,
+      );
+    }
+
+    return { value: values, byteLength: cursor };
+  }
+
+  const primitive = decodePrimitiveValue(normalizedType, bytes, path, expectedByteSize);
+  if (primitive) return primitive;
+
+  if (expectedByteSize !== undefined && bytes.length >= expectedByteSize) {
+    return {
+      value: bytes.subarray(0, expectedByteSize),
+      byteLength: expectedByteSize,
+    };
+  }
+
+  throw new Error(`Unsupported type expression at ${path.join(".")}: ${typeExpression}`);
+}
+
+function resolveTypeByteLength(
+  typeExpression: string,
+  context: CodecContext,
+  seen: Set<string>,
+): number | undefined {
+  const normalizedType = normalizeTypeExpression(typeExpression);
+  if (seen.has(normalizedType)) {
+    throw new Error(`Recursive type definition detected: ${normalizedType}`);
+  }
+
+  const primitiveSize = getPrimitiveByteLength(normalizedType);
+  if (primitiveSize !== undefined) return primitiveSize;
+
+  const arraySpec = parseArrayType(normalizedType);
+  if (arraySpec) {
+    const elementSize = resolveTypeByteLength(arraySpec.elementType, context, seen);
+    return elementSize !== undefined ? elementSize * arraySpec.length : undefined;
+  }
+
+  const resolvedTypeName = resolveIoTypeName(normalizedType, context.ioTypeByName);
+  if (!resolvedTypeName) return undefined;
+  const typeDef = context.ioTypeByName.get(resolvedTypeName);
+  if (!typeDef) return undefined;
+
+  seen.add(resolvedTypeName);
+  if (typeDef.byteSize !== undefined) {
+    seen.delete(resolvedTypeName);
+    return typeDef.byteSize;
+  }
+
+  if (typeDef.kind === "alias") {
+    const size = resolveTypeByteLength(typeDef.target, context, seen);
+    seen.delete(resolvedTypeName);
+    return size;
+  }
+
+  if (!context.allowSequentialLayout) {
+    seen.delete(resolvedTypeName);
+    return undefined;
+  }
+
+  let total = 0;
+  for (const field of typeDef.fields) {
+    const fieldSize = resolveTypeByteLength(field.type, context, seen);
+    if (fieldSize === undefined) {
+      seen.delete(resolvedTypeName);
+      return undefined;
+    }
+    total += fieldSize;
+  }
+  seen.delete(resolvedTypeName);
+  return total;
+}
+
+function normalizeTypeExpression(value: string): string {
+  return value
+    .trim()
+    .replace(/\bQPI::/g, "")
+    .replace(/^::+/, "")
+    .replace(/\bint8_t\b/g, "sint8")
+    .replace(/\buint8_t\b/g, "uint8")
+    .replace(/\bint16_t\b/g, "sint16")
+    .replace(/\buint16_t\b/g, "uint16")
+    .replace(/\bint32_t\b/g, "sint32")
+    .replace(/\buint32_t\b/g, "uint32")
+    .replace(/\bint64_t\b/g, "sint64")
+    .replace(/\buint64_t\b/g, "uint64")
+    .replace(/\bconst\b/g, "")
+    .replace(/\bvolatile\b/g, "")
+    .replace(/\bstruct\b/g, "")
+    .replace(/\bclass\b/g, "")
+    .replace(/\s*&+/g, "")
+    .replace(/\s*\*+/g, "")
+    .replace(/\s+/g, " ")
+    .replace(/\s*<\s*/g, "<")
+    .replace(/\s*>\s*/g, ">")
+    .replace(/\s*,\s*/g, ", ")
+    .trim();
+}
+
+function resolveIoTypeName(
+  typeExpression: string,
+  ioTypeByName: ReadonlyMap<string, ContractIoTypeDefinition>,
+): string | undefined {
+  for (const candidate of getTypeLookupCandidates(typeExpression)) {
+    if (ioTypeByName.has(candidate)) return candidate;
+  }
+  return undefined;
+}
+
+function getTypeLookupCandidates(value: string): readonly string[] {
+  const candidates: string[] = [];
+  const seen = new Set<string>();
+
+  const push = (candidate: string | undefined): void => {
+    const normalized = normalizeTypeExpression(candidate ?? "");
+    if (!normalized || seen.has(normalized)) return;
+    seen.add(normalized);
+    candidates.push(normalized);
+  };
+
+  const normalized = normalizeTypeExpression(value);
+  push(normalized);
+  push(extractUnqualifiedTypeName(normalized));
+
+  const templateBase = extractTemplateBaseName(normalized);
+  if (templateBase) {
+    push(templateBase);
+    push(extractUnqualifiedTypeName(templateBase));
+  }
+
+  return candidates;
+}
+
+function extractTemplateBaseName(value: string): string | undefined {
+  const index = value.indexOf("<");
+  if (index <= 0) return undefined;
+  return value.slice(0, index).trim();
+}
+
+function extractUnqualifiedTypeName(value: string): string {
+  const trimmed = value.trim();
+  const segments = trimmed.split("::").filter((segment) => segment.length > 0);
+  return segments[segments.length - 1] ?? trimmed;
+}
+
+function parseArrayType(value: string): Readonly<{ elementType: string; length: number }> | null {
+  const genericMatch = value.match(/^Array<(.*)>$/);
+  if (genericMatch) {
+    const args = splitTopLevelGenericArgs(genericMatch[1] ?? "");
+    const elementType = args[0]?.trim();
+    const lengthRaw = args[1]?.trim();
+    const length = lengthRaw ? Number.parseInt(lengthRaw, 10) : Number.NaN;
+    if (elementType && Number.isFinite(length) && length >= 0) {
+      return { elementType, length };
+    }
+  }
+
+  const cArrayMatch = value.match(/^(.*)\[(\d+)\]$/);
+  if (!cArrayMatch) return null;
+  const elementType = cArrayMatch[1]?.trim();
+  const length = Number.parseInt(cArrayMatch[2] ?? "", 10);
+  if (!elementType || !Number.isFinite(length) || length < 0) return null;
+  return { elementType, length };
+}
+
+function splitTopLevelGenericArgs(value: string): readonly string[] {
+  const out: string[] = [];
+  let depth = 0;
+  let current = "";
+
+  for (const char of value) {
+    if (char === "<") depth += 1;
+    if (char === ">") depth = Math.max(0, depth - 1);
+    if (char === "," && depth === 0) {
+      out.push(current);
+      current = "";
+      continue;
+    }
+    current += char;
+  }
+
+  if (current.trim().length > 0) out.push(current);
+  return out;
+}
+
+function encodePrimitiveValue(
+  typeName: string,
+  value: unknown,
+  path: readonly string[],
+  expectedByteSize?: number,
+): Uint8Array | null {
+  switch (typeName) {
+    case "NoData":
+      validateNoData(value, path);
+      return withExpectedSize(new Uint8Array(1), expectedByteSize, path);
+    case "bit":
+    case "bool":
+      return withExpectedSize(Uint8Array.of(asBoolByte(value, path)), expectedByteSize, path);
+    case "sint8":
+      return withExpectedSize(
+        Uint8Array.of(asInt(value, -0x80, 0x7f, path) & 0xff),
+        expectedByteSize,
+        path,
+      );
+    case "uint8":
+      return withExpectedSize(Uint8Array.of(asInt(value, 0, 0xff, path)), expectedByteSize, path);
+    case "sint16":
+      return withExpectedSize(
+        writeInt16(asInt(value, -0x8000, 0x7fff, path)),
+        expectedByteSize,
+        path,
+      );
+    case "uint16":
+      return withExpectedSize(writeUint16(asInt(value, 0, 0xffff, path)), expectedByteSize, path);
+    case "sint32":
+      return withExpectedSize(
+        writeInt32(asInt(value, -0x8000_0000, 0x7fff_ffff, path)),
+        expectedByteSize,
+        path,
+      );
+    case "uint32":
+      return withExpectedSize(
+        writeUint32(asInt(value, 0, 0xffff_ffff, path)),
+        expectedByteSize,
+        path,
+      );
+    case "sint64":
+      return withExpectedSize(
+        writeBigInt64(asBigInt(value, MIN_SAFE_S64, MAX_SAFE_S64, path)),
+        expectedByteSize,
+        path,
+      );
+    case "uint64":
+      return withExpectedSize(
+        writeBigUint64(asBigInt(value, 0n, MAX_SAFE_U64, path)),
+        expectedByteSize,
+        path,
+      );
+    case "uint128":
+      return withExpectedSize(
+        writeBigUint128(asBigInt(value, 0n, MAX_SAFE_U128, path)),
+        expectedByteSize,
+        path,
+      );
+    case "id":
+    case "m256i":
+      return withExpectedSize(encodeId32(value, path), expectedByteSize, path);
+    default:
+      return null;
+  }
+}
+
+function decodePrimitiveValue(
+  typeName: string,
+  bytes: Uint8Array,
+  path: readonly string[],
+  expectedByteSize?: number,
+): Readonly<{ value: unknown; byteLength: number }> | null {
+  const size = getPrimitiveByteLength(typeName);
+  if (size === undefined) return null;
+
+  const expected = expectedByteSize ?? size;
+  if (bytes.length < expected) {
+    throw new Error(
+      `Not enough bytes at ${path.join(".")} for ${typeName}: expected ${expected}, received ${bytes.length}`,
+    );
+  }
+  const view = bytes.subarray(0, size);
+
+  switch (typeName) {
+    case "NoData":
+      return { value: {}, byteLength: expected };
+    case "bit":
+    case "bool":
+      return { value: view[0] !== 0, byteLength: expected };
+    case "sint8":
+      return {
+        value: new DataView(view.buffer, view.byteOffset, 1).getInt8(0),
+        byteLength: expected,
+      };
+    case "uint8":
+      return { value: view[0], byteLength: expected };
+    case "sint16":
+      return {
+        value: new DataView(view.buffer, view.byteOffset, 2).getInt16(0, true),
+        byteLength: expected,
+      };
+    case "uint16":
+      return {
+        value: new DataView(view.buffer, view.byteOffset, 2).getUint16(0, true),
+        byteLength: expected,
+      };
+    case "sint32":
+      return {
+        value: new DataView(view.buffer, view.byteOffset, 4).getInt32(0, true),
+        byteLength: expected,
+      };
+    case "uint32":
+      return {
+        value: new DataView(view.buffer, view.byteOffset, 4).getUint32(0, true),
+        byteLength: expected,
+      };
+    case "sint64":
+      return {
+        value: new DataView(view.buffer, view.byteOffset, 8).getBigInt64(0, true),
+        byteLength: expected,
+      };
+    case "uint64":
+      return {
+        value: new DataView(view.buffer, view.byteOffset, 8).getBigUint64(0, true),
+        byteLength: expected,
+      };
+    case "uint128":
+      return { value: readBigUint128(view), byteLength: expected };
+    case "id":
+    case "m256i":
+      return { value: decodeId32(view), byteLength: expected };
+    default:
+      return null;
+  }
+}
+
+function getPrimitiveByteLength(typeName: string): number | undefined {
+  switch (typeName) {
+    case "NoData":
+    case "bit":
+    case "bool":
+    case "sint8":
+    case "uint8":
+      return 1;
+    case "sint16":
+    case "uint16":
+      return 2;
+    case "sint32":
+    case "uint32":
+      return 4;
+    case "sint64":
+    case "uint64":
+      return 8;
+    case "uint128":
+      return 16;
+    case "id":
+    case "m256i":
+      return 32;
+    default:
+      return undefined;
+  }
+}
+
+function asRecord(value: unknown, path: readonly string[]): Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new Error(`Expected object at ${path.join(".")}`);
+  }
+  return value as Record<string, unknown>;
+}
+
+function asArray(value: unknown, path: readonly string[]): readonly unknown[] {
+  if (!Array.isArray(value)) {
+    throw new Error(`Expected array at ${path.join(".")}`);
+  }
+  return value;
+}
+
+function validateNoData(value: unknown, path: readonly string[]): void {
+  if (value === undefined || value === null) return;
+  if (
+    typeof value === "object" &&
+    !Array.isArray(value) &&
+    Object.keys(value as object).length === 0
+  ) {
+    return;
+  }
+  throw new Error(`Expected empty object for NoData at ${path.join(".")}`);
+}
+
+function asBoolByte(value: unknown, path: readonly string[]): number {
+  if (typeof value === "boolean") return value ? 1 : 0;
+  if (typeof value === "number" && (value === 0 || value === 1)) return value;
+  throw new Error(`Expected boolean (or 0/1) at ${path.join(".")}`);
+}
+
+function asInt(value: unknown, min: number, max: number, path: readonly string[]): number {
+  if (typeof value !== "number" || !Number.isInteger(value)) {
+    throw new Error(`Expected integer number at ${path.join(".")}`);
+  }
+  if (value < min || value > max) {
+    throw new Error(
+      `Integer out of range at ${path.join(".")}: expected ${min}..${max}, received ${value}`,
+    );
+  }
+  return value;
+}
+
+function asBigInt(value: unknown, min: bigint, max: bigint, path: readonly string[]): bigint {
+  const out =
+    typeof value === "bigint"
+      ? value
+      : typeof value === "number" && Number.isInteger(value)
+        ? BigInt(value)
+        : null;
+
+  if (out === null) {
+    throw new Error(`Expected bigint (or integer number) at ${path.join(".")}`);
+  }
+  if (out < min || out > max) {
+    throw new Error(`BigInt out of range at ${path.join(".")}`);
+  }
+  return out;
+}
+
+function writeInt16(value: number): Uint8Array {
+  const out = new Uint8Array(2);
+  new DataView(out.buffer).setInt16(0, value, true);
+  return out;
+}
+
+function writeUint16(value: number): Uint8Array {
+  const out = new Uint8Array(2);
+  new DataView(out.buffer).setUint16(0, value, true);
+  return out;
+}
+
+function writeInt32(value: number): Uint8Array {
+  const out = new Uint8Array(4);
+  new DataView(out.buffer).setInt32(0, value, true);
+  return out;
+}
+
+function writeUint32(value: number): Uint8Array {
+  const out = new Uint8Array(4);
+  new DataView(out.buffer).setUint32(0, value, true);
+  return out;
+}
+
+function writeBigInt64(value: bigint): Uint8Array {
+  const out = new Uint8Array(8);
+  new DataView(out.buffer).setBigInt64(0, value, true);
+  return out;
+}
+
+function writeBigUint64(value: bigint): Uint8Array {
+  const out = new Uint8Array(8);
+  new DataView(out.buffer).setBigUint64(0, value, true);
+  return out;
+}
+
+function writeBigUint128(value: bigint): Uint8Array {
+  const out = new Uint8Array(16);
+  let current = value;
+  for (let i = 0; i < out.length; i++) {
+    out[i] = Number(current & 0xffn);
+    current >>= 8n;
+  }
+  return out;
+}
+
+function readBigUint128(value: Uint8Array): bigint {
+  let out = 0n;
+  for (let i = value.length - 1; i >= 0; i--) {
+    out = (out << 8n) | BigInt(value[i] ?? 0);
+  }
+  return out;
+}
+
+function encodeId32(value: unknown, path: readonly string[]): Uint8Array {
+  if (value instanceof Uint8Array) {
+    if (value.length !== 32) {
+      throw new Error(`Expected 32-byte id at ${path.join(".")}`);
+    }
+    return value.slice();
+  }
+
+  if (typeof value === "string") {
+    const hex = value.startsWith("0x") ? value.slice(2) : value;
+    if (!/^[0-9a-fA-F]{64}$/.test(hex)) {
+      throw new Error(`Expected 32-byte id hex string at ${path.join(".")}`);
+    }
+    const out = new Uint8Array(32);
+    for (let i = 0; i < 32; i++) {
+      out[i] = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+    }
+    return out;
+  }
+
+  throw new Error(`Expected 32-byte id (hex string or Uint8Array) at ${path.join(".")}`);
+}
+
+function decodeId32(value: Uint8Array): string {
+  return `0x${[...value].map((byte) => byte.toString(16).padStart(2, "0")).join("")}`;
+}
+
+function withExpectedSize(
+  value: Uint8Array,
+  expectedByteSize: number | undefined,
+  path: readonly string[],
+): Uint8Array {
+  if (expectedByteSize !== undefined && value.length !== expectedByteSize) {
+    throw new Error(
+      `Encoded value size mismatch at ${path.join(".")}: expected ${expectedByteSize}, received ${value.length}`,
+    );
+  }
+  return value;
+}
+
+function concatBytes(chunks: readonly Uint8Array[]): Uint8Array {
+  const total = chunks.reduce((sum, chunk) => sum + chunk.length, 0);
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    out.set(chunk, offset);
+    offset += chunk.length;
+  }
+  return out;
+}