mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/visual_run/contracts.py

@@ -0,0 +1,673 @@
+"""Strict, data-only contracts for durable visual run events.
+
+The records in this module describe persisted work. They do not authorize a Build, dataset
+handoff, approval, publication, or release. Sequence is the only ordering coordinate; timestamps
+are observability metadata. Large values live in immutable artifacts and events carry references.
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+import json
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass
+from types import MappingProxyType
+from typing import Any, Literal
+
+EVENT_SCHEMA_VERSION = "visual-run-event.v2"
+ARTIFACT_SCHEMA_VERSION = "visual-run-artifact-ref.v2"
+MAX_EVENT_BYTES = 32 * 1024
+MAX_IDENTIFIER_CHARS = 128
+MAX_STAGE_CHARS = 64
+MAX_TEXT_CHARS = 512
+MAX_ARTIFACT_BYTES = 1 << 40
+
+ACTORS = frozenset({"agent", "worker", "coordinator", "viewer"})
+DISPLAY_DISPOSITIONS = frozenset({"inline", "summary", "download-only", "redacted"})
+TERMINAL_STATUSES = frozenset({"completed", "failed", "interrupted"})
+DOCUMENT_HEADER_CELL_ID = "research-report"
+LEGACY_DOCUMENT_HEADER_CELL_ID_PREFIX = "legacy-research-report"
+RESERVED_CELL_IDS = frozenset({"build", "table", "quality"})
+RESERVED_CELL_PREFIXES = ("attempt:", "notebook:", "run:", "source:", "stage:")
+
+_IDENTIFIER = re.compile(r"\A[A-Za-z0-9](?:[A-Za-z0-9._:-]{0,127})\Z")
+_COORDINATE = re.compile(r"\A[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*\.v[1-9][0-9]*\Z")
+_MEDIA_TYPE = re.compile(r"\A[a-z0-9!#$&^_.+-]+/[a-z0-9!#$&^_.+-]+\Z")
+_DIGEST = re.compile(r"\A[0-9a-f]{64}\Z")
+_ERROR_CODE = re.compile(r"\A[A-Z][A-Z0-9_]{0,63}\Z")
+_TIMESTAMP = re.compile(
+    r"\A[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:\.[0-9]{1,6})?Z\Z"
+)
+
+_EVENT_FIELDS = frozenset(
+    {
+        "schema_version",
+        "run_id",
+        "sequence",
+        "event_type",
+        "event_version",
+        "actor",
+        "phase",
+        "stage",
+        "object_id",
+        "object_version",
+        "previous_object_version",
+        "observed_at",
+        "idempotency_key",
+        "payload",
+        "artifact",
+        "status",
+        "error",
+    }
+)
+_ARTIFACT_FIELDS = frozenset(
+    {
+        "schema_version",
+        "artifact_id",
+        "sha256",
+        "media_type",
+        "artifact_schema",
+        "byte_size",
+        "truncated",
+        "original_byte_size",
+        "display",
+    }
+)
+_ERROR_FIELDS = frozenset({"code", "message", "retryable"})
+
+
+class VisualRunError(ValueError):
+    """A typed contract refusal safe for presentation at the protocol boundary."""
+
+    def __init__(self, code: str, message: str) -> None:
+        super().__init__(message)
+        self.code = code
+
+
+@dataclass(frozen=True)
+class PayloadField:
+    kind: Literal["text", "integer", "boolean", "digest"]
+    choices: frozenset[str] = frozenset()
+
+
+@dataclass(frozen=True)
+class EventSpec:
+    version: int
+    payload: Mapping[str, PayloadField]
+    object_rule: Literal["create", "update"]
+    artifact_policy: Literal["forbidden", "optional", "required"] = "forbidden"
+    artifact_schemas: frozenset[str] = frozenset()
+    terminal_status: str | None = None
+    error_policy: Literal["forbidden", "optional", "required"] = "forbidden"
+
+
+def _fields(**values: PayloadField) -> Mapping[str, PayloadField]:
+    return MappingProxyType(values)
+
+
+TEXT = PayloadField("text")
+INTEGER = PayloadField("integer")
+BOOLEAN = PayloadField("boolean")
+DIGEST = PayloadField("digest")
+CELL_TYPE = PayloadField("text", frozenset({"markdown", "code"}))
+OUTPUT_KIND = PayloadField("text", frozenset({"stream", "display_data", "execute_result", "error"}))
+
+_CELL_OUTPUT_SCHEMA = "mostlyright.cell-output.v1"
+_CELL_SOURCE_SCHEMA = "mostlyright.cell-source.v1"
+_SOURCE_OBSERVATION_SCHEMA = "mostlyright.source-observation.v1"
+_STAGE_OBSERVATION_SCHEMA = "stage-observation.v1"
+_STAGE_OBSERVATION_SCHEMA_V2 = "stage-observation.v2"
+_TABLE_SCHEMA = "mostlyright.table-reference.v1"
+_NOTEBOOK_SCHEMA = "mostlyright.notebook.v1"
+_QUALITY_OBSERVATION_SCHEMA = "mostlyright.quality-observation.v1"
+
+ARTIFACT_SCHEMAS: Mapping[str, frozenset[str]] = MappingProxyType(
+    {
+        _CELL_OUTPUT_SCHEMA: frozenset({"application/json", "text/plain"}),
+        _CELL_SOURCE_SCHEMA: frozenset({"text/markdown", "text/x-python"}),
+        _SOURCE_OBSERVATION_SCHEMA: frozenset({"application/json"}),
+        _STAGE_OBSERVATION_SCHEMA: frozenset({"application/json"}),
+        _STAGE_OBSERVATION_SCHEMA_V2: frozenset({"application/json"}),
+        _TABLE_SCHEMA: frozenset({"application/json"}),
+        _NOTEBOOK_SCHEMA: frozenset({"application/x-ipynb+json"}),
+        _QUALITY_OBSERVATION_SCHEMA: frozenset({"application/json"}),
+    }
+)
+
+
+def _spec(
+    payload: Mapping[str, PayloadField],
+    object_rule: Literal["create", "update"],
+    *,
+    artifact_policy: Literal["forbidden", "optional", "required"] = "forbidden",
+    artifact_schemas: frozenset[str] = frozenset(),
+    terminal_status: str | None = None,
+    error_policy: Literal["forbidden", "optional", "required"] = "forbidden",
+) -> EventSpec:
+    return EventSpec(
+        1,
+        payload,
+        object_rule,
+        artifact_policy,
+        artifact_schemas,
+        terminal_status,
+        error_policy,
+    )
+
+
+# One declaration owns the initial vocabulary, payload coordinate, object-version rule, artifact
+# policy, and terminal shape. Consumers inspect this table; they do not restate it.
+EVENT_REGISTRY: Mapping[str, EventSpec] = MappingProxyType(
+    {
+        "run.started": _spec(_fields(), "create"),
+        "run.completed": _spec(_fields(), "update", terminal_status="completed"),
+        "run.failed": _spec(_fields(), "update", terminal_status="failed", error_policy="required"),
+        "run.interrupted": _spec(
+            _fields(), "update", terminal_status="interrupted", error_policy="optional"
+        ),
+        "phase.started": _spec(_fields(), "create"),
+        "phase.completed": _spec(_fields(), "update"),
+        "phase.failed": _spec(_fields(), "update", error_policy="required"),
+        "cell.created": _spec(_fields(cell_type=CELL_TYPE), "create"),
+        "cell.source_extended": _spec(
+            _fields(source_length=INTEGER),
+            "update",
+            artifact_policy="required",
+            artifact_schemas=frozenset({_CELL_SOURCE_SCHEMA}),
+        ),
+        "cell.source_revised": _spec(
+            _fields(source_length=INTEGER),
+            "update",
+            artifact_policy="required",
+            artifact_schemas=frozenset({_CELL_SOURCE_SCHEMA}),
+        ),
+        "cell.moved": _spec(_fields(after_cell_id=TEXT), "update"),
+        "cell.execution_started": _spec(_fields(execution_count=INTEGER), "update"),
+        "cell.output_appended": _spec(
+            _fields(output_index=INTEGER, output_kind=OUTPUT_KIND),
+            "update",
+            artifact_policy="required",
+            artifact_schemas=frozenset({_CELL_OUTPUT_SCHEMA}),
+        ),
+        "cell.output_replaced": _spec(
+            _fields(output_index=INTEGER, output_kind=OUTPUT_KIND),
+            "update",
+            artifact_policy="required",
+            artifact_schemas=frozenset({_CELL_OUTPUT_SCHEMA}),
+        ),
+        "cell.completed": _spec(_fields(), "update"),
+        "cell.failed": _spec(_fields(), "update", error_policy="required"),
+        "source.selected": _spec(_fields(source_kind=TEXT), "create"),
+        "source.rejected": _spec(_fields(reason_code=TEXT), "update"),
+        "source.schema_observed": _spec(
+            _fields(column_count=INTEGER),
+            "update",
+            artifact_policy="required",
+            artifact_schemas=frozenset({_SOURCE_OBSERVATION_SCHEMA}),
+        ),
+        "source.observation_ready": _spec(
+            _fields(observation_kind=TEXT),
+            "update",
+            artifact_policy="required",
+            artifact_schemas=frozenset({_SOURCE_OBSERVATION_SCHEMA}),
+        ),
+        "transformation.started": _spec(_fields(operation=TEXT), "create"),
+        "transformation.completed": _spec(_fields(operation=TEXT, row_count=INTEGER), "update"),
+        "stage.observation_ready": _spec(
+            _fields(operation=TEXT, row_count=INTEGER),
+            "update",
+            artifact_policy="required",
+            artifact_schemas=frozenset({_STAGE_OBSERVATION_SCHEMA, _STAGE_OBSERVATION_SCHEMA_V2}),
+        ),
+        "quality.completed": _spec(
+            _fields(checks_passed=INTEGER, checks_total=INTEGER),
+            "create",
+            artifact_policy="required",
+            artifact_schemas=frozenset({_QUALITY_OBSERVATION_SCHEMA}),
+        ),
+        "table_written": _spec(
+            _fields(row_count=INTEGER, column_count=INTEGER),
+            "create",
+            artifact_policy="required",
+            artifact_schemas=frozenset({_TABLE_SCHEMA}),
+        ),
+        "build.sealed": _spec(_fields(candidate_digest=DIGEST), "create"),
+        "build.verified": _spec(_fields(candidate_digest=DIGEST), "update"),
+        "notebook.research_materialized": _spec(
+            _fields(notebook_digest=DIGEST),
+            "create",
+            artifact_policy="required",
+            artifact_schemas=frozenset({_NOTEBOOK_SCHEMA}),
+        ),
+        "notebook.table_materialized": _spec(
+            _fields(notebook_digest=DIGEST),
+            "create",
+            artifact_policy="required",
+            artifact_schemas=frozenset({_NOTEBOOK_SCHEMA}),
+        ),
+    }
+)
+
+
+def _refuse(code: str, message: str) -> None:
+    raise VisualRunError(code, message)
+
+
+def _exact_fields(value: Mapping[str, Any], expected: frozenset[str]) -> None:
+    actual = set(value)
+    if actual != expected:
+        unknown = sorted(actual - expected)
+        missing = sorted(expected - actual)
+        code = "VISUAL_RUN_UNKNOWN_FIELD" if unknown else "VISUAL_RUN_MISSING_FIELD"
+        _refuse(code, f"unknown={unknown!r}, missing={missing!r}")
+
+
+def _identifier(value: Any, name: str, *, max_chars: int = MAX_IDENTIFIER_CHARS) -> str:
+    if not isinstance(value, str) or len(value) > max_chars or _IDENTIFIER.fullmatch(value) is None:
+        _refuse("VISUAL_RUN_INVALID_IDENTIFIER", f"{name} is not a bounded identifier")
+    return value
+
+
+def _integer(value: Any, code: str, *, minimum: int = 0, maximum: int = 2**63 - 1) -> int:
+    if isinstance(value, bool) or not isinstance(value, int) or not minimum <= value <= maximum:
+        _refuse(code, "integer is outside its closed range")
+    return value
+
+
+def _timestamp(value: Any) -> str:
+    if not isinstance(value, str) or _TIMESTAMP.fullmatch(value) is None:
+        _refuse("VISUAL_RUN_INVALID_TIMESTAMP", "observed_at must be an RFC 3339 UTC timestamp")
+    try:
+        parsed = dt.datetime.fromisoformat(value.removesuffix("Z") + "+00:00")
+    except ValueError:
+        _refuse("VISUAL_RUN_INVALID_TIMESTAMP", "observed_at is not a real UTC timestamp")
+    if parsed.utcoffset() != dt.timedelta(0):
+        _refuse("VISUAL_RUN_INVALID_TIMESTAMP", "observed_at must use UTC")
+    return value
+
+
+def _freeze_json(value: Any) -> Any:
+    if value is None or isinstance(value, (str, bool, int)):
+        return value
+    if isinstance(value, list):
+        return tuple(_freeze_json(item) for item in value)
+    if isinstance(value, Mapping):
+        return MappingProxyType({key: _freeze_json(item) for key, item in value.items()})
+    _refuse("VISUAL_RUN_INVALID_JSON_VALUE", "contract data must contain JSON values only")
+
+
+def _thaw_json(value: Any) -> Any:
+    if isinstance(value, Mapping):
+        return {key: _thaw_json(item) for key, item in value.items()}
+    if isinstance(value, tuple):
+        return [_thaw_json(item) for item in value]
+    return value
+
+
+@dataclass(frozen=True)
+class ArtifactReference:
+    schema_version: str
+    artifact_id: str
+    sha256: str
+    media_type: str
+    artifact_schema: str
+    byte_size: int
+    truncated: bool
+    original_byte_size: int
+    display: str
+
+    @classmethod
+    def from_mapping(cls, value: Mapping[str, Any]) -> ArtifactReference:
+        if not isinstance(value, Mapping):
+            _refuse("VISUAL_RUN_INVALID_ARTIFACT", "artifact must be an object")
+        _exact_fields(value, _ARTIFACT_FIELDS)
+        if value["schema_version"] != ARTIFACT_SCHEMA_VERSION:
+            _refuse("VISUAL_RUN_UNKNOWN_SCHEMA", "unknown artifact reference schema")
+        artifact_id = _identifier(value["artifact_id"], "artifact_id")
+        digest = value["sha256"]
+        media_type = value["media_type"]
+        artifact_schema = value["artifact_schema"]
+        byte_size = value["byte_size"]
+        truncated = value["truncated"]
+        original_byte_size = value["original_byte_size"]
+        display = value["display"]
+        if not isinstance(digest, str) or _DIGEST.fullmatch(digest) is None:
+            _refuse("VISUAL_RUN_INVALID_ARTIFACT", "artifact digest must be lowercase SHA-256")
+        if not isinstance(media_type, str) or _MEDIA_TYPE.fullmatch(media_type) is None:
+            _refuse("VISUAL_RUN_INVALID_ARTIFACT", "artifact media type is not canonical")
+        admitted_media = ARTIFACT_SCHEMAS.get(artifact_schema)
+        if admitted_media is None or media_type not in admitted_media:
+            _refuse("VISUAL_RUN_INVALID_ARTIFACT", "unknown artifact schema/media coordinate")
+        byte_size = _integer(
+            byte_size, "VISUAL_RUN_INVALID_ARTIFACT", minimum=0, maximum=MAX_ARTIFACT_BYTES
+        )
+        original_byte_size = _integer(
+            original_byte_size,
+            "VISUAL_RUN_INVALID_ARTIFACT",
+            minimum=0,
+            maximum=MAX_ARTIFACT_BYTES,
+        )
+        if not isinstance(truncated, bool) or (truncated and original_byte_size <= byte_size):
+            _refuse("VISUAL_RUN_INVALID_ARTIFACT", "truncation facts are inconsistent")
+        if not truncated and original_byte_size != byte_size:
+            _refuse("VISUAL_RUN_INVALID_ARTIFACT", "untruncated sizes must be identical")
+        if display not in DISPLAY_DISPOSITIONS:
+            _refuse("VISUAL_RUN_INVALID_ARTIFACT", "unknown display disposition")
+        return cls(
+            ARTIFACT_SCHEMA_VERSION,
+            artifact_id,
+            digest,
+            media_type,
+            artifact_schema,
+            byte_size,
+            truncated,
+            original_byte_size,
+            display,
+        )
+
+    def to_mapping(self) -> dict[str, Any]:
+        return {
+            "schema_version": self.schema_version,
+            "artifact_id": self.artifact_id,
+            "sha256": self.sha256,
+            "media_type": self.media_type,
+            "artifact_schema": self.artifact_schema,
+            "byte_size": self.byte_size,
+            "truncated": self.truncated,
+            "original_byte_size": self.original_byte_size,
+            "display": self.display,
+        }
+
+
+@dataclass(frozen=True)
+class TerminalError:
+    code: str
+    message: str
+    retryable: bool
+
+    @classmethod
+    def from_mapping(cls, value: Mapping[str, Any]) -> TerminalError:
+        if not isinstance(value, Mapping):
+            _refuse("VISUAL_RUN_INVALID_TERMINAL", "error must be an object")
+        _exact_fields(value, _ERROR_FIELDS)
+        code, message, retryable = value["code"], value["message"], value["retryable"]
+        if not isinstance(code, str) or _ERROR_CODE.fullmatch(code) is None:
+            _refuse("VISUAL_RUN_INVALID_TERMINAL", "error code is outside the closed grammar")
+        if not isinstance(message, str) or not message or len(message) > MAX_TEXT_CHARS:
+            _refuse("VISUAL_RUN_INVALID_TERMINAL", "error message is empty or oversized")
+        if not isinstance(retryable, bool):
+            _refuse("VISUAL_RUN_INVALID_TERMINAL", "retryable must be boolean")
+        return cls(code, message, retryable)
+
+    def to_mapping(self) -> dict[str, Any]:
+        return {"code": self.code, "message": self.message, "retryable": self.retryable}
+
+
+def _validate_payload(spec: EventSpec, value: Any) -> Mapping[str, Any]:
+    if not isinstance(value, Mapping) or set(value) != set(spec.payload):
+        _refuse("VISUAL_RUN_INVALID_PAYLOAD", "payload fields differ from the event registry")
+    normalized: dict[str, Any] = {}
+    for key, field in spec.payload.items():
+        item = value[key]
+        if field.kind == "integer":
+            normalized[key] = _integer(item, "VISUAL_RUN_INVALID_PAYLOAD")
+        elif field.kind == "boolean":
+            if not isinstance(item, bool):
+                _refuse("VISUAL_RUN_INVALID_PAYLOAD", f"{key} must be boolean")
+            normalized[key] = item
+        elif field.kind == "digest":
+            if not isinstance(item, str) or _DIGEST.fullmatch(item) is None:
+                _refuse("VISUAL_RUN_INVALID_PAYLOAD", f"{key} must be lowercase SHA-256")
+            normalized[key] = item
+        else:
+            if not isinstance(item, str) or not item or len(item) > MAX_TEXT_CHARS:
+                _refuse("VISUAL_RUN_INVALID_PAYLOAD", f"{key} must be bounded text")
+            if field.choices and item not in field.choices:
+                _refuse("VISUAL_RUN_INVALID_PAYLOAD", f"{key} is outside the closed vocabulary")
+            normalized[key] = item
+    return MappingProxyType(normalized)
+
+
+def _validate_event_mapping(value: Mapping[str, Any], *, sequence_required: bool) -> dict[str, Any]:
+    expected = _EVENT_FIELDS if sequence_required else _EVENT_FIELDS - {"sequence"}
+    _exact_fields(value, frozenset(expected))
+    if value["schema_version"] != EVENT_SCHEMA_VERSION:
+        _refuse("VISUAL_RUN_UNKNOWN_SCHEMA", "unknown visual event schema")
+    event_type = value["event_type"]
+    if not isinstance(event_type, str) or event_type not in EVENT_REGISTRY:
+        _refuse("VISUAL_RUN_UNKNOWN_EVENT", "event type is outside the closed registry")
+    spec = EVENT_REGISTRY[event_type]
+    if value["event_version"] != spec.version:
+        _refuse("VISUAL_RUN_UNKNOWN_EVENT_VERSION", "unknown event coordinate version")
+    actor = value["actor"]
+    if actor not in ACTORS:
+        _refuse("VISUAL_RUN_UNKNOWN_ACTOR", "actor is outside the closed vocabulary")
+    object_version = _integer(
+        value["object_version"], "VISUAL_RUN_INVALID_OBJECT_VERSION", minimum=1
+    )
+    previous = value["previous_object_version"]
+    if spec.object_rule == "create":
+        if object_version != 1 or previous is not None:
+            _refuse("VISUAL_RUN_INVALID_OBJECT_VERSION", "creation must start at object version 1")
+    else:
+        previous = _integer(previous, "VISUAL_RUN_INVALID_OBJECT_VERSION", minimum=1)
+        if object_version != previous + 1:
+            _refuse("VISUAL_RUN_INVALID_OBJECT_VERSION", "update must name the exact predecessor")
+    artifact_value = value["artifact"]
+    artifact = None if artifact_value is None else ArtifactReference.from_mapping(artifact_value)
+    if spec.artifact_policy == "required" and artifact is None:
+        _refuse("VISUAL_RUN_ARTIFACT_REQUIRED", "event requires an immutable artifact reference")
+    if spec.artifact_policy == "forbidden" and artifact is not None:
+        _refuse("VISUAL_RUN_ARTIFACT_FORBIDDEN", "event cannot carry an artifact reference")
+    if artifact is not None and artifact.artifact_schema not in spec.artifact_schemas:
+        _refuse("VISUAL_RUN_INVALID_ARTIFACT", "artifact schema is invalid for this event")
+    status = value["status"]
+    error_value = value["error"]
+    error = None if error_value is None else TerminalError.from_mapping(error_value)
+    if status != spec.terminal_status:
+        _refuse("VISUAL_RUN_INVALID_TERMINAL", "status differs from the registry")
+    if spec.error_policy == "required" and error is None:
+        _refuse("VISUAL_RUN_INVALID_TERMINAL", "event requires a terminal error")
+    if spec.error_policy == "forbidden" and error is not None:
+        _refuse("VISUAL_RUN_INVALID_TERMINAL", "event cannot carry a terminal error")
+    object_id = _identifier(value["object_id"], "object_id")
+    if event_type.startswith("cell.") and (
+        object_id == value["run_id"]
+        or object_id in RESERVED_CELL_IDS
+        or object_id.startswith(RESERVED_CELL_PREFIXES)
+    ):
+        _refuse("VISUAL_RUN_RESERVED_CELL_ID", "cell id is reserved for worker protocol objects")
+    result = {
+        "schema_version": EVENT_SCHEMA_VERSION,
+        "run_id": _identifier(value["run_id"], "run_id"),
+        "event_type": event_type,
+        "event_version": spec.version,
+        "actor": actor,
+        "phase": _identifier(value["phase"], "phase", max_chars=MAX_STAGE_CHARS),
+        "stage": _identifier(value["stage"], "stage", max_chars=MAX_STAGE_CHARS),
+        "object_id": object_id,
+        "object_version": object_version,
+        "previous_object_version": previous,
+        "observed_at": _timestamp(value["observed_at"]),
+        "idempotency_key": _identifier(value["idempotency_key"], "idempotency_key"),
+        "payload": _validate_payload(spec, value["payload"]),
+        "artifact": artifact,
+        "status": status,
+        "error": error,
+    }
+    if sequence_required:
+        result["sequence"] = _integer(value["sequence"], "VISUAL_RUN_INVALID_SEQUENCE", minimum=1)
+    return result
+
+
+@dataclass(frozen=True)
+class VisualRunEvent:
+    schema_version: str
+    run_id: str
+    sequence: int
+    event_type: str
+    event_version: int
+    actor: str
+    phase: str
+    stage: str
+    object_id: str
+    object_version: int
+    previous_object_version: int | None
+    observed_at: str
+    idempotency_key: str
+    payload: Mapping[str, Any]
+    artifact: ArtifactReference | None
+    status: str | None
+    error: TerminalError | None
+
+    @classmethod
+    def from_mapping(cls, value: Mapping[str, Any]) -> VisualRunEvent:
+        if not isinstance(value, Mapping):
+            _refuse("VISUAL_RUN_INVALID_JSON", "visual event must be an object")
+        normalized = _validate_event_mapping(value, sequence_required=True)
+        event = cls(**normalized)
+        encoded = _canonical_json(event.to_mapping())
+        if len(encoded) > MAX_EVENT_BYTES:
+            _refuse("VISUAL_RUN_EVENT_TOO_LARGE", "visual event exceeds the byte ceiling")
+        return event
+
+    def to_mapping(self) -> dict[str, Any]:
+        return {
+            "schema_version": self.schema_version,
+            "run_id": self.run_id,
+            "sequence": self.sequence,
+            "event_type": self.event_type,
+            "event_version": self.event_version,
+            "actor": self.actor,
+            "phase": self.phase,
+            "stage": self.stage,
+            "object_id": self.object_id,
+            "object_version": self.object_version,
+            "previous_object_version": self.previous_object_version,
+            "observed_at": self.observed_at,
+            "idempotency_key": self.idempotency_key,
+            "payload": _thaw_json(self.payload),
+            "artifact": None if self.artifact is None else self.artifact.to_mapping(),
+            "status": self.status,
+            "error": None if self.error is None else self.error.to_mapping(),
+        }
+
+
+@dataclass(frozen=True)
+class VisualRunDraft:
+    schema_version: str
+    run_id: str
+    event_type: str
+    event_version: int
+    actor: str
+    phase: str
+    stage: str
+    object_id: str
+    object_version: int
+    previous_object_version: int | None
+    observed_at: str
+    idempotency_key: str
+    payload: Mapping[str, Any]
+    artifact: ArtifactReference | None
+    status: str | None
+    error: TerminalError | None
+
+    @classmethod
+    def from_event(cls, event: VisualRunEvent) -> VisualRunDraft:
+        mapping = event.to_mapping()
+        mapping.pop("sequence")
+        return cls.from_mapping(mapping)
+
+    @classmethod
+    def from_mapping(cls, value: Mapping[str, Any]) -> VisualRunDraft:
+        normalized = _validate_event_mapping(value, sequence_required=False)
+        return cls(**normalized)
+
+    def to_mapping(self) -> dict[str, Any]:
+        mapping = {
+            "schema_version": self.schema_version,
+            "run_id": self.run_id,
+            "event_type": self.event_type,
+            "event_version": self.event_version,
+            "actor": self.actor,
+            "phase": self.phase,
+            "stage": self.stage,
+            "object_id": self.object_id,
+            "object_version": self.object_version,
+            "previous_object_version": self.previous_object_version,
+            "observed_at": self.observed_at,
+            "idempotency_key": self.idempotency_key,
+            "payload": _thaw_json(self.payload),
+            "artifact": None if self.artifact is None else self.artifact.to_mapping(),
+            "status": self.status,
+            "error": None if self.error is None else self.error.to_mapping(),
+        }
+        return mapping
+
+    def with_sequence(self, sequence: int) -> VisualRunEvent:
+        mapping = self.to_mapping()
+        mapping["sequence"] = sequence
+        return VisualRunEvent.from_mapping(mapping)
+
+
+def _canonical_json(value: Mapping[str, Any]) -> bytes:
+    return (
+        json.dumps(
+            value, ensure_ascii=False, allow_nan=False, sort_keys=True, separators=(",", ":")
+        )
+        + "\n"
+    ).encode("utf-8")
+
+
+def canonical_event_bytes(event: VisualRunEvent) -> bytes:
+    encoded = _canonical_json(event.to_mapping())
+    if len(encoded) > MAX_EVENT_BYTES:
+        _refuse("VISUAL_RUN_EVENT_TOO_LARGE", "visual event exceeds the byte ceiling")
+    return encoded
+
+
+def canonical_draft_bytes(draft: VisualRunDraft) -> bytes:
+    encoded = _canonical_json(draft.to_mapping())
+    if len(encoded) > MAX_EVENT_BYTES:
+        _refuse("VISUAL_RUN_EVENT_TOO_LARGE", "visual event draft exceeds the byte ceiling")
+    return encoded
+
+
+def _pairs_object(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
+    result: dict[str, Any] = {}
+    for key, value in pairs:
+        if key in result:
+            _refuse("VISUAL_RUN_DUPLICATE_KEY", f"duplicate JSON key: {key!r}")
+        result[key] = value
+    return result
+
+
+def parse_event(raw: str | bytes | bytearray) -> VisualRunEvent:
+    if isinstance(raw, str):
+        try:
+            encoded = raw.encode("utf-8")
+        except UnicodeEncodeError:
+            _refuse("VISUAL_RUN_INVALID_JSON", "event is not UTF-8 encodable")
+    elif isinstance(raw, (bytes, bytearray)):
+        encoded = bytes(raw)
+    else:
+        _refuse("VISUAL_RUN_INVALID_JSON", "event input must be UTF-8 text or bytes")
+    if len(encoded) > MAX_EVENT_BYTES:
+        _refuse("VISUAL_RUN_EVENT_TOO_LARGE", "visual event exceeds the byte ceiling")
+    try:
+        text = encoded.decode("utf-8")
+        value = json.loads(
+            text,
+            object_pairs_hook=_pairs_object,
+            parse_constant=lambda token: _refuse(
+                "VISUAL_RUN_INVALID_JSON", f"non-finite JSON token: {token}"
+            ),
+        )
+    except VisualRunError:
+        raise
+    except (UnicodeDecodeError, ValueError, RecursionError):
+        _refuse("VISUAL_RUN_INVALID_JSON", "event is not bounded strict JSON")
+    if not isinstance(value, dict):
+        _refuse("VISUAL_RUN_INVALID_JSON", "visual event must be a JSON object")
+    return VisualRunEvent.from_mapping(value)