arch: Enhanced codec with explicit edge case handling

[bbopen]

Overview

Multiple issues relate to codec edge cases that fail silently or with unclear errors. This tracking issue proposes enhanced codec error handling and edge case support.

Related Issues

• Surface Pydantic model_dump failures explicitly #55 - Surface Pydantic model_dump failures explicitly
• Reject dicts with non-string keys explicitly #54 - Reject dicts with non-string keys explicitly
• Handle bytes/bytearray return values explicitly #53 - Handle bytes/bytearray return values explicitly
• Invalid TYWRAP_CODEC_MAX_BYTES should surface explicit error #52 - Invalid TYWRAP_CODEC_MAX_BYTES should surface explicit error
• Add adversarial coverage for optional codec edge cases #48 - Add adversarial coverage for optional codec edge cases
• Serialize numpy/pandas scalar return values #41 - Serialize numpy/pandas scalar return values

Proposed Architecture

New Error Type

export class BridgeCodecError extends BridgeError {
  constructor(
    message: string,
    public readonly codecPhase: 'encode' | 'decode',
    public readonly valueType: string,
    options?: ErrorOptions
  ) {
    super(message, options);
  }
}

Explicit Edge Case Handlers

// src/utils/codec.ts

function encodeValue(value: unknown): unknown {
  // Dict key validation
  if (isPlainObject(value)) {
    for (const key of Object.keys(value)) {
      if (typeof key !== 'string') {
        throw new BridgeCodecError(
          `Dict keys must be strings, got ${typeof key}`,
          'encode',
          'dict'
        );
      }
    }
  }
  
  // Bytes handling
  if (value instanceof Uint8Array || value instanceof ArrayBuffer) {
    throw new BridgeCodecError(
      'bytes/bytearray must be base64 encoded before sending',
      'encode',
      'bytes'
    );
  }
  
  return value;
}

function decodeValue(value: unknown): unknown {
  // numpy/pandas scalar handling
  if (isNumpyScalar(value)) {
    return convertNumpyScalar(value);
  }
  
  // Pydantic model handling
  if (isPydanticModel(value)) {
    try {
      return value.model_dump();
    } catch (error) {
      throw new BridgeCodecError(
        'Pydantic model_dump() failed',
        'decode',
        'pydantic',
        { cause: error }
      );
    }
  }
  
  return value;
}

Environment Validation

function getMaxBytesFromEnv(): number {
  const raw = process.env.TYWRAP_CODEC_MAX_BYTES;
  if (!raw) return DEFAULT_MAX_BYTES;
  
  const parsed = parseInt(raw, 10);
  if (!Number.isFinite(parsed) || parsed <= 0) {
    throw new BridgeCodecError(
      `Invalid TYWRAP_CODEC_MAX_BYTES: ${raw}`,
      'encode',
      'config'
    );
  }
  return parsed;
}

Acceptance Criteria

• Non-string dict keys throw explicit BridgeCodecError
• bytes/bytearray values have clear error or explicit encoding
• Pydantic model_dump failures surface with context
• numpy/pandas scalars serialize correctly
• Invalid env vars throw explicit errors
• Adversarial tests cover all edge cases
• All 6 related issues can be closed

Scope

This fix touches:

• src/utils/codec.ts - edge case handling
• src/runtime/errors.ts - BridgeCodecError type
• runtime/python_bridge.py - Python-side encoding
• test/adversarial_playground.test.ts - edge case tests

[bbopen]

Superseded by #149

This issue is addressed by the unified BoundedContext abstraction proposed in #149.

The codec edge case concerns here will be implemented via:

• validateOutput(output) override in codec layer
• Explicit validation before serialization
• classifyError() for clear codec error messages

The codec will extend BoundedContext and validate outputs before JSON serialization.