diff --git a/docs/FORMAT.md b/docs/FORMAT.md index e4e648c2..3abf4294 100644 --- a/docs/FORMAT.md +++ b/docs/FORMAT.md @@ -19,7 +19,7 @@ The single overriding rule: **a canonical episode is spec-conforming MCAP.** Eve - MCAP magic, `Header`, data section, `DataEnd`, summary section, `Footer`, closing magic, per the [MCAP spec](https://mcap.dev/spec). - `Header.profile` is the empty string `""` (the file mixes protobuf video channels with pass-through channels of arbitrary encoding, so no single profile applies). -- `Header.library` is informational only (currently `hebbian-mcap/0.1.2`). Its exact value is not part of the format contract, and no reader may key behavior off it (see [Identifier rules](#identifier-rules)). +- `Header.library` is informational only (currently `hflow`, with no version, so a release that serializes the same way writes the same bytes). Its exact value is not part of the format contract, and no reader may key behavior off it (see [Identifier rules](#identifier-rules)). - Chunks are compressed with **zstd** by default (`"none"` is permitted). Each `Chunk` record carries `uncompressed_crc`; the `Footer` carries a summary CRC. - The summary section repeats all `Schema` and `Channel` records and contains `Statistics`, all `ChunkIndex` records, `AttachmentIndex`/`MetadataIndex` records, and `SummaryOffset` records. A canonical episode always has a complete summary; unindexed files are not canonical. - Each topic names exactly one channel. MCAP allows several channels to share a topic; a canonical episode does not, because topic-keyed reads would be ambiguous. diff --git a/src/hflow/behavior.py b/src/hflow/behavior.py index 8f8b81c7..46819d8d 100644 --- a/src/hflow/behavior.py +++ b/src/hflow/behavior.py @@ -109,9 +109,10 @@ # library identifier, schema/channel placement, and compressed bytes can change. # Regenerate derived outputs rather than mixing both writers under one identity. # -# "13": video messages are encoded and rewritten by hebbian-mcap (0.1.2). The -# CompressedVideo schema record now carries protobuf ``json_name`` entries, the -# library identifier names the new release, and a pass-through protobuf message -# that gains an access unit delimiter keeps its original field order. Decoded -# message content is unchanged. +# "13": video messages are encoded and rewritten by hebbian-mcap. The +# CompressedVideo schema record now carries protobuf ``json_name`` entries, and +# a pass-through protobuf message that gains an access unit delimiter keeps its +# original field order. Decoded message content is unchanged. The header's +# library identifier becomes the fixed string ``hflow``: it used to name the +# hebbian-mcap release, so every dependency bump changed canonical bytes. TRANSFORM_BEHAVIOR_VERSION: str = "13" diff --git a/src/hflow/format.py b/src/hflow/format.py index 6abbef59..ff0fa657 100644 --- a/src/hflow/format.py +++ b/src/hflow/format.py @@ -131,6 +131,11 @@ } ) +# Written to the MCAP header of every canonical episode. It carries no version, +# so a dependency or HFlow release that serializes the same way writes the same +# bytes and leaves episode identities alone. +CANONICAL_LIBRARY_IDENTIFIER = "hflow" + CANONICAL_VIDEO_SCHEMA_NAME = "foxglove.CompressedVideo" # Already-encoded video schemas whose payload contract the built-in transform diff --git a/src/hflow/transform.py b/src/hflow/transform.py index 85e37053..d80a8620 100644 --- a/src/hflow/transform.py +++ b/src/hflow/transform.py @@ -84,6 +84,7 @@ from hflow.format import ( BULK_MESSAGE_BYTES, CAMERA_SCHEMA_NAMES, + CANONICAL_LIBRARY_IDENTIFIER, CANONICAL_VIDEO_SCHEMA_NAME, DEFAULT_BULK_GROUP, DEFAULT_CAMERA_GROUP, @@ -846,6 +847,7 @@ def output_topic(message: _OutgoingMessage) -> str: else transform_config.chunk_size_bytes ), compression=transform_config.compression, + library=CANONICAL_LIBRARY_IDENTIFIER, ) as writer: video_schema_id: SchemaId | None = None # Source channel id (or derived topic) -> output writer channel diff --git a/tests/test_identity_stability.py b/tests/test_identity_stability.py index e484a5d9..f2a7e51e 100644 --- a/tests/test_identity_stability.py +++ b/tests/test_identity_stability.py @@ -8,6 +8,7 @@ from mcap.reader import make_reader import hflow +from hflow.format import CANONICAL_LIBRARY_IDENTIFIER from hflow.testing import SyntheticEpisodeSpec from hflow.transform import ( TransformConfig, @@ -124,3 +125,14 @@ def test_canonical_write_order_is_total_so_identity_cannot_ride_on_append_order( f"{tied_messages} of {len(written)} share a timestamp, and without a " "total order their arrangement is decided by append order" ) + + +def test_canonical_header_does_not_name_a_library_release(tmp_path: Path) -> None: + """A dependency release that serializes the same way must write the same header.""" + canonical = synthesize_canonical_episode( + tmp_path, SyntheticEpisodeSpec(duration_s=1.0, cameras=()) + ) + with canonical.open("rb") as stream: + header = make_reader(stream).get_header() + assert header.library == CANONICAL_LIBRARY_IDENTIFIER + assert not any(character.isdigit() for character in header.library)