Architecture

Signal Dataset is organized into four public domains with a one-way dependency direction:

              record ──┐
_internal ─────────────┼──> dataset ──> annotation ──> top-level facade
              storage ─┘

_internal owns JSON primitives and format constants. record owns immutable logical values, record descriptors, validation, and record/metadata codecs. storage owns transport and indexed-byte container contracts. dataset owns control-document layouts and composes the foundations into immutable ordered datasets. annotation adds snapshot-aligned derived data. The top-level package is a curated convenience facade; it contains no implementation.

Persisted-format documents are versioned independently from the Python package, so the package version and the layout version move on their own schedules. The layout a build writes is LAYOUT_VERSION, and the layouts it accepts are SUPPORTED_LAYOUT_VERSIONS, both in signal_dataset._internal.constants. Moving Python symbols never changes persisted bytes or meanings.

Imports must not point against the dependency direction. The complete allowed matrix is:

Domain	May import project code from
_internal	_internal
record	_internal, record, errors
storage	_internal, storage, errors
dataset	_internal, record, storage, dataset, errors
annotation	_internal, record, storage, dataset, annotation, errors
top-level facade	all public domains and errors

The top-level __init__.py may only import and export names; it contains no operational logic.