Add MATLAB-Python bridge contracts for epoch and common namespaces

[stevevanhooser]

Summary

This PR introduces formal MATLAB-Python bridge contracts via YAML specification files for the ndi.epoch and ndi.common namespaces. These contracts document the API mapping between MATLAB and Python implementations, establishing clear naming policies, indexing conventions, and design decisions for cross-language compatibility.

Key Changes

• Added src/ndi/epoch/ndi_matlab_python_bridge.yaml: Comprehensive bridge contract for the epoch namespace covering:

  • 6 standalone functions (epochrange, findepochnode, is_epoch_or_empty, parse_devicestring, build_devicestring)
  • 4 classes: epochset (abstract base), epoch, epochprobemap, and epochprobemap_daqsystem
  • Detailed method signatures, type mappings, and decision logs explaining divergences
  • Semantic parity indexing policy: 1-based for user-facing concepts, 0-based for internal data access

• Added src/ndi/common/ndi_matlab_python_bridge.yaml: Bridge contract for the common namespace covering:

  • 4 standalone functions (timestamp, getLogger, getCache, getDatabaseHierarchy, assertDIDInstalled)
  • 1 class: PathConstants with class properties and configuration methods
  • Type mappings and design rationale for each API element

• Removed deprecated get_logger alias: Cleaned up backwards compatibility wrapper in src/ndi/common/__init__.py and updated imports in src/ndi/__init__.py to use only the canonical getLogger function name

Notable Implementation Details

• Bridge contracts establish "Strict MATLAB Mirror" naming policy while allowing Python-idiomatic implementations (e.g., immutable tuples instead of cell arrays, pathlib.Path instead of char arrays)
• Indexing policy explicitly documents the intentional divergence in findepochnode: MATLAB returns 1-based indices for user concepts, Python returns 0-based indices for internal array access
• Extracted utility functions (parse_devicestring, build_devicestring) are documented as Python-specific refactorings of inline MATLAB logic
• All abstract methods, properties, and computed properties are explicitly documented with their Python equivalents

https://claude.ai/code/session_012G5yTp2wY8NwPHZzNbbahD