robotics-runtime-contracts 0.17.0__py3-none-any.whl

robotics_runtime_contracts/__init__.py

@@ -0,0 +1,281 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from copy import deepcopy
+from functools import cache
+from hashlib import sha256
+from pathlib import Path
+from typing import Any, cast
+
+from jsonschema import Draft202012Validator, FormatChecker
+from jsonschema.exceptions import ValidationError, best_match
+from referencing import Registry
+from referencing.exceptions import Unresolvable
+from referencing.jsonschema import DRAFT202012, SchemaRegistry
+
+from robotics_runtime_contracts._resources import schema_directory
+from robotics_runtime_contracts.canonical import dumps_canonical, file_sha256
+from robotics_runtime_contracts.catalog import (
+    UnknownContractRoleError,
+    contract_roles,
+    contract_set,
+    internal_schema_names,
+    role_schemas,
+    schema_for_role,
+)
+from robotics_runtime_contracts.errors import ContractError
+from robotics_runtime_contracts.extensions import (
+    ExtensionValidationError,
+)
+from robotics_runtime_contracts.extensions import (
+    validate_extensions as _validate_extensions,
+)
+from robotics_runtime_contracts.providers import (
+    ProviderRequirementError,
+    scene_satisfies,
+    validate_provider_requirements,
+)
+from robotics_runtime_contracts.qualification_policy import (
+    CHANNEL_ERROR_VIOLATIONS,
+    CHANNEL_INCOMPLETE_VIOLATIONS,
+    RESERVED_ASSERTION_IDS,
+    RESERVED_METRIC_NAMES,
+    ChannelObservationStatus,
+    ClockEvidenceValidationError,
+    channel_observation_status,
+    derive_channel_violations,
+    hardware_clock_within_policy,
+    validate_clock_relation_evidence,
+)
+from robotics_runtime_contracts.receipts import (
+    ArtifactReceiptValidationError,
+    validate_artifact_receipt,
+)
+from robotics_runtime_contracts.semantics import (
+    SemanticValidationError,
+)
+from robotics_runtime_contracts.semantics import (
+    validate_semantics as _validate_semantics,
+)
+from robotics_runtime_contracts.serialization import (
+    DocumentParseError,
+    NonFiniteNumberError,
+    ensure_finite_numbers,
+    load_mapping,
+    loads_mapping,
+)
+from robotics_runtime_contracts.status import OutcomeStatus, worst_status
+
+_PUBLIC_SCHEMA_FILES = {name: f"{name}.schema.json" for name in role_schemas().values()}
+_INTERNAL_SCHEMA_FILES = {name: f"{name}.schema.json" for name in internal_schema_names()}
+_SCHEMA_FILES = _PUBLIC_SCHEMA_FILES | _INTERNAL_SCHEMA_FILES
+
+
+class ContractValidationError(ContractError):
+    """Raised when a document does not satisfy a public contract."""
+
+    error_id = "schema.validation_failed"
+
+    def __init__(self, schema_name: str, error: ValidationError) -> None:
+        self.schema_name = schema_name
+        self.json_path = error.json_path
+        self.validation_message = error.message
+        super().__init__(f"{self.json_path}: {self.validation_message}", json_path=error.json_path)
+
+
+class UnknownSchemaError(ContractError):
+    """Raised when a requested schema version or identifier is not published."""
+
+    error_id = "schema.unknown"
+
+
+def schema_names() -> tuple[str, ...]:
+    """Return canonical public schemas in stable role order."""
+
+    return tuple(_PUBLIC_SCHEMA_FILES)
+
+
+def schema_resource_names() -> tuple[str, ...]:
+    """Return public and internal resources used by the offline registry."""
+
+    return tuple(_SCHEMA_FILES)
+
+
+@cache
+def _schema_ids() -> dict[str, str]:
+    return {
+        cast(str, json.loads((schema_dir() / file_name).read_text(encoding="utf-8"))["$id"]): name
+        for name, file_name in _SCHEMA_FILES.items()
+    }
+
+
+def resolve_schema_name(schema: str) -> str:
+    """Resolve a schema version, file name, or canonical identifier."""
+
+    if schema in _SCHEMA_FILES:
+        return schema
+    if schema in _schema_ids():
+        return _schema_ids()[schema]
+    for schema_name, file_name in _SCHEMA_FILES.items():
+        if schema == file_name:
+            return schema_name
+    raise UnknownSchemaError(f"Unknown schema: {schema}")
+
+
+def schema_dir() -> Path:
+    """Return a resource directory that remains available until process exit."""
+
+    return schema_directory()
+
+
+def schema_path(schema: str) -> Path:
+    schema_name = resolve_schema_name(schema)
+    path = schema_dir() / _SCHEMA_FILES[schema_name]
+    if not path.is_file():
+        raise FileNotFoundError(path)
+    return path
+
+
+def schema_digest(schema: str) -> str:
+    """Return the SHA-256 digest of the packaged schema resource."""
+
+    return sha256(schema_path(schema).read_bytes()).hexdigest()
+
+
+@cache
+def _load_schema(schema: str) -> dict[str, Any]:
+    schema_name = resolve_schema_name(schema)
+    return cast(
+        dict[str, Any],
+        json.loads(schema_path(schema_name).read_text(encoding="utf-8")),
+    )
+
+
+def load_schema(schema: str) -> dict[str, Any]:
+    """Return an isolated copy of a published schema."""
+
+    return deepcopy(_load_schema(resolve_schema_name(schema)))
+
+
+@cache
+def _validator(schema: str) -> Draft202012Validator:
+    schema_name = resolve_schema_name(schema)
+    contract = _load_schema(schema_name)
+    Draft202012Validator.check_schema(contract)
+    return Draft202012Validator(
+        contract,
+        format_checker=FormatChecker(),
+        registry=_schema_registry(),
+    )
+
+
+@cache
+def _schema_registry() -> SchemaRegistry:
+    return Registry().with_resources(
+        (
+            schema["$id"],
+            DRAFT202012.create_resource(schema),
+        )
+        for name in _SCHEMA_FILES
+        for schema in (_load_schema(name),)
+    )
+
+
+def schema_registry() -> SchemaRegistry:
+    """Return an isolated offline registry for all published schema IDs."""
+
+    return Registry().with_resources(
+        (
+            schema["$id"],
+            DRAFT202012.create_resource(schema),
+        )
+        for name in _SCHEMA_FILES
+        for schema in (load_schema(name),)
+    )
+
+
+def validate_document(
+    document: Mapping[str, Any],
+    schema: str | None = None,
+    *,
+    extension_schemas: Mapping[str, bytes | str] | None = None,
+) -> None:
+    """Validate a document against an explicit or declared schema version."""
+
+    ensure_finite_numbers(document)
+    declared_schema = document.get("schema_version")
+    selected_schema = schema if schema is not None else declared_schema
+    if not isinstance(selected_schema, str):
+        raise UnknownSchemaError("Document must declare schema_version")
+    schema_name = resolve_schema_name(selected_schema)
+    try:
+        error = best_match(_validator(schema_name).iter_errors(document))
+    except Unresolvable as cause:
+        raise ContractError(
+            f"unresolvable schema reference: {cause.ref}",
+            error_id="schema.reference_invalid",
+        ) from cause
+    if error is not None:
+        raise ContractValidationError(schema_name, error) from error
+    _validate_semantics(schema_name, document)
+    _validate_extensions(schema_name, document, extension_schemas)
+
+
+def validate_role(
+    document: Mapping[str, Any],
+    role: str,
+    *,
+    extension_schemas: Mapping[str, bytes | str] | None = None,
+) -> None:
+    """Validate a document against the canonical schema for its role."""
+
+    validate_document(document, schema_for_role(role), extension_schemas=extension_schemas)
+
+
+__all__ = [
+    "CHANNEL_ERROR_VIOLATIONS",
+    "CHANNEL_INCOMPLETE_VIOLATIONS",
+    "OutcomeStatus",
+    "RESERVED_ASSERTION_IDS",
+    "RESERVED_METRIC_NAMES",
+    "ChannelObservationStatus",
+    "ClockEvidenceValidationError",
+    "ContractValidationError",
+    "ContractError",
+    "ArtifactReceiptValidationError",
+    "DocumentParseError",
+    "ExtensionValidationError",
+    "NonFiniteNumberError",
+    "ProviderRequirementError",
+    "SemanticValidationError",
+    "UnknownContractRoleError",
+    "UnknownSchemaError",
+    "contract_roles",
+    "contract_set",
+    "dumps_canonical",
+    "ensure_finite_numbers",
+    "file_sha256",
+    "load_schema",
+    "load_mapping",
+    "loads_mapping",
+    "resolve_schema_name",
+    "role_schemas",
+    "schema_digest",
+    "schema_dir",
+    "schema_for_role",
+    "schema_names",
+    "schema_path",
+    "schema_registry",
+    "schema_resource_names",
+    "scene_satisfies",
+    "channel_observation_status",
+    "derive_channel_violations",
+    "hardware_clock_within_policy",
+    "validate_clock_relation_evidence",
+    "validate_artifact_receipt",
+    "validate_document",
+    "validate_provider_requirements",
+    "validate_role",
+    "worst_status",
+]

robotics_runtime_contracts/_mcap_crc.py

@@ -0,0 +1,101 @@
+"""Verify the two CRC kinds not covered by MCAP 1.4's public StreamReader.
+
+This is a checksum-range locator, not an MCAP decoder. It skips top-level
+records using their fixed nine-byte envelopes and reads only attachment length
+prefixes and the fixed footer. Decoding, decompression and data/chunk CRCs remain
+upstream responsibilities. Attachment extension bytes after its CRC are allowed.
+Ranges cover original bytes, never reserialized records, in bounded read blocks.
+See https://mcap.dev/spec (Attachment and Footer).
+"""
+
+from typing import IO
+from zlib import crc32
+
+from mcap.opcode import Opcode
+from mcap.stream_reader import MAGIC_SIZE
+
+from robotics_runtime_contracts.writers import WriterError
+
+
+def _invalid(message: str) -> WriterError:
+    return WriterError(message, error_id="writer.invalid_mcap")
+
+
+def _read_integer(stream: IO[bytes], size: int, end: int) -> int:
+    if stream.tell() + size > end:
+        raise _invalid("truncated MCAP checksum fields")
+    raw = stream.read(size)
+    if len(raw) != size:
+        raise _invalid("truncated MCAP checksum fields")
+    return int.from_bytes(raw, "little")
+
+
+def _skip(stream: IO[bytes], size: int, end: int) -> None:
+    destination = stream.tell() + size
+    if destination > end:
+        raise _invalid("MCAP checksum field exceeds its record")
+    stream.seek(destination)
+
+
+def _check_crc(stream: IO[bytes], start: int, end: int, label: str) -> None:
+    stream.seek(end)
+    expected = _read_integer(stream, 4, end + 4)
+    if expected == 0:
+        return  # The format explicitly permits an unavailable checksum.
+    stream.seek(start)
+    actual = 0
+    remaining = end - start
+    while remaining:
+        block = stream.read(min(remaining, 64 * 1024))
+        if not block:
+            raise _invalid(f"truncated MCAP {label} checksum range")
+        actual = crc32(block, actual)
+        remaining -= len(block)
+    if actual != expected:
+        raise _invalid(f"MCAP {label} CRC mismatch")
+
+
+def _attachment_crc(stream: IO[bytes], start: int, end: int) -> None:
+    # Two timestamps, two length-prefixed strings, then uint64-prefixed data.
+    stream.seek(start)
+    _skip(stream, 16, end)
+    for _ in range(2):
+        _skip(stream, _read_integer(stream, 4, end), end)
+    _skip(stream, _read_integer(stream, 8, end), end)
+    crc_offset = stream.tell()
+    if crc_offset + 4 > end:
+        raise _invalid("truncated MCAP attachment CRC")
+    _check_crc(stream, start, crc_offset, "attachment")
+
+
+def _footer_crc(stream: IO[bytes], start: int, end: int) -> None:
+    if end - start != 20:
+        raise _invalid("invalid MCAP footer length")
+    stream.seek(start)
+    summary_start = _read_integer(stream, 8, end)
+    if summary_start and not MAGIC_SIZE <= summary_start <= start - 9:
+        raise _invalid("invalid MCAP summary checksum range")
+    # With no summary records the checksum covers only the footer prefix.
+    _check_crc(stream, summary_start or start - 9, end - 4, "summary")
+
+
+def verify_extra_crcs(stream: IO[bytes]) -> None:
+    """Check attachment/summary CRCs in the same seekable snapshot as the reader."""
+    limit = stream.seek(0, 2) - MAGIC_SIZE
+    position = MAGIC_SIZE
+    while position < limit:
+        stream.seek(position)
+        opcode = _read_integer(stream, 1, limit)
+        length = _read_integer(stream, 8, limit)
+        start = stream.tell()
+        end = start + length
+        if end > limit:
+            raise _invalid("MCAP record extends past the trailing magic")
+        if opcode == Opcode.ATTACHMENT:
+            _attachment_crc(stream, start, end)
+        elif opcode == Opcode.FOOTER:
+            if end != limit:
+                raise _invalid("MCAP footer must be the last record")
+            _footer_crc(stream, start, end)
+        position = end
+    stream.seek(0)

robotics_runtime_contracts/_mcap_observations.py

@@ -0,0 +1,91 @@
+"""Observed MCAP facts, with data definitions authoritative over summary copies."""
+
+from collections import Counter
+from dataclasses import dataclass, field
+
+from mcap.records import Attachment, Channel, DataEnd, McapRecord, Message, Metadata, Schema
+
+from robotics_runtime_contracts.writers import WriterError
+
+
+def _invalid(message: str) -> WriterError:
+    return WriterError(message, error_id="writer.invalid_mcap")
+
+
+def _definition[RecordT: (Schema, Channel)](
+    definitions: dict[int, RecordT], record: RecordT, in_summary: bool
+) -> None:
+    previous = definitions.get(record.id)
+    if previous is not None:
+        if record != previous:
+            raise _invalid(f"conflicting MCAP {type(record).__name__} ID {record.id}")
+    elif in_summary:
+        raise _invalid(f"MCAP summary {type(record).__name__} lacks a data definition")
+    else:
+        definitions[record.id] = record
+
+
+@dataclass
+class Observations:
+    schemas: dict[int, Schema] = field(default_factory=dict)
+    channels: dict[int, Channel] = field(default_factory=dict)
+    messages: Counter[int] = field(default_factory=Counter)
+    attachments: int = 0
+    metadata: int = 0
+    start: int | None = None
+    end: int = 0
+    in_summary: bool = False
+
+    def definition(self, record: Schema | Channel) -> None:
+        if isinstance(record, Schema):
+            if record.id == 0:
+                raise _invalid("MCAP schema ID must be nonzero")
+            _definition(self.schemas, record, self.in_summary)
+        else:
+            if record.schema_id == 0:
+                raise _invalid("recording-summary.v1 requires a named schema for every channel")
+            if record.schema_id not in self.schemas:
+                raise _invalid(f"MCAP channel refers to undefined schema {record.schema_id}")
+            _definition(self.channels, record, self.in_summary)
+
+    def message(self, record: Message) -> None:
+        if self.in_summary:
+            raise _invalid("MCAP message occurs after DataEnd")
+        if record.channel_id not in self.channels:
+            raise _invalid(f"MCAP message refers to undefined channel {record.channel_id}")
+        self.messages[record.channel_id] += 1
+        self.start = record.log_time if self.start is None else min(self.start, record.log_time)
+        self.end = max(self.end, record.log_time)
+
+    def auxiliary(self, record: Attachment | Metadata) -> None:
+        if self.in_summary:
+            raise _invalid("MCAP attachment/metadata occurs after DataEnd")
+        if isinstance(record, Attachment):
+            self.attachments += 1
+        else:
+            self.metadata += 1
+
+    def observe(self, record: McapRecord) -> None:
+        if isinstance(record, DataEnd):
+            if self.in_summary:
+                raise _invalid("duplicate MCAP DataEnd")
+            self.in_summary = True
+        elif isinstance(record, (Schema, Channel)):
+            self.definition(record)
+        elif isinstance(record, Message):
+            self.message(record)
+        elif isinstance(record, (Attachment, Metadata)):
+            self.auxiliary(record)
+
+    def statistics(self) -> dict[str, int]:
+        if not self.in_summary:
+            raise _invalid("MCAP requires DataEnd before its summary")
+        return {
+            "message_count": sum(self.messages.values()),
+            "schema_count": len(self.schemas),
+            "channel_count": len(self.channels),
+            "attachment_count": self.attachments,
+            "metadata_count": self.metadata,
+            "message_start_time_ns": 0 if self.start is None else self.start,
+            "message_end_time_ns": self.end,
+        }

robotics_runtime_contracts/_mcap_summary.py

@@ -0,0 +1,118 @@
+"""MCAP-library implementation kept behind the optional dependency boundary."""
+
+from __future__ import annotations
+
+import hashlib
+import shutil
+from collections import Counter
+from pathlib import Path
+from tempfile import TemporaryFile
+from typing import IO, Any
+
+from mcap.reader import make_reader
+from mcap.records import Chunk, Statistics
+from mcap.stream_reader import StreamReader
+from mcap.summary import Summary
+
+from robotics_runtime_contracts._mcap_crc import verify_extra_crcs
+from robotics_runtime_contracts._mcap_observations import Observations
+from robotics_runtime_contracts.writers import WriterError
+
+
+def _statistics(summary: Summary) -> dict[str, int]:
+    stats = summary.statistics
+    if stats is None:
+        raise WriterError(
+            "MCAP requires finalized summary Statistics", error_id="writer.invalid_mcap"
+        )
+    return {
+        "message_count": stats.message_count,
+        "schema_count": stats.schema_count,
+        "channel_count": stats.channel_count,
+        "attachment_count": stats.attachment_count,
+        "metadata_count": stats.metadata_count,
+        "chunk_count": stats.chunk_count,
+        "message_start_time_ns": stats.message_start_time,
+        "message_end_time_ns": stats.message_end_time,
+    }
+
+
+def _observed_statistics(stream: IO[bytes]) -> Observations:
+    observed = Observations()
+    stream.seek(0)
+    for record in StreamReader(stream, validate_crcs=True).records:
+        observed.observe(record)
+    return observed
+
+
+def _compressions(stream: IO[bytes]) -> tuple[list[str], int]:
+    stream.seek(0)
+    compressions: set[str] = set()
+    chunks = 0
+    for record in StreamReader(stream, emit_chunks=True, validate_crcs=True).records:
+        if isinstance(record, Chunk):
+            chunks += 1
+            compressions.add(record.compression or "none")
+    return sorted(compressions or {"none"}), chunks
+
+
+def _channels(observed: Observations) -> list[dict[str, Any]]:
+    channels = []
+    for channel in sorted(observed.channels.values(), key=lambda item: (item.topic, item.id)):
+        schema = observed.schemas[channel.schema_id]
+        channels.append(
+            {
+                "topic": channel.topic,
+                "message_encoding": channel.message_encoding,
+                "schema_name": schema.name,
+                "message_count": observed.messages[channel.id],
+            }
+        )
+    return channels
+
+
+def _check_channel_counts(statistics: Statistics, observed: Observations) -> None:
+    counts = statistics.channel_message_counts
+    if counts and (
+        +Counter(counts) != observed.messages or not counts.keys() <= observed.channels.keys()
+    ):
+        raise WriterError(
+            "MCAP per-channel Statistics contradict its messages", error_id="writer.invalid_mcap"
+        )
+
+
+def _summarize_stream(stream: IO[bytes], digest: str) -> dict[str, Any]:
+    verify_extra_crcs(stream)
+    summary = make_reader(stream, validate_crcs=True).get_summary()
+    if summary is None:
+        raise WriterError("MCAP requires a finalized summary", error_id="writer.invalid_mcap")
+    expected = _statistics(summary)
+    observed = _observed_statistics(stream)
+    statistics = observed.statistics()
+    compressions, statistics["chunk_count"] = _compressions(stream)
+    if expected != statistics:
+        raise WriterError("MCAP Statistics contradict its records", error_id="writer.invalid_mcap")
+    assert summary.statistics is not None
+    _check_channel_counts(summary.statistics, observed)
+    return {
+        "schema_version": "recording-summary.v1",
+        "source_sha256": digest,
+        "statistics": statistics,
+        "compressions": compressions,
+        "channels": _channels(observed),
+    }
+
+
+def summarize(source: Path) -> dict[str, Any]:
+    # Parse/hash the same private byte snapshot; source replacement cannot mix passes.
+    with source.open("rb") as original, TemporaryFile() as snapshot:
+        shutil.copyfileobj(original, snapshot)
+        snapshot.seek(0)
+        digest = hashlib.file_digest(snapshot, "sha256").hexdigest()
+        snapshot.seek(0)
+        try:
+            return _summarize_stream(snapshot, digest)
+        except WriterError:
+            raise
+        except Exception as error:
+            raise WriterError(f"invalid MCAP: {error}", error_id="writer.invalid_mcap") from error

robotics_runtime_contracts/_merge_patch.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from copy import deepcopy
+
+type JSONValue = None | bool | int | float | str | list[JSONValue] | dict[str, JSONValue]
+
+
+def json_equal(left: JSONValue, right: JSONValue) -> bool:
+    """Compare JSON trees without Python's bool/int/float equality coercions."""
+
+    if type(left) is not type(right):
+        return False
+    if isinstance(left, dict) and isinstance(right, dict):
+        return left.keys() == right.keys() and all(
+            json_equal(value, right[key]) for key, value in left.items()
+        )
+    if isinstance(left, list) and isinstance(right, list):
+        return len(left) == len(right) and all(
+            json_equal(a, b) for a, b in zip(left, right, strict=True)
+        )
+    return left == right
+
+
+def merge_patch(target: JSONValue, patch: JSONValue) -> JSONValue:
+    """Apply RFC 7396 section 2 without modifying or sharing input containers."""
+
+    # https://www.rfc-editor.org/rfc/rfc7396#section-2
+    if not isinstance(patch, dict):
+        return deepcopy(patch)
+    result = deepcopy(target) if isinstance(target, dict) else {}
+    for key, value in patch.items():
+        if value is None:
+            result.pop(key, None)
+        else:
+            result[key] = merge_patch(result.get(key), value)
+    return result
+
+
+def create_patch(
+    source: dict[str, JSONValue], target: dict[str, JSONValue]
+) -> dict[str, JSONValue]:
+    """Build an object patch; callers must check representability by round-trip."""
+
+    patch: dict[str, JSONValue] = {key: None for key in source if key not in target}
+    for key, value in target.items():
+        if key in source and json_equal(source[key], value):
+            continue
+        if isinstance(value, dict):
+            previous = source.get(key)
+            # Keep even an empty patch when adding an object or replacing a scalar.
+            patch[key] = create_patch(previous if isinstance(previous, dict) else {}, value)
+        else:
+            patch[key] = deepcopy(value)
+    return patch