Enforce non-empty OCF arrays and quality guardrails

jest.config.js

@@ -9,10 +9,10 @@ module.exports = {
   collectCoverageFrom: ['src/**/*.ts', '!src/**/*.d.ts'],
   coverageThreshold: {
     global: {
-      branches: 60,
-      functions: 68,
-      lines: 72,
-      statements: 72,
+      branches: 68,
+      functions: 76,
+      lines: 75,
+      statements: 75,
     },
   },
   setupFilesAfterEnv: ['<rootDir>/test/setupTests.ts'],

package.json

@@ -49,7 +49,7 @@
     "test": "npm run -s typecheck && jest --passWithNoTests",
     "test:ci": "npm run -s typecheck && jest --runInBand --coverage",
     "test:coverage": "jest --coverage --passWithNoTests",
-    "test:declarations": "ts-node --project tsconfig.tests.json scripts/check-declarations.ts && tsc -p tsconfig.declaration-tests.json --noEmit && npm run -s test:exact-public-config",
+    "test:declarations": "ts-node --project tsconfig.tests.json scripts/check-declarations.ts && tsc -p tsconfig.declaration-tests.json --noEmit && npm run -s test:exact-public-config && node scripts/check-built-cardinality.cjs",
     "test:exact-public-config": "tsc -p tsconfig.exact-public-config-tests.json --noEmit",
     "test:integration": "npm run -s typecheck && jest -c jest.integration.config.js --passWithNoTests",
     "test:integration:ci": "npm run -s typecheck && jest -c jest.integration.config.js --runInBand",

scripts/check-built-cardinality.cjs

@@ -0,0 +1,101 @@
+'use strict';
+
+const assert = require('node:assert/strict');
+
+function loadBuiltModules() {
+  const originalConsoleDebug = console.debug;
+  const originalConsoleLog = console.log;
+  try {
+    console.debug = () => undefined;
+    console.log = () => undefined;
+    return {
+      errors: require('../dist/errors'),
+      readDispatcher: require('../dist/functions/OpenCapTable/capTable/damlToOcf'),
+      stockConsolidationWriter: require('../dist/functions/OpenCapTable/stockConsolidation/stockConsolidationDataToDaml'),
+      stockTransferWriter: require('../dist/functions/OpenCapTable/stockTransfer/createStockTransfer'),
+      typeConversions: require('../dist/utils/typeConversions'),
+    };
+  } finally {
+    console.debug = originalConsoleDebug;
+    console.log = originalConsoleLog;
+  }
+}
+
+const built = loadBuiltModules();
+const { OcpErrorCodes, OcpValidationError } = built.errors;
+const { convertToOcf } = built.readDispatcher;
+const { stockConsolidationDataToDaml } = built.stockConsolidationWriter;
+const { stockTransferDataToDaml } = built.stockTransferWriter;
+const { toNonEmptyStringArray } = built.typeConversions;
+
+function expectValidationError(action, expectedPath, expectedCode) {
+  assert.throws(action, (error) => {
+    assert(error instanceof OcpValidationError);
+    assert.equal(error.fieldPath, expectedPath);
+    assert.equal(error.code, expectedCode);
+    return true;
+  });
+}
+
+expectValidationError(
+  () => toNonEmptyStringArray(['duplicate', 'duplicate'], 'items', { uniqueItems: true }),
+  'items.1',
+  OcpErrorCodes.INVALID_FORMAT
+);
+
+let trapCalls = 0;
+const proxy = new Proxy(['secret'], {
+  get(target, property, receiver) {
+    trapCalls += 1;
+    return Reflect.get(target, property, receiver);
+  },
+  ownKeys(target) {
+    trapCalls += 1;
+    return Reflect.ownKeys(target);
+  },
+});
+expectValidationError(() => toNonEmptyStringArray(proxy, 'items'), 'items', OcpErrorCodes.SCHEMA_MISMATCH);
+assert.equal(trapCalls, 0);
+
+const transferDaml = {
+  balance_security_id: null,
+  comments: [],
+  consideration_text: null,
+  date: '2026-01-01T00:00:00.000Z',
+  id: 'transfer-1',
+  quantity: '1',
+  resulting_security_ids: ['duplicate', 'duplicate'],
+  security_id: 'security-1',
+};
+expectValidationError(
+  () => convertToOcf('stockTransfer', transferDaml),
+  'stockTransfer.resulting_security_ids.1',
+  OcpErrorCodes.INVALID_FORMAT
+);
+
+expectValidationError(
+  () =>
+    stockTransferDataToDaml({
+      date: '2026-01-01',
+      id: 'transfer-1',
+      object_type: 'TX_STOCK_TRANSFER',
+      quantity: '1',
+      resulting_security_ids: ['duplicate', 'duplicate'],
+      security_id: 'security-1',
+    }),
+  'stockTransfer.resulting_security_ids.1',
+  OcpErrorCodes.INVALID_FORMAT
+);
+
+expectValidationError(
+  () =>
+    stockConsolidationDataToDaml({
+      date: '2026-01-01',
+      id: 'consolidation-1',
+      object_type: 'TX_STOCK_CONSOLIDATION',
+      security_ids: [],
+      resulting_security_id: 'result-1',
+    }),
+  'stockConsolidation.security_ids',
+  OcpErrorCodes.OUT_OF_RANGE
+);

src/functions/OpenCapTable/convertibleTransfer/convertibleTransferDataToDaml.ts

@@ -1,27 +1,33 @@
-import { OcpErrorCodes, OcpValidationError } from '../../../errors';
+import { OcpValidationError } from '../../../errors';
 import type { OcfConvertibleTransfer } from '../../../types';
-import { cleanComments, dateStringToDAMLTime, monetaryToDaml, optionalString } from '../../../utils/typeConversions';
+import {
+  cleanComments,
+  dateStringToDAMLTime,
+  monetaryToDaml,
+  optionalString,
+  toNonEmptyStringArray,
+} from '../../../utils/typeConversions';
+import { assertCanonicalJsonGraph } from '../shared/ocfValues';
 
 export function convertibleTransferDataToDaml(d: OcfConvertibleTransfer): Record<string, unknown> {
+  assertCanonicalJsonGraph(d, 'convertibleTransfer', { rejectUndefined: true });
   if (!d.id) {
     throw new OcpValidationError('convertibleTransfer.id', 'Required field is missing or empty', {
       expectedType: 'string',
       receivedValue: d.id,
     });
   }
-  // Validate required array field
-  if (d.resulting_security_ids.length === 0) {
-    throw new OcpValidationError('convertibleTransfer.resulting_security_ids', 'Must contain at least one element', {
-      code: OcpErrorCodes.REQUIRED_FIELD_MISSING,
-      receivedValue: d.resulting_security_ids,
-    });
-  }
+  const resultingSecurityIds = toNonEmptyStringArray(
+    d.resulting_security_ids,
+    'convertibleTransfer.resulting_security_ids',
+    { uniqueItems: true }
+  );
   return {
     id: d.id,
     date: dateStringToDAMLTime(d.date, 'convertibleTransfer.date'),
     security_id: d.security_id,
     amount: monetaryToDaml(d.amount),
-    resulting_security_ids: d.resulting_security_ids,
+    resulting_security_ids: resultingSecurityIds,
     balance_security_id: optionalString(d.balance_security_id),
     consideration_text: optionalString(d.consideration_text),
     comments: cleanComments(d.comments),

src/functions/OpenCapTable/convertibleTransfer/damlToOcf.ts

@@ -3,7 +3,7 @@
  */
 
 import type { OcfConvertibleTransfer } from '../../../types';
-import { damlMonetaryToNative, damlTimeToDateString } from '../../../utils/typeConversions';
+import { damlMonetaryToNative, damlTimeToDateString, toNonEmptyStringArray } from '../../../utils/typeConversions';
 
 /**
  * DAML ConvertibleTransfer data structure.
@@ -33,7 +33,11 @@ export function damlConvertibleTransferToNative(d: DamlConvertibleTransferData):
     date: damlTimeToDateString(d.date, 'convertibleTransfer.date'),
     security_id: d.security_id,
     amount: damlMonetaryToNative(d.amount),
-    resulting_security_ids: d.resulting_security_ids,
+    resulting_security_ids: toNonEmptyStringArray(
+      d.resulting_security_ids,
+      'convertibleTransfer.resulting_security_ids',
+      { uniqueItems: true }
+    ),
     ...(d.balance_security_id ? { balance_security_id: d.balance_security_id } : {}),
     ...(d.consideration_text ? { consideration_text: d.consideration_text } : {}),
     ...(Array.isArray(d.comments) && d.comments.length > 0 ? { comments: d.comments } : {}),

src/functions/OpenCapTable/convertibleTransfer/getConvertibleTransferAsOcf.ts

@@ -2,7 +2,7 @@ import type { LedgerJsonApiClient } from '@fairmint/canton-node-sdk';
 import { type Fairmint } from '@fairmint/open-captable-protocol-daml-js';
 import type { GetByContractIdParams } from '../../../types/common';
 import type { OcfConvertibleTransfer } from '../../../types/native';
-import { damlTimeToDateString, normalizeNumericString } from '../../../utils/typeConversions';
+import { damlTimeToDateString, normalizeNumericString, toNonEmptyStringArray } from '../../../utils/typeConversions';
 import { readSingleContract } from '../shared/singleContractRead';
 
 /**
@@ -48,7 +48,11 @@ export async function getConvertibleTransferAsOcf(
       amount: normalizeNumericString(amountStr),
       currency: data.amount.currency,
     },
-    resulting_security_ids: data.resulting_security_ids,
+    resulting_security_ids: toNonEmptyStringArray(
+      data.resulting_security_ids,
+      'convertibleTransfer.resulting_security_ids',
+      { uniqueItems: true }
+    ),
     ...(data.balance_security_id ? { balance_security_id: data.balance_security_id } : {}),
     ...(data.consideration_text ? { consideration_text: data.consideration_text } : {}),
     ...(Array.isArray(data.comments) && data.comments.length ? { comments: data.comments } : {}),

src/functions/OpenCapTable/equityCompensationIssuance/getEquityCompensationIssuanceAsOcf.ts

@@ -7,9 +7,11 @@ import type {
   PeriodType,
   TerminationWindowReason,
 } from '../../../types/native';
+import { assertSafeGeneratedDamlJson } from '../../../utils/generatedDamlValidation';
 import {
   damlTimeToDateString,
   isRecord,
+  nonEmptyArrayOrUndefined,
   normalizeNumericString,
   nullableDamlTimeToDateString,
   optionalDamlTimeToDateString,
@@ -111,40 +113,43 @@ export function damlEquityCompensationIssuanceDataToNative(d: Record<string, unk
   const basePrice = equityCompensationMonetaryFromDaml(d.base_price, 'equityCompensationIssuance.base_price');
 
   const vestings =
-    Array.isArray(d.vestings) && d.vestings.length > 0
-      ? d.vestings.map((v, index) => {
-          if (!isRecord(v)) {
-            throw new OcpValidationError(
-              `equityCompensationIssuance.vestings[${index}]`,
-              `Must be an object, got ${v === null ? 'null' : Array.isArray(v) ? 'array' : typeof v}`,
-              {
-                code: OcpErrorCodes.INVALID_TYPE,
-                expectedType: 'object',
-                receivedValue: v,
-              }
-            );
-          }
+    d.vestings === undefined
+      ? undefined
+      : (() => {
+          assertSafeGeneratedDamlJson(d.vestings, 'equityCompensationIssuance.vestings');
+          return nonEmptyArrayOrUndefined(d.vestings, 'equityCompensationIssuance.vestings', (v, { index }) => {
+            if (!isRecord(v)) {
+              throw new OcpValidationError(
+                `equityCompensationIssuance.vestings[${index}]`,
+                `Must be an object, got ${v === null ? 'null' : Array.isArray(v) ? 'array' : typeof v}`,
+                {
+                  code: OcpErrorCodes.INVALID_TYPE,
+                  expectedType: 'object',
+                  receivedValue: v,
+                }
+              );
+            }
 
-          // Validate vesting amount
-          if (typeof v.amount !== 'string' && typeof v.amount !== 'number') {
-            throw new OcpValidationError(
-              `equityCompensationIssuance.vestings[${index}].amount`,
-              `Must be string or number, got ${typeof v.amount}`,
-              {
-                code: OcpErrorCodes.INVALID_TYPE,
-                expectedType: 'string | number',
-                receivedValue: v.amount,
-              }
-            );
-          }
-          // Convert to string after validation
-          const amountStr = typeof v.amount === 'number' ? v.amount.toString() : v.amount;
-          return {
-            date: damlTimeToDateString(v.date, `equityCompensationIssuance.vestings[${index}].date`),
-            amount: normalizeNumericString(amountStr),
-          };
-        })
-      : undefined;
+            // Validate vesting amount
+            if (typeof v.amount !== 'string' && typeof v.amount !== 'number') {
+              throw new OcpValidationError(
+                `equityCompensationIssuance.vestings[${index}].amount`,
+                `Must be string or number, got ${typeof v.amount}`,
+                {
+                  code: OcpErrorCodes.INVALID_TYPE,
+                  expectedType: 'string | number',
+                  receivedValue: v.amount,
+                }
+              );
+            }
+            // Convert to string after validation
+            const amountStr = typeof v.amount === 'number' ? v.amount.toString() : v.amount;
+            return {
+              date: damlTimeToDateString(v.date, `equityCompensationIssuance.vestings[${index}].date`),
+              amount: normalizeNumericString(amountStr),
+            };
+          });
+        })();
 
   const terminationWindows = optionalCollection(
     d.termination_exercise_windows,

src/functions/OpenCapTable/equityCompensationTransfer/equityCompensationTransferDataToDaml.ts

@@ -1,33 +1,33 @@
-import { OcpErrorCodes, OcpValidationError } from '../../../errors';
+import { OcpValidationError } from '../../../errors';
 import type { OcfEquityCompensationTransfer } from '../../../types';
 import {
   cleanComments,
   dateStringToDAMLTime,
   normalizeNumericString,
   optionalString,
+  toNonEmptyStringArray,
 } from '../../../utils/typeConversions';
+import { assertCanonicalJsonGraph } from '../shared/ocfValues';
 
 export function equityCompensationTransferDataToDaml(d: OcfEquityCompensationTransfer): Record<string, unknown> {
+  assertCanonicalJsonGraph(d, 'equityCompensationTransfer', { rejectUndefined: true });
   if (!d.id) {
     throw new OcpValidationError('equityCompensationTransfer.id', 'Required field is missing or empty', {
       expectedType: 'string',
       receivedValue: d.id,
     });
   }
-  // Validate required array field
-  if (d.resulting_security_ids.length === 0) {
-    throw new OcpValidationError(
-      'equityCompensationTransfer.resulting_security_ids',
-      'Must contain at least one element',
-      { code: OcpErrorCodes.REQUIRED_FIELD_MISSING, receivedValue: d.resulting_security_ids }
-    );
-  }
+  const resultingSecurityIds = toNonEmptyStringArray(
+    d.resulting_security_ids,
+    'equityCompensationTransfer.resulting_security_ids',
+    { uniqueItems: true }
+  );
   return {
     id: d.id,
     date: dateStringToDAMLTime(d.date, 'equityCompensationTransfer.date'),
     security_id: d.security_id,
     quantity: normalizeNumericString(d.quantity),
-    resulting_security_ids: d.resulting_security_ids,
+    resulting_security_ids: resultingSecurityIds,
     balance_security_id: optionalString(d.balance_security_id),
     consideration_text: optionalString(d.consideration_text),
     comments: cleanComments(d.comments),

src/functions/OpenCapTable/equityCompensationTransfer/getEquityCompensationTransferAsOcf.ts

@@ -2,7 +2,7 @@ import type { LedgerJsonApiClient } from '@fairmint/canton-node-sdk';
 import { type Fairmint } from '@fairmint/open-captable-protocol-daml-js';
 import type { GetByContractIdParams } from '../../../types/common';
 import type { OcfEquityCompensationTransfer } from '../../../types/native';
-import { damlTimeToDateString, normalizeNumericString } from '../../../utils/typeConversions';
+import { damlTimeToDateString, normalizeNumericString, toNonEmptyStringArray } from '../../../utils/typeConversions';
 import { readSingleContract } from '../shared/singleContractRead';
 
 /**
@@ -46,7 +46,11 @@ export async function getEquityCompensationTransferAsOcf(
     date: damlTimeToDateString(data.date, 'equityCompensationTransfer.date'),
     security_id: data.security_id,
     quantity: normalizeNumericString(quantityStr),
-    resulting_security_ids: data.resulting_security_ids,
+    resulting_security_ids: toNonEmptyStringArray(
+      data.resulting_security_ids,
+      'equityCompensationTransfer.resulting_security_ids',
+      { uniqueItems: true }
+    ),
     ...(data.balance_security_id ? { balance_security_id: data.balance_security_id } : {}),
     ...(data.consideration_text ? { consideration_text: data.consideration_text } : {}),
     ...(Array.isArray(data.comments) && data.comments.length ? { comments: data.comments } : {}),