Model canonical conversion mechanisms

src/errors/OcpError.ts

@@ -17,7 +17,7 @@ export interface OcpErrorDetails {
 }
 
 const MAX_DIAGNOSTIC_STRING_LENGTH = 256;
-const MAX_DIAGNOSTIC_TEXT_LENGTH = 768;
+const MAX_DIAGNOSTIC_TEXT_LENGTH = 512;
 const MAX_DIAGNOSTIC_CONTAINER_ITEMS = 12;
 const MAX_DIAGNOSTIC_DEPTH = 6;
 const MAX_DIAGNOSTIC_NODES = 48;
@@ -304,13 +304,41 @@ export class OcpError extends Error {
 
   /** Return a globally bounded, JSON-safe representation for logs and telemetry. */
   toJSON(): unknown {
-    return toSafeDiagnosticValue({
-      name: this.name,
-      code: this.code,
-      message: this.message,
-      classification: this.classification,
-      context: this.context,
-      ...(this.cause !== undefined ? { cause: this.cause } : {}),
-    });
+    const ownDataValue = (key: string): unknown => {
+      const descriptor = Object.getOwnPropertyDescriptor(this, key);
+      return descriptor !== undefined && 'value' in descriptor ? descriptor.value : undefined;
+    };
+    const rawName = ownDataValue('name');
+    const rawMessage = ownDataValue('message');
+    const rawCode = ownDataValue('code');
+    const rawClassification = ownDataValue('classification');
+    const rawContext = ownDataValue('context');
+    const rawCause = ownDataValue('cause');
+    const result: Record<string, unknown> = {
+      name: typeof rawName === 'string' ? toSafeDiagnosticText(rawName) : 'OcpError',
+      message: typeof rawMessage === 'string' ? toSafeDiagnosticText(rawMessage) : 'OCP SDK error',
+      code: toSafeDiagnosticValue(rawCode),
+      ...(typeof rawClassification === 'string'
+        ? { classification: toSafeDiagnosticText(rawClassification, 256) }
+        : {}),
+      ...(rawContext !== undefined ? { context: toSafeDiagnosticValue(rawContext) } : {}),
+      ...(rawCause !== undefined ? { cause: toSafeDiagnosticValue(rawCause) } : {}),
+    };
+
+    for (const key of [
+      'fieldPath',
+      'expectedType',
+      'receivedValue',
+      'source',
+      'contractId',
+      'templateId',
+      'choice',
+      'endpoint',
+      'statusCode',
+    ]) {
+      const value = ownDataValue(key);
+      if (value !== undefined) result[key] = toSafeDiagnosticValue(value);
+    }
+    return toSafeDiagnosticValue(result);
   }
 }

src/errors/diagnosticValue.ts

@@ -0,0 +1,137 @@
+import { types as nodeUtilTypes } from 'node:util';
+
+const MAX_DIAGNOSTIC_STRING_LENGTH = 256;
+const MAX_DIAGNOSTIC_KEY_LENGTH = 64;
+const MAX_DIAGNOSTIC_CONTAINER_ITEMS = 12;
+const MAX_DIAGNOSTIC_DEPTH = 2;
+const MAX_DIAGNOSTIC_NODES = 8;
+
+interface DiagnosticState {
+  nodes: number;
+  readonly seen: WeakSet<object>;
+}
+
+function truncate(value: string, maximum = MAX_DIAGNOSTIC_STRING_LENGTH): string {
+  if (value.length <= maximum) return value;
+  const suffix = `...[${value.length} chars]`;
+  return `${value.slice(0, Math.max(0, maximum - suffix.length))}${suffix}`;
+}
+
+/** Bound text that may become part of an SDK diagnostic message. */
+export function boundedDiagnosticText(value: string): string {
+  return truncate(value, 512);
+}
+
+/** Bound user-influenced paths while preserving ordinary field paths verbatim. */
+export function boundedDiagnosticPath(value: string): string {
+  return truncate(value, 512);
+}
+
+/** Build a bounded child path without retaining an arbitrarily large property name. */
+export function diagnosticPropertyPath(parent: string, property: string | symbol): string {
+  const boundedParent = boundedDiagnosticPath(parent);
+  if (typeof property === 'symbol') {
+    return boundedDiagnosticPath(`${boundedParent}[${truncate(String(property), 96)}]`);
+  }
+  const boundedProperty = truncate(property, 96);
+  const path = /^(?:0|[1-9]\d*|[A-Za-z_$][A-Za-z0-9_$]*)$/.test(boundedProperty)
+    ? `${boundedParent}.${boundedProperty}`
+    : `${boundedParent}[${JSON.stringify(boundedProperty)}]`;
+  return boundedDiagnosticPath(path);
+}
+
+function metadata(type: string, details: Readonly<Record<string, string | number | boolean>> = {}): unknown {
+  return { type, ...details };
+}
+
+function summarize(value: unknown, depth: number, state: DiagnosticState): unknown {
+  if (value === null || value === undefined) return value;
+
+  const valueType = typeof value;
+  if (valueType === 'string') return truncate(value as string);
+  if (valueType === 'boolean') return value;
+  if (valueType === 'number') return value;
+  if (valueType === 'bigint') return metadata('bigint');
+  if (valueType === 'symbol') {
+    const symbolValue = value as symbol;
+    const { description } = symbolValue;
+    return metadata('symbol', description === undefined ? {} : { description: truncate(description) });
+  }
+
+  if (nodeUtilTypes.isProxy(value)) return metadata('proxy');
+  if (valueType === 'function') return metadata('function');
+  if (valueType !== 'object') return metadata(valueType);
+
+  const object = value;
+  if (state.seen.has(object)) return metadata('circular');
+  if (depth >= MAX_DIAGNOSTIC_DEPTH || state.nodes >= MAX_DIAGNOSTIC_NODES) {
+    return metadata(Array.isArray(object) ? 'array' : 'object');
+  }
+
+  state.nodes += 1;
+  state.seen.add(object);
+  try {
+    if (Array.isArray(object)) {
+      const { length } = object;
+      if (length > MAX_DIAGNOSTIC_CONTAINER_ITEMS) return metadata('array', { length });
+
+      const result: unknown[] = [];
+      for (let index = 0; index < length; index += 1) {
+        const descriptor = Object.getOwnPropertyDescriptor(object, String(index));
+        if (descriptor === undefined) {
+          result.push(metadata('array-hole'));
+        } else if ('value' in descriptor) {
+          result.push(summarize(descriptor.value, depth + 1, state));
+        } else {
+          result.push(metadata('accessor'));
+        }
+      }
+      return result;
+    }
+
+    const prototype = Object.getPrototypeOf(object) as object | null;
+    if (prototype !== Object.prototype && prototype !== null) return metadata('object');
+
+    const keys = Object.getOwnPropertyNames(object);
+    const symbols = Object.getOwnPropertySymbols(object);
+    if (keys.length > MAX_DIAGNOSTIC_CONTAINER_ITEMS || keys.some((key) => key.length > MAX_DIAGNOSTIC_KEY_LENGTH)) {
+      return metadata('object', { keys: keys.length, symbolKeys: symbols.length });
+    }
+
+    const result: Record<string, unknown> = {};
+    for (const key of keys) {
+      const descriptor = Object.getOwnPropertyDescriptor(object, key);
+      const summarized =
+        descriptor === undefined
+          ? metadata('missing-property')
+          : 'value' in descriptor
+            ? summarize(descriptor.value, depth + 1, state)
+            : metadata('accessor');
+      Object.defineProperty(result, key, { configurable: true, enumerable: true, value: summarized, writable: true });
+    }
+    if (symbols.length > 0) result.$symbolKeys = symbols.length;
+    return result;
+  } catch {
+    return metadata('uninspectable-object');
+  } finally {
+    state.seen.delete(object);
+  }
+}
+
+/**
+ * Convert arbitrary runtime input into a JSON-safe, size-bounded diagnostic.
+ * No getters, custom serializers, or Proxy traps are invoked.
+ */
+export function toBoundedDiagnosticValue(value: unknown): unknown {
+  return summarize(value, 0, { nodes: 0, seen: new WeakSet<object>() });
+}
+
+/** Convert arbitrary structured error context into a bounded JSON-safe record. */
+export function toBoundedDiagnosticContext(value: unknown): Record<string, unknown> | undefined {
+  if (value === undefined) return undefined;
+  const summarized = toBoundedDiagnosticValue(value);
+  if (summarized === null || typeof summarized !== 'object' || Array.isArray(summarized)) {
+    return { value: summarized };
+  }
+  return summarized as Record<string, unknown>;
+}

src/functions/OpenCapTable/capTable/batchTypes.ts

@@ -9,11 +9,11 @@ import { Fairmint } from '@fairmint/open-captable-protocol-daml-js';
 import type { OcfObjectType } from '../../../types/native';
 import type {
   OcfCreatableEntityType,
-  OcfDataTypeFor,
   OcfDeletableEntityType,
   OcfEditableEntityType,
   OcfEntityDataMap,
   OcfEntityType,
+  OcfWritableDataTypeFor,
 } from './entityTypes';
 
 export {
@@ -40,6 +40,7 @@ export {
   type OcfEntityTypeForObjectType,
   type OcfReadableDataForObjectType,
   type OcfReadableObjectType,
+  type OcfWritableDataTypeFor,
 } from './entityTypes';
 
 // Re-export DAML types for convenience
@@ -500,7 +501,7 @@ export type DamlEntityArguments = {
 
 /** Correlated entity-kind and native-data tuples accepted by the converter dispatcher. */
 export type OcfEntityArguments = {
-  [EntityType in OcfEntityType]: readonly [type: EntityType, data: OcfDataTypeFor<EntityType>];
+  [EntityType in OcfEntityType]: readonly [type: EntityType, data: OcfWritableDataTypeFor<EntityType>];
 }[OcfEntityType];
 
 function entityRegistryEntries(): Array<[OcfEntityType, OcfEntityRegistryEntry]> {